Feature lookup tables

Current version: v3.2

The Mapbox Boundaries lookup tables are JSON and CSV files that are delivered to you when you buy access to Boundaries. They provide extra information about features that is not directly available in the vector tiles.

Each boundary feature is indexed in a lookup table. Lookup tables are designed to be used locally in your application. They are delivered as flat files so they can be customized, parsed down, and adjusted in a way that best suits your solution.

The lookup tables are organized by data type and level and are provided in both JSON and CSV format. The different formats contain the same information, so you can use whichever one is better suited to your workflow.

Field descriptions

The Mapbox Boundaries lookup tables include this metadata about each polygon and point feature:

  • id: A string identifier for the feature that is globally unique within a worldview. For most functionality that deals with the vector tiles you should use feature_id instead. These are provided for backwards compatibility with Boundaries v2 and are likely to be deprecated in favor of feature_id in the future.
  • feature_id: The integer ID used for each feature in the vector tiles. It can be used for data-joins with Mapbox GL JS's feature state. Like id, it is globally unique within a worldview.
  • type: The data type (for example admin, postal, or stats). See the Boundary types for a full list of values and definitions.
  • level: A numeric value between 0 and 5 that shows the level of boundaries within the type. (Note: different data types have different level ranges available.)
  • layer: A shortened concatenation of type and level with feature's administrative (adm), postal (pos), or statistical (sta) hierarchy and level (0-5). For example, administrative level 1 would have a level of adm1.
  • worldview: Used to display alternate boundary data depending on regional map display requirements. See the Boundaries reference for an explanation of possible values.
  • unit_code: The country-specific identifier for the feature, such as postcode or FIPS code.
  • name: The local feature name.
  • name_en: An English translation or Latin transliteration of the local name. Generally only provided when name is in a non-latin script, otherwise may be null.
  • names: An array that contains additional translations or aliases for the feature name. May be null.
  • description: A text qualifier of the level respective to each country's boundary hierarchy. For example, US admin-1 boundaries have a description of states while Italian admin-1 boundaries have a description of regions.
  • wikidata_id: The associated Wikidata ID for the boundary. May be null, as not all features can be directly associated with Wikidata entities.
  • source_date: Recency of boundary data.
  • iso_3166_1_alpha_3: The ISO 3166-1 alpha-3 country code for the feature's parent country or territory.
  • iso_3166_1: The ISO 3166-1 alpha-2 country code for the feature's parent country or territory.
  • grouping_attributes: A JSON object with properties that allows associating the feature to relevant geographic groups like UN M49 regions for countries (admin-0).
  • join_atrributes: A JSON object with properties that allows associating the feature to relevant geographic codes like UN M49 regions for countries (admin-0) and ISO 3166-2 subdivision codes for admin-1 or admin-2 polygons.
  • parent_1: The id of the level-1 parent of a feature, if any.
  • parent_2: The id of the level-2 parent of a feature, if any.
  • parent_3: The id of the level-3 parent of a feature, if any.
  • parent_4: The id of the level-4 parent of a feature, if any.
  • z_min: The minimum zoom level at which a polygon feature appears in a tileset.
  • centroid: An approximate central point of the feature's polygon as an array of [longitude, latitude].
  • bounds: An array of the features bounding box as [minlong, minlat, maxlong, maxlat]. Longitude values for features crossing the date line will be outside the (-180:180) range.
  • polytilesetname: The tileset ID for the tileset containing the feature's polygon. See the list of tilesets for more details.
  • polylayername: The name of the source-layer within the polygon tileset containing the feature.
  • pointtilesetname: The tileset ID for the tileset containing the feature's point. See the list of tilesets for more details.
  • pointlayername: The name of the source-layer within the point tileset containing the feature.

Data structure

CSV

Boundaries with alternate worldview representations will have multiple entries and can be correctly targeted using the corresponding worldview property.

// Header row
layer,type,level,polytilesetname,polylayername,pointtilesetname,pointlayername,id,feature_id,wikidata_id,worldview,unit_code,name,name_en,names,description,source_date,iso_3166_1_alpha_3,iso_3166_1,grouping_attributes,join_attributes,parent_1,parent_2,parent_3,parent_4,z_min,area_sqkm,centroid,bounds

JSON

In the nested JSON structure, individual boundary entries will be keyed by their unique string id value in the <layer>.data.all path, while boundaries with alternate worldview representations will be available in the corresponding <layer>.data.<worldview> path.

// Sample entry from admin-0 lookup table
{
    "adm0":{
       "type":"admin",
       "level":0,
       "PolyTilesetName":"mapbox.boundaries-adm0-v3",
       "PolyLayerName":"boundaries_admin_0",
       "PointTilesetName":"mapbox.boundaries-admPoints-v3",
       "PointLayerName":"points_admin_0",
       "data":{
          "all":{
             "AD":{
                "feature_id":331777,
                "wikidata_id":"Q228",
                "worldview":"all",
                "unit_code":"AD",
                "name":"Andorra",
                "names":{
                   "ar":[
                      "أندورا"
                   ],
                   "ca":[
                      "Andorra",
                      "Principat d'Andorra",
                      "el país dels Pirineus",
                      "les Valls d'Andorra"
                   ],
                   "de":[
                      "Andorra"
                   ],
                   "en":[
                      "AND",
                      "Andorra",
                      "Principality of Andorra",
                      "Principality of the Valleys of Andorra",
                      "ad",
                      "🇦🇩"
                   ],
                   "es":[
                      "Andorra",
                      "Principado de Andorra"
                   ],
                   "fr":[
                      "Andorre"
                   ],
                   "it":[
                      "Andorra"
                   ],
                   "ja":[
                      "アンドラ"
                   ],
                   "ko":[
                      "안도라"
                   ],
                   "pt":[
                      "Andorra"
                   ],
                   "ru":[
                      "Андорра"
                   ],
                   "vi":[
                      "Andorra"
                   ],
                   "zh-Hans":[
                      "安道尔"
                   ],
                   "zh-Hant":[
                      "安道爾"
                   ]
                },
                "description":"state",
                "source_date":"2016",
                "iso_3166_1_alpha_3":"AND",
                "iso_3166_1":"AD",
                "grouping_attributes":{
                   "UN M49 Region":[
                      "Europe"
                   ],
                   "UN M49 Sub-region":[
                      "Southern Europe"
                   ]
                },
                "join_attributes":{
                   "UN M49 Sub-region code":"039",
                   "UN M49 Region code":"150"
                },
                "z_min":0,
                "centroid":[
                   1.5893,
                   42.5425
                ],
                "bounds":[
                   1.4138,
                   42.4288,
                   1.7865,
                   42.6549
                ],
                "area_sqkm":629
             }
             ...more boundaries
          }
          ...more worldviews
       }
    }
 }