Category Files

Organization

The data/* folder contains a lot of files - one file per category.

Category files are organized in a tree/key/value path. Each category file contains all the items that share an OpenStreetMap key/value tag.

• tree - The highest level of organization - each tree contains categories that follow a similar approach to naming and linking to Wikidata.
• key - An OpenStreetMap tree key (e.g. "amenity")
• value - An OpenStreetMap tag value (e.g. "fast_food")

The name-suggestion-index currently supports these trees:

• brands - Branded businesses like restaurants, banks, fuel stations, shops identified by brand/brand:wikidata tags
• operators - Organizations like post offices, police departments, hospitals identified by operator/operator:wikidata tags
• flags - Flagpoles hoisting common kinds of flags (national, regional, religious, advertising) identified by flag:wikidata tag
• transit - Transit networks (bus, rail, ferry, etc.) and related infrastructure identified by network/network:wikidata tags

For example:

• data/
  • brands/amenity/fast_food.json
  • brands/shop/supermarket.json
  • operators/amenity/post_office.json
  • flags/man_made/flagpole.json
  • transit/route/bus.json
  • and so on…

Category file contents

Each category file contains:

• properties - Object containing category-wide properties
• items - Array containing the items in the category

For example brands/amenity/fast_food.json (comments added for clarity):

"properties": {                           // CATEGORY PROPERTIES:
  "path": "brands/amenity/fast_food"      // "path" - the tree/key/value path for this category
  …
},
"items": [                                // An array of items belonging to this category
  …
  {                                         // ITEM PROPERTIES:
    "displayName": "McDonald's",            // "displayName" - Name to display in summary screens and lists
    "id": "mcdonalds-658eea",               // "id" - a unique identifier added and generated automatically
    "locationSet": {"include": ["001"]},    // "locationSet" - defines where this brand is valid ("001" = worldwide)
    "tags": {                               // "tags" - OpenStreetMap tags that every McDonald's should have
      "amenity": "fast_food",               //   The OpenStreetMap tag for a "fast food" restaurant
      "brand": "McDonald's",                //   `brand` - Brand name in the local language (English)
      "brand:wikidata": "Q38076",           //   `brand:wikidata` - Universal Wikidata identifier
      "brand:wikipedia": "en:McDonald's",   //   `brand:wikipedia` - Reference to English Wikipedia
      "cuisine": "burger",                  //   `cuisine` - What kind of fast food is served here
      "name": "McDonald's"                  //   `name` - Display name, also in the local language (English)
    }
  },
  …

There may also be items for McDonald's in other languages! For example, this is how McDonald's should be mapped in Japan:

  …
  {                                         // ITEM PROPERTIES:
    "displayName": "マクドナルド",            // "displayName" - Name to display in summary screens and lists
    "id": "マクドナルド-3e7699",              // "id" - a unique identifier added and generated automatically
    "locationSet": { "include": ["jp"] },   // "locationSet" - defines where this brand is valid ("jp" = Japan)
    "tags": {
      "amenity": "fast_food",
      "brand": "マクドナルド",                // `brand` - Brand name in the local language (Japanese)
      "brand:en": "McDonald's",             // `brand:en` - For non-English brands, tag the English version too
      "brand:ja": "マクドナルド",             // `brand:ja` - Add at least one `brand:xx` tag that matches `brand`
      "brand:wikidata": "Q38076",           // `brand:wikidata` - Same Universal wikidata identifier
      "brand:wikipedia": "ja:マクドナルド",   // `brand:wikipedia` - Reference to Japanese Wikipedia
      "cuisine": "burger",
      "name": "マクドナルド",                 // `name` - Display name, also in the local language (Japanese)
      "name:en": "McDonald's"               // `name:en` - For non-English names, tag the English version too
      "name:ja": "マクドナルド",              // `name:ja` - Add at least one `name:xx` tag that matches `name`
    }
  },
  …