Refresh docs
This commit is contained in:
Bryan Housel
parent
e0d7f413af
commit
d0721aae8b
7 changed files with 271 additions and 195 deletions
125
CONTRIBUTING.md
125
CONTRIBUTING.md
|
|
@ -2,39 +2,51 @@
|
|||
|
||||
### tl;dr
|
||||
|
||||
##### :raising_hand: How to help:
|
||||
##### 🙋♀️ How to help:
|
||||
|
||||
* [Prerequisites & installation instruction in the README](https://github.com/osmlab/name-suggestion-index#prerequisites)
|
||||
<!-- * [Prerequisites & installation instruction in the README](https://github.com/osmlab/name-suggestion-index#prerequisites) -->
|
||||
* `npm run build` will reprocess the files and output warnings
|
||||
* Resolve warnings - [show me](#thinking--resolve-warnings)
|
||||
* Remove generic names - [show me](#hocho--remove-generic-names)
|
||||
* Add `brand:wikidata` and `brand:wikipedia` tags - [show me](#female_detective--add-wiki-tags)
|
||||
* Add missing brands - [show me](#convenience_store--add-missing-brands)
|
||||
* Edit Wikidata in compliance with their policies - [show me](#memo--edit-wikidata)
|
||||
|
||||
Tip: You can browse the index at https://nsi.guide/
|
||||
to see which brands are missing Wikidata links, or have incomplete Wikipedia pages.
|
||||
👉 Tip: You can browse the index at https://nsi.guide/ to see which brands are missing Wikidata links, or have incomplete Wikipedia pages.
|
||||
|
||||
|
||||
##### :no_entry_sign: Don't edit the files in `dist/` - they are generated:
|
||||
#### Source files (edit these):
|
||||
|
||||
* `dist/collected/*` - all the frequent names and tags collected from OpenStreetMap
|
||||
* `dist/filtered/*` - subset of names and tags that we are keeping or discarding
|
||||
* `dist/wikidata.json` - cached brand data retrieved from Wikidata
|
||||
The files under `config/*`, `data/*`, and `features/*` can be edited:
|
||||
|
||||
##### :white_check_mark: Do edit the files in `config/`, `data/`, and `features/`:
|
||||
- `data/*` - Data files for each feature category, organized by topic and OpenStreetMap tag
|
||||
- `brands/**/*.json`
|
||||
- `flags/**/*.json`
|
||||
- `operators/**/*.json`
|
||||
- `transit/**/*.json`
|
||||
|
||||
* `config/*`:
|
||||
* `config/genericWords.json` - Regular expressions used to find and discard generic names
|
||||
* `config/matchGroups.json` - Groups of OpenStreetMap tags that are considered equivalent for purposes of matching
|
||||
* `config/replacements.json` - Mapping of old Wikidata QIDs map to their replacement new Wikidata and Wikipedia values.
|
||||
* `config/trees.json` - Metadata about subtrees in this project, and regular expressions used to keep and discard tags
|
||||
* `data/*` - Data files for each kind of branded business, organized by topic and OpenStreetMap tag
|
||||
* `data/brands/amenity/*.json`
|
||||
* `data/brands/leisure/*.json`
|
||||
* `data/brands/shop/*.json`
|
||||
* and so on...
|
||||
* `features/*` - Source files for custom locations where brands are active
|
||||
- `features/*` - GeoJSON files that define custom regions (aka [geofences](https://en.wikipedia.org/wiki/Geo-fence))
|
||||
- `us/new_jersey.geojson`
|
||||
- `ca/quebec.geojson`
|
||||
- and so on…
|
||||
|
||||
- `config/*`
|
||||
- `genericWords.json` - Regular expressions used to find and discard generic names
|
||||
- `matchGroups.json` - Groups of OpenStreetMap tags that are considered equivalent for purposes of matching
|
||||
- `replacements.json` - Mapping of old Wikidata QIDs to replacement new Wikidata/Wikipedia values
|
||||
- `trees.json` - Metadata about subtrees supported in this project
|
||||
|
||||
|
||||
#### Generated files (do not edit):
|
||||
|
||||
The files under `dist/*` are generated:
|
||||
- `dist/nsi.json` - The complete index
|
||||
- `dist/dissolved.json` - List of items that we believe may be dissolved based on Wikidata claims
|
||||
- `dist/taginfo.json` - List of all tags this project supports (see: https://taginfo.openstreetmap.org/)
|
||||
- `dist/wikidata.json` - Cached data retrieved from Wikidata (names, social accounts, logos)
|
||||
- `dist/collected/*` - Frequently occuring tags collected from OpenStreetMap
|
||||
- `dist/config/*` - A copy of the config files (see below)
|
||||
- `dist/filtered/*` - Subset of tags that we are keeping or discarding
|
||||
- `dist/presets/*` - Preset files generated for iD and JOSM editors
|
||||
|
||||
|
||||
|
||||
|
|
@ -42,8 +54,7 @@ to see which brands are missing Wikidata links, or have incomplete Wikipedia pag
|
|||
|
||||
### :world_map: About OpenStreetMap
|
||||
|
||||
[OpenStreetMap](https://openstreetmap.org) is a free, editable map of the whole world that
|
||||
is being built by volunteers.
|
||||
[OpenStreetMap](https://openstreetmap.org) is a free, editable map of the whole world that is being built by volunteers.
|
||||
Features on the map are defined using _tags_. Each tag is a `key=value` pair of text strings.
|
||||
|
||||
For example, a McDonald's restaurant might have these tags:
|
||||
|
|
@ -58,9 +69,13 @@ For example, a McDonald's restaurant might have these tags:
|
|||
|
||||
### :bulb: About the name-suggestion-index
|
||||
|
||||
The goal of this project is to define the _most correct tags_ to assign to each common brand name.
|
||||
This helps people contribute to OpenStreetMap, because they can pick "McDonald's" from a list
|
||||
and not need to worry about the tags being added.
|
||||
The goal of this project is to define the _most correct tags_ for common features,
|
||||
and to link these features to a [Wikidata](https://www.wikidata.org/) QID identifer.
|
||||
|
||||
- This helps people contribute to OpenStreetMap, because they can pick "McDonald's"
|
||||
from a list and not need to worry about the tags being added.
|
||||
- This helps the OpenStreetMap project because consumers can use and understand the
|
||||
data better when it is tagged consistently.
|
||||
|
||||
|
||||
|
||||
|
|
@ -240,7 +255,7 @@ This project includes a "fuzzy" matcher that can match alternate names and tags
|
|||
…
|
||||
```
|
||||
|
||||
:point_right: The matcher code also has some useful automatic behaviors...
|
||||
👉 The matcher code also has some useful automatic behaviors…
|
||||
|
||||
You don't need to add `matchNames` for:
|
||||
- Name variations in capitalization, punctuation, spacing (the middots common in Japanese names count as punctuation, so "V・ドラッグ" already matches "vドラッグ")
|
||||
|
|
@ -264,23 +279,15 @@ You can optionally add a `note` property to any item. The note can contain any
|
|||
The notes just stay with the name-suggestion-index; they aren't OpenStreetMap tags or used by other software.
|
||||
|
||||
```js
|
||||
"path": "brands/amenity/bank",
|
||||
"items": [
|
||||
…
|
||||
{
|
||||
"displayName": "United Bank (Connecticut)",
|
||||
"id": "unitedbank-28419b",
|
||||
"locationSet": { "include": ["peoples_united_bank_ct.geojson"] },
|
||||
"note": "Merged into People's United Bank (Q7165802) in 2019, see https://en.wikipedia.org/wiki/United_Financial_Bancorp",
|
||||
"tags": {
|
||||
"amenity": "bank",
|
||||
"brand": "United Bank",
|
||||
"brand:wikidata": "Q16959074",
|
||||
"brand:wikipedia": "en:United Financial Bancorp",
|
||||
"name": "United Bank"
|
||||
…
|
||||
}
|
||||
},
|
||||
…
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -295,7 +302,6 @@ You should also give each entry a unique `displayName`, so everyone can tell the
|
|||
|
||||
|
||||
```js
|
||||
…
|
||||
{
|
||||
"displayName": "Price Chopper (Kansas City)",
|
||||
"id": "pricechopper-9554e9",
|
||||
|
|
@ -320,7 +326,6 @@ You should also give each entry a unique `displayName`, so everyone can tell the
|
|||
"shop": "supermarket"
|
||||
}
|
||||
},
|
||||
…
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -338,7 +343,7 @@ Feature files look like this:
|
|||
"properties": {},
|
||||
"geometry": {
|
||||
"type": "Polygon",
|
||||
"coordinates": [...]
|
||||
"coordinates": […]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -365,46 +370,6 @@ To rebuild the index, run:
|
|||
|
||||
This will output a lot of warnings, which you can help fix!
|
||||
|
||||
|
||||
|
||||
### :thinking: Resolve warnings
|
||||
|
||||
Warnings mean that you need to edit files under `data/brands/*`.
|
||||
The warning output gives a clue about how to fix or suppress the warning.
|
||||
If you aren't sure, just ask on GitHub!
|
||||
|
||||
|
||||
|
||||
#### Duplicate names
|
||||
|
||||
```
|
||||
Warning - Potential duplicate:
|
||||
------------------------------------------------------------------------------------------------------
|
||||
If the items are two different businesses,
|
||||
make sure they both have accurate locationSets (e.g. "us"/"ca") and wikidata identifiers.
|
||||
If the items are duplicates of the same business,
|
||||
add `matchTags`/`matchNames` properties to the item that you want to keep, and delete the unwanted item.
|
||||
If the duplicate item is a generic word,
|
||||
add a filter to config/genericWords.json and delete the unwanted item.
|
||||
------------------------------------------------------------------------------------------------------
|
||||
"shop/supermarket|Carrefour" -> duplicates? -> "amenity/fuel|Carrefour"
|
||||
"shop/supermarket|VinMart" -> duplicates? -> "shop/department_store|VinMart"
|
||||
```
|
||||
|
||||
_What it means:_ These names are commonly tagged differently in OpenStreetMap. This might be ok, but it might be a mistake.
|
||||
|
||||
For "VinMart" we really prefer for it to be tagged as a supermarket. It's a single brand frequently mistagged.
|
||||
* Add `"matchTags": ["shop/department_store"]` to the (preferred) `"shop/supermarket|VinMart"` entry
|
||||
* Delete the (not preferred) entry for `"shop/department_store|VinMart"`
|
||||
|
||||
For "Carrefour" we know that can be both a supermarket and a fuel station. It's two different things.
|
||||
* Make sure both items have a `brand:wikidata` tag and appropriate `locationSet`.
|
||||
|
||||
Existing tagging (you can compare counts in `dist/filtered/names_keep.json`), information at the relevant Wikipedia page or the company's website, and [OpenStreetMap Wiki tag documentation](https://wiki.openstreetmap.org/wiki/Map_Features) all help in deciding how to address duplicate warnings.
|
||||
|
||||
If the situation is unclear, one may contact the [local community](https://community.osm.be/) and ask for help.
|
||||
|
||||
|
||||
|
||||
### :hocho: Remove generic names
|
||||
|
||||
|
|
@ -621,7 +586,7 @@ is a valuable way to get ahead of incorrect tagging.
|
|||
|
||||
4. If instances of this brand are commonly mistagged add the `"matchNames": []` key to list these. Again, refer to [here](#card_file_box--about-the-data-files) for syntax.
|
||||
|
||||
5. Run `npm run build` and resolve any [duplicate name warnings](#thinking--resolve-warnings).
|
||||
5. Run `npm run build`
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
44
DEVELOPING.md
Normal file
44
DEVELOPING.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
## Info for Developers
|
||||
|
||||
This file contains useful information for developers who want to use the name-suggestion-index in another project.
|
||||
|
||||
|
||||
### Downloading the index files
|
||||
|
||||
You can download the files from the index directly from GitHub or use a CDN.
|
||||
|
||||
#### Latest published release (stable forever):
|
||||
|
||||
Direct from GitHub <sub><sup>([docs](https://stackoverflow.com/questions/39065921/what-do-raw-githubusercontent-com-urls-represent))</sup></sub>:
|
||||
```js
|
||||
https://raw.githubusercontent.com/osmlab/name-suggestion-index/{branch or tag}/{path to file}
|
||||
https://raw.githubusercontent.com/osmlab/name-suggestion-index/v5.0.20210315/dist/name-suggestions.presets.min.xml
|
||||
```
|
||||
|
||||
Via JSDelivr CDN <sub><sup>([docs](https://www.jsdelivr.com/))</sup></sub>:
|
||||
```js
|
||||
https://cdn.jsdelivr.net/npm/name-suggestion-index@{semver}/{path to file}
|
||||
https://cdn.jsdelivr.net/npm/name-suggestion-index@5.0/dist/name-suggestions.presets.min.xml
|
||||
```
|
||||
|
||||
#### Current development version (breaks sometimes!):
|
||||
|
||||
Direct from GitHub <sub><sup>([docs](https://stackoverflow.com/questions/39065921/what-do-raw-githubusercontent-com-urls-represent))</sup></sub>:
|
||||
```js
|
||||
https://raw.githubusercontent.com/osmlab/name-suggestion-index/{branch or tag}/{path to file}
|
||||
https://raw.githubusercontent.com/osmlab/name-suggestion-index/main/dist/presets/nsi-josm-presets.min.xml
|
||||
```
|
||||
|
||||
Via JSDelivr CDN <sub><sup>([docs](https://www.jsdelivr.com/?docs=gh))</sup></sub>:
|
||||
```js
|
||||
https://cdn.jsdelivr.net/gh/name-suggestion-index@{branch or tag}/{path to file}
|
||||
https://cdn.jsdelivr.net/gh/osmlab/name-suggestion-index@main/dist/presets/nsi-josm-presets.min.xml
|
||||
```
|
||||
|
||||
|
||||
### Code
|
||||
|
||||
Some of the JavaScript code is available in both ES6 module (.mjs) and CommonJS (.js) formats.
|
||||
|
||||
More info soon.
|
||||
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
Copyright 2018, name-suggestion-index contributors
|
||||
Copyright 2021, name-suggestion-index contributors
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
|
||||
|
||||
|
|
|
|||
100
MAINTAINING.md
Normal file
100
MAINTAINING.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
## Info For Maintainers
|
||||
|
||||
This file contains useful information for maintainers.
|
||||
You don't need to know any of this if you just want to contribute to the index!
|
||||
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Node.js](https://nodejs.org/) version 10 or newer
|
||||
- [`git`](https://www.atlassian.com/git/tutorials/install-git/) for your platform
|
||||
|
||||
|
||||
### Installing
|
||||
|
||||
- Clone this project, for example:
|
||||
`git clone git@github.com:osmlab/name-suggestion-index.git`
|
||||
- `cd` into the project folder,
|
||||
- Run `npm install` to install libraries
|
||||
|
||||
|
||||
### Updates
|
||||
|
||||
- `git pull origin --rebase` is a good way to keep your local copy of the index updated
|
||||
- rerun `npm install` after dependencies are updated in `package.json`
|
||||
|
||||
|
||||
### Building the index
|
||||
|
||||
- `npm run build`
|
||||
- Takes a few seconds and should be run whenever any of the `data/*` or `config/*` files change
|
||||
- Make sure to check in code when done, with something like `git add . && git commit -m 'npm run build'`
|
||||
- Processes any custom locations under `features/**/*.geojson`
|
||||
- Regenerates `dist/filtered/*` keep and discard lists
|
||||
- Any new items from the keep list not already present in the index will be merged into it
|
||||
- Outputs many warnings to suggest updates to `data/**/*.json`
|
||||
|
||||
|
||||
### Syncing with Wikidata
|
||||
|
||||
- `npm run wikidata`
|
||||
- Takes about 15 minutes and should be run occasionally to keep NSI in sync with Wikidata
|
||||
- Make sure to check in code when done, with something like `git add . && git commit -m 'npm run wikidata'`
|
||||
- Fetches related Wikidata names, descriptions, logos, then updates `dist/wikidata.json`
|
||||
- Updates the Wikidata pages to contain the current NSI identifiers
|
||||
- Outputs many warnings to suggest fixes on Wikidata for missing social accounts, or other common errors
|
||||
- (We may try to automate more of this eventually)
|
||||
|
||||
|
||||
### Releasing
|
||||
|
||||
- `npm run dist`
|
||||
- Takes a few seconds and builds all the files in `dist/*`
|
||||
- The semantic version number of the project is updated automatically: `major.minor.patch` where patch is the date in `yyyymmdd` format
|
||||
- Make sure to check in code when done, with something like `git add . && git commit -m 'npm run dist'`
|
||||
- Rebuilds iD and JOSM presets, taginfo file, other output files
|
||||
- Should be run whenever the index is in a good state (build and wikidata sync has happened successfully)
|
||||
- Projects which pull NSI data from GitHub (such as <https://nsi.guide/>) will appear updated soon after `npm run dist`
|
||||
- Other downstream projects may pull from `dist/*` too
|
||||
|
||||
To publish an official release, follow the steps in [RELEASE.md](RELEASE.md).
|
||||
- Official releases are stable forever and available via NPM or on CDNs like JSDelivr
|
||||
- Projects which pull name-suggestion-index from NPM or a CDN (sucn as iD) will appear updated soon after publishing
|
||||
- Publishing the code to NPM requires rights to run `npm publish`
|
||||
|
||||
|
||||
### Building nsi.guide
|
||||
|
||||
<https://nsi.guide/> is a web application written in ReactJS that lets anyone browse the index.
|
||||
|
||||
- `npm run appbuild`
|
||||
- Rebuilds the ReactJS code for <https://nsi.guide/>
|
||||
- The source code for this app can be found under `app/*`
|
||||
- Only need to rebuild this when the app code changes, not when the index changes.
|
||||
|
||||
|
||||
### Other commands
|
||||
|
||||
- `npm run lint` - Checks the Javascript code for correctness
|
||||
- `npm run test` - Runs tests agains the Javascript code
|
||||
- `npm run` - Lists other available commands
|
||||
|
||||
|
||||
### Collecting names from the OSM planet
|
||||
|
||||
This takes a long time and a lot of disk space. It can be done occasionally by project maintainers.
|
||||
|
||||
- Install `osmium` command-line tool and node package (may only be available on some environments)
|
||||
- `apt-get install osmium-tool` or `brew install osmium-tool` or similar
|
||||
- `npm install --no-save osmium`
|
||||
- [Download the planet](http://planet.osm.org/pbf/)
|
||||
- `curl -L -o planet-latest.osm.pbf https://planet.openstreetmap.org/pbf/planet-latest.osm.pbf`
|
||||
- Prefilter the planet file to only include named items with keys we are looking for:
|
||||
- `osmium tags-filter planet-latest.osm.pbf -R name,brand,operator,network -o filtered.osm.pbf`
|
||||
- Run `node scripts/collect_all.js /path/to/filtered.osm.pbf`
|
||||
- results will go in `dist/collected/*.json`
|
||||
- A new challenge:
|
||||
- Attempt an `npm run build`. Now that unique `id` properties are generated, it is possible that this command will fail.
|
||||
- This can happen if there are *multiple* new items that end up with the same `id` (e.g. "MetroBus" vs "Metrobus")
|
||||
- You'll need to just pick one to keep, then keep trying to run `npm run build` until the duplicate `id` issues are gone.
|
||||
- `git add . && git commit -m 'Collected common names from latest planet'`
|
||||
144
README.md
144
README.md
|
|
@ -1,10 +1,11 @@
|
|||
[](https://github.com/osmlab/name-suggestion-index/actions?query=workflow%3A%22build%22)
|
||||
[](https://badge.fury.io/js/name-suggestion-index)
|
||||
|
||||
## name-suggestion-index
|
||||
## name-suggestion-index (aka "NSI")
|
||||
|
||||
Canonical features for OpenStreetMap
|
||||
|
||||
|
||||
### What is it?
|
||||
|
||||
The goal of this project is to maintain a [canonical](https://en.wikipedia.org/wiki/Canonicalization)
|
||||
|
|
@ -12,9 +13,11 @@ list of commonly used features for suggesting consistent spelling and tagging in
|
|||
|
||||
[Watch the video](https://2019.stateofthemap.us/program/sat/mapping-brands-with-the-name-suggestion-index.html) from our talk at State of the Map US 2019 to learn more about this project!
|
||||
|
||||
|
||||
### Browse the index
|
||||
|
||||
You can browse the index at <https://nsi.guide/>.
|
||||
👉 You can browse the index at <https://nsi.guide/>.
|
||||
|
||||
|
||||
### How it's used
|
||||
|
||||
|
|
@ -40,74 +43,50 @@ Currently used in:
|
|||
- [osmfeatures](https://github.com/westnordost/osmfeatures)
|
||||
- [Go Map!!](https://github.com/bryceco/GoMap)
|
||||
|
||||
|
||||
### About the index
|
||||
|
||||
#### Generated files (do not edit):
|
||||
You can learn more from these pages:
|
||||
- <https://nsi.guide/> - Browse and search all the data
|
||||
- [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute data about brands, transit, and other features to this index
|
||||
- [DEVELOPING.md](DEVELOPING.md) - If you are a developer and want to use the name-suggestion-index in your project
|
||||
- [MAINTAINING.md](MAINTAINING.md) - How to setup and build the index, sync with wikidata, and make releases
|
||||
|
||||
The files under `dist/*` are generated:
|
||||
* `dist/nsi.json` - The complete index
|
||||
* `dist/dissolved.json` - List of items that we believe may be dissolved based on Wikidata claims
|
||||
* `dist/taginfo.json` - List of all tags this project supports (see: https://taginfo.openstreetmap.org/)
|
||||
* `dist/wikidata.json` - Cached data retrieved from Wikidata
|
||||
* `dist/collected/*` - Frequently occuring tags collected from OpenStreetMap
|
||||
* `dist/config/*` - A copy of the config files (see below)
|
||||
* `dist/filtered/*` - Subset of tags that we are keeping or discarding
|
||||
* `dist/presets/*` - Preset files generated for iD and JOSM editors
|
||||
|
||||
#### Source files (edit these):
|
||||
|
||||
The files under `config/*`, `data/*`, and `features/*` can be edited:
|
||||
|
||||
* `config/*`:
|
||||
* `config/genericWords.json` - Regular expressions used to find and discard generic names
|
||||
* `config/matchGroups.json` - Groups of OpenStreetMap tags that are considered equivalent for purposes of matching
|
||||
* `config/replacements.json` - Mapping of old Wikidata QIDs map to their replacement new Wikidata and Wikipedia values.
|
||||
* `config/trees.json` - Metadata about subtrees in this project, and regular expressions used to keep and discard tags
|
||||
* `data/*` - Data files for each kind of feature, organized by topic and OpenStreetMap tag
|
||||
* `data/brands/**/*.json`
|
||||
* `data/flags/**/*.json`
|
||||
* `data/operators/**/*.json`
|
||||
* `data/transit/**/*.json`
|
||||
* and so on…
|
||||
* `features/*` - GeoJSON files that define custom regions where the features are allowed
|
||||
* `features/us/new_jersey.geojson`
|
||||
* `features/ca/quebec.geojson`
|
||||
* and so on…
|
||||
- `data/*` - Data files for each feature category, organized by topic and OpenStreetMap tag
|
||||
- `brands/**/*.json`
|
||||
- `flags/**/*.json`
|
||||
- `operators/**/*.json`
|
||||
- `transit/**/*.json`
|
||||
|
||||
:point_right: See [CONTRIBUTING.md](CONTRIBUTING.md) for info about how to contribute to this index.
|
||||
- `features/*` - GeoJSON files that define custom regions (aka [geofences](https://en.wikipedia.org/wiki/Geo-fence))
|
||||
- `us/new_jersey.geojson`
|
||||
- `ca/quebec.geojson`
|
||||
- and so on…
|
||||
|
||||
- `config/*`:
|
||||
- `genericWords.json` - Regular expressions used to find and discard generic names
|
||||
- `matchGroups.json` - Groups of OpenStreetMap tags that are considered equivalent for purposes of matching
|
||||
- `replacements.json` - Mapping of old Wikidata QIDs to replacement new Wikidata/Wikipedia values
|
||||
- `trees.json` - Metadata about subtrees supported in this project
|
||||
|
||||
|
||||
#### Downloading the index files:
|
||||
#### Generated files (do not edit):
|
||||
|
||||
You can download the files from the index directly from GitHub or use a CDN.
|
||||
The files under `dist/*` are generated:
|
||||
- `dist/nsi.json` - The complete index
|
||||
- `dist/dissolved.json` - List of items that we believe may be dissolved based on Wikidata claims
|
||||
- `dist/taginfo.json` - List of all tags this project supports (see: https://taginfo.openstreetmap.org/)
|
||||
- `dist/wikidata.json` - Cached data retrieved from Wikidata (names, social accounts, logos)
|
||||
- `dist/collected/*` - Frequently occuring tags collected from OpenStreetMap
|
||||
- `dist/config/*` - A copy of the config files (see below)
|
||||
- `dist/filtered/*` - Subset of tags that we are keeping or discarding
|
||||
- `dist/presets/*` - Preset files generated for iD and JOSM editors
|
||||
|
||||
##### Latest published release (stable forever):
|
||||
|
||||
Direct from GitHub <sub><sup>([docs](https://stackoverflow.com/questions/39065921/what-do-raw-githubusercontent-com-urls-represent))</sup></sub>:
|
||||
```js
|
||||
https://raw.githubusercontent.com/osmlab/name-suggestion-index/{branch or tag}/{path to file}
|
||||
https://raw.githubusercontent.com/osmlab/name-suggestion-index/v4.0.2/dist/name-suggestions.presets.min.xml
|
||||
```
|
||||
|
||||
Via JSDelivr CDN <sub><sup>([docs](https://www.jsdelivr.com/))</sup></sub>:
|
||||
```js
|
||||
https://cdn.jsdelivr.net/npm/name-suggestion-index@{semver}/{path to file}
|
||||
https://cdn.jsdelivr.net/npm/name-suggestion-index@4.0.2/dist/name-suggestions.presets.min.xml
|
||||
```
|
||||
|
||||
##### Current development version (breaks sometimes!):
|
||||
|
||||
Direct from GitHub <sub><sup>([docs](https://stackoverflow.com/questions/39065921/what-do-raw-githubusercontent-com-urls-represent))</sup></sub>:
|
||||
```js
|
||||
https://raw.githubusercontent.com/osmlab/name-suggestion-index/{branch or tag}/{path to file}
|
||||
https://raw.githubusercontent.com/osmlab/name-suggestion-index/main/dist/presets/nsi-josm-presets.min.xml
|
||||
```
|
||||
|
||||
Via JSDelivr CDN <sub><sup>([docs](https://www.jsdelivr.com/?docs=gh))</sup></sub>:
|
||||
```js
|
||||
https://cdn.jsdelivr.net/gh/name-suggestion-index@{branch or tag}/{path to file}
|
||||
https://cdn.jsdelivr.net/gh/osmlab/name-suggestion-index@main/dist/presets/nsi-josm-presets.min.xml
|
||||
```
|
||||
|
||||
### Participate!
|
||||
|
||||
|
|
@ -117,57 +96,6 @@ https://cdn.jsdelivr.net/gh/osmlab/name-suggestion-index@main/dist/presets/nsi-j
|
|||
We're always looking for help! If you have any questions or want to reach out to a maintainer, ping `bhousel` on:
|
||||
- [OpenStreetMap US Slack](https://slack.openstreetmap.us/) (`#poi` or `#general` channels)
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- [Node.js](https://nodejs.org/) version 10 or newer
|
||||
- [`git`](https://www.atlassian.com/git/tutorials/install-git/) for your platform
|
||||
|
||||
#### Installing
|
||||
|
||||
- Clone this project, for example:
|
||||
`git clone git@github.com:osmlab/name-suggestion-index.git`
|
||||
- `cd` into the project folder,
|
||||
- Run `npm install` to install libraries
|
||||
|
||||
#### Building the index
|
||||
|
||||
- `npm run build`
|
||||
- Processes any custom locations under `features/**/*.geojson`
|
||||
- Regenerates `dist/filtered/*` keep and discard lists
|
||||
- Any new items from the keep list not already present in the index will be merged into it
|
||||
- Outputs many warnings to suggest updates to `data/**/*.json`
|
||||
|
||||
#### Building nsi.guide
|
||||
|
||||
<https://nsi.guide/> is a web application written in ReactJS that lets anyone browse the index.
|
||||
* The source code for this app can be found under `app/*`
|
||||
* `npm run appbuild` will rebuild it.
|
||||
|
||||
#### Other commands
|
||||
|
||||
- `npm run wikidata` - Fetch useful data from Wikidata - labels, descriptions, logos, etc.
|
||||
- `npm run dist` - Rebuild and minify the generated files in the `dist/` folder.
|
||||
- `npm run` - Lists other available commands
|
||||
|
||||
#### Collecting names from planet
|
||||
|
||||
This takes a long time and a lot of disk space. It can be done occasionally by project maintainers.
|
||||
You do not need to do these steps in order to contribute to the index.
|
||||
|
||||
- Install `osmium` command-line tool and node package (may only be available on some environments)
|
||||
- `apt-get install osmium-tool` or `brew install osmium-tool` or similar
|
||||
- `npm install --no-save osmium`
|
||||
- [Download the planet](http://planet.osm.org/pbf/)
|
||||
- `curl -L -o planet-latest.osm.pbf https://planet.openstreetmap.org/pbf/planet-latest.osm.pbf`
|
||||
- Prefilter the planet file to only include named items with keys we are looking for:
|
||||
- `osmium tags-filter planet-latest.osm.pbf -R name,brand,operator,network -o filtered.osm.pbf`
|
||||
- Run `node scripts/collect_all.js /path/to/filtered.osm.pbf`
|
||||
- results will go in `dist/collected/*.json`
|
||||
- A new challenge:
|
||||
- Attempt an `npm run build`. Now that unique `id` properties are generated, it is possible that this command will fail.
|
||||
- This can happen if there are *multiple* new items that end up with the same `id` (e.g. "MetroBus" vs "Metrobus")
|
||||
- You'll need to just pick one to keep, then keep trying to run `npm run build` until the duplicate `id` issues are gone.
|
||||
- `git add . && git commit -m 'Collected common names from latest planet'`
|
||||
|
||||
### License
|
||||
|
||||
|
|
|
|||
11
RELEASE.md
11
RELEASE.md
|
|
@ -1,14 +1,13 @@
|
|||
## Release Checklist
|
||||
|
||||
#### Update version, tag, and publish
|
||||
### Update version, tag, and publish
|
||||
- [ ] git checkout main
|
||||
- [ ] git pull origin
|
||||
- [ ] npm install
|
||||
- [ ] npm run build
|
||||
- [ ] Update version number in `package.json` and `README.md`
|
||||
- [ ] npm run wikidata
|
||||
- [ ] npm run dist
|
||||
- [ ] git add . && git commit -m 'vA.B.C'
|
||||
- [ ] git tag vA.B.C
|
||||
- [ ] git push origin main vA.B.C
|
||||
- [ ] npm run dist _(version number updates automatically and will print to console)_
|
||||
- [ ] git add . && git commit -m 'A.B.C'
|
||||
- [ ] git tag A.B.C
|
||||
- [ ] git push origin main A.B.C
|
||||
- [ ] npm publish
|
||||
|
|
|
|||
40
WARNINGS.md
Normal file
40
WARNINGS.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
## Resolving Warnings
|
||||
|
||||
### :thinking: Resolve warnings
|
||||
|
||||
Warnings mean that you need to edit files under `data/brands/*`.
|
||||
The warning output gives a clue about how to fix or suppress the warning.
|
||||
If you aren't sure, just ask on GitHub!
|
||||
|
||||
|
||||
|
||||
#### Duplicate names
|
||||
|
||||
```
|
||||
Warning - Potential duplicate:
|
||||
------------------------------------------------------------------------------------------------------
|
||||
If the items are two different businesses,
|
||||
make sure they both have accurate locationSets (e.g. "us"/"ca") and wikidata identifiers.
|
||||
If the items are duplicates of the same business,
|
||||
add `matchTags`/`matchNames` properties to the item that you want to keep, and delete the unwanted item.
|
||||
If the duplicate item is a generic word,
|
||||
add a filter to config/genericWords.json and delete the unwanted item.
|
||||
------------------------------------------------------------------------------------------------------
|
||||
"shop/supermarket|Carrefour" -> duplicates? -> "amenity/fuel|Carrefour"
|
||||
"shop/supermarket|VinMart" -> duplicates? -> "shop/department_store|VinMart"
|
||||
```
|
||||
|
||||
_What it means:_ These names are commonly tagged differently in OpenStreetMap. This might be ok, but it might be a mistake.
|
||||
|
||||
For "VinMart" we really prefer for it to be tagged as a supermarket. It's a single brand frequently mistagged.
|
||||
* Add `"matchTags": ["shop/department_store"]` to the (preferred) `"shop/supermarket|VinMart"` entry
|
||||
* Delete the (not preferred) entry for `"shop/department_store|VinMart"`
|
||||
|
||||
For "Carrefour" we know that can be both a supermarket and a fuel station. It's two different things.
|
||||
* Make sure both items have a `brand:wikidata` tag and appropriate `locationSet`.
|
||||
|
||||
Existing tagging (you can compare counts in `dist/filtered/names_keep.json`), information at the relevant Wikipedia page or the company's website, and [OpenStreetMap Wiki tag documentation](https://wiki.openstreetmap.org/wiki/Map_Features) all help in deciding how to address duplicate warnings.
|
||||
|
||||
If the situation is unclear, one may contact the [local community](https://community.osm.be/) and ask for help.
|
||||
|
||||
|
||||
Loading…
Add table
Reference in a new issue