Glossary

worldview

In Mapbox services, the worldview data field is used to identify geographic features whose characteristics are defined differently by audiences belonging to various regional, cultural, or political groups.

Available worldviews

ValueDescription
CNFeatures for a mainland Chinese audience
INFeatures conforming to cartographic requirements for use in India
JPFeatures for a Japanese audience
USFeatures for an American audience

Vector tilesets

Some Mapbox vector tilesets, including Mapbox Streets v8 and Boundaries v3, include the worldview data field in several layers. Those layers may contain multiple versions of some features, each with a worldview value indicating the intended audience.

Filtering data

When creating a map style with a tileset that uses worldviews, you must apply a filter to any layers that include a worldview data field. When a worldview filter is not applied, the user will see all possible worldviews at once resulting in conflicting and overlapping shapes.

If you are using a Mapbox-designed style (like Mapbox Light or Mapbox Outdoors), the worldview filter is set up to show the US worldview by default.

The value of the worldview property will either be:

  • an ISO 3166-1 country code, for example US or CN
  • all if the feature does not vary between audiences (most features across the world will have a worldview value of all)

When you apply the worldview filter, it must include both all and one of the region-specific values. Additionally, there are classes in respective layers, prefixed with disputed_, which you must select in conjunction with the worldview filter.

Below is an example filter (using the get expression) for the admin-0-boundary-disputed layer in the Mapbox Outdoors v11 style:

[
  "all",
  ["==", ["get", "disputed"], "true"],
  ["==", ["get", "admin_level"], 0],
  ["==", ["get", "maritime"], "false"],
  ["match", ["get", "worldview"], ["all", "US"], true, false]
]
Use an "in" expression with Boundaries v3

In the Boundaries v3 tileset, the value of the worldview property can also be a comma-separated list of one or more ISO 3166-1 country codes, (for example US or CN,JP). Because a single feature can belong to more than one worldview, you must use the "in" operator to construct a layer filter. Below is an example filter to enable a US worldview using Mapbox Boundaries v3.

[
  "any",
  ["==", "all", ["get", "worldview"]],
  ["in", "US", ["get", "worldview"]]
]

Related resources:

Was this page helpful?