> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ja/data/boundaries/llms.txt) # Mapbox Boundaries v3 > **Note (legacy)** > > This guide discusses a deprecated version of Mapbox Boundaries. For the most updated version, see [Mapbox Boundaries v4](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v4/). Mapbox users who have access to Mapbox Boundaries can add global administrative, postal, and statistical boundaries to their maps and data visualizations. This guide covers how to use Mapbox Boundaries in a web application and navigate feature lookup tables. ![The Mapbox Boundaries tileset in x-ray mode.](https://docs.mapbox.com/ja/assets/ideal-img/enterprise-boundaries-xray.f86fdb8.480.png) ## Basic example To add Mapbox Boundaries to a Mapbox GL JS map, use [`map.addSource`](https://docs.mapbox.com/mapbox-gl-js/api/#map#addsource) to add a Boundaries tileset to the map, then use [`map.addLayer`](https://docs.mapbox.com/mapbox-gl-js/api/#map#addlayer) to apply a style to the data. Here is an example adding the `admin-1` polygon tileset and styling it with a basic fill. ```js map.on('load', function() { // Add source for admin-1 Boundaries map.addSource('admin-1', { type: 'vector', url: 'mapbox://mapbox.boundaries-adm1-v3' }); // Add a layer with boundary polygons map.addLayer( { id: 'admin-1-fill', type: 'fill', source: 'admin-1', 'source-layer': 'boundaries_admin_1', paint: { 'fill-color': '#CCCCCC' } }, // This final argument indicates that we want to add the Boundaries layer // before the `waterway-label` layer that is in the map from the Mapbox // Light style. This ensures the admin polygons will be rendered on top of // the 'waterway-label' ); }); ``` ## Add a worldview filter The Mapbox Boundaries tilesets provide multiple [`worldview`](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v3#worldviews) options in each tileset. That means that there are multiple versions of certain features, each intended for a different audience. Filters on each style layer determine which worldview you show. You should add a worldview filter to every Boundaries layer you add to a map. Since you might add more Boundaries layers to a project later, it makes sense to define the filter as a variable. This example uses a variable called `worldviewFilter`: ```js map.on('load', function() { // Add source for admin-1 Boundaries map.addSource('admin-1', { type: 'vector', url: 'mapbox://mapbox.boundaries-adm1-v3' }); var worldviewFilter = [ "any", ["==", "all", ["get", "worldview"]], ["in", "US", ["get", "worldview"]] ]; // Add a layer with boundary polygons map.addLayer( { id: 'admin-1-fill', type: 'fill', source: 'admin-1', 'source-layer': 'boundaries_admin_1', filter: worldviewFilter, paint: { 'fill-color': '#CCCCCC' } }, // This final argument indicates that we want to add the Boundaries layer // before the `waterway-label` layer that is in the map from the Mapbox // Light style. This ensures the admin polygons will be rendered on top of // the 'waterway-label' ); }); ``` This creates a map style with Mapbox Boundaries that's ready to have custom data joined into it. # Reference ## Worldviews The `worldview` property will be either `all` or a comma-separated list of one or more ISO 3166-1 country codes. The supported region-specific worldviews are: | Value | Description | | --- | --- | | `all` | Features common for all worldviews | | `AR` | Features for an Argentinian audience | | `CN` | Features for a mainland Chinese audience | | `IN` | Features for an Indian audience | | `JP` | Features for a Japanese audience | | `MA` | Features for a Moroccan audience | | `RU` | Features for a Russian audience | | `TR` | Features for a Turkish audience | | `US` | Features for an American audience | *Disclaimer: Mapbox worldviews have been internally reviewed for accuracy, but have not been officially endorsed by respective countries.* ## Vector tilesets Same as [v4 tileset ids](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v4#tileset-ids), but with the `v3` version suffix. ### Tileset schema ### Polygon tilesets `boundaries_{type}_{level}` Each polygon tileset contains a single layer named `boundaries_{type}_{level}`, where `{type}` is one of the [Boundary types](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v4#layer-types-and-levels), and `{level}` is the level number. #### feature `id` The feature id provides an identifier integer for each feature. These IDs are globally unique within a given [*worldview*](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v3#worldviews). Some are duplicated, but only where they represent different versions of the same feature for different worldviews. > **Note: What is a Feature ID?** > > The `id` is a special property of a vector tile feature. It is always a whole number, and it is treated differently than normal feature properties. To reference an `id` in a [Mapbox GL expression](https://docs.mapbox.com/style-spec/reference/expressions/), you would write [`["id"]`](https://docs.mapbox.com/style-spec/reference/expressions/#id) rather than [`["get", "property_name"]`](https://docs.mapbox.com/style-spec/reference/expressions/#get), as you would use for normal properties. #### `iso_3166_1` *text* The `iso_3166_1` property contains the ISO 3166-1 code of each feature's administrative level 0 parent (or the feature itself in the case of the `adm0` tileset). #### `worldview` *text* See [worldviews](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v3#worldviews) for details. ## Feature lookup tables 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. ### Boundary identifiers Every boundary feature is assigned a unique integer feature `id` in the vector tiles and is cross referenced by a corresponding `feature_id` in the feature lookup table. ### 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](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#setfeaturestate). Like `id`, it is globally unique within a worldview. - **`type`**: The data type (for example `admin`, `postal`, or `stats`). See the [Boundary types](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v4#layer-types-and-levels) 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](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v3#worldviews) 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 not in a Latin based 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](https://www.wikidata.org/wiki/Wikidata:Main_Page) 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](https://www.iso.org/iso-3166-country-codes.html) for the feature's parent country or territory. - **`iso_3166_1`**: The [ISO 3166-1 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html) 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](https://unstats.un.org/unsd/methodology/m49/) for countries (admin-0). - **`join_atrributes`**: A JSON object with properties that allows associating the feature to relevant geographic codes like [UN M49 regions](https://unstats.un.org/unsd/methodology/m49/) for countries (admin-0) and [ISO 3166-2 subdivision codes](https://www.iso.org/standard/72483.html) 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](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v3#vector-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](https://docs.mapbox.com/ja/data/boundaries/reference/mapbox-boundaries-v3#vector-tilesets) for more details. - **`pointlayername`**: The name of the `source-layer` within the point tileset containing the feature. ### Format **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 `.data.all` path, while boundaries with alternate worldview representations will be available in the corresponding `.data.` path. ```json // 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 } } } ```