Item Property Reference

Each category file contains an Array of items that belong to that category.

The items can include:

"Normal" items - items representing brands, flags, routes, or other map features.
Templates - placeholders that will expand all the normal items from another source category, but modify the source tags to fit the destination category.

You can include both normal and template items in the same items Array.

Normal Items

"items": [
  …
  {
    "displayName": "McDonald's",
    "id": "mcdonalds-658eea",
    "locationSet": {"include": ["001"]},
    "tags": {
      "amenity": "fast_food",
      "brand": "McDonald's",
      "brand:wikidata": "Q38076",
      "cuisine": "burger",
      "name": "McDonald's"
    }
  },
  …

Normal item properties:

displayName
id
locationSet
matchNames
matchTags
note
preserveTags
tags

displayName

_{Required
yes

Type
String

Example
"McDonald's"}

The displayName can contain anything, but it should be a short text appropriate for display in lists or as preset names in editor software. This is different from the OpenStreetMap name tag.

The displayName should be written in the local language of the item, and the displayName value must be unique within a category file.

Disambiguating between entries

By convention, if you need to disambiguate between multiple brands, operators, or transit networks with the same name, we add text in parenthesis. Values used for disambiguation should be concise, but also distinct enough so that everyone can tell the entities apart. For a general overview of how the build script handles similarly-named entries, see Category Files.

As an example, here is a snippet from brands/shop/department_store.json with two items named "Target". Each entry has been assigned a different display name to tell them apart.

"items": [
  …
  {
    "displayName": "Target (Australia)",
    "id": "target-c93bbd",
    "locationSet": {"include": ["au"]},
    "tags": {
      "brand": "Target",
      "brand:wikidata": "Q7685854",
      "name": "Target",
      "shop": "department_store"
    }
  },
  {
    "displayName": "Target (USA)",
    "id": "target-592fe0",
    "locationSet": {"include": ["us"]},
    "tags": {
      "brand": "Target",
      "brand:wikidata": "Q1046951",
      "name": "Target",
      "shop": "department_store"
    }
  },
  …

Disambiguation in the NSI for entries with identical names has generally followed the following guidelines:

Entries for completely different entities (brands, operators, etc.) are each given a disambiguator, such as in the Target example above.
Entries pertaining to local branches or subsidiaries of a larger entity are given disambiguators while the entry for the larger entity is not typically given a disambiguator.
- Example: in brands/amenity/fast_food.json, an entry for McDonald's locations in France has a displayName of "McDonald's (France)" while the global entry for McDonald's has a displayName of just "McDonald's".
- One exception to this practice is when a local branch or subsidiary shares an operating area with its parent. For example, in brands/amenity/bank.json, State Bank of India and State Bank of India (California) both operate in California, United States. In order to clearly distinguish the entries for end users in California, the global State Bank of India entry is given a displayName of "State Bank of India (Global)".

Disambiguation values are usually geographic in nature, such as the administrative area (e.g., country) in which the entry operates or the name of the city or area in which the entry is based.

id

_{Required
no (generated automatically)

Type
String

Example
"mcdonalds-658eea"}

Each item has a unique id generated for it. When adding a new item, you don't need to add an id. Running the build script (npm run build) after modifying a data file will generate the id for the new data automatically. You can run npm run build before submitting your pull request if you'd like, but this is completely optional. If you don't know how to run npm run build, don't worry: maintainers routinely perform this operation on the index and can generate the id for you.

The identifiers are generated based on these values:

The name specified in the tag most applicable to the entry's parent tree (brand for brands, operator for operators, flag:name for flags, and network for transit operators). If this value is in a language other than English, the build script will attempt to find an English value for the identifier. This process begins by searching for a companion *:en tag (e.g., brand:en); if the entry does not have this tag, the script continues by looking for English values in a handful of other tags before defaulting to a six-character hash based on the original, non-English name value.
The key and value pairing associated with the entry's parent category file (e.g., shop=supermarket for brands/shop/supermarket.json).
The contents of the entry's locationSet Array.

The id value is stable unless any of the above values are modified.

locationSet

_{Required
yes

Type
Object {}}

Each item requires a locationSet to define where the item is available. You can define the locationSet as an Object with include and exclude properties:

"locationSet": {
  "include": [ Array of locations ],
  "exclude": [ Array of locations ]
}

The "locations" can be any of the following:

Strings recognized by the country-coder library.
These include ISO 3166-1 two- or three-letter country codes, UN M49 numeric codes, and supported Wikidata QIDs.
Examples: "de", "001", "conus", "gb-sct", "Q620634"
👉 A current list of supported codes can be found at https://ideditor.codes
👉 See Regional Features for country subdivisions, such as US States and international regions.
The id values of custom .geojson features (see Feature Files for details). Existing features can be found under the features/* folder of this project. If you want to use your own features, you need to add the new features to the features/* folder as part of your pull request.
Each feature must have an id that ends in .geojson. Running npm run build will automatically generate and add an id to the feature if an id is not already specified.
Examples: "de-hh.geojson", "us-nj.geojson"
Circular areas defined as a [longitude, latitude, radius?] Array.
longitude and latitude are the coordinates of the area's center point. radius is specified in kilometers and is optional. If radius is not specified, the area will default to a 25km radius around the center point.
Examples: [8.67039, 49.41882], [-88.3726, 39.4818, 32]

`locationSet` Tips:

The M49 code for the whole world is "001"
A current list of supported codes can be found at https://ideditor.codes
You can view examples and learn more about working with locationSets in the @rapideditor/location-conflation project.
You can test locationSets on this interactive map: https://location-conflation.com/

matchNames, matchTags

_{Required
no

Type
Array[Strings]}

Brands are often tagged inconsistently in OpenStreetMap. For example, some mappers write "International House of Pancakes" and others write "IHOP".

This project includes a "fuzzy" matcher that can match alternate names and tags to a single entry in the Name Suggestion Index. The matcher keeps duplicate items out of the index, and the names collected by the matcher are used in the iD editor to help suggest tag improvements.

matchNames and matchTags properties can be used to supply the matcher with a list of the less-preferred alternatives.

"properties": {
  "path": "brands/amenity/fast_food"      // all items in this file will match the tag `amenity=fast_food`
  …
},
"items": [
  …
  {
    "displayName": "Honey Baked Ham",
    "id": "honeybakedham-4d2ff4",
    "locationSet": { "include": ["us"] },
    "matchNames": ["honey baked ham company"],    // also match these less-preferred names
    "matchTags": ["shop/butcher", "shop/deli"],   // also match these less-preferred tags
    "tags": {
      "alt_name": "HoneyBaked Ham",                    // match `alt_name`
      "amenity": "fast_food",
      "brand": "Honey Baked Ham",                      // match `brand`
      "brand:wikidata": "Q5893363",
      "cuisine": "american",
      "name": "Honey Baked Ham",                       // match `name`
      "official_name": "The Honey Baked Ham Company"   // match `official_name`
    }
  },
  …

👉 The matcher code also has some useful automatic behaviors…

You don't need to add matchNames for:

variations in capitalization, punctuation, spacing (the middots common in Japanese names count as punctuation, so "V・ドラッグ" already matches "vドラッグ")
variations that already appear in the name, brand, operator, network.
variations that already appear in an alternate name tag (e.g. alt_name, short_name, official_name, etc.)
variations that already appear in any international version of those tags (e.g. name:en, official_name:ja, etc.)
variations in diacritic marks (e.g. "Häagen-Dazs" already matches "Haagen-Dazs")
variations in & vs. and

You don't need to add matchTags for:

Tags assigned to match groups (defined in config/matchGroups.json). For example, you don't need add matchTags: ["shop/doityourself"] to every "shop/hardware" and vice versa. Tags in a match group will automatically match any other tags in the same match group.

👉 Bonus: The build script (npm run build) will automatically remove any extra matchNames and matchTags that are unnecessary due to the above automatic features.

Note: the automatic behaviors described above apply only to the NSI category files, and not to products that use NSI data (such as OSM's iD editor). Releases of the NSI contain only a static list of names and tags for each entry, and any efforts to match this data to suggestions and presets are the responsibility of the downstream product. See #10040 for details.

note

_{Required
no

Type
String}

You can optionally add a note property to any item. The note can contain any text useful for maintaining the index - for example, information about the item's real-world status, or a link to a GitHub issue.

The notes just stay within the Name Suggestion Index; they aren't OpenStreetMap tags or used by other software.

{
  "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": {
    …
  }
}

preserveTags

_{Required
no

Type
Array[Regex Strings]

Example
["^name"]}

For tags matching these regular expressions, values in NSI should not replace an existing value in OSM.

By default, all of the tags as they appear in NSI are how they should appear on an OSM feature. Validator software (such as built into iD) can suggest updates to OSM by comparing an OSM feature's tags against NSI's tags.

In some situations, we want to leave an existing OSM tag value alone. preserveTags contains an Array of regular expressions to match OSM keys where we want to preserve any existing tag value and never suggest a replacement.

👉 The preserveTags property can be set per-category (applying to all items in a category) or per-item.

preserveTags is useful for tags such as "^name" (key starts with "name"), on items where the name tag is expected to be unique:

Amazon Locker ("Amazon Locker - Robot")
Apple Store ("Apple Bridgewater")

Templates

Templates can appear in the items Array alongside the "normal" items.

A template is placeholder that will expand all the normal items from another source category, but modify the source tags to fit the destination category.

Templates are used in the name-suggestion-index to implement several convenient rules:

For each Bank in brands/amenity/bank, create an ATM in brands/amenity/atm but with the operator set to the bank
For each Post Office in operators/amenity/post_office, create a Post Box item in operators/amenity/post_box
For each Bus Route in transit/route/bus, create a Bus Stop item in transit/highway/bus_stop
and more…

templateSource

_{Required
yes

Type
String

Example
"brands/amenity/bank"}

A tree/key/value path to use as the source of the expanded items.

templateTags

_{Required
yes

Type
Object {}}

By default, all source item tags are copied as-is into the destination item tags.

The templateTags Object contains the tags which should be different (added, modified, or removed).

You can use replacement tokens in the form {source.tags.key} to refer to source tag values. For example, to copy the bank brand tags to ATM operator tags:

{
  "templateSource": "brands/amenity/bank",
  "templateTags": {
    "amenity": "atm",
    "operator": "{source.tags.brand}",
    "operator:wikidata": "{source.tags.brand:wikidata}"
  }
},

You can also use empty tags to indicate that a source tag should not be copied. For example, to expand bus stops for every bus route, you can remove the source route tag like this:

{
  "templateSource": "transit/route/bus",
  "templateTags": {
    "highway": "bus_stop",
    "route": ""
  }
}

templateInclude

_{Required
no

Type
Array[Regex Strings]}

By default, a template will expand all source items into destination items.

If templateInclude is specified, only the source items with id matching the regular expressions in the templateInclude Array will be included.

templateExclude

_{Required
no

Type
Array[Regex Strings]}

By default, a template will expand all source items into destination items.

If templateExclude is specified, source items with id matching the regular expressions in the templateExclude Array will be excluded.

Home

Home

For Contributors

Contributing to the index

Advanced Topics

Feature Files (geofences)
- Creating/Editing Guide
- Regional Features
Using Overpass Turbo
Config Files
Property Reference
- Category Properties
- Item Properties
Technical Details

For Developers

Information for developers using the name-suggestion-index in another project.

For Maintainers

Information for maintainers, including how to clone and build the project.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Item Property Reference

Normal Items

displayName

Disambiguating between entries

id

locationSet

`locationSet` Tips:

matchNames, matchTags

note

preserveTags

tags

Templates

templateSource

templateTags

templateInclude

templateExclude

Home

For Contributors

Advanced Topics

For Developers

For Maintainers

Clone this wiki locally

Required	no (generated automatically)
Type	`String`
Example	`"mcdonalds-658eea"`

Required	no
Type	`Array[Regex Strings]`
Example	`["^name"]`

Required	no
Type	`Array[Regex Strings]`

Required	no
Type	`Array[Regex Strings]`

Item Property Reference

Normal Items

displayName

Disambiguating between entries

id

locationSet

locationSet Tips:

matchNames, matchTags

note

preserveTags

tags

Templates

templateSource

templateTags

templateInclude

templateExclude

Home

For Contributors

Advanced Topics

For Developers

For Maintainers

Clone this wiki locally

`locationSet` Tips: