# Overture Maps Documentation

This file contains all documentation content in a single document following the llmstxt.org standard.

## Accessing the Overture Catalog

Overture publishes a full catalog of aassets in each monthly release: global map data, vector tiles, a STAC catalog, a GERS registry, bridge files, and a changelog. Everything is hosted on Amazon S3 and Microsoft Azure Blob Storage.

## Published datasets

Overture distributes its core map data as [GeoParquet](https://geoparquet.org/) files, a column-oriented spatial data format optimized for cloud-native queries. You can scan across the files and pull only the data you need without downloading everything. See [this guide](https://guide.cloudnativegeo.org/geoparquet/) from the Cloud Native Geospatial Forum for more on GeoParquet.

| Provider | Path |
|---|---|
| Amazon S3 | `s3://overturemaps-us-west-2/release/<RELEASE>` |
| Microsoft Azure | `https://overturemapswestus2.blob.core.windows.net/release/<RELEASE>` |

Find the latest `<RELEASE>` value in the [STAC catalog](https://stac.overturemaps.org/catalog.json) or the [STAC viewer](https://stac.overturemaps.org/). See the [quickstart](/getting-data/) for how to query the catalog programmatically.

### Path structure

The base paths above point to the core map datasets in a release. Overture partitions the data by `theme` and `type`; specifying those directories narrows the data you access.

Example S3 path to the `infrastructure` feature type in the `base` theme:

```
s3://overturemaps-us-west-2/release/<RELEASE>/theme=base/type=infrastructure/*.parquet
```

Path components:

- **`<RELEASE>`**: date-based version in the format `yyyy-mm-dd.x`. An archive of releases is maintained on both S3 and Azure.
- **`<theme>`**: one of Overture's six themes — addresses, base, buildings, divisions, places, and transportation.
- **`<type>`**: a feature type within a theme, e.g. `infrastructure` within `base`.
- **`*.parquet`**: the `*` indicates all Parquet files in the directory.

### Theme and type mapping

| Theme | Feature types |
|---|---|
| [Addresses](/guides/addresses/) | address |
| [Base](/guides/base/) | bathymetry, infrastructure, land, land_cover, land_use, water |
| [Buildings](/guides/buildings/) | building, building_part |
| [Divisions](/guides/divisions/) | division, division_area, division_boundary |
| [Places](/guides/places/) | place |
| [Transportation](/guides/transportation/) | segment, connector |

## Accessing the files

The [Python CLI](/getting-data/overturemaps-py/) and [DuckDB](/getting-data/duckdb/) are the most common ways to query and download Overture data. Both read directly from the cloud and transfer only the data you need. See the [quickstart](/getting-data/) to get started with either tool.

For bulk downloads, use the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) or [AzCopy](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-v10) to copy full Parquet directories to your local machine.

**AWS CLI** — download all files in the `infrastructure` type:

```bash
aws s3 cp --no-sign-request --recursive \
  s3://overturemaps-us-west-2/release/<RELEASE>/theme=base/type=infrastructure/ .
```

**AzCopy** — download all `place` data from Azure:

```bash
azcopy copy \
  "https://overturemapswestus2.dfs.core.windows.net/release/<RELEASE>/theme=places/type=place/" \
  "<local directory path>" --recursive
```

You can also access Overture data through Amazon Athena, Microsoft Synapse, Sedona, and other tools. See the [examples](/examples/) for walkthroughs.

## PMTiles

Overture generates [PMTiles](https://docs.protomaps.com/pmtiles/) vector map tiles with each release. These tiles power the [Explorer site](https://explore.overturemaps.org) and are designed for data inspection rather than production cartography.

| Provider | Path |
|---|---|
| Amazon S3 | `s3://overturemaps-extras-us-west-2/tiles/<RELEASE>/<THEME>.pmtiles` |
| HTTP | `https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles/<RELEASE>/<THEME>.pmtiles` |

Preview any PMTiles URL at [pmtiles.io](https://pmtiles.io). To create your own tiles from Overture data, see the [PMTiles example](/examples/overture-tiles/) and the [overture-tiles](https://github.com/OvertureMaps/overture-tiles) repository.

## STAC catalog

Overture's [STAC catalog](https://stac.overturemaps.org/catalog.json) is the machine-readable index for all releases. It always points to the latest release and includes metadata for every theme and type: spatial extents, feature counts, column names, links to GeoParquet files on AWS and Azure, and links to PMTiles. Browse it in the [STAC viewer](https://stac.overturemaps.org/).

## GERS registry, bridge files, and changelog

Each release includes artifacts from the [Global Entity Reference System (GERS)](/gers/):

- **[GERS registry](/gers/registry/)**: maps stable GERS IDs to current feature data across releases.
- **[Bridge files](/gers/bridge-files/)**: tracks how GERS IDs change between releases — additions, removals, and geometry updates.
- **[Data changelog](/gers/changelog/)**: records schema and data changes across releases.

## Data mirrors

Several partners maintain mirrors on these platforms:

- [BigQuery](/getting-data/data-mirrors/bigquery/)
- [Databricks](/getting-data/data-mirrors/databricks/)
- [Fused](/getting-data/data-mirrors/fused/)
- [Source Cooperative](https://source.coop/)
- [Snowflake](/getting-data/data-mirrors/snowflake/)
- [Wherobots](/getting-data/data-mirrors/wherobots/)

These are community-maintained resources that may offer different access patterns or platform-specific tooling.

---

## BigQuery

Overture data is accessible in Google BigQuery as part of the [Google Cloud Public Dataset Program](https://cloud.google.com/bigquery/public-data), with the data being listed and maintained by [CARTO](https://www.carto.com).

![Overture data in Google Cloud](../assets/BigQuery-1.png)

Below is a step-by-step guide on how to access and use Overture data in BigQuery:

## Before you begin

To get started using Overture data in BigQuery, you must create or select a Google Cloud project with billing [enabled](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project). BigQuery is automatically enabled in new projects, but in order to activate it in a preexisting project, you should enable the [BigQuery API](https://console.cloud.google.com/apis/enableflow?apiid=bigquery&inv=1&invt=Abns8w).

## Getting Overture data in Google BigQuery

1. Log in to your [Google Cloud Console](https://console.cloud.google.com/).
2. Navigate to the **BigQuery** section by selecting `BigQuery` from the side menu or searching for it in the search bar.

    ![Overture data in Google Cloud](../assets/bigquery-2.png)

3. In the BigQuery console, click **Add Data**. Then, click on **Public Datasets**.

    ![Overture data in Google Cloud](../assets/bigquery-4.png)

4. The Google Cloud data marketplace will open. In the search box look for **Overture Maps**.

    ![Overture data in Google Cloud](../assets/bigquery-5.png)

5. Select the **Overture Maps Data** listing. Then, click on **View dataset**.

    ![Overture data in Google Cloud](../assets/bigquery-6.png)

6. Back again in the BigQuery console you will see the `bigquery-public-data` project and the `overture_maps`dataset selected.

    ![Overture data in Google Cloud](../assets/bigquery-7.png)

7. Our recommendation is that you add the `overture_maps` dataset or entirely the `bigquery-public-data` project in your starred selection in order to have access to the Overture data always at hand.

    ![Overture data in Google Cloud](../assets/bigquery-8.png)

## Working with Overture data in BigQuery

1. Now that Overture Maps data is available in your BigQuery console, you can start using it. Note that in the `overture_maps` dataset you have access to all tables from all the different Overture Maps themes: Addresses, Base, Buildings, Divisions, Places and Transportation.

    ![Overture data in Google Cloud](../assets/bigquery-9.png)

2. The release version is detailed as a `label` in each of the tables. You can check it out in the **Details** section of each table.

    ![Overture data in Google Cloud](../assets/bigquery-10.png)

3. You can now query any of the tables directly from your SQL Editor in BigQuery. Here's one example for the Places data in Overture Maps.

    ![Overture data in Google Cloud](../assets/bigquery-11.png)

    ```sql
    -- Identify places within the "Restaurant" category
    SELECT id, phones.list[0].element AS phone, names.primary AS name
    FROM `bigquery-public-data.overture_maps.place`
    WHERE categories.primary = "restaurant"
    LIMIT 100;
    ```

## Additional notes

- **Updates**: CARTO regularly updates the Overture datasets in BigQuery and keeps the dataset synced with the last release. You can check the release version of the data as a metadata label in each table.
- **Support**: If you encounter issues accessing the data, contact CARTO support via [support@carto.com](mailto:support@carto.com).

---

## Databricks

Overture data is accessible through the [Databricks Marketplace](https://marketplace.databricks.com/?searchKey=CARTO&sortBy=date) via public listings published and maintained by [CARTO](https://www.carto.com). Below is a step-by-step guide on how to access and use the data:

## Before you begin

Before accessing the Overture Maps data in Databricks, ensure you have:

- **Databricks Account**: An active Databricks account with access to the Databricks Marketplace.
- **Workspace Access**: A Databricks workspace where you can import and analyze the data.
- **Marketplace Permissions**: The appropriate permissions to browse and subscribe to datasets in the Databricks Marketplace.

## Getting Overture data from Databricks Marketplace

1. Log in to your Databricks workspace.
2. From the Databricks workspace home page, navigate to the **Databricks Marketplace** by selecting the **Marketplace** tab from the sidebar.

    ![Databricks Marketplace](../assets/databricks-1.png)

3. Use the search bar in the Databricks Marketplace to search for `CARTO` or `Overture Maps`.

    ![Databricks Marketplace](../assets/databricks-2.png)

4. The listings have been organized by Overture theme; therefore, you will find the following listings available: Addresses, Base, Buildings, Divisions, Places and Transportation. Select one to access the listing details.

    ![Databricks Marketplace](../assets/databricks-3.png)

5. Review the dataset description, terms of use, and any documentation provided by CARTO.
6. Click **Get instant access** to request access to the dataset.

    ![Databricks Marketplace](../assets/databricks-4.png)

7. Before you get access you can specify where are you planning to use the data and also provide a custom name to the Databricks Catalog in which the data will be made available. After accepting the terms, click on **Get instant access**.

    ![Databricks Marketplace](../assets/databricks-5.png)

8. Now, in the same listing page you have the option to click on **Open**.

    ![Databricks Marketplace](../assets/databricks-6.png)

9. After clicking on **Open** you will be taken to your Catalogs with the newly created Catalog `carto_overtue_maps_places`open.

    ![Databricks Marketplace](../assets/databricks-7.png)

## Working with Overture data in Databricks

1. Once you have the Overture Maps data that you need in your Catalogs you can start working with it. Following our example, in the Place table you can click on **Create** and then **Query**.

    ![Databricks Marketplace](../assets/databricks-8.png)

2. That will open the SQL Editor ready to query the `place` table.

    ![Databricks Marketplace](../assets/databricks-9.png)

## Additional notes

- **Updates**: CARTO regularly updates the Overture datasets in Databricks and keeps the listings synced with the last release. You can check the release version of the data from the share description in each listing.
- **Support**: If you encounter issues accessing the data, contact CARTO support via [support@carto.com](mailto:support@carto.com).
- **Databricks**: For more information on Databricks Marketplace, refer to the official [Databricks documentation](https://docs.databricks.com/en/marketplace/index.html).

---

## Fused

[Fused](https://www.fused.io/) is a cloud analytics platform to process data with [User Defined Functions](https://docs.fused.io/core-concepts/write/) (UDFs). UDFs are reusable Python functions that can be invoked from anywhere. The Fused Overture UDF enables you to quickly load Overture data, perform operations like joins with other datasets, visualize results directly on your browser, and integrate smoothly with data tools.

## Load data with the Overture UDF

The Fused Overture UDF loads data from GeoParquet files of the Overture Dataset hosted by [Source Cooperative](https://beta.source.coop/repositories/fused/overture/description/). You can view the source code of the Fused Overture UDF in this [GitHub repo](https://github.com/fusedio/udfs/blob/main/public/Overture_Maps_Example/Overture_Maps_Example.py).

### Install Fused

We install the [Fused Python library](https://pypi.org/project/fused/) with pip. 

```python
pip install 'fused[all]'
```

### Define the area of interest

We specify the area for the UDF to download data by passing a `GeoDataFrame` to the `bbox` parameter.

```python

bounds = [4.895,52.368,4.914,52.377]
```

### Run the Overture UDF
We may run the Fused Overture UDF with `fused.run` (see more about `fused.run` on the [Fused docs](https://docs.fused.io/core-concepts/run-udfs/)). We specify the area to load data with the `bbox` parameter. The UDF also provides optional parameters to select specific Overture releases, datasets, and columns - giving you flexibility to fetch only the data you need.

<Tabs queryString="fused-run">
    <TabItem value="buildings" label="Buildings">
        <QueryBuilder query={`fused.run('UDF_Overture_Maps_Example', bounds=bounds, overture_type='building') `}></QueryBuilder>
    </TabItem>
    <TabItem value="water" label="Water">
        <QueryBuilder query={`fused.run('UDF_Overture_Maps_Example', bounds=bounds, overture_type='water')`}></QueryBuilder>
    </TabItem>
    <TabItem value="divisions" label="Divisions">
        <QueryBuilder query={`fused.run('UDF_Overture_Maps_Example', bounds=bounds, overture_type='division_boundary')
fused.run('UDF_Overture_Maps_Example', bounds=bounds, overture_type='division')
fused.run('UDF_Overture_Maps_Example', bounds=bounds, overture_type='division_area')`}></QueryBuilder>
    </TabItem>
    <TabItem value="segments-connectors" label="Segments & Connectors">
        <QueryBuilder query={`fused.run('UDF_Overture_Maps_Example', bounds=bounds, overture_type='segment')
fused.run('UDF_Overture_Maps_Example', bounds=bounds, overture_type='connector')`}></QueryBuilder>
    </TabItem>
    <TabItem value="landuse" label="Land Use">
        <QueryBuilder query={`fused.run('UDF_Overture_Maps_Example', bounds=bounds, overture_type='land_use')`}></QueryBuilder>
    </TabItem>
</Tabs>

## Next steps
- Visualize Overture datasets interactively in the [Fused UDF Editor](https://www.fused.io/workbench/catalog/Overture_Maps_Example-64071fb8-2c96-4015-adb9-596c3bac6787)
- See an [example](/examples/fused/) of how to join Overture with other datasets

---

## Data Mirrors


In addition to the official Overture sources on Amazon S3 and Microsoft Azure Blob Storage, several Overture Maps Foundation members and partners maintain mirrors of the data on cloud platforms. These mirrors let you access Overture data directly in your preferred cloud environment.

The mirrors are updated with each monthly Overture release, though there may be a slight delay from the official release date. The schema and structure of the data are maintained as close to the original as possible.

| Platform | Maintained by | Access |
| --- | --- | --- |
| [BigQuery](/getting-data/data-mirrors/bigquery) | CARTO | Google Cloud Public Dataset Program |
| [Databricks](/getting-data/data-mirrors/databricks) | CARTO | Databricks Marketplace |
| [Fused](/getting-data/data-mirrors/fused) | Fused | Source Cooperative via Fused UDFs |
| [Snowflake](/getting-data/data-mirrors/snowflake) | CARTO | Snowflake Data Marketplace |
| [Wherobots](/getting-data/data-mirrors/wherobots) | Wherobots | Wherobots Spatial Catalog |

:::note
These are community-maintained resources. The official distribution on S3 and Azure remains the source of record.
:::

---

## Snowflake

Overture data is accessible through the [Snowflake Data Marketplace](https://app.snowflake.com/marketplace/providers/GZT0ZKUCHE3/CARTO) via public listings published and maintained by [CARTO](https://www.carto.com). Below is a step-by-step guide on how to access and use the data:

## Getting Overture data from Snowflake Marketplace

1. Log in to your Snowflake account. Note that you must have an active Snowflake account with the necessary permissions to access the Data Marketplace.
2. In the Snowflake interface, navigate to the **Marketplace** tab in the sidebar menu within section **Data Products**.

    ![Snowflake Data Marketplace](../assets/snowflake-marketplace-1.png)

3. Use the search bar at the top of the Data Marketplace and enter `CARTO`.
4. The listings have been organized by Overture theme; therefore, you will find the following listings available: Addresses, Base, Buildings, Divisions, Places and Transportation. Select one to access the listing details.

    ![Overture Listings](../assets/snowflake-marketplace-2.png)

5. Review the data description, example queries, terms of use, etc.
6. Click on **Get**.

    ![Overture Places](../assets/snowflake-marketplace-3.png)

7. After clicking on **Get**, you are allowed to specify the name of the database in which to include the data and the user roles that will be able to work with it.

    ![Getting data](../assets/snowflake-marketplace-4.png)

## Working with Overture data in Snowflake

1. After access is granted, navigate to the **Databases** section in Snowflake (under **Data**).
2. Locate the Overture dataset in the database that you have just created.

    ![Overture data in database](../assets/snowflake-marketplace-5.png)

3. Once the database is created, you can then navigate to your worksheet in Snowflake and start working with the data.
4. Use SQL to query the Overture data. Below is an example query to retrieve some attributes from the Places data in Overture.

    ```sql
    -- Identify places within the "Restaurant" category
    SELECT id, phones['list'][0]['element'] AS phone, names['primary'] AS name
    FROM CARTO.PLACE
    WHERE categories['primary'] = 'restaurant'
    LIMIT 100;
    ```

    ![Overture data in database](../assets/snowflake-marketplace-6.png)

## Additional notes

- **Updates**: CARTO regularly updates the Overture datasets in Snowflake and keeps the listings synced with the last release. You can check the release version of the data from the share description in each listing.
- **Support**: If you encounter issues accessing the data, contact CARTO support via [support@carto.com](mailto:support@carto.com).
- **Snowflake**: For more information on Snowflake Data Marketplace, refer to the official [Snowflake documentation](https://docs.snowflake.com/en/user-guide/data-marketplace.html).

---

## Wherobots

Wherobots is a cloud-native environment for geospatial data processing, powered by Apache Sedona. Their hosted notebook environments and data pipeline APIs allow you to work with massive geospatial datasets at scale. As an Overture Maps Foundation member, Wherobots maintains a mirror of all Overture Maps datasets in its cloud environment. Here's how you can access that data.

:::info
**Before you start** ensure that you have a free Wherobots Community Edition Organization or a paid Professional or Enterprise Edition Organization. For more information, see [Create a Wherobots Account](https://docs.wherobots.com/latest/get-started/create-account/#create-or-join-an-organization).
:::

## Navigate to the Wherobots spatial data catalog

1. Log in to [Wherobots Cloud](https://cloud.wherobots.com/).

2. Go to the [spatial catalog](https://cloud.wherobots.com/spatial-catalog).

## Locate the Overture Maps database

1. In the sidebar, expand either the `wherobots_open_data` catalog or `wherobots_pro_data`. 

If you have a Wherobots Professional or Enterprise Edition Organization, you also have access to `wherobots_pro_data`, which includes datasets for enriching your analysis, such as US Census demographics and local weather events.

2. Within `wherobots_open_data`, expand the `overture_maps_foundation` database.

Here, you'll find Overture Maps tables, named according to Overture Maps theme and type: `{theme}_{type}`. For example, `buildings_building` is a table of the `building` type in the `buildings` theme and `transportation_segment` is a table of the `segment` type in the `transportation` theme. 

3. Select a table to view its detailed schema and confirm it contains the data you need.

Each table contains the following:
- catalog name
- catalog storage path
- database
- table name
- table schema

## Next steps
- See the [Wherobots example](/examples/wherobots/) in this documentation to learn more about working with Overture Maps data on the Wherobots platform
- For more on using the Wherobots platform, see the official [Wherobots Documentation](https://docs.wherobots.com/).

---

## DuckDB

[DuckDB](https://duckdb.org/) is powerful analytics tool that allows you to query remote files and download only the data you want. You'll need to install at least [DuckDB 1.1.0](https://duckdb.org/2024/09/09/announcing-duckdb-110.html), which supports reading and writing geoparquet.

## Installation

[Install DuckDB](https://duckdb.org/docs/installation/). You'll need extensions to work with spatial data in the cloud. Run the following commands in the DuckDB command line:

1. `INSTALL SPATIAL;` to install the [duckdb_spatial](https://github.com/duckdblabs/duckdb_spatial) extension.
2. `INSTALL httpfs;` or `INSTALL azure;` to read from either Amazon S3 ([httpfs](https://duckdb.org/docs/guides/import/s3_import.html)) or Microsoft Azure Blob Storage ([azure](https://duckdb.org/docs/extensions/azure)).

## Downloading Overture Data

These SQL queries will access Overture data in the cloud and download only the attributes that you request.

<Tabs queryString="query">

<TabItem value="Places" label="Places">

Download all pizza restaurants in New York City as a `GeoJSON` file.

<QueryBuilder query={NewYorkPizza}></QueryBuilder>

See the [places schema](/schema/reference/places/place) to learn more about each attribute or the [common schema concepts](/schema/reference/core/names) to better understand `names.primary` from `names.common`.
</TabItem>

<TabItem value="Buildings" label="Buildings">

Access Overture buildings data hosted on Azure to download named buildings around Detroit, Michigan. Saves as newline-delimited GeoJSON.

<QueryBuilder query={DetroitBuildings}></QueryBuilder>
</TabItem>

<TabItem value="Roads" label="Roads">

Download all roads intersecting a given bounding box around the Arc de Triomphe in Paris and save as GeoJSON.

<QueryBuilder query={ParisRoadsIntersecting}></QueryBuilder>
_Note: This will result in a GeoJSON file that contains all road segments that intersect the bounding box, not just road segments contained within the bounding box._

To download only roads contained within that bounding box around the Arc de Triomphe in Paris, use the following:
<QueryBuilder query={ParisRoadsContained}></QueryBuilder>
</TabItem>

<TabItem value="Mountains" label="Mountains">

Download mountain peaks in Oregon, USA from the base theme, convert the elevation attribute to feet, and save the result as a GeoJSON file.

<QueryBuilder query={Peaks}></QueryBuilder>

</TabItem>

<TabItem value="Counties" label="Counties">

County-level geometries for Pennsylvania from the divisions theme and outputs a GeoPackage.

<QueryBuilder query={CountyGeometries}></QueryBuilder>

</TabItem>

<TabItem value="geoparquet" label="As GeoParquet">

DuckDB v1.1.0 supports reading and writing GeoParquet directly. It recognizes the `geometry` type and will write the appropriate metadata.

<QueryBuilder query={WriteGeoparquet}></QueryBuilder>

DuckDB recognizes the input as geoparquet and will automatically cast the _geometry_ column to a `GEOMETRY` type.
The `COPY` command writes a parquet file of 100,000 places named `places.parquet` with the appropriate geoparquet metadata.

</TabItem>
</Tabs>

---

:::tip
To download the data as `shapefile`, replace the last line of any of the above queries:

```sql
) TO 'overture_data.shp' WITH (FORMAT GDAL, DRIVER 'ESRI Shapefile');
```

or as a `geopackage`:

```sql
) TO 'overture_data.gpkg' WITH (FORMAT GDAL, DRIVER 'GPKG');
```

The DuckDB Spatial extension supports more than [50 geospatial file formats](https://duckdb.org/docs/extensions/spatial.html#st_read--read-spatial-data-from-files).

You can also use DuckDB to loop over the Parquet files in a directory and convert the data to a spatial format of your choice. The spatial extension uses GDAL so you could export to flatgeobuf if that's the data format that works best for you. Here's a bash script that shows you how:

```bash
for f in *.parquet;
do duckdb -c \
"install spatial;
load spatial;
COPY (SELECT id, st_geomfromwkb(geometry) from read_parquet('$f'))
to '$f.fgb' WITH (FORMAT GDAL, DRIVER 'flatgeobuf');";
done
```
:::

## Regional Extracts

We can use data from Overture's division theme to define our bounds for a regional extract.

This example stores the GERS ID for the division in the `division_id` variable. If you know the GERS ID, you can simply set it with: `SET variable division_id = '<GERS ID>'`.

If you don't know the ID, you can set the variable to the result of a query for that specific division, as shown here:

<QueryBuilder query={BuildingsInDivision}></QueryBuilder>

:::note
This query is broken into discrete steps for efficiency:

1. Using DuckDBs variables in the `WHERE` clause proved more performant than joining to the bounds table.
2. Storing the result first as GeoParquet and then converting to another format is significantly faster than doing it all in one step.
:::

## Next steps

- Visualize the data in [QGIS](/examples/QGIS) or [kepler.gl](/examples/kepler-gl).
- [Make an interactive map](/examples/build-a-map).
- Consult one of our Data Guides to learn more about the data and for more advanced queries.

---

## Explorer

---

[Overture Maps Explorer](https://explore.overturemaps.org) is a no-code, browser-based tool for browsing, searching, and inspecting the data and schema. Explorer is the fastest way to answer these questions:

- What does Overture data look like in a specific area?
- What properties are on a building or a road segment?
- How does Overture represent a particular place or address?
- What's the GERS ID for a specific feature?

You can download data directly from Explorer or you can use it for visual inspection of the data before writing queries with the [Python Client](/getting-data/overturemaps-py/) or [DuckDB](/getting-data/duckdb/).

## Explore and Inspect modes

**Explore mode** presents the data as a styled, readable map. Browse places, roads, buildings, land use, and water features with cartographic styling. Toggle feature types on and off in the layers panel and click features to see their properties.

<figure className="screenshot-frame">

![Explore mode showing places in the Fishtown neighborhood of Philadelphia](./assets/explore-explore-mode.webp)

<figcaption>Explore mode showing places in the Fishtown neighborhood of Philadelphia. The layers panel on the left toggles Overture's six themes on and off.</figcaption>
</figure>

**Inspect mode** exposes the raw data. The layers panel mirrors the Overture schema: base breaks down into land, water, bathymetry, land cover, and land use; transportation shows segments and connectors; divisions shows areas, boundaries, and labels. Features are symbolized as simple points, lines, and polygons.

<figure className="screenshot-frame">

![Inspect mode showing the properties panel for a place feature in Philadelphia](./assets/explore-inspect-mode.webp)

<figcaption>Inspect mode showing the properties panel for a place feature in Philadelphia. The panel displays the feature's GERS ID, category, source attribution, confidence score, and address.</figcaption>
</figure>

## Search

The Explorer includes a search bar for navigating directly to a location or feature. Use the **Search Type** dropdown to switch between search modes.

<figure className="screenshot-frame screenshot-frame--narrow">

![Search bar showing a locality search for Philadelphia, PA](./assets/explore-search.webp)

<figcaption>Searching for "Philadelphia, PA" by locality. The Search Type dropdown also supports Country and GERS ID lookups.</figcaption>
</figure>

**Locality** and **Country** searches use a [geocoding service](https://github.com/brad-richardson/overture-geocoder) built entirely from Overture's divisions data. It covers 450K+ cities, neighborhoods, and administrative areas worldwide, with full-text search and autocomplete.

**GERS** search lets you jump directly to a specific feature by its [GERS ID](/gers/). This lookup is powered by the GERS manifest published in the [Overture STAC catalog](/getting-data/cloud-sources/), which maps every GERS ID to a bounding box. Paste a GERS ID into the search bar to fly to that feature on the map.

## Multilingual names

Toggle between languages to see place names rendered in dozens of scripts. This comes from the `names` field in Overture data, which carries common names, alternate names, and translations.

## How it works

Explorer is built with [MapLibre GL JS](https://maplibre.org/) and powered by [PMTiles](https://docs.protomaps.com/pmtiles/) vector tile archives generated from each Overture release. Tiles are hosted on S3 and loaded directly in the browser.

The site uses a token-based design system: primitives (color palette, fonts), semantics (feature-level color assignments), and components (stylesheet properties referencing the semantic values). A new style requires changing one file.

Explorer is pinned to a specific Overture release. Updates go through a validation process that audits stylesheets against the current schema and tile metadata before reaching the live site.

Source code: [explore-site](https://github.com/OvertureMaps/explore-site) repository.

## Next steps

- Use the [Python Client](/getting-data/overturemaps-py/) to download features by bounding box or the [DuckDB guide](/getting-data/duckdb/) to query the full dataset with SQL. 
- Explorer surfaces properties like GERS IDs, categories, and source attribution. To learn what those fields mean and how the data is structured, explore the [schema reference](/schema/).
- Found a bug in the Explorer? Want to request a new feature? Open an issue in the [explore-site](https://github.com/OvertureMaps/explore-site) repository.
- Found an issue in the underlying data? Open an issue in the [data](https://github.com/OvertureMaps/data) respository.

---

## Python Client

Overture's [Python client](https://github.com/OvertureMaps/overturemaps-py) provides a command-line interface and a Python library for downloading data within a bounding box and converting it to common geospatial file formats. It reads directly from Overture's cloud-hosted GeoParquet and uses the [STAC catalog](https://stac.overturemaps.org/catalog.json) to target the latest release automatically.

## Installation

```bash
pip install overturemaps
```

The package is also available on [conda-forge](https://anaconda.org/conda-forge/overturemaps):

```bash
conda install -c conda-forge overturemaps
```

If you have [uv](https://docs.astral.sh/uv/) installed, you can run overturemaps [with uvx](https://docs.astral.sh/uv/guides/tools/#running-tools) without installing it:

```bash
uvx overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=building -o boston.geojson
```

## Usage

### download

The `overturemaps download` command downloads Overture data with an optional bounding box into the specified file format. When a bounding box is specified, only the minimum data is transferred. Results are streamed, so arbitrarily large areas work.

```bash
overturemaps download \
  --bbox=-71.068,42.353,-71.058,42.363 \
  -f geojson \
  --type=building \
  -o boston_buildings.geojson
```

**Options:**

| Flag | Description |
|---|---|
| `--bbox` | West, south, east, north coordinates. Omit to download the entire type. |
| `-f` | Output format: `geojson`, `geojsonseq`, or `geoparquet` |
| `--type/-t` | Feature type to download, e.g. `building`, `place`, `segment`, `address`. Run `overturemaps download --help` for the complete list. |
| `--output/-o` | Output file path. Omit to write to stdout. |
| `--stac/--no-stac` | Use Overture's STAC catalog to speed up queries (default: on). |

:::tip
Use [this bounding box tool](https://boundingbox.klokantech.com/) to find coordinates for your area of interest. Choose CSV format and copy the value directly into the `--bbox` field.
:::

### gers

The `overturemaps gers` command looks up a [GERS](/gers/) ID in the registry. If the feature is present in the latest release, it downloads the feature and writes it in the specified format.

```bash
overturemaps gers d4e59dbf-fda4-47eb-bf05-f7576f17e2c1 -f geojson -o feature.geojson
```

**Options:**

| Flag | Description |
|---|---|
| `-f` | Output format: `geojson`, `geojsonseq`, or `geoparquet`. Defaults to `geojsonseq`. |
| `--output/-o` | Output file path. Omit to write to stdout. |

## Next steps

- Visualize the data in [QGIS](/examples/QGIS/) or [kepler.gl](/examples/kepler-gl/)
- [Make an interactive map](/examples/build-a-map/)
- Explore the [schema reference](/schema/)

---

## Quickstart

## Explore in the browser

The [Explorer site](./explore) is the fastest way to browse Overture data and inspect the schema. No installation, no account. Click any feature to view its properties. Download visible data as GeoJSON. 

## Download by area of interest

Install Overture's [Python client](./overturemaps-py) and download building footprints for a specific area:

```bash
pip install overturemaps

overturemaps download \
  --bbox=-71.068,42.353,-71.058,42.363 \
  -f geojson \
  --type=building \
  -o boston_buildings.geojson
```

The tool reads directly from Overture's cloud-hosted GeoParquet and transfers only the data inside your bounding box.

## Query with DuckDB

[DuckDB](./duckdb) lets you query Overture's GeoParquet files with SQL. [Install DuckDB](https://duckdb.org/docs/installation/), then:

<QueryBuilder query={PlacesWawa}></QueryBuilder>

This extracts Wawa convenience stores in the Philadelphia area and saves them as GeoJSON.

## Get the latest release

Overture publishes a [STAC catalog](https://stac.overturemaps.org/catalog.json) that always points to the latest release. Query it with DuckDB instead of hardcoding release paths:

```sql
SET VARIABLE latest = (
    SELECT latest FROM 'https://stac.overturemaps.org/catalog.json'
);
```

Browse all release artifacts in the [STAC viewer](https://stac.overturemaps.org/). The Python client uses the STAC catalog automatically.

## Next steps

- [Access the full Overture catalog](./cloud-sources) — storage paths, PMTiles, STAC, and GERS artifacts
- [Guides](../guides/) — understanding and working with Overture data and schema properties
- [Schema reference](../schema/) — schema modules, column definitions, and data types
- [Examples](../examples/) — QGIS, Athena, Spark, Pandas, and more

---

## Overview

# Addresses Guide 

:::note
This theme is currently in Alpha. We invite the Overture community to test the addresses schema and data and offer feedback via the [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repos.
:::

Overture maintains over 446 million address point entities. Data in the address theme is derived from over 175 sources, many distributed by [OpenAddresses](https://openaddresses.io/) and [AddressForAll](https://www.addressforall.org/en/), but also includes open data from the [City of New York](https://data.cityofnewyork.us/City-Government/NYC-Address-Points/g6pj-hd8k), the [U.S. Department of Transportation](https://www.transportation.gov/gis/national-address-database), and various public agencies.

For licensing information, please see the [Attribution and Licensing page](../../attribution).

Address data can be used for a variety of purposes, which can include:

- **Mapping**: Addresses may be displayed on the map for reference purposes.
- **Geocoding**: Addresses are a primary component of high-accuracy geocoding services (i.e. converting text for an address to a complete address with a location).
- **Conflation**: Addresses can be used to conflate to other data themes (e.g. places, buildings) where appropriate for mapping or other use cases (e.g. refining search).
- **Standardization**: Parsing an input address into address components based on an existing schema or address model.
- **Normalization**: Adhering to standard and consistent forms of address components.
- **Validation and Verification**: Confirming an address exists within a known list of addresses.

| ![Overture address coverage](/img/addresses/address-coverage-h3-apr.png) |
|:--:|
| *April 2026 coverage of Overture address data, visualized using H3 cells.* |

## Dataset description

### Feature type descriptions

An `address` is a feature type that represents a physical place through a series of attributes: street number, street name, unit, address_levels, postalcode and/or country. They also have a `Point` geometry, which provides an approximate location of the position most commonly associated with the feature. We encourage you to consult the [schema reference documentation for the `address` feature type](/schema/reference/addresses/address/).

<details>
	<summary>Address counts, per country</summary>

| country | address count |
| --- | --- |
| AT      | 2,516,341      |
| AU      | 15,652,756     |
| BE      | 6,661,706      |
| BR      | 89,899,299     |
| CA      | 16,818,065     |
| CH      | 3,286,614      |
| CL      | 4,199,023      |
| CO      | 7,786,046      |
| CZ      | 3,014,023      |
| DE      | 19,258,860     |
| DK      | 3,933,282      |
| EE      | 2,230,000      |
| ES      | 15,656,333     |
| FI      | 3,633,089      |
| FO      | 26,244        |
| FR      | 26,056,645     |
| GL      | 20,322        |
| HK      | 175,794       |
| HR      | 1,545,914      |
| IS      | 138,179       |
| IT      | 25,914,431     |
| JP      | 19,568,315     |
| LI      | 12,723        |
| LT      | 1,124,174      |
| LU      | 178,981       |
| LV      | 548,712       |
| MX      | 30,723,333     |
| NL      | 9,889,259      |
| NO      | 3,579,347      |
| NZ      | 2,408,549      |
| PL      | 8,528,581      |
| PT      | 5,614,635      |
| RS      | 2,681,230      |
| SG      | 141,676       |
| SI      | 578,790       |
| SK      | 1,697,528      |
| TW      | 9,630,602      |
| US      | 126,495,881    |
| UY      | 1,059,027      |

</details>

### Data Dictionary

<details>
	<summary>Column definitions for addresses</summary>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry. MUST be a Point as defined by GeoJSON schema. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| country | string | ISO 3166-1 alpha-2 country code of the country or country-like entity, that this address represents or belongs to. |
| postcode | string | The postcode for the address. |
| street | string | The street name associated with this address. The street name can include the street "type" or street suffix, e.g., Main Street. Ideally this is fully spelled out and not abbreviated but we acknowledge that many address datasets abbreviate the street name so it is acceptable. |
| number | string | The house number for this address. This field may not strictly be a number. Values such as "74B", "189 1/2", "208.5" are common as the number part of an address and they are not part of the "unit" of this address. |
| unit | string | The suite/unit/apartment/floor number. |
| address_levels | array | The administrative levels present in an address. The number of values in this list and their meaning is country-dependent. For example, in the United States we expect two values: the state and the municipality. In other countries there might be only one. Other countries could have three or more. The array is ordered with the highest levels first. |
| postal_city | string | In some countries or regions, a mailing address may need to specify a different city name than the city that actually contains the address coordinates. This optional field can be used to specify the alternate city name to use. |
| version | boolean | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | array | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</details>

## Data access and retrieval

Overture's addresses theme data is freely available on both Amazon S3 and Microsoft Azure Blob Storage at these locations:

| provider | location |
| --- | --- |
| Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=addresses/type=address/*" language="text"></QueryBuilder> |
| Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=addresses/type=address/*" language="text"></QueryBuilder> |

Overture distributes its datasets as [GeoParquet](https://geoparquet.org/), a column-oriented spatial data format that is a backwards-compatible extension of [Apache Parquet](https://parquet.apache.org/). Parquet (and GeoParquet) is optimized for "cloud-native" queries, which means you can use many developer-friendly tools to efficiently fetch column "chunks" of cloud-hosted data. We encourage users who are new to GeoParquet to consult [this guide](https://guide.cloudnativegeo.org/geoparquet/).

[The Getting Data section of this documentation](/getting-data/cloud-sources/) offers instructions for using several tools to access Overture data, including DuckDB and Overture's Python command-line tool. See examples below for addresses.

We recommend querying and downloading only the Overture data you need.
If you have a particular geographic area of interest, there are several options for using a simple bounding box to extract address data.

<Tabs>

<TabItem value="DuckDB" label="DuckDB" default>
First, follow the [setup guide for DuckDB](/getting-data/duckdb/).

DuckDB allows you to pass a bounding box in your query to select features in a specified geogrpahic area.

This example returns address data for Calgary, CA and the surrounding area:
<QueryBuilder query={AddressesCalgary}></QueryBuilder>
</TabItem>

<TabItem value="Python Client" label="Python Client" default>
You can find documentation about Overture's official Python Client [here](/getting-data/overturemaps-py/).

This tool helps to download Overture data within a region of interest and converts it to a few different file formats. In this example, a bounding box is passed to obtain all address data around Boston, MA:

```
overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=address -o boston.geojson
```

This command results in the following address points, displayed in QGIS:

![Boston address coverage via bbox](/img/addresses/boston-export.png)

</TabItem>

</Tabs>

## Data manipulation and analysis

Using this query, you can get a count of addresses per country:

<details>
	<summary>Query</summary>
<QueryBuilder query={AddressCounts}></QueryBuilder>

</details>

This query will create a shapefile of address data in New Zealand, with limited attributes:

<details>
	<summary>Query</summary>
<QueryBuilder query={AddressesNZExport}></QueryBuilder>
</details>

This query will create a CSV file of address within the State of Utah, using the `divisions` theme data in a spatial query:

<details>
	<summary>Query</summary>
<QueryBuilder query={UtahAddresses}></QueryBuilder>
</details>

## Get support

Overture is an open project and we welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps).

**Where to go.** Use [GitHub Discussions](https://github.com/orgs/OvertureMaps/discussions) for general questions, workflow help, feature suggestions, or broader conversations about Overture. Use GitHub Issues in the [data repository](https://github.com/OvertureMaps/data) or the [schema repository](https://github.com/OvertureMaps/schema) for specific bug reports: missing entities, geometry problems, duplicate records, or country-specific data concerns.

**What to expect.** We review incoming issues regularly and try to respond within a few business days, but we can't guarantee a resolution timeline. Issues that affect data integrity or block common workflows get higher priority.

**Filing a good issue.** The more detail you include, the faster we can help. When reporting a data problem, please include: the Overture release version you're using, a query or code snippet that reproduces the issue, specific entity IDs or bounding boxes where you see the problem, and any relevant screenshots or map views. If you can share a minimal reproducible example, that goes a long way.

---

## Overview(Base)

# Base Guide 

The Overture Maps base theme provides the land, water, infrastructure, and bathymetry features that are necessary to render a complete basemap. The majority of these features come from OpenStreetMap. We classify OSM features into *type*, *subtype*, and *class* based on their tags. The land and ocean polygons are derived from the [Daylight Coastlines](https://daylightmap.org/coastlines.html). The theme includes six feature types:

- **`bathymetry`**: derived vectorized bathymetric data products from [ETOPO1](https://www.ncei.noaa.gov/products/etopo-global-relief-model) and [GLOBathy](https://www.nature.com/articles/s41597-022-01132-9) data.
- **`infrastructure`**: Infrastructure features such as communication towers and lines, piers, and bridges from OpenStreetMap.
- **`land`**: physical representations of land surfaces derived from the inverse of OSM Coastlines; translates natural tags from OpenStreetMap.
- **`land_cover`**: derived from [ESA WorldCover](https://esa-worldcover.org/en), high-resolution optical Earth observation data.
- **`land_use`**: classifications of the human use of a section of land; translates landuse tag from OpenStreetMap.
- **`water`**: physical representations of inland and ocean marine surfaces; translates natural and waterway tags from OpenStreetMap.

## Data dictionary

<details>
	<summary>Column definitions in the base theme</summary>

<Tabs>
<TabItem value="bathymetry" label="bathymetry" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID that may be associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry - a Polygon or MultiPolygon. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature. Each source object lists the property in JSON Pointer notation and the dataset from which that specific value originated. |
| depth | integer | Depth below surface level (in meters) of the feature. |
| cartography | struct | Defines cartographic hints for optimal use of Overture features in map-making. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="infrastructure" label="infrastructure" default>

| column | type | description |
| --- | --- | --- |
| id | varchar | A feature ID that may be associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry - a Point, Polygon, MultiPolygon, or LineString. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature. Each source object lists the property in JSON Pointer notation and the dataset from which that specific value originated. |
| subtype | varchar | A broad category of the building type and purpose. |
| names | struct | The name associated with the feature. The first entry in the array of names must have a "local" language. |
| class | varchar | Further delineation of the building's built purpose. |
| level | integer | The building feature's Z-order, i.e., stacking order. A Z-order of 0 is ground level. |
| height | double | Height of the feature in meters. |
| surface | varchar | Surface material, mostly from the OSM tag, with some normalization. |
| source_tags | struct | Any attributes/tags from the original source data that should be passed through. |
| wikidata | varchar | The Wikidata ID for the feature. |
| filename | varchar | Name of the file being queried. |
| theme | varchar | Name of the Overture theme being queried. |
| type | varchar | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="land" label="land" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID that may be associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry - a Point, Polygon, MultiPolygon, or LineString. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature. Each source object lists the property in JSON Pointer notation and the dataset from which that specific value originated. |
| level | integer | The building feature's Z-order, i.e., stacking order. A Z-order of 0 is ground level. |
| subtype | string | A broad category of the building type and purpose. |
| class | string | Further delineation of the building's built purpose. |
| surface | string | Surface material, mostly from the OSM tag, with some normalization. |
| names | struct | The name associated with the feature. The first entry in the array of names must have a "local" language. |
| source_tags | struct | Any attributes/tags from the original source data that should be passed through. |
| wikidata | string | The Wikidata ID for the feature. |
| elevation | integer | Elevation above sea level (in meters) of the feature. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="land_cover" label="land_cover" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID that may be associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry - a Polygon or MultiPolygon. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature. Each source object lists the property in JSON Pointer notation and the dataset from which that specific value originated. |
| cartography | struct | Defines cartographic hints for optimal use of Overture features in map-making. |
| subtype | string | A broad category of the building type and purpose. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="land_use" label="land_use" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID that may be associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry - a Point, Polygon, MultiPolygon, or LineString. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature. Each source object lists the property in JSON Pointer notation and the dataset from which that specific value originated. |
| level | integer | The building feature's Z-order, i.e., stacking order. A Z-order of 0 is ground level. |
| subtype | string | A broad category of the building type and purpose. |
| class | string | Further delineation of the building's built purpose. |
| surface | string | Surface material, mostly from the OSM tag, with some normalization. |
| names | struct | The name associated with the feature. The first entry in the array of names must have a "local" language. |
| source_tags | struct | Any attributes/tags from the original source data that should be passed through. |
| wikidata | string | The Wikidata ID for the feature. |
| elevation | integer | Elevation above sea level (in meters) of the feature. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="water" label="water" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID that may be associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry - a Point, Polygon, MultiPolygon, or LineString. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature. Each source object lists the property in JSON Pointer notation and the dataset from which that specific value originated. |
| level | integer | The building feature's Z-order, i.e., stacking order. A Z-order of 0 is ground level. |
| subtype | string | A broad category of the building type and purpose. |
| class | string | Further delineation of the building's built purpose. |
| names | struct | The name associated with the feature. The first entry in the array of names must have a "local" language. |
| source_tags | struct | Any attributes/tags from the original source data that should be passed through. |
| wikidata | string | The Wikidata ID for the feature. |
| is_salt | boolean | Indicates the presence of salt water. |
| is_intermittent | boolean | Indicates whether or not the water is intermittent. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
</Tabs>

</details>

## Data access and retrieval

Overture's base theme data is freely available on both Amazon S3 and Microsoft Azure Blob Storage at these locations:

<Tabs>
  <TabItem value="bathymetry" label="Bathymetry">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=base/type=bathymetry/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=base/type=bathymetry/*" language="text"></QueryBuilder> |
  </TabItem>
  <TabItem value="infrastructure" label="Infrastructure">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=base/type=infrastructure/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=base/type=infrastructure/*" language="text"></QueryBuilder> |
  </TabItem>
  <TabItem value="land" label="Land">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=base/type=land/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=base/type=land/*" language="text"></QueryBuilder> |
  </TabItem>
  <TabItem value="land_cover" label="Land Cover">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=base/type=land_cover/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=base/type=land_cover/*" language="text"></QueryBuilder> |
  </TabItem>
  <TabItem value="land_use" label="Land Use">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=base/type=land_use/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=base/type=land_use/*" language="text"></QueryBuilder> |
  </TabItem>
  <TabItem value="water" label="Water">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=base/type=water/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=base/type=water/*" language="text"></QueryBuilder> |
  </TabItem>
</Tabs>

Overture distributes its datasets as [GeoParquet](https://geoparquet.org/), a column-oriented spatial data format that is a backwards-compatible extension of [Apache Parquet](https://parquet.apache.org/). Parquet (and GeoParquet) is optimized for "cloud-native" queries, which means you can use many developer-friendly tools to efficiently fetch column "chunks" of cloud-hosted data. We encourage users who are new to GeoParquet to consult [this guide](https://guide.cloudnativegeo.org/geoparquet/).

[The Getting Data section of this documentation](/getting-data/cloud-sources/) offers instructions for accessing the full Overture catalog.

We recommend querying and downloading only the Overture data you need.
If you have a particular geographic area of interest, there are several options for using a simple bounding box to extract address data.

## Schema design choices

- basic classification of features into `type`, `subtype` and `class` where appropriate.
- parsing and normalization of common OSM tags, such as `height` and `ele`.
- extraction of consistent OSM tags, such as `wikidata` to top-level properties.
- direct pass-through of remaining relevant OSM tags.

## Schema reference

- [Explore the schema for the bathymetry feature type](/schema/reference/base/bathymetry/).
- [Explore the schema for the infrastructure feature type](/schema/reference/base/infrastructure/).
- [Explore the schema for the land feature type](/schema/reference/base/land/).
- [Explore the schema for the land cover feature type](/schema/reference/base/land_cover/).
- [Explore the schema for the land use feature type](/schema/reference/base/land_use/).
- [Explore the schema for the water feature type](/schema/reference/base/water/).

## Get support

Overture is an open project and we welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps).

**Where to go.** Use [GitHub Discussions](https://github.com/orgs/OvertureMaps/discussions) for general questions, workflow help, feature suggestions, or broader conversations about Overture. Use GitHub Issues in the [data repository](https://github.com/OvertureMaps/data) or the [schema repository](https://github.com/OvertureMaps/schema) for specific bug reports: missing entities, geometry problems, duplicate records, or country-specific data concerns.

**What to expect.** We review incoming issues regularly and try to respond within a few business days, but we can't guarantee a resolution timeline. Issues that affect data integrity or block common workflows get higher priority.

**Filing a good issue.** The more detail you include, the faster we can help. When reporting a data problem, please include: the Overture release version you're using, a query or code snippet that reproduces the issue, specific entity IDs or bounding boxes where you see the problem, and any relevant screenshots or map views. If you can share a minimal reproducible example, that goes a long way.

---

## Overview(Buildings)

# Buildings Guide

The Overture Maps buildings theme describes human-made structures with roofs or interior spaces that are permanently or semi-permanently in one place (source: [OSM building definition](https://wiki.openstreetmap.org/wiki/Key:building)). Overture's goal is to provide the world's most comprehensive set of building structures compiled from the best available open data sources, covering all the world's buildings. The theme includes two feature types:

- **`building`**: The most basic form of a building feature. The geometry is expected to be the most outer footprint&mdash;roofprint if traced from satellite/aerial imagery&mdash;of a building. Buildings have a boolean attribute `has_parts` that describe whether there are any associated building parts.
- **`building_part`**: A single part of a building. Building parts may share the same properties as buildings. A building part is associated with a parent building via a `building_id`.

### Data access and retrieval

Overture's `building` and `building_part` datasets are freely available on both Amazon S3 and Microsoft Azure Blob Storage at the locations listed below. We provide [a comprehensive guide](/getting-data/cloud-sources/) to accessing the entire Overture catalog in our documentation.

<Tabs>
  <TabItem value="building" label="building" default>
    | Provider | Location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=buildings/type=building/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=buildings/type=building/*" language="text"></QueryBuilder> |
  </TabItem>
  <TabItem value="building_part" label="building_part">
    | Provider | Location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=buildings/type=building_part/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=buildings/type=building_part/*" language="text"></QueryBuilder> |
  </TabItem>
</Tabs>

### Use cases

Our buildings data is intended to support multiple use cases, as defined and prioritized by various Overture members, but may be used for other use cases as imagined by Overture data users assuming they comply with the open data license.

- **2D Visualization**: Display of the buildings in a 2D map display, perhaps symbolized by other properties.
- **3D Visualization**: Display of the buildings (and parts) in a 3D (or 2.5D) display, extruded by building height or levels.
- **Data Enrichment**: Enable end users to enrich the buildings with additional attributes using GERS ID.
- **Spatial Analysis**: Enable end users to perform analysis to create derivative datasets or train AI models.

## Data dictionary

Overture releases its data as GeoParquet files. The `building` and `building_part` datasets have slightly different schemas, and the column definitions for those data files are described below. For more detailed information about the buildings schema see Overture [schema reference documentation](/schema/). 

<details>
	<summary>Column definitions for the `building` and `building_part` datasets</summary>

<Tabs>
<TabItem value="building" label="building" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID that may be associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A building's geometry is defined as its footprint or roofprint (if traced from aerial/satellite imagery). It MUST be a Polygon or MultiPolygon as defined by the GeoJSON schema. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature. Each source object lists the property in JSON Pointer notation and the dataset from which that specific value originated. |
| subtype | string | A broad category of the building type and purpose. |
| names | struct | The name associated with the feature. The first entry in the array of names must have a "local" language. |
| class | string | Further delineation of the building's built purpose. |
| level | integer | The building feature's Z-order, i.e., stacking order. A Z-order of 0 is ground level. |
| has_parts | boolean | Flag indicating whether the building has parts. |
| is_underground | boolean | Whether the entire building or part is completely below ground. This is useful for rendering which typically omits these buildings or styles them differently because they are not visible above ground. This is different than the level column which is used to indicate z-ordering of elements and negative values may be above ground. |
| height | double | Height of the building or part in meters. The height is the distance from the lowest point to the highest point. |
| num_floors | integer | Number of above-ground floors of the building or part. |
| num_floors_underground | integer | Number of below-ground floors of the building or part. |
| min_height | double | The height of the bottom part of building in meters. Used if a building or part of building starts above the ground level. |
| min_floor | integer | The "start" floor of a building or building part. Indicates that the building or part is "floating" and its bottom-most floor is above ground level, usually because it is part of a larger building in which some parts do reach ground level. |
| facade_color | string | The color (name or color triplet) of the facade of a building or building part in hexadecimal. |
| facade_material | string | The outer surface material of building facade. |
| roof_material | string | The outermost material of the roof. |
| roof_shape | string | The shape of the roof. |
| roof_direction | double | Bearing of the roof ridge line. |
| roof_orientation | string | Orientation of the roof shape relative to the footprint shape. Either "along" or "across." |
| roof_color | string | The color (name or color triplet) of the roof of a building or building part in hexadecimal. |
| roof_height | double | The height of the building roof in meters. This represents the distance from the base of the roof to the highest point of the roof. |
| filename | string | Name of the file being queried. |
| theme | varchar | Name of the Overture theme being queried. |
| type | varchar | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="building_part" label="building_part" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID that may be associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | The geometry of a single building part. It MUST be a Polygon or MultiPolygon as defined by the GeoJSON schema. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature. Each source object lists the property in JSON Pointer notation and the dataset from which that specific value originated. |
| names | struct | The name associated with the feature. The first entry in the array of names must have a "local" language. |
| level | integer | The building feature's Z-order, i.e., stacking order. A Z-order of 0 is ground level. |
| is_underground | boolean | Whether the entire building or part is completely below ground. This is useful for rendering which typically omits these buildings or styles them differently because they are not visible above ground. This is different than the level column which is used to indicate z-ordering of elements and negative values may be above ground. |
| height | double | Height of the building or part in meters. The height is the distance from the lowest point to the highest point. |
| num_floors | integer | Number of above-ground floors of the building or part. |
| num_floors_underground | integer | Number of below-ground floors of the building or part. |
| min_height | double | The height of the bottom part of building in meters. Used if a building or part of building starts above the ground level. |
| min_floor | integer | The "start" floor of a building or building part. Indicates that the building or part is "floating" and its bottom-most floor is above ground level, usually because it is part of a larger building in which some parts do reach ground level. |
| facade_color | string | The color (name or color triplet) of the facade of a building or building part in hexadecimal. |
| facade_material | string | The outer surface material of building facade. |
| roof_material | string | The outermost material of the roof. |
| roof_shape | string | The shape of the roof. |
| roof_direction | double | Bearing of the roof ridge line. |
| roof_orientation | string | Orientation of the roof shape relative to the footprint shape. Either "along" or "across." |
| roof_color | string | The color (name or color triplet) of the roof of a building or building part in hexadecimal. |
| roof_height | double | The height of the building roof in meters. This represents the distance from the base of the roof to the highest point of the roof. |
| building_id | string | The building ID to which this part belongs. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
</Tabs>

</details>

## How we build the dataset

### Sources

Currently, the Overture `building` dataset is a combination of the following open building datasets. (The `building_part` dataset comes from one source: OpenStreetMap.)

| Source | Type | Conflation Priority | Count |
|--------|------|-------------------|--------|
| [OpenStreetMap](//osm.org) | Community-contributed | 1 | ~680 Million |
| [Esri Community Maps](https://communitymaps.arcgis.com/home) | Community-contributed | 2 | ~17 Million |
| [Instituto Geográfico Nacional (España)](https://www.ign.es/) | National dataset | 3 | ~12.6 Million |
| [City of Vancouver, Canada](https://opendata.vancouver.ca/) | Municipal dataset | 4 | ~17 Thousand |
| [Google Open Buildings](https://sites.research.google/open-buildings/) | ML-derived roofprints (>90% precision) | 5 | ~340 Million |
| [Microsoft](https://github.com/microsoft/GlobalMLBuildingFootprints) | ML-derived roofprints | 6 | ~708 Million |
| [Google Open Buildings](https://sites.research.google/open-buildings/) | ML-derived roofprints (\<90  % precision) | 7 | ~640 Million |
| [Buildings in East Asian Countries](https://zenodo.org/records/8174931) | ML-derived roofprints | 8 | ~213 Million |

### Quality and prioritization

To help ensure quality as well as quantity, the conflation process for the `building` dataset prioritizes community contributed data over machine learning (ML) generated data. The highest priority dataset used in conflation is OpenStreetMap. This ensures that any data added to OpenStreetMap based on local knowledge or manual editing of ML data is prioritized with each update of Overture Maps buildings. If there is a quality issue in one of the Overture Maps buildings, it can be addressed by adding, updating, or deleting that same building structure in OpenStreetMap and it will be reflected in the next Overture Maps release.

Many Overture Maps buildings are derived from ML sources (e.g. Microsoft and Google Open Buildings). These ML datasets are known to include some detections that do not qualify as building structures as defined above. These might be shipping containers, car ports, solar panels, or other objects that resemble buildings in satellite or aerial imagery. To remove most of these invalid features from the buildings theme, the Overture Maps conflation process excludes ML features below a certain size that are unlikely to be valid buildings. These exclusion rules might result in some valid features being missed but, on balance, improve the quality of the buildings theme. Missing features can be added through OpenStreetMap editing (e.g. Rapid editor accessing ML features).

### Conflation and matching

As part of the conflation process, features in the open data sources are matched and assigned a GERS ID. The intent is to have a single, stable GERS ID for each building feature. If there are multiple sources for an individual building feature (e.g. the Lincoln Memorial), then that building feature in each data source should be assigned the same GERS ID, whether that feature is included in the Overture buildings theme that is released or not. 

The matching step in the conflation process is based on the geometry of the building features, using a metric called Intersection over Union (IoU). Buildings are considered a match if the IoU score exceeds 50%. The score is calculated by dividing the area where the two building shapes overlap by the total area they cover combined. On this scale, a 100% score signifies a perfect overlap, whereas disconnected (non-overlapping) geometries score 0%.

The visualization below shows Overture buildings data looking across the US-Mexico border toward San Diego. Notice how Esri and OSM buildings appear in big blocks while the Google and Microsoft buildings appear to mix together. This is a product of our conflation process that prioritizes community contributed data first and then "fills in" the rest of the map with the best ML data available.

<figure>
  <BuildingsMap></BuildingsMap>
  <figcaption>
  
    
    &#x25AC;   OpenStreetMap | 
    &#x25AC;   Esri Community Maps | 
    &#x25AC; Microsoft ML Buildings | 
    &#x25AC; Google Open Buildings 
    
  
  </figcaption>
</figure>
*© OpenStreetMap contributors, OvertureMaps Foundation*

## Licensing

The Overture Maps buildings theme is provided under the ODbL license, largely because the primary OpenStreetMap data is provided under that license. This requires that other data sources that are included in the buildings theme are also provided under ODbL or a license that is compatible with ODbL, such as CC BY 4.0. Overture Maps determine if potential sources of open data that would expand coverage or improve quality are provided under a license that is compatible with ODbL before adding to the conflation process. For more information, see the [licensing and attribution](../../attribution) section of our documentation.

## Get support

Overture is an open project and we welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps).

**Where to go.** Use [GitHub Discussions](https://github.com/orgs/OvertureMaps/discussions) for general questions, workflow help, feature suggestions, or broader conversations about Overture. Use GitHub Issues in the [data repository](https://github.com/OvertureMaps/data) or the [schema repository](https://github.com/OvertureMaps/schema) for specific bug reports: missing entities, geometry problems, duplicate records, or country-specific data concerns.

**What to expect.** We review incoming issues regularly and try to respond within a few business days, but we can't guarantee a resolution timeline. Issues that affect data integrity or block common workflows get higher priority.

**Filing a good issue.** The more detail you include, the faster we can help. When reporting a data problem, please include: the Overture release version you're using, a query or code snippet that reproduces the issue, specific entity IDs or bounding boxes where you see the problem, and any relevant screenshots or map views. If you can share a minimal reproducible example, that goes a long way.

---

## Overview(Divisions)

# Divisions Guide

The Overture divisions theme has three feature types: `division`, `division_area`, and `division_boundary`.

There are more than 5.5 million point, line, and polygon representations of human settlements, such as countries, regions, states, cities, and even neighborhoods. The theme is derived from a conflation of [OpenStreetMap](https://www.openstreetmap.org/) data and [geoBoundaries](https://www.geoboundaries.org/) data and is available under an [ODbL](https://opendatacommons.org/licenses/odbl/) license. (See the [attribution page](../../attribution) for more information.)

Divisions data can be used for many purposes, which can include, but are not limited to:
- reverse-geocoding
- cartographic styling and map rendering
- place labels
- choropleth rendering
- containment checks (e.g. point-in-polygon analysis)
- choosing a geometry based on your use case

| ![Overture divisions coverage - country and region boundaries](/img/divisions/divisions-admin0-admin1-coverage.png) |
|:--:|
| *Overture divisions data, styled by subtype: countries in purple, region boundaries as green lines.* |

## Dataset description

### Feature type descriptions

A `division` is a feature type that represents an official or non-official organization of people: country, region, province, city, neighborhood, etc. &mdash; as seen from a given political perspective. It has a `Point` geometry which gives an approximate location of the position most commonly associated with the feature. We encourage you to consult the [schema reference documentation for the `division` feature type](/schema/reference/divisions/division/).

A `division_area` is a feature type that captures the shape of the land area, or land and territorial sea (maritime), belonging to a `division` feature. It has a `Polygon` or `MultiPolygon` geometry. We encourage you to consult the [schema reference documentation for the `division_area` feature type](/schema/reference/divisions/division_area/).

A `division_boundary` is a feature type that represents a shared border between two `division` features. It has a `LineString` geometry. The geometry of a `divison_boundary` is either wholly non-maritime, or wholly maritime. A maritime boundary is the extension of a non-maritime boundary into the water. Please consult the [schema reference documentation for the `division_boundary` feature type](/schema/reference/divisions/division_boundary/).

### Subtype descriptions

Subtypes can represent each feature's administrative level, from `country` down to `microhood`. Subtypes can also represent a place hierarchy within a country and offer a standardized place definition for divisions. See below for a list of subtypes and their descriptions in the divisions theme:

<details>
	<summary>List of all subtypes in the divisions theme</summary>

| subtype | description | example |
| --- | --- | --- |
| **country** | Largest unit of independent sovereignty. | United States |
| **dependency** | A place that is not exactly a sub-region of a country but is dependent on a parent company for defence, passport control, subsidies, etc. | Puerto Rico |
| **macroregion** | A bundle of regions. These exist mainly in Europe. | Scotland; Île-de-France |
| **region** | States, provinces, regions. Largest sub-country administrative unit most countries, unless they have dependencies/macroregions. | Alaska; Alberta |
| **macrocounty** | A bundle of counties. Again, these exist mainly in Europe. | Inverness |
| **county** | Counties... Largest sub-region administrative unit in most countries, unless they have macrocounties. | Kings County, NY |
| **localadmin** | A level of government available in some parts of the world that contains localities or populated places that themselves have no authority. Often but not exclusively found in Europe. | Paris |
| **locality** | A populated place that may or may not have its own administrative authority. (It won't if it belongs to a localadmin.) | Taipei |
| **borough** | A local government unit, below the locality placetype. | Brooklyn, Queens, etc. |
| **macrohood** | A super-neighborhood that contains smaller divisions of type neighborhood. | BoCoCa (Boerum Hill, Cobble Hill, and Carroll Gardens) |
| **neighborhood** | A neighborhood. Most neighborhoods will be just this, unless there's enough granular division to warrant introducing macrohood and/or microhood divisions. | Cobble Hill |
| **microhood** | A mini-neighborhood that is contained within a division of type neighborhood. | Gätjensort in Hamburg |

</details>

## Data dictionary

<details>
    <summary>Column definitions in the divisions theme</summary>

<Tabs>
<TabItem value="division" label="division" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry. MUST be a Point as defined by GeoJSON schema. |
| bbox | struct | The bounding box of an entity's geometry, represented with float values, in a `xmin, xmax, ymin, ymax` format. |
| country | string | ISO 3166-1 alpha-2 country code of the country or country-like entity, that this division represents or belongs to. If the entity this division represents has a country code, the country property contains it. If it does not, the country property contains the country code of the first division encountered by traversing the parent_division_id chain to the root. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
| cartography | struct | Contains a prominence property, which offers a suggestion for displaying Overture features at specific zoom levels based on it's importance and significance. |
| subtype | string | Category of the division from a finite, hierarchical, ordered list of categories (e.g. country, region, locality, etc.) similar to a Who's on First placetype. |
| class | string | A value to represent whether an entity represents a `maritime` or `land` feature. |
| names | struct | A primary name of the entity, and a set of optional name translations. Name translations are represented in key, value pairs, where the key is an ISO language code and the value is the translated name. |
| wikidata | string | A wikidata ID if available, as found on https://www.wikidata.org/. |
| region | string | ISO 3166-2 principal subdivision code of the subdivision-like entity this division represents or belongs to. If the entity this division represents has a principal subdivision code, the region property contains it. If it does not, the region property contains the principal subdivision code of the first division encountered by traversing the parent_division_id chain to the root. |
| perspectives | struct | Political perspectives from which this division boundary is considered to be an accurate representation. If this property is absent, then this boundary is not known to be disputed from any political perspective. Consequently, there is only one boundary feature representing the entire real world entity. If this property is present, it means the boundary represents one of several alternative perspectives on the same real-world entity. |
| local_type | string | Local name for the subtype property, optionally localized. This property is localized using a standard Overture names structure. |
| hierarchies | struct | Hierarchies in which this division participates. |
| parent_division_id | string | Division ID of this division's parent division. Not allowed for top-level divisions (countries) and required for all other divisions. The default parent division is the parent division as seen from the default political perspective, if there is one, and is otherwise chosen somewhat arbitrarily. The hierarchies property can be used to inspect the exhaustive list of parent divisions. |
| norms | array | Collects information about local norms and rules within the division that are generally useful for mapping and map-related use cases. If the norms property or a desired sub-property of the norms property is missing on a division, but at least one of its ancestor divisions has the norms property and the desired sub-property, then the value from the nearest ancestor division may be assumed. |
| population | integer | Population of the division. |
| capital_division_ids | struct | Division IDs of this division's capital divisions. If present, this property will refer to the division IDs of the capital cities, county seats, etc. of a division. |
| capital_of_divisions | array | Division ID of the division that this feature is the capital of. If present, this property will refer to the division IDs of a parent county, region, country, etc. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="division_area" label="division_area" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry. MUST be a Polygon or MultiPolygon as defined by GeoJSON schema. |
| bbox | struct | The bounding box of an entity's geometry, represented with float values, in a `xmin, xmax, ymin, ymax` format. |
| country | string | ISO 3166-1 alpha-2 country code of the country or country-like entity, that this division represents or belongs to. If the entity this division represents has a country code, the country property contains it. If it does not, the country property contains the country code of the first division encountered by traversing the parent_division_id chain to the root. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
| subtype | string | Category of the division from a finite, hierarchical, ordered list of categories (e.g. country, region, locality, etc.) similar to a Who's on First placetype. |
| class | string | A value to represent whether an entity represents a `maritime` or `land` feature. |
| names | struct | A primary name of the entity, and a set of optional name translations. Name translations are represented in key, value pairs, where the key is an ISO language code and the value is the translated name. |
| is_land | boolean | Indicates whether or not the feature geometry represents the non-maritime "land" boundary, which can be used for map rendering, cartographic display, and similar purposes. |
| is_territorial | boolean | Indicates whether or not the feature geometry represents the full territorial boundary or claim of a feature. |
| region | string | ISO 3166-2 principal subdivision code of the subdivision-like entity this division represents or belongs to. If the entity this division represents has a principal subdivision code, the region property contains it. If it does not, the region property contains the principal subdivision code of the first division encountered by traversing the parent_division_id chain to the root. |
| division_id | string | Division ID of the division this area belongs to. |
| filename | string | Name of the S3 file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="division_boundary" label="division_boundary" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | A WKB representation of the entity's geometry. MUST be a LineString or MultiLineString as defined by GeoJSON schema. |
| bbox | struct | The bounding box of an entity's geometry, represented with float values, in a `xmin, xmax, ymin, ymax` format. |
| country | string | ISO 3166-1 alpha-2 country code of the country or country-like entity, that this division represents or belongs to. If the entity this division represents has a country code, the country property contains it. If it does not, the country property contains the country code of the first division encountered by traversing the parent_division_id chain to the root. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
| subtype | string | Category of the division from a finite, hierarchical, ordered list of categories (e.g. country, region, locality, etc.) similar to a Who's on First placetype. |
| class | string | A value to represent whether an entity represents a `maritime` or `land` feature. |
| is_land | boolean | Indicates whether or not the feature geometry represents the non-maritime "land" boundary, which can be used for map rendering, cartographic display, and similar purposes. |
| is_territorial | boolean | Indicates whether or not the feature geometry represents the full territorial boundary or claim of a feature. |
| division_ids | array | A list of the two division IDs that share this division boundary. |
| region | string | ISO 3166-2 principal subdivision code of the subdivision-like entity this division represents or belongs to. If the entity this division represents has a principal subdivision code, the region property contains it. If it does not, the region property contains the principal subdivision code of the first division encountered by traversing the parent_division_id chain to the root. |
| is_disputed | boolean | Indicator if there are entities disputing this division boundary. Information about entities disputing this boundary should be included in perspectives property. This property should also be true if boundary between two entities is unclear and this is "best guess". So having it true and no perspectives gives map creators reason not to fully trust the boundary, but use it if they have no other. |
| perspectives | struct | Political perspectives from which this division boundary is considered to be an accurate representation. If this property is absent, then this boundary is not known to be disputed from any political perspective. Consequently, there is only one boundary feature representing the entire real world entity. If this property is present, it means the boundary represents one of several alternative perspectives on the same real-world entity. |
| filename | string | Name of the S3 file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
</Tabs>

</details>

## Data access and retrieval

Overture's divisions theme data is freely available on both Amazon S3 and Microsoft Azure Blob Storage at these locations:

<Tabs>
  <TabItem value="division" label="division">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=divisions/type=division/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=divisions/type=division/*" language="text"></QueryBuilder> |
  </TabItem>
  <TabItem value="division_area" label="division_area">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=divisions/type=division_area/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=divisions/type=division_area/*" language="text"></QueryBuilder> |
  </TabItem>
  <TabItem value="division_boundary" label="division_boundary">
    | provider | location |
    | --- | --- |
    | Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=divisions/type=division_boundary/*" language="text"></QueryBuilder> |
    | Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=divisions/type=division_boundary/*" language="text"></QueryBuilder> |
  </TabItem>
</Tabs>
Overture distributes its datasets as [GeoParquet](https://geoparquet.org/), a column-oriented spatial data format that is a backwards-compatible extension of [Apache Parquet](https://parquet.apache.org/). Parquet (and GeoParquet) is optimized for "cloud-native" queries, which means you can use many developer-friendly tools to efficiently fetch column "chunks" of cloud-hosted data. We encourage users who are new to GeoParquet to consult [this guide](https://guide.cloudnativegeo.org/geoparquet/).

[The Getting Data section of this documentation](/getting-data/cloud-sources/) offers instructions accessing the full Overture catalog. See examples below for divisions.

<Tabs>

<TabItem value="Python Client" label="Python Client" default>
You can find Overture's official Python command-line tool [here](https://github.com/OvertureMaps/overturemaps-py).

This tool helps to download Overture data within a region of interest and converts it to a few different file formats. In this example, a bounding box is passed to obtain all divisions data around Boston, MA:

```
overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=division -o boston.geojson
```

</TabItem>

<TabItem value="DuckDB" label="DuckDB" default>
First, follow the [setup guide for DuckDB](../../getting-data/duckdb).
<QueryBuilder query={ToParquet}></QueryBuilder>
Note: Running this query will result in a ~6.4GB file.
</TabItem>

</Tabs>

## Data usage guidelines

We recommend querying and downloading only the Overture data you need.
If you have a particular geographic area of interest, there are several options for using a simple bounding box to extract divisions data.

<Tabs>

<TabItem value="Overture Maps Explorer" label="Overture Maps Explorer" default>
To quickly view and download modest amounts of data, you can use the [Overture Maps Explorer website](https://explore.overturemaps.org/#15.07/41.89731/12.47626).

To download data: Pan to the area you are interested in, turn off the other layers, then click `Download Visible`.

This will download the area visible on your screen.

<figure>
  <video autoPlay loop muted playsInline style={{ width: '100%' }}>
    <source src={useBaseUrl('/img/divisions/divisions-us.mp4')} type="video/mp4" />
  </video>
  <figcaption style={{ textAlign: 'center' }}>
    Exploring divisions data in NYC using Overture's Explore tool.
  </figcaption>
</figure>
</TabItem>

<TabItem value="Python Client" label="Python Client" default>
First, follow the [setup guide for the Python Client](../../getting-data/overturemaps-py).

You can alter the `bbox` value to download a particular area.

```
overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=division -o boston.geojson
```
</TabItem>

<TabItem value="DuckDB" label="DuckDB" default>
First, follow the [setup guide for DuckDB](../../getting-data/duckdb).

DuckDB allows you to pass a bounding box in your query to select features in a specified geogrpahic area.

This example returns results for the country boundary between the US and Mexico:
<QueryBuilder query={BorderUSMX}></QueryBuilder>
</TabItem>

</Tabs>

## Data manipulation and analysis

Using these queries, you can get counts for each feature type in divisions.

<Tabs>

<TabItem value="total counts" label="total counts" default>
<QueryBuilder query={CountsPerType}></QueryBuilder>
</TabItem>

<TabItem value="division counts" label="division counts" default>
<QueryBuilder query={DivCounts}></QueryBuilder>
</TabItem>

<TabItem value="division_area counts" label="division_area counts" default>
<QueryBuilder query={DivAreaCounts}></QueryBuilder>
</TabItem>

<TabItem value="division_boundary counts" label="division_boundary counts" default>
<QueryBuilder query={BoundaryCounts}></QueryBuilder>
</TabItem>

</Tabs>

<Tabs>

<TabItem value="query using an Overture ID" label="query using an Overture ID" default>
<QueryBuilder query={SpecificFeature}></QueryBuilder>
</TabItem>

<TabItem value="query using an OSM ID" label="query using an OSM ID" default>
<QueryBuilder query={OSMLookUp}></QueryBuilder>
</TabItem>

</Tabs>

#### Exporting locality and neighborhood divisions to a local shapefile

This query will return a subset of fields and the geometry for each locality and neighborhood division entity in Denmark.

<details>
	<summary>Query</summary>
<QueryBuilder query={DenmarkLocalityNeighborhood}></QueryBuilder>
</details>

#### Exporting places data within Philadelphia to a local Parquet file

This query will return Places theme data for any place within the locality of Philadelphia

<details>
	<summary>Query</summary>
<QueryBuilder query={PhillyPlaces}></QueryBuilder>
</details>

## Get support

Overture is an open project and we welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps).

**Where to go.** Use [GitHub Discussions](https://github.com/orgs/OvertureMaps/discussions) for general questions, workflow help, feature suggestions, or broader conversations about Overture. Use GitHub Issues in the [data repository](https://github.com/OvertureMaps/data) or the [schema repository](https://github.com/OvertureMaps/schema) for specific bug reports: missing entities, geometry problems, duplicate records, or country-specific data concerns.

**What to expect.** We review incoming issues regularly and try to respond within a few business days, but we can't guarantee a resolution timeline. Issues that affect data integrity or block common workflows get higher priority.

**Filing a good issue.** The more detail you include, the faster we can help. When reporting a data problem, please include: the Overture release version you're using, a query or code snippet that reproduces the issue, specific entity IDs or bounding boxes where you see the problem, and any relevant screenshots or map views. If you can share a minimal reproducible example, that goes a long way.

---

## Guides


**View Theme Definitions Table →**

- **[Addresses](./addresses)**
- **[Base](./base)**
- **[Buildings](./buildings)**
- **[Divisions](./divisions)**
- **[Places](./places)**
- **[Transportation](./transportation)**

---

## Overview(Places)

# Places Guide 

The Overture places theme has one feature type, called `place`, and contains more than 64 million point representations of real-world entities: schools, businesses, hospitals, religious organizations, landmarks, mountain peaks, and much more.

| ![Overture places theme coverage](/img/places/places-coverage-h3-apr.png) |
|:--:|
| *Overture places data, April 2026* |

| Sources | License | feature count, April 2026 |
| --- | --- | --- |
| AllThePlaces, Overture | CC0-1.0              | 1,749,242    |
| Foursquare, Overture   | Apache-2.0           | 6,749,057    |
| DAC, Overture          | CDLA-Permissive-2.0  | 166,108      |
| Krick, Overture        | CDLA-Permissive-2.0  | 2,791        |
| Microsoft, Overture    | CDLA-Permissive-2.0  | 7,261,643    |
| PinMeTo, Overture      | CDLA-Permissive-2.0  | 147,902      |
| RenderSEO, Overture    | CDLA-Permissive-2.0  | 5,740        |
| meta, Overture         | CDLA-Permissive-2.0  | 59,413,511   |

## Data dictionary

All Overture data, including places data, is distributed as GeoParquet, a column-based data structure. Below you'll find a table with column-by-column descriptions of the properties in the place feature type. 

<details>
    <summary>Column definitions for the Places theme</summary>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | The point representation of the Place's location. Place's geometry which MUST be a Point as defined by GeoJSON schema. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
| names | struct | Properties defining the names of a feature. |
| categories | struct | The categories of the place. Complete list is available on GitHub: https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/overture_categories.csv |
| basic_category | string | A simplified category taxonomy |
| confidence | double | The confidence of the existence of the place. It's a number between 0 and 1. 0 means that we're sure that the place doesn't exist (anymore). 1 means that we're sure that the place exists. If there's no value for the confidence, it means that we don't have any confidence information. |
| websites | string | The websites of the place. |
| socials | string | The social media URLs of the place. |
| emails | string | The email addresses of the place. |
| phones | string | The phone numbers of the place. |
| brand | struct | The brand of the place. A location with multiple brands is modeled as multiple separate places, each with its own brand. |
| addresses | struct | The addresses of the place. |
| operating_status | string | Indicates the operating status of a place. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</details>

## Data access and retrieval

Overture's places theme data is freely available on both Amazon S3 and Microsoft Azure Blob Storage at these locations:

| provider | location |
| --- | --- |
| Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=places/type=place/*" language="text"></QueryBuilder>|
| Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=places/type=place/*" language="text"></QueryBuilder> |

More information can be found in the [Getting Overture Data](/getting-data/cloud-sources/) section of this documentation. You can download the entire dataset directly from the S3 or Azure locations above. Warning: the output will be a very large file.
Depending on your use case, these methods might be more practical for you:

<Tabs>
<TabItem value="Python Client" label="Python Client" default>
First, follow the [setup guide for the Python Client](/getting-data/overturemaps-py/).

```
overturemaps download -f geoparquet --type=place -o places.geoparquet
```
</TabItem>
<TabItem value="DuckDB" label="DuckDB" default>
First, follow the [setup guide for DuckDB](/getting-data/duckdb/).

<QueryBuilder query={PlacesQuery}></QueryBuilder>
</TabItem>
</Tabs>

## Data usage guidelines

We recommend downloading only the Overture data you need. If you have a particular geographic area of interest, there are several options for using a simple bounding box to extract places data and output a GeoJSON file.

<Tabs>
<TabItem value="Overture Maps Explorer" label="Overture Maps Explorer" default>
To quickly view and download modest amounts of data, you can use the [Overture Maps Explorer website](https://explore.overturemaps.org/#15.07/41.89731/12.47626).

To download data: Pan to the area you are interested in, turn off the other layers, then click `Download Visible`.

This will download the area visible on your screen.
</TabItem>
<TabItem value="Python Client" label="Python Client" default>
First, follow the [setup guide for the Python Client](/getting-data/overturemaps-py/).

Simply alter the `bbox` value to download a particular area.
```
overturemaps download --bbox=12.46,41.89,12.48,41.91 -f geojson --type=place -o rome.geojson
```
</TabItem>
<TabItem value="DuckDB" label="DuckDB" default>
First, follow the [setup guide for DuckDB](/getting-data/duckdb/).

Replace the `bbox.xmin` and `bbox.ymin` values with a new bounding box to run the query for a different area.
<QueryBuilder query={RomeQuery}></QueryBuilder>
</TabItem>
</Tabs>

## Data manipulation and analysis

### Querying by properties

These examples use data properties in the address, category, and confidence scores columns to filter the data in useful ways using DuckDB.
<Tabs>
<TabItem value="Query by address" label="Query by address" default>
The `address` column can be used to quickly filter data down to a particular political unit. This example uses the country key to get all the data with addresses in Lithuania. Region can be likewise used to extract data from smaller units such as US states.
<QueryBuilder query={LithuaniaQuery}></QueryBuilder>
</TabItem>
<TabItem value="Query by category" label="Query by category" default>
For filtering data by a particular type of place we can use the `categories` column. In this example we'll extract all the places with categories of `rice_mill` or `flour_mill`

The full category list is available [here](https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/overture_categories.csv).
<QueryBuilder query={MillQuery}></QueryBuilder>
</TabItem>
<TabItem value="Query by confidence score" label="Query by confidence score" default>
Suppose you only want data that definitely exists and is accurate. We can use the `confidence` score to filter out data below a certain threshold to remove any suspect data.
<QueryBuilder query={ConfidenceQuery}></QueryBuilder>
</TabItem>
</Tabs>

### Advanced examples

These examples present some use cases that combine places data with other datasets.

<Tabs>
<TabItem value="Conflate with OpenStreetMap" label="Conflate with OpenStreetMap" default>
Overture Places can be a valuable source for conflating with or enhancing your own existing dataset.

In this example, suppose we want to use OpenStreetMap POIs for a project but would like to fill in any missing attributes such as addresses or phone numbers with Overture Place data.

Using some basic matching logic, we can join these two datasets together to create a more robust final product. By also joining the GERS ID to our output dataset we could easily keep our now conflated dataset synced with future Overture releases with a simple join.

To run this example yourself, an Oregon PBF can be obtained from [Geofabrik](https://download.geofabrik.de/north-america/us/oregon.html).

Note: Joining data with a CDLA Permissive 2.0 license to OSM is permitted but the resulting data may need to carry the Open Database License (ODbL) if it is a derivative database.  Please see the [OSM Collective Database Guideline](https://osmfoundation.org/wiki/Licence/Community_Guidelines/Collective_Database_Guideline_Guideline) for information on this topic.
<details>
    <summary>Query</summary>

<QueryBuilder query={ConflateOSMQuery}></QueryBuilder>

</details>
</TabItem>
<TabItem value="Find building addresses" label="Find building addresses" default>
Suppose you are interested in having address data attached to buildings. The [Overture addresses](/schema/reference/addresses/address/) theme might be a good place to check, but let's assume it does not cover the area you are interested in.

The places theme has wide coverage and many of the place point features have addresses associated with them. Using an intersect we can find places that fall inside buildings and then join the place's address to the building polygon.
<details>
    <summary>Query</summary>

<QueryBuilder query={PlacesInBuildingsQuery}></QueryBuilder>

</details>
</TabItem>
</Tabs>

## Tools and libraries

### Rapid
Rapid, an OpenStreetMap editor, is capable of displaying places data as a reference layer by following the guide [here](/examples/rapid/).

The license is compatible with OSM and this data can be used for mapping.

## Get support

Overture is an open project and we welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps).

**Where to go.** Use [GitHub Discussions](https://github.com/orgs/OvertureMaps/discussions) for general questions, workflow help, feature suggestions, or broader conversations about Overture. Use GitHub Issues in the [data repository](https://github.com/OvertureMaps/data) or the [schema repository](https://github.com/OvertureMaps/schema) for specific bug reports: missing entities, geometry problems, duplicate records, or country-specific data concerns.

**What to expect.** We review incoming issues regularly and try to respond within a few business days, but we can't guarantee a resolution timeline. Issues that affect data integrity or block common workflows get higher priority.

**Filing a good issue.** The more detail you include, the faster we can help. When reporting a data problem, please include: the Overture release version you're using, a query or code snippet that reproduces the issue, specific entity IDs or bounding boxes where you see the problem, and any relevant screenshots or map views. If you can share a minimal reproducible example, that goes a long way.

---

## Taxonomy Browser


Explore and compare updates to the Overture Taxonomy.

<TaxonomyBrowser releases={[
  {
    id: 'original',
    label: 'April (Original Taxonomy)',
    releaseUrl: 'https://docs.overturemaps.org/blog/2025/04/23/release-notes/',
    note: "April's release was used as the basis for the taxonomy project.",
    tags: [
      { label: '23 April 2025', title: 'Date' },
      { label: '2025-04-23.0', title: 'Data version' },
      { label: 'v1.8.0', title: 'Schema version' },
    ],
    dataCsv: originalCsv,
    countsCsv: originalCountsCsv,
    hierarchyFields: ['theme', 'category', 'sub_category', 'speciality'],
    codeField: 'category_key',
    fieldNames: ['category_key', 'theme', 'category', 'sub_category', 'speciality'],
    basicCategoryField: null,
    displayFields: [
      { field: 'category_key', label: 'Category Key' },
    ],
  },
  {
    id: 'basicLevel',
    label: 'October (Basic Level Category Addition)',
    releaseUrl: 'https://docs.overturemaps.org/blog/2025/10/22/release-notes/',
    tags: [
      { label: '22 October 2025', title: 'Date' },
      { label: '2025-10-22.0', title: 'Data version' },
      { label: 'v1.13.0', title: 'Schema version' },
    ],
    dataCsv: basicLevelCsv,
    countsCsv: basicLevelCountsCsv,
    hierarchyField: 'overture_hierarchy',
    codeField: 'overture_label',
    fieldNames: ['basic_hierarchy', 'basic_label', 'modified', 'remove_from_v1', 'match_type', 'overture_label', 'overture_hierarchy'],
    basicCategoryField: 'basic_label',
    displayFields: [
      { field: 'match_type', label: 'Match Type' },
      { field: 'modified', label: 'Modified' },
      { field: 'remove_from_v1', label: 'Removed from V1' },
    ],
  },
  {
    id: 'december',
    label: 'December (New Hierarchy Addition)',
    releaseUrl: 'https://docs.overturemaps.org/blog/2025/12/17/release-notes/',
    tags: [
      { label: '17 December 2025', title: 'Date' },
      { label: '2025-12-17.0', title: 'Data version' },
      { label: 'v1.15.0', title: 'Schema version' },
    ],
    dataCsv: decemberCsv,
    countsCsv: decemberCountsCsv,
    hierarchyField: 'new_primary_hierarchy',
    codeField: 'new_primary_category',
    fieldNames: ['new_primary_category', 'new_primary_hierarchy', 'basic_level_category', 'old_primary_category', 'old_primary_hierarchy'],
    basicCategoryField: 'basic_level_category',
    matchColumn: 'old_primary_category',
    matchType: 'original',
    displayFields: null
  },
  {
    id: 'march',
    label: 'March (Bug Fixes, Simplified Basic)',
    releaseUrl: 'https://docs.overturemaps.org/blog/',
    enabled: true,
    tags: [
      { label: '04 March 2026', title: 'Date' },
      { label: '2025-12-17.0', title: 'Data version' },
      { label: 'v1.15.0', title: 'Schema version' },
    ],
    dataCsv: marchCsv,
    countsCsv: null,
    hierarchyField: 'new_primary_hierarchy',
    codeField: 'new_primary_category',
    fieldNames: ['group', 'level', 'is_basic', 'new_primary_hierarchy', 'new_primary_category', 'new_display_name', 'new_basic_level_category', 'old_primary_hierarchy', 'old_primary_category', 'old_basic_level_category', 'pc_added', 'pc_hierarchy_change', 'pc_name_change', 'pc_removed', 'pc_redirect_to', 'blc_change'],
    basicCategoryField: 'new_basic_level_category',
    matchColumn: 'old_primary_category',
    matchType: 'new',
    displayFields: [
      { field: 'new_display_name', label: 'Display Name' },
      { field: 'is_basic', label: 'Is Basic' },
      { field: 'pc_added', label: 'Primary Category Added' },
      { field: 'pc_hierarchy_change', label: 'Primary Category Hierarchy Change' },
      { field: 'pc_name_change', label: 'Primary Category Name Change' },
      { field: 'pc_removed', label: 'Primary Category Removed' },
      { field: 'pc_redirect_to', label: 'Primary Category Redirect To' },
      { field: 'blc_change', label: 'Basic Level Category Change' },
    ],
  },
]} />

---

## Taxonomy

# Places Taxonomy

Recently, Overture introduced new `basic_category` and `taxonomy` properties for places data. These new properties are designed to better categorize location entities such as businesses, landmarks, and attractions and facilitate search, display, and navigation in map applications. With these changes, Overture is embarking on an iterative process to address known issues with the original `categories` property, including structural inconsistencies, naming ambiguity, and coverage gaps. We are implementing taxonomy design best practices to improve granularity and ease of use.

:::tip

The original `categories` property will be available alongside the new `basic_category` and `taxonomy` properties for several months. You can explore the old-to-new category mappings [here](https://docs.google.com/spreadsheets/d/1_i2S48zTDoHff0uX-d8Nes3bR-Xee8drx27Gyi80CQ0/edit?usp=sharing0). We'd love your [feedback](https://github.com/orgs/OvertureMaps/discussions) on the new structure and suggestions for further improvement. 

:::

## Taxonomy Change Summary 
Users should be aware of the following key updates when evaluating and integrating the new places taxonomy.

| Change area | Details | Impact on Data Use |
| -------- | -------- | -------- |
| Top-Level Overhaul (L0) | Reduced top-level categories from 22 to 13. | Requires updating logic dependent on L0 categories. Consolidation reduces ambiguity. |
| New Categories| 209 new categories added (e.g., artist_studio, pickleball_court). | New, more granular POI types are available for filtering and display. |
| Removed Categories | 80 categories removed (resolved duplicates, merged obscure types). | Users must use the provided "redirect" rules to map old category IDs to active categories for backfill/historical data continuity. |
| Renamed Categories | 407 categories renamed (primarily plural-to-singular conversion, e.g., banks to bank). | Update category-based lookups and display logic to use singular forms for better mapping interface labeling. |
| Reparented Categories | 482 categories moved under a different direct parent. | The immediate parent-child relationship has changed for nearly 500 categories. |
| Repathed Categories (Hierarchy) | 2,108 categories have a different hierarchical structure or "path". | Critical: Hierarchy-dependent processing (e.g., aggregation) must be updated to reflect the new paths, especially in areas like food_and_drink and arts_and_entertainment. |
| Basic Category Mapping | All place categories are now mapped to a "Basic Level Category" (approx. 280 labels like restaurant, museum). | Facilitates simplified map iconography, high-level filtering, and cross-taxonomy mapping. |

## Comparing the Original and New Properties

#### Original Categories System 

The original `categories` property will remain in the schema for several months to allow users to compare the old system to the new taxonomy and facilitate migration.

```
properties:
    categories:
        primary: greasy_diner
```

#### New Basic Level Category

The new `basic_category`, introduced in the October release, provides a single, high-level, "cognitively basic" label.

```
properties:
    basic_category: casual_eatery
```

#### New Taxonomy Structure

The new `taxonomy` property, introduced in the December 2025 release, contains a new hierarchy and category labels.

```
properties:
    basic_category: casual_eatery
    taxonomy:
        hierarchy: [food_and_drink, restaurant, casual_eatery, gas_station_sushi]
        primary: gas_station_sushi
        alternate:
            - gas_station
            - sushi_restaurant
```

## Key Taxonomy Fields
- `hierarchy`: An ordered list representing the full path from the top-level (L0) category down to the primary category. This array is essential for aggregating POIs based on subtype/supertype relationships (e.g., for aggregating all cantonese_restaurant POIs up to chinese_restaurant). 
- `primary`: The most specific and appropriate category label for the POI, consistent with the lowest level of the hierarchy.
- basic_category`: Identifies a  “cognitively basic” category, as a supplement to the Primary Place category. This is recommended for use in map applications for high-level filtering and defining map iconography, LLM’s as it offers a streamlined set of labels (approx. 280) that are less specific than the full 2.1k taxonomy.
- `alternate`: Other relevant category labels for the POI.

## Aggregation and Generalization

The structured `hierarchy` property is designed to support robust aggregation logic. Users can reliably generalize specialized POIs by traversing the path. For example, you can find all Asian restaurants by traversing the `hierarchy` property of POIs and checking for `asian_restaurant`.

| Hierarchy Path | Aggregation Level |
| -------- | -------- | 
| [food_and_drink, ...] | Food and Drink POIs |
| [..., restaurant, ...] | All Restaurants |
| [..., asian_restaurant, ...] | All Asian Restaurants | 
| [..., chinese_restaurant, ...] | All Chinese Restaurants |
| [..., cantonese_restaurant] | Specific Cantonese Restaurants |

---

## Overview(Transportation)

# Transportation Guide

Every time you ask for directions, hail a ride, or check a map, you're relying on a model of how the world's roads, rails, and waterways connect. The Overture transportation theme is such a model: a global, open dataset of paths people and vehicles travel, built from OpenStreetMap and enhanced with data from TomTom and other local and regional authoritative data sources.

The dataset is simple at its core — just two feature types, `segment` and `connector` — but expressive enough to capture highway speed limits that change by time of day, one-way streets that allow buses to go the wrong way, and weight-restricted bridges with axle limits. Three subtypes within `segment` cover `road`, `rail`, and `water` transportation.

The rest of this page covers the feature types and subtypes, describes the dataset and how to access it, and points to tools and libraries for working with the data. The deeper topics are covered in the rest of the guide:

- **[Segments and connectors](./segments-and-connectors):** The building blocks of the network. Segments are the paths; connectors are the junctions where they meet. This page covers how they combine to form a routable graph, along with orientation, heading, and how Overture decides where to split a road.
- **[Linear referencing](./linear-referencing):** How properties can apply to just *part* of a segment — say, the first 500 meters — without chopping the geometry in two. Includes calculation methods and code examples.
- **[Scoping and travel modes](./scoping-and-travel-modes):** The rule system that makes properties conditional. A speed limit might apply only to trucks, only on weekdays, or only in the forward direction. Scoping is how all of that gets expressed.
- **[Roads](./roads):** The details specific to road segments — access restrictions, turn restrictions, speed limits, and more.

You might use Overture transportation data for mapping, routing, navigation, or geocoding street intersections. For the full schema details, see the reference documentation.

## Feature types

The Overture transportation schema defines two feature types:

- The **segment** type has a LineString geometry that represents the center-line of a path repeatedly traversed by people or objects. Segment properties describe both the physical properties (e.g. road surface and width) and non-physical properties (e.g. access restriction rules) of that path.
- The **connector** type has a Point geometry that represents the physical positions where two or more segments meet. While topology is defined by the connectors field within the `segment` type, the `connector` type provides a convenient, queryable list of those connection points. Connectors do not have properties beyond geometry and the common properties required for all Overture features.

A more detailed overview of these feature types can be found in [segments and connectors](./segments-and-connectors).

## Subtypes, classes, and subclasses

Transportation segments are divided into three subtypes: **rail**, **water**, and **road**. These subtypes are further divided into a variety of different classes based on usage captured in the table below.

<details>
 <summary>Class and subclass feature counts</summary>

<Tabs>
<TabItem value="classes" label="classes" default>

| subtype | class | subclass | feature count, April 2026 |
| --- | --- | --- | --- |
| rail    | funicular      | NULL           | 1,364         |
| rail    | light_rail     | NULL           | 16,855        |
| rail    | monorail       | NULL           | 3,087         |
| rail    | narrow_gauge   | NULL           | 31,622        |
| rail    | standard_gauge | NULL           | 1,463,298      |
| rail    | subway         | NULL           | 55,282        |
| rail    | tram           | NULL           | 59,481        |
| rail    | unknown        | NULL           | 391,728       |
| road    | bridleway      | NULL           | 102,509       |
| road    | cycleway       | cycle_crossing | 65,583        |
| road    | cycleway       | NULL           | 1,332,229      |
| road    | footway        | crosswalk      | 2,463,298      |
| road    | footway        | sidewalk       | 4,004,529      |
| road    | footway        | NULL           | 17,075,021     |
| road    | living_street  | NULL           | 3,417,398      |
| road    | motorway       | link           | 649,838       |
| road    | motorway       | NULL           | 439,849       |
| road    | path           | NULL           | 14,026,572     |
| road    | pedestrian     | NULL           | 474,442       |
| road    | primary        | link           | 505,653       |
| road    | primary        | NULL           | 6,852,053      |
| road    | residential    | NULL           | 127,190,332    |
| road    | secondary      | link           | 398,907       |
| road    | secondary      | NULL           | 10,888,521     |
| road    | service        | alley          | 1,859,902      |
| road    | service        | driveway       | 17,792,302     |
| road    | service        | parking_aisle  | 6,588,285      |
| road    | service        | NULL           | 34,209,026     |
| road    | steps          | NULL           | 1,985,926      |
| road    | tertiary       | link           | 304,782       |
| road    | tertiary       | NULL           | 20,296,138     |
| road    | track          | NULL           | 26,056,895     |
| road    | trunk          | link           | 570,908       |
| road    | trunk          | NULL           | 3,524,390      |
| road    | unclassified   | NULL           | 30,009,932     |
| road    | unknown        | NULL           | 9,003,800      |
| water   | NULL           | NULL           | 28,741        |

</TabItem>
</Tabs>

</details>

## Data dictionary

All Overture data, including transportation data, is distributed as GeoParquet, a column-based data structure. Below you'll find tables with column-by-column descriptions of the properties for the segment and connector feature types.

<details>
 <summary>Column definitions in the transportation theme</summary>

<Tabs>
<TabItem value="segment" label="segment" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | The line representation of the segment's location. Segment's geometry which MUST be a LineSting as defined by GeoJSON schema. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
| subtype | string | The broad category of transportation segment. |
| class | string | Captures the kind of road and its position in the road network hierarchy. |
| names | struct | Properties defining the names of a feature. |
| connectors | struct | Array of connector IDs identifying the connectors this segment is physically connected to linearly referenced with their location. Each connector is a possible routing decision point, meaning it defines a place along the segment in which there is possibility to transition to other segments which share the same connector. |
| routes | struct | Routes this segment belongs to. |
| subclass_rules | struct | Defines the portion of a road that the subclass applies to. |
| access_restrictions | struct | Rules governing access to this road segment or lane. |
| level_rules | struct | Defines the Z-order, i.e. stacking order, of the road segment. |
| destinations | struct | Describes objects that can be reached by following a transportation segment in the same way those objects are described on signposts or ground writing that a traveller following the segment would observe in the real world. This allows navigation systems to refer to signs and observable writing that a traveller actually sees. |
| prohibited_transitions | struct | Defines where traveling from the segment to another is disallowed for navigation. This covers things situations prohibited turns or a transition from road to bike lane disallowing cars. |
| road_surface | struct | Defines the surface material on a road such as paved, asphalt, or unpaved. |
| road_flags | struct | Additional properties relevant to roads such as is_bridge or is_under_construction. |
| speed_limits | struct | Defines the speed limit of the road segment. |
| width_rules | struct | Defines the width of the road segment for rendering. |
| subclass | string | Specifies the usage of a length of road. |
| rail_flags | struct | Additional properties relevant to rail such as is_tunnel or is_freight. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
<TabItem value="connector" label="connector" default>

| column | type | description |
| --- | --- | --- |
| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| geometry | binary | The line representation of the segment's location. Segment's geometry which MUST be a LineSting as defined by GeoJSON schema. |
| bbox | struct | Area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. |
| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
| filename | string | Name of the file being queried. |
| theme | string | Name of the Overture theme being queried. |
| type | string | Name of the Overture feature type being queried. |

</TabItem>
</Tabs>

</details>

## Data access and retrieval

Overture's transportation theme data is freely available on both Amazon S3 and Microsoft Azure Blob Storage at these locations:

<Tabs>
<TabItem value="segment_url" label="Segment" default>
| provider | location |
| --- | --- |
| Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=transportation/type=segment/*" language="text"></QueryBuilder>|
| Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=transportation/type=segment/*" language="text"></QueryBuilder> |
</TabItem>
<TabItem value="connector_url" label="Connector" default>
| provider | location |
| --- | --- |
| Amazon S3 | <QueryBuilder query="s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=transportation/type=connector/*" language="text"></QueryBuilder>|
| Azure Blob Storage | <QueryBuilder query="https://overturemapswestus2.blob.core.windows.net/release/__OVERTURE_RELEASE/theme=transportation/type=connector/*" language="text"></QueryBuilder> |
</TabItem>
</Tabs>

We recommend downloading only the Overture data you need. If you have a particular geographic area of interest, there are several options for using a simple bounding box to extract data and output a GeoJSON file.

<Tabs>
<TabItem value="Python Client" label="Python Client" default>
First, follow the [setup guide for the Python Client](/getting-data/overturemaps-py/).

Set type to either `segment` or `connector` and simply alter the `bbox` value to download a particular area.
```
overturemaps download --bbox=12.46,41.89,12.48,41.91 -f geojson --type=segment -o rome_segments.geojson
```
</TabItem>
<TabItem value="DuckDB" label="DuckDB" default>
First, follow the [setup guide for DuckDB (/getting-data/duckdb/).

Set the parquet link to either the **connector** or **segment** url depending on your needs.

Replace the `bbox.xmin` and `bbox.ymin` values with a new bounding box to run the query for a different area.
<QueryBuilder query={SegmentBBOX}></QueryBuilder>
</TabItem>
</Tabs>

## Querying transportation data

### Querying by properties in DuckDB

These examples use data properties to filter the data in useful ways using DuckDB.
<Tabs>
<TabItem value="Query by class" label="Query by class" default>
The `class` column can be used to pull out subsets of the road data. Similarly, you could use subtype to select only water, rail, or road features. This example extracts only the **parking_aisle** features within the bounding box.
<QueryBuilder query={ParkingAisles}></QueryBuilder>
</TabItem>
<TabItem value="Query by routes" label="Query by routes" default>
You might be interested in a network of roads, such as a US Interstate. These can be extracted using the `routes` column and either using the `network` and `ref` properties and/or the `wikidata` column to identify the route.

This example extracts all the roads that are part of US I-5. To get all US Interstates simply remove `AND routes[1].ref = '5'` from the query.
<QueryBuilder query={Routes}></QueryBuilder>
</TabItem>
</Tabs>

### Querying by properties in Athena
Athena can allow for faster querying of the transportation layer than DuckDB given the size of the data. These examples are designed for Athena, but could be reworked for DuckDB with some tweaking.

<Tabs>
<TabItem value="Query by speed limit" label="Query by speed limit" default>
To properly return a linear referenced feature like a speed limit, we will need to query all the possible values of the feature as the queried value may only exist on one portion of the line. In this example, we're extracting roads with any speed limit `max_speed` value of **27** and unit of **mph** using the any_match function.

This same general query would also work for querying other similar columns such as `prohibited_transitions` and `access_restrictions`.
<QueryBuilder query={SpeedLimits}></QueryBuilder>
</TabItem>
<TabItem value="Select connecting segments" label="Select connecting segments" default>
With the `connectors` column it is simple to query for all features that connect with a particular segment without the need for a spatial query.

This example selects all the segments that that connect to the example id.
<QueryBuilder query={ConnectingSegments}></QueryBuilder>
</TabItem>
</Tabs>

## Tools and libraries

### transportation-splitter

| ![Overture Splitter](/img/transportation/splitter_concept.png) |
|:--|
| *Conceptual diagram of the splitter tool output. The numbers following 1234@ represent start_lr and end_lr values.* |

The [transportation-spitter tool](https://github.com/OvertureMaps/transportation-splitter) transforms Overture road data into simpler sub-segments. It will optionally divide features at each connector point and at each change of a [scoped based property](/schema/reference/core/scoping/linearly_referenced_range), depending on configuration. Depending on your needs and map stack, the resulting dataset may be easier to manipulate than the original Overture data as each segment will only have connections at either end and have one set of properties for its entire length.

Since a GERS ID will no longer be unique with this output, the resulting data will have two additional columns: `start_lr` and `end_lr` which are linear references describing which section of the original feature this new segment comes from.

#### Splitter example
To help visualize this process better, here is a real-world example of a residential street in OpenStreetMap, Overture, and after being run through the splitter tool.
<Tabs>
<TabItem value="OpenStreetMap" label="OpenStreetMap" default>
| ![OpenStreetMap Splitter Example](/img/transportation/splitter_osm.png) |
|:--|
| In OpenStreetMap this residential road is represented by two different features with the same tags with feature 1 having an additional restricted access tag. |
</TabItem>
<TabItem value="Overture" label="Overture" default>
| ![Overture Splitter Example](/img/transportation/splitter_overture.png) |
|:--|
| In Overture the two segments have been combined into one feature and the restricted access tag has been stored as this linear reference in **access_restrictions**:
`[{'access_type': allowed, 'when': {'during': , 'heading': , 'using': , 'recognized': [as_private], 'mode': , 'vehicle': }, 'between': [0.521962729, 1.0]}]` |
</TabItem>
<TabItem value="Transportation Splitter" label="Transportation Splitter" default>
![Splitter Output Example](/img/transportation/splitter_output.png)
|:--|
| The splitter has sliced the Overture feature at each connector point for the driveways as well as at the point where the access restriction begins. This results in six unique features in the output all still sharing the same GERS ID. |
</TabItem>
</Tabs>

#### More information and feedback

The tool requires a Spark environment to run and has been tested using Azure Databricks and AWS Glue. For setup information the [transportation-spitter GitHub](https://github.com/OvertureMaps/transportation-splitter) will contain the most up-to-date information as the tool is in active development still.

If you have feedback, questions, etc. on the tool you can create an [issue](https://github.com/OvertureMaps/transportation-splitter/issues) on the GitHub.

## Get support

Overture is an open project and we welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps).

**Where to go.** Use [GitHub Discussions](https://github.com/orgs/OvertureMaps/discussions) for general questions, workflow help, feature suggestions, or broader conversations about Overture. Use GitHub Issues in the [data repository](https://github.com/OvertureMaps/data) or the [schema repository](https://github.com/OvertureMaps/schema) for specific bug reports: missing entities, geometry problems, duplicate records, or country-specific data concerns.

**What to expect.** We review incoming issues regularly and try to respond within a few business days, but we can't guarantee a resolution timeline. Issues that affect data integrity or block common workflows get higher priority.

**Filing a good issue.** The more detail you include, the faster we can help. When reporting a data problem, please include: the Overture release version you're using, a query or code snippet that reproduces the issue, specific entity IDs or bounding boxes where you see the problem, and any relevant screenshots or map views. If you can share a minimal reproducible example, that goes a long way.

---

## Linear Referencing

Linear referencing allows properties to apply to portions of a [segment](../segments-and-connectors#segments) without splitting the geometry. This promotes shape stability and reduces versioning when only part of a road changes.

To avoid splitting road segments at any and every property change, linear referencing defines how properties that apply to portions of a segment can vary along that segment while it is generally understood to be the same "road." Segment splits are then reserved for more significant intersections so that we don't have to version the entire road any time any piece of the road changes.

## Linear reference values

A linear reference is a **normalized position** from `0.0` (start of segment) to `1.0` (end of segment).

## `at` vs `between`

| Property | Purpose | Example |
|----------|---------|---------|
| `at` | Single point location | `at: 0.3` — 30% along segment |
| `between` | Range along segment | `between: [0.2, 0.7]` — 20% to 70% |

When `between` is not provided (or is null), the attribute applies to the full segment.

## Calculation method

Overture computes linear references using **WGS84 geodetic distance** in meters:

```
linear_ref = geodetic_distance_along_segment_from_start / total_geodetic_length
```

Both distances must be computed on the WGS84 ellipsoid, not planar distance on raw lon/lat coordinates. Other approaches exist (e.g., projected coordinates), but geodetic distance provides consistent accuracy globally.

### Examples

**Apache Sedona (SQL):**

```sql
SELECT ST_LENGTHSPHEROID(ST_GEOMFROMWKB(geometry)) AS segment_length_m
FROM segments;
```

**pyproj (Python):**

```python
from pyproj import Geod
from shapely import wkb

geod = Geod(ellps="WGS84")
line_geometry = wkb.loads(geometry)  # geometry is WKB bytes
segment_length = geod.geometry_length(line_geometry)  # meters
```

See the [transportation-splitter](https://github.com/OvertureMaps/transportation-splitter) for a complete implementation.

:::warning
Functions like `ST_LINELOCATEPOINT` can produce incorrect results on geometries that cross over or near themselves in 2D (curved on-ramps, mountain switchbacks, cul-de-sacs). These functions may pick the wrong location when the line passes over or close to itself, even though the geometry is valid because crossings occur at different elevations or positions along the segment. Note that Overture [disallows self-intersecting segments](../segments-and-connectors#loops) in its own data.
:::

## Why geodetic distance matters

Using planar distance (treating lon/lat as Cartesian x/y) can produce incorrect linear references, especially at high latitudes or for long segments. For a 10 km east-west segment at 60°N latitude, planar calculations can underestimate length by ~50%. Some map projections (e.g., EPSG:3857) yield reasonable results for short, straight segments, but accuracy degrades with segment length and curvature.

If a consumer calculates linear references differently than Overture, attribution or connector positions may be misaligned, potentially causing visual discrepancies on rendered maps or routing failures.

## Edge cases

For very short segments (under 1 meter), floating-point precision may be limited. Treat `at` values near `0.0` or `1.0` as equivalent to endpoints. When a connector does not fall exactly on the geometry, the linear reference corresponds to the closest point on the segment.

---

## Roads

In the Overture transportation theme, a road is any kind of road, street, or path, including a dedicated path for walking or cycling. (Railways and waterways are separate subtypes in the transportation schema.) Road segments comprise the majority of ground-based transportation segments. Roads are modeled using [segment](/schema/reference/transportation/segment) features with the `subtype` property value set to `road`.

This document describes properties specific to the `road` subtype. For more general information regarding segments, please refer to [segments and connectors](../segments-and-connectors).

## Subclass

The subclass property refines the descriptions of segments by:

- clearly specifying the usage of a length of road, and using linear referencing instead of further segmentation to pinpoint a change in how the road is used
- properly classifying detailed information from OpenStreetMap

Subclasses require non-overlapping geometries, which will make it easier for routing engines to consume our road data and generate turn-by-turn directions. The class and subclass structures allow us to capture more information about roads from our data sources. For example, we've been able to move more than 30 million "unknown" road segments from OSM into subclasses, laying the groundwork for richer and more detailed map displays with Overture data.

## Surface

The `road_surface` property of a road indicates its physical surface. If omitted, a reasonable default value should be assumed based on the `class` and `subclass`.

Like many road segment properties, the `road_surface` property supports [geometric scoping](../scoping-and-travel-modes#geometric-scoping-linear-referencing) (linear referencing). Consequently, the effective road surface may vary along different sub-ranges of a road segment's geometry.

## Restrictions

### Access restrictions

Access restrictions on a road segment specify who is allowed to use the road, and under what circumstances.

Every road segment has an *implied* set of access restrictions defined by its road class and local rules, norms, and customs. (The Overture transportation schema does not specify these implied access restrictions, which are left to the specific application to resolve.)

The implied access restrictions may be modified for the road segment as a whole by providing an explicit value for the property `access_restrictions`.

It is technically possible to specify a blanket access grant or refusal of access applying to everyone and everything; but where, as is typical, a more precise outcome is needed, one or more [rules](../scoping-and-travel-modes#rules-and-rule-based-properties) will be used to specify access restrictions. As with all rule-based properties, if no rule matches the specific facts, then the default restrictions for the road class govern.

<Tabs>
  <TabItem value="blanketDenial" label="Blanket denial of access." default>

```yaml
id: access-restrictions-segment-blanket
type: Feature
geometry:
  type: LineString
  coordinates:
    - [0, 0]
    - [0, 1]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: residential
  access_restrictions:
    - access_type: denied
```

  </TabItem>

  <TabItem value="businessHoursDelivery" label="Private access, deliveries OK during business hours." default>

```yaml
id: access-restrictions-segment-private-with-deliveries
type: Feature
geometry:
  type: LineString
  coordinates:
    - [0, 0]
    - [0, 1]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: residential
  access_restrictions:
    - access_type: denied
    - access_type: allowed
      when: { recognized: [as_private] }
    - access_type: allowed
      when:
        using: [to_deliver]
        during: Mo-Fr 08:30-16:30
```

  </TabItem>

  <TabItem value="noMotorVehiclesExceptDestination" label="No motor vehicles except to destination." default>

```yaml
id: access-restrictions-segment-motor-vehicles-destination-only
type: Feature
geometry:
  type: LineString
  coordinates:
    - [0, 0]
    - [0, 1]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: residential
  access_restrictions:
    - access_type: denied
      when: { mode: [motor_vehicle] }
    - access_type: allowed
      when: { using: [at_destination] }
```

  </TabItem>

  <TabItem value="noNorthboundTrucks" label="No trucks with &ge; 5 axles." default>

```yaml
id: access-restrictions-segment-axle-limit
type: Feature
geometry:
  type: LineString
  coordinates:
    - [0, 0]
    - [0, 1]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: motorway
  access_restrictions:
    - access_type: denied
      when:
        mode: [hgv]
        vehicle:
          - dimension: axle_count
            comparison: greater_than_equal
            value: 5
```

  </TabItem>
</Tabs>

### Turn restrictions

Turn restrictions on a road segment limit the transitions which are allowed from that segment into other [physically connected](../segments-and-connectors#physical-connectivity) segments.

Every road segment has an implied set of allowed transitions defined by its [access restrictions](#access-restrictions) as well as local rules, norms, and customs. An example of a transition restriction implied by an access restriction: if the segment can only be used along the `forward` [heading](../segments-and-connectors#heading), then it is implied that no transitions are allowed to any connected segments if travelling along the `backward` heading. An example of a transition restriction implied by a local rule or norm would be a blanket prohibition on U-turns in a given jurisdiction.

Overture takes a permissive-by-default approach to transition restrictions. By default, all implied transitions are allowed. The set of allowed transitions may be reduced by adding explicit transition restrictions in the `prohibited_transitions` property.

Turn restrictions come in two flavors: **simple** and **via**. A simple turn restriction allows a simple regulation to be stated, such as "No right turn onto Elm Street"; a via restriction covers more elaborate cases where the sequence of maneuvers is important.

<Tabs>
  <TabItem value="simple" label="Simple restriction." default>

<figure>

<ThemedImage
  alt="A simple transition restriction prohibiting a right turn."
  sources={{
    light: useBaseUrl('/img/transportation/turn-restriction-01-light.png'),
    dark: useBaseUrl('/img/transportation/turn-restriction-01-dark.png'),
  }}
/>

<figcaption>

*Prohibited right turn from "source" to "target" segment at connector 2.*

</figcaption>

</figure>

<details>
<summary>Source segment</summary>
```yaml
id: overture:transportation:example:simple-turn-restriction-source
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-113.57822030759499, 50.01868388494378]
    - [-113.57831482025354, 50.018860947117304]
    - [-113.57851814418316, 50.01923724443006]
properties:
  theme: transportation
  type: segment
  version: 5
  subtype: road
  class: secondary
  connectors:
    - connector_id: overture:transportation:example:via-turn-restriction-connector1
      at: 0
    - connector_id: overture:transportation:example:via-turn-restriction-connector2
      at: 1
  prohibited_transitions:
      - sequence:
        - segment_id: overture:transportation:example:simple-turn-restriction-target
          connector_id: overture:transportation:example:simple-turn-restriction-connector2
        final_heading: forward
        when: {heading: forward}
```
</details>

<details>
<summary>Connector 1</summary>

*This connector is not an important part of the example, since it does
not participate in the turn restriction, but it is included to bring
real-world context to the example.*

```yaml
id: overture:transportation:example:simple-turn-restriction-connector1
type: Feature
geometry:
  type: Point
  coordinates:  [-113.57831482025354, 50.018860947117304]
properties:
  theme: transportation
  type: connector
  version: 0
```
</details>

<details>
<summary>Exit segment</summary>

*This segment is not an important part of the example, since all implied
transitions are allowed on it. We include it to bring real-world context
to the example.*

```yaml
id: overture:transportation:example:simple-turn-restriction-exit
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-113.57831482025354, 50.018860947117304]
    - [-113.5783121688577, 50.019016827708754]
    - [-113.57829228338763, 50.019079861246865]
    - [-113.57826444373009, 50.019121599625294]
    - [-113.57816369068271, 50.01919400284882]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: secondary
  connectors:
    - connector_id: overture:transportation:example:via-turn-restriction-connector1
      at: 0
    - connector_id: overture:transportation:example:via-turn-restriction-connector2
      at: 1
```

</details>

<details>
<summary>Connector 2</summary>

*The right turn from the source segment (`forward` heading) to the
target segment (`forward` heading) is prohibited at this connector.*

```yaml
id: overture:transportation:example:simple-turn-restriction-connector2
type: Feature
geometry:
  type: Point
  coordinates: [-113.57851814418316, 50.01923724443006]
properties:
  theme: transportation
  type: connector
  version: 1
```
</details>

<details>
<summary>Target segment</summary>

*Traffic heading `forward` on the source segment may not enter this
segment heading `forward`, i.e. the right turn from the source segment
to this segment is prohibited.*

```yaml
id: overture:transportation:example:simple-turn-restriction-target
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-113.57851814418316, 50.01923724443006]
    - [-113.57837460847787, 50.01919574268962]
    - [-113.57812342099429, 50.01919343703648]
    - [-113.57803729957116, 50.01923263312719]
    - [-113.57766410673773, 50.01923263312719]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: secondary
  connectors:
    - connector_id: overture:transportation:example:via-turn-restriction-connector1
      at: 0
    - connector_id: overture:transportation:example:via-turn-restriction-connector2
      at: 1
```
</details>

<details>
<summary>Connector 3</summary>

*This connector is not an important part of the example, since it does
not participate in the turn restriction, but it is included to bring
real-world context to the example.*

```yaml
id: overture:transportation:example:simple-turn-restriction-connector3
type: Feature
geometry:
  type: Point
  coordinates: [-113.57816369068271, 50.01919400284882]
properties:
  theme: transportation
  type: connector
  version: 1
```
</details>

  </TabItem>

  <TabItem value="via" label="Via restriction" default>

<figure>

<ThemedImage
  alt="A via restriction."
  sources={{
    light: useBaseUrl('/img/transportation/turn-restriction-02-light.png'),
    dark: useBaseUrl('/img/transportation/turn-restriction-02-dark.png'),
  }}
/>

<figcaption>

*Prohibited transition from "source" to "target" through `via` segment.*

</figcaption>

</figure>

<details>
<summary>Source segment</summary>
```yaml
id: overture:transportation:example:via-turn-restriction-source
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-71.1100226929593, 42.30156668552357]
    - [-71.11055493812631, 42.30157222996385]
    - [-71.11102971081017, 42.30157407811038]
    - [-71.11143701579662, 42.30156114108277]
    - [-71.11197425857047, 42.30152602627953]
    - [-71.11234408150312, 42.30149091145671]
    - [-71.1126589307566, 42.30147612626226]
    - [-71.11301376086777, 42.301494607754876]
    - [-71.11320616874515, 42.301516785538524]
properties:
  theme: transportation
  type: segment
  version: 5
  subtype: road
  class: primary
  connectors:
    - connector_id: overture:transportation:example:via-turn-restriction-connector1
      at: 0
    - connector_id: overture:transportation:example:via-turn-restriction-connector2
      at: 1
  names:
    primary: Arborway
  prohibited_transitions:
    - sequence:
        - segment_id: overture:transportation:example:via-turn-restriction-target
          connector_id: overture:transportation:example:via-turn-restriction-connector2
        - segment_id: overture:transportation:example:via-turn-restriction-via
          connector_id: overture:transportation:example:via-turn-restriction-connector1
      final_heading: forward
      when:
        heading: forward
        during: Mo-Fr 06:00-09:00, 15:00-19:00
  road_surface:
    - value: paved
```
</details>

<details>
<summary>Connector 1</summary>
```yaml
id: overture:transportation:example:via-turn-restriction-connector1
type: Feature
geometry:
  type: Point
  coordinates: [-71.11234408150312, 42.30149091145671]
properties:
  theme: transportation
  type: connector
  version: 1
```
</details>

<details>
<summary>Via segment</summary>
```yaml
id: overture:transportation:example:simple-road2
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-71.11213418200086, 42.3017182333833]
    - [-71.11234408150312, 42.30149091145671]
    - [-71.11248901211202, 42.3013264259736]
    - [-71.11283634581244, 42.30093831245662]
properties:
  theme: transportation
  type: segment
  version: 5
  subtype: road
  class: secondary
  connectors:
    - connector_id: overture:transportation:example:via-turn-restriction-connector1
      at: 0
    - connector_id: overture:transportation:example:via-turn-restriction-connector2
      at: 1
  names:
    primary: Washington Street
  road_surface:
    - value: paved
```
</details>

<details>
<summary>Connector 2</summary>
```yaml
id: overture:transportation:example:via-turn-restriction-connector2
type: Feature
geometry:
  type: Point
  coordinates: [-71.11248901211202, 42.3013264259736]
properties:
  theme: transportation
  type: connector
  version: 1
```
</details>

<details>
<summary>Target segment</summary>
```yaml
id: overture:transportation:example:turn-restriction-target
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-71.11325364601365, 42.301374477956756]
    - [-71.11278137213321, 42.3013264259736]
    - [-71.11248901211202, 42.3013264259736]
    - [-71.11157195119078, 42.30139295947919]
    - [-71.1109997251666, 42.301428074356636]
    - [-71.11058492376937, 42.30143177065813]
    - [-71.11002519176327, 42.301415137298676]
properties:
  theme: transportation
  type: segment
  version: 5
  subtype: road
  class: primary
  connectors:
    - connector_id: overture:transportation:example:via-turn-restriction-connector1
      at: 0
    - connector_id: overture:transportation:example:via-turn-restriction-connector2
      at: 1
  names:
    primary: Arborway
  road_surface:
    - value: paved
```
</details>

  </TabItem>
</Tabs>

### Speed limits

Speed limits restrict the speed at which travel is permitted on a road. Typically speed limits specify maximum allowed speeds, but the Overture schema also allows minimum speed limits to be set and variable speed corridors to be indicated.

Every road segment has an implied speed limit or set of speed limits defined by its road class and local rules, norms, and customs. As with access and turn restrictions, the Overture transportation schema does not attempt to specify these implied speed limits.

The implied speed limits may be configured for the whole road segment by providing an explicit value for the property `speed_limits`.

As with access restrictions and turn restrictions, speed limits can be specified using [rules](../scoping-and-travel-modes#rules-and-rule-based-properties).

<Tabs>
  <TabItem value="speedLimitSimple" label="Simple speed limit" default>

```yaml
id: speed-limits-simple
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.09348187774302, 49.280278741717865]
    - [-123.0895720621171, 49.280195795155265]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: residential
  speed_limits:
    - max_speed:
        value: 30
        unit: km/h
```

  </TabItem>

  <TabItem value="speedLimitDirectional" label="Different speed limit for northbound trucks" default>

```yaml
id: speed-limits-variable-max
type: Feature
geometry:
  type: LineString
  coordinates:
    - [0, 0]
    - [0, 1]
properties:
  theme: transportation
  type: segment
  version: 2
  subtype: road
  class: secondary
  speed_limits:
    - max_speed: {value: 70, unit: "mph"}
    - when:
        mode: [hgv]
        heading: forward
      max_speed: {value: 65, unit: "mph"}
```

  </TabItem>

  <TabItem value="speedLimitVariable" label="Variable speed corridor" default>

```yaml
id: speed-limits-variable-max
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.12895930023527, 50.007761789070344]
    - [-123.12637500433082, 50.00945836227345]
    - [-123.12506896231434, 50.011762034223324]
    - [-123.12415195409014, 50.01351203677902]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: motorway
  speed_limits:
    - max_speed:
        value: 100
        unit: km/h
      is_max_speed_variable: true
```

  </TabItem>
</Tabs>

---

## Scoping Rules and Travel Modes

In the real world, many facts and rules affecting entities have only a partial application, meaning they don't apply everywhere, or they don't apply at all times, or to everyone, or to all sets of external conditions. For example, access restrictions on a road segment might not apply to all people or all kinds of vehicles, or they might vary according to the day of the week.

The Overture schema uses two related concepts to capture the partial application of facts and rules: **scoped values** and **rule-based properties**.

## Scoped values and scoping properties

A *scoped* value is a value which only applies within a limited scope. Most scoped values are rules in the rule lists of [rule-based properties](#rules-and-rule-based-properties). However, scoped values also exist outside of rule-based properties. For example, a `destinations` property belonging to a road segment might be geometrically scoped to its position along the road.

The scope in which a scoped value applies is controlled by one or more special child properties of the value known as *scoping* properties.

### Geometric scoping (linear referencing)

<Tabs>
  <TabItem value="description" label="Description" default>

The geometric scoping properties `at` and `between` limit the scope of their parent value to a position or range of positions, respectively, along a segment's geometry. When the parent value is a rule object, the rule only matches the position or range of positions specified in the `at` or `between` property.

The value of the `at` property is a single real number `a` where `0` &le; `a`
&le; `1`. It represents a discrete position along the segment's geometry. The
value of the `between` property is a pair of numbers `[a, b]` where `0` &le;
`a` &lt; `b` &le; `1`. It represents a range of positions along the segment's
geometry. The numbers `a` and `b` are interpreted as percentage displacements
along the parent segment's geometry starting from the start of the segment.
(*The terms "start" and "end" are explained in
[segments and connectors](../segments-and-connectors#start-end-and-orientation).*)

So, for example, the scoping property `"at": 0.15` scopes its parent value
to the position on the segment that is displaced 15% of the segment length from
the start.

<figure>

<ThemedImage
  alt="Diagram showing a single geometrically-scoped position"
  sources={{
    light: useBaseUrl('/img/transportation/geometric-scoping-position-light.png'),
    dark: useBaseUrl('/img/transportation/geometric-scoping-position-dark.png'),
  }}
  />
<figcaption>
*The position along the segment geometry described by `"at": 0.15`.*
</figcaption>
</figure>

The scoping property `"between": [0.35, 0.75]` scopes its parent value to the range of positions on the segment beginning at 35% and extending to 75% of the segment length from the start.

  <ThemedImage
    alt="Diagram showing a geometrically-scoped range"
    sources={{
      light: useBaseUrl('/img/transportation/geometric-scoping-range-light.png'),
      dark: useBaseUrl('/img/transportation/geometric-scoping-range-dark.png'),
    }}
  />
  <figcaption>
    *The range on the segment geometry described by `"between": [0.35, 0.75]`.*
  </figcaption>

</TabItem>
<TabItem value="example" label="Example" default>

  The example below shows a road segment whose speed limit is defined by two geometrically-scoped speed limit rules:
  ```yaml
id: overture:transportation:example:geometric-scoping
type: Feature
geometry:
  type: LineString
  coordinates: [[0, 0], [1, 1]]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: primary
  speed_limits:
    - between: [0, 0.15]
      max_speed:
        value: 100
        unit: km/h
    - between: [0.15, 1]
      max_speed:
        value: 60
        unit: km/h
```
  </TabItem>
</Tabs>

For details on how linear references are calculated, see the [linear referencing](../linear-referencing) guide.

### Temporal scoping (opening hours)

<Tabs>
  <TabItem value="description" label="Description" default>

The temporal, or time-based, scoping construct `when: { during: "..." }` limits the scope of its parent value to one or more recurring time ranges. When the parent value is a rule object, the rule only matches the time range or time ranges specified in the `during` property.

The `during` property must contain a string expressed in the OpenStreetMap
[opening hours specification](https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification).

  </TabItem>
  <TabItem value="example" label="Example" default>

The example below shows a road segment with a temporally-scoped access restriction rule. The rule states that non-bus travellers are prohibited from access to the segment on weekdays between 3PM and 6PM.

```yaml
id: overture:transportation:example:temporal-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-122.90019762265949, 49.20784664905824]
    - [-122.9003738558948, 49.207833436710956]
    - [-122.90052986564378, 49.207871186265805]
properties:
  theme: transportation
  type: segment
  version: 2
  subtype: road
  class: unknown
  access_restrictions:
    - access_type: denied
      when:
        mode: [bus]
        during: "Mo-Fr 15:00-18:00"
```

  </TabItem>
</Tabs>

### Subjective scoping

Subjective scoping means that the scope of a property can be constrained based on subjective factors like *who* or *what* is travelling on the transportation network, or *how* they are doing it.

The Overture transportation schema supports several subjective factors:

#### Travel-mode scoping

A travel mode is a way of moving about the transportation network, for example driving in a motor vehicle, or, more specifically, driving in a high-occupancy vehicle.

The property construct `when: { mode: [...] }` limits the scope of its parent value to apply only to people or things travelling using the listed travel modes. See [travel modes](#travel-modes) below for more detail.

#### Heading

<Tabs>
  <TabItem value="description" label="Description" default>

Heading scoping limits the scope of a parent value to apply only when the traveller is proceeding along the segment geometry in the named direction, either `forward` or `backward`. (*The directions `forward` and `backward` are defined in [segments and connectors](../segments-and-connectors#heading).*)

The property construct `when: { heading: forward|backward }` applies heading scoping to a parent value.

  </TabItem>
  <TabItem value="example" label="Example" default>

The example below shows a road segment with multiple heading-scoped access restriction rules. The rules allow all standard travel modes for the segment class to travel in the forward direction, but only allow buses to travel in the backward direction.

```yaml
id: overture:transportation:example:subjective-heading-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-1.3023158, 54.5579329]
    - [-1.3020090, 54.5577898]
    - [-1.3014511, 54.5575155]
    - [-1.3009618, 54.5572737]
    - [-1.3004518, 54.5570288]
    - [-1.3003009, 54.5569580]
properties:
  theme: transportation
  type: segment
  version: 2
  subtype: road
  class: primary
  access_restrictions:
    - access_type: denied
      when: { heading: backward }
    - access_type: allowed
      when:
        heading: backward
        mode: [bus]
```
  </TabItem>
</Tabs>

#### Purpose of use scoping

<Tabs>
  <TabItem value="description" label="Description" default>

Usage purpose scoping limits the scope of a parent value to apply only when the user is using the feature for one of the listed purposes. This type of scoping is common when it matters that a person is in the process of doing something like making a delivery or acting as the customer of a business.

The property construct `when: { using: [...] }` applies usage purpose scoping to a parent value.

  </TabItem>
  <TabItem value="example" label="Example" default>

The example below shows a road segment representing a hotel driveway where through traffic is not permitted (only usage by hotel customers or as a final destination is allowed):

  ```yaml
id: overture:transportation:example:subjective-usage-purpose-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.12700676422021, 49.279826628301635]
    - [-123.12680748254229, 49.27995121574301]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: tertiary
  access_restrictions:
    - access_type: denied
    - access_type: allowed
      when: { using: [as_customer, at_destination] }
```

  </TabItem>
</Tabs>

#### Status scoping (membership in a recognized group)

<Tabs>
  <TabItem value="description" label="Description" default>

Status scoping limits the scope of a parent value to apply only when the user has a certain recognized status or is a member of a recognized group. This type of scoping is useful when it matters whether a person or thing has a recognized characteristic, such as holding a permit or being an employee of a business or student at an academic institution.

The property construct `when: { recognized: [...] }` applies status scoping to a parent value.

  </TabItem>
  <TabItem value="example" label="Example" default>

The example below shows a road segment modeling a private condominium tower driveway where access is denied to the general public, but allowed to privately-authorized individuals, such as condo unit owners:

```yaml
id: overture:transportation:example:subjective-status-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.12791513926058, 49.287502049554945]
    - [-123.12795068403449, 49.287522915661725]
    - [-123.12797769806272, 49.28756882106529]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: tertiary
  access_restrictions:
    - access_type: denied
    - access_type: allowed
      when: { recognized: [as_private] }
```

  </TabItem>
</Tabs>

### Vehicle attributes scoping

<Tabs>
  <TabItem value="description" label="Description" default>

Vehicle attribute scoping limits the scope of a parent value to apply only when the vehicle in use meets certain criteria.

The property construct `when: { vehicle: [{ dimension: ..., comparison: ..., value: ... }] }` applies vehicle attributes scoping to a parent value.

Note that vehicle attribute scoping can overlap to some degree with [travel mode scoping](#travel-mode-scoping). For example, some access rules may be scoped to the travel mode "heavy goods vehicle", while another equivalent access rule could be scoped to the vehicle attribute "gross vehicle weight."

  </TabItem>
  <TabItem value="example" label="Example" default>

```yaml
id: overture:transportation:example:subjective-vehicle-attributes-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.12791513926058, 49.287502049554945]
    - [-123.12795068403449, 49.287522915661725]
    - [-123.12797769806272, 49.28756882106529]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: residential
  access_restrictions:
    - access_type: denied
      when:
        vehicle:
          - dimension: weight
            comparison: greater_than
            value: 23
            unit: 't'
```

  </TabItem>
</Tabs>

## Rules and rule-based properties

A *rule-based* property is a property whose value in a given situation is determined by evaluating a list of rules against the facts applicable to that situation. Each individual rule in the list of rules is itself a scoped value, and the assessment of which rule applies to a given set of facts is done by the rule evaluation algorithm.

### Absolute form

There are cases when specifying a property value using rules makes sense, and cases where doing so is unnecessarily complicated because the real-world entity being modeled has a single unchanging state which is the same in all fact situations. In these cases, most rule-based properties support a simpler absolute form without a list of rules.

### Rule evaluation algorithm

Given a rule-based property, the actual value of the property in a given fact pattern is determined by a three-step process: first, all matching rules are identified; second, the single determining rule is chosen if possible; lastly, if there is no applicable rule, an appropriate default value may be assumed.

1. **Matching rules.** For a given rule and a given set of facts, the rule *matches* the facts if the scope of the rule contains all the facts, *i.e.* the facts fit within all of the scoping properties expressed in the rule. The matching criteria for a rule can be thought of as the logical AND of all the scoping properties expressed in the rule.
2. **Determining rule.** For a given rule-based property and a given set of facts, *at most* one rule can *determine* the property value. If only one rule matches, that rule determines the property value. If more than one rule matches, the last matching rule in the list determines the value. (This is similar to how OpenStreetMap [conditional restrictions](https://wiki.openstreetmap.org/wiki/Conditional_restrictions) are evaluated.) Therefore it is important to write more general rules before more specific ones in a rule list.
3. **Fallback to default.** If there are no matching rules, an appropriate default value may apply, depending on the property being evaluated.

## Travel modes

In the real world, a travel mode can be thought of intuitively as a way of getting from point A to point B. Travel modes can include non-vehicle modes (foot), vehicle modes (a bicycle or motor vehicle), and occasionally more granular details, e.g. a motor vehicle classified as a high occupancy vehicle or a heavy goods vehicle.

Within the Overture transportation theme schema model, a travel mode is a recognized mode by which a person or thing may use a [segment](/schema/reference/transportation/segment) feature.

### Implied travel modes

Every segment has an *implied* set of travel modes that are allowed to use the segment. For [road](../roads) segments, this implied set derives from the road class, as well as local rules, norms, and customs operative where the road segment is situated.

Since this implied set depends on locality or jurisdiction, and is susceptible of varying over time, the Overture transportation schema does not try to specify the implied set. Resolution of the implied set is done by the specific application in the case where this level of detail is important for its proper functioning. An accurate routing engine may need this information, whereas a 2D map render or a geocoder likely do not.

### General definitions

Overture's recognized travel modes are defined in general terms that are broadly applicable. For example, `hov` is a high-occupancy vehicle and `hgv` is a heavy goods vehicle. In most jurisdictions, these general terms map to a concept that is in use within the jurisdiction, even though the local name for the concept may vary.

Despite being broadly applicable, travel modes may have different definitions in different places and at different times:

- in one jurisdiction, an `hgv` might mean any vehicle with a gross vehicle weight in excess of 3.5 tonnes (3,500 kg). In another place, an `hgv` might have a gross vehicle weight of at least 10,001 lbs.
- in one jurisdiction, an `hov` might require a minimum of 2 passengers while in another place it might have a higher minimum passenger count, or include battery-electric vehicles, or exclude certain classes of vehicle or usage.

As a consequence of the variance in definition across place and time, Overture gives only general definitions for travel modes, leaving precise definition to those applications that require them.

### Travel mode scoping in the schema

#### The `mode` scoping property

The scoping property `mode` controls whether a given scoped property applies when a given travel mode is being used for traveling along a road segment.

If `mode` is provided, it must be a non-empty array of string values identifying travel modes, and is interpreted as a set. Values must be unique, but order is not important.

#### Vehicle attribute scoping: `vehicle`

Because travel modes are a fuzzy concept, there are inevitably areas of overlap with the more precise, but more limited, `vehicle` scoping property which is used for [vehicle attributes scoping](#vehicle-attributes-scoping). Where there is potential overlap, the method of scoping used in Overture data releases will depend on how the upstream data source has expressed the equivalent concept. Where there is choice, it is preferable to select the scoping method that most accurately reflects the intention expressed on local signage.

#### Similar scoping properties: `using` and `recognized`

The scoping properties `using` and `recognized` express concepts that are meant to be orthogonal to (completely separate from) travel modes:

- The `using` property indicates [purpose of use](#purpose-of-use-scoping) scoping, which relates to the purpose for which the person or thing travelling is using a given segment of the transportation network. Travel modes should ideally not embed a purpose of use.
- The `recognized` property indicates [status scoping](#status-scoping-membership-in-a-recognized-group), which relates to a recognized status given to the person or thing traveling, where the recognized status is distinct from the mode of travel itself. Travel modes should ideally not embed a status.

### The travel modes taxonomy

Travel modes in Overture form a shallow taxonomy. Some travel modes are more general, while others are more specific, and a more general travel mode may contain a more specific one. For example, the general travel mode `vehicle` contains the more specific mode `motor_vehicle`.

<figure>

<ThemedImage
  alt="Overture travel modes taxonomy"
  sources={{
    light: useBaseUrl('/img/transportation/travel-modes-light.png'),
    dark: useBaseUrl('/img/transportation/travel-modes-dark.png'),
  }}
/>

<figcaption>

*The Overture travel modes taxonomy.*

</figcaption>

</figure>

As many of the above travel modes draw on the body of knowledge accumulated in relation to OpenStreetMap [transport mode access restrictions](https://wiki.openstreetmap.org/wiki/Key:access#Transport_mode_restrictions), Overture Maps would like acknowledge an intellectual debt to the OSM community in relation to travel modes as well as to other aspects of the transportation schema.

---

## Segments and Connectors

In the Overture transportation theme, features with their `type` property set to `segment` represent **paths repeatedly traversed by people or objects**. For example, a segment may represent a major highway, an abandoned subway line, or a ferry route. The `connector` feature type carries point geometry which describes a location where a physical connection between two or more segments occurs.

Together, segments and connectors capture the shape and connectivity of the transportation network.

<figure>

<ThemedImage
  alt="Three segments physically joined by a connector"
  sources={{
    light: useBaseUrl('/img/transportation/network-light.png'),
    dark: useBaseUrl('/img/transportation/network-dark.png'),
  }}
/>

<figcaption>

*A connector physically joining three segments.*

</figcaption>
</figure>

## Connectors

The [connector](/schema/reference/transportation/connector) feature type carries point geometry representing a location where a physical connection between two or more segments occurs (or may occur in the future). Connectors have no properties apart from geometry and standard Overture feature properties. All other aspects of the transportation theme are modeled on segments.

To better support routing use cases, the `segment` feature type has a property called `connectors`: an array of IDs with pre-computed linear reference values that explicitly link segments and connector features via coordinates. Each connector is a possible routing decision point, meaning it defines a place along the segment where there is a possibility to transition to other segments that share the same connector.

Here's an example of how the connectors property is modeled in the schema:

```yaml
id: overture:transportation:segment:123
type: Feature
geometry:
  type: LineString
  coordinates: [[0, 0], [0.03, 0], [0.10, 0]]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: secondary
  connectors:
    - connector_id: fooConnector
      at: 0
    - connector_id: barConnector
      at: 0.3
    - connector_id: bazConnector
      at: 1
  road_surface:
    - value: paved
```

### Physical connectivity

Two or more segments are physically connected at a given connector if each segment's connectors property contains a reference to the connector.

The connector geometry's coordinates should preferably be contained within the segment geometry's coordinates, in which case the connector coordinates define the point of physical connection. This constraint will always be met by official Overture data releases. Where this is not possible, the point of physical connection is the closest point to the connector coordinates which intersects the segment geometry.

Conversely, two segments are **not** physically connected if their connectors properties do not reference a shared connector, even if their geometries overlap or even share a coordinate in common.

Travel from a point on one segment to a point on another physically-connected segment is allowed, unless limited by an explicit restriction such as an access or turn restriction.

All segments in official Overture transportation data releases have a minimum of two connectors, one at each end of the geometry, even if those endpoint connectors are not attached to any other segment. This is done to allow new segments to connect into the existing network without needing to change the properties of existing segments.

## Segments

The [segment](/schema/reference/transportation/segment) feature type carries `LineString` geometry which describes the physical shape of a section of the transportation network. A segment may represent an entity with a tangible real-world existence, such as a paved road, or it may represent an intangible entity, such as a ferry route, which has a well-known shape but no observable presence in the real world.

### Subtypes

Because of their many possible uses, the segment `type` is further organized by its `subtype`, `class`, and `subclass` properties. Currently, the Overture transportation theme supports three segment subtypes:

| Subtype | Description | % of total segment length |
|---------|-------------|---------------------------|
| [`road`](../roads) | Roads and footpaths | ~97% |
| `rail` | Any transit system in which vehicles ride on metal rails | ~3% |
| `water` | Shipping lanes and ferry routes | &lt;1% |

### Geometry

A segment's geometry approximates the physical centerline of the section of path it models. For roads, information regarding the width of this path is captured in the `width_rules` road-specific property.

### Class

The `class` property of a segment specifies its general purpose of use within its subtype. Unlike many segment properties, a segment's `class` property does not support [geometric scoping](../scoping-and-travel-modes#geometric-scoping-linear-referencing) (linear referencing). Consequently, whenever a linear range of real-world road or rail makes a class transition (for example, between secondary and residential roads), the Overture transportation segmentation algorithm will generate a segment split.

Currently, **only roads and railways have the `class` property**. Within these subtypes, every segment has a class. If the `class` property is missing from a segment's source dataset, the `class` for that segment will be given default value `unknown`, indicating the class is undetermined and may be updated in a later release.

### Flags

A segment's flags (`road_flags` for roads, `rail_flags` for rails) are a set of named flag values indicating the presence or absence of simple physical characteristics. For example, a road segment with `road_flags = [is_link, is_under_construction]` is a link segment that is physically under construction.

Like many segment properties, the `road_flags`/`rail_flags` property supports [geometric scoping](../scoping-and-travel-modes#geometric-scoping-linear-referencing). Consequently, the applicable flags may vary along different sub-ranges of a road segment's geometry.

**Here's an example of how classes, subclasses, and flags are modeled in the Overture schema:**

```yaml
class: footway
subclass_rules:
  - value: sidewalk
    between: [0, 0.6]
  - value: crosswalk
    between: [0.6, 1.0]
road_flags:
  - values: [is_bridge]
    between: [0.2, 0.3]
  - values: [is_under_construction]
    between: [0.3, 0.5]

class: service
subclass_rules:
  - value: driveway
    between: [0, 0.5]

class: primary
subclass: link
subclass_rules:
  - value: link
```

### Granularity

Occasionally, a real-world feature admits different representations at different granularities. For example, a dual carriageway may be modeled as one segment, or two parallel segments. Segments support modeling the transportation network at a range of granularities. A single segment can represent a bidirectional street including all of its sidewalks, a single sidewalk, two parallel subway tracks, a one-way street, or one direction of a dual carriageway.

### Start, end, and orientation

The first coordinate in a segment's geometry is the **start** of the segment and the last coordinate is the **end**. A segment is oriented away from the start and toward the end.

<figure>

```yaml
type: LineString
coordinates:
  - [1, 0]   # Start
  - [0, 0]
  - [-1, 0]  # End
```

<ThemedImage
  alt="West-oriented segment geometry"
  sources={{
    light: useBaseUrl('/img/transportation/oriented-west-light.png'),
    dark: useBaseUrl('/img/transportation/oriented-west-dark.png'),
  }}
/>

<figcaption>

*This segment geometry is oriented due west.*

</figcaption>
</figure>

<figure>

```yaml
type: LineString
coordinates:
  - [-1, 0]  # Start
  - [0, 0]
  - [1, 0]   # End
```

<ThemedImage
  alt="East-oriented segment geometry"
  sources={{
    light: useBaseUrl('/img/transportation/oriented-east-light.png'),
    dark: useBaseUrl('/img/transportation/oriented-east-dark.png'),
  }}
/>

<figcaption>

*This segment geometry is oriented due east.*

</figcaption>
</figure>

### Heading

Travel along a segment's geometry can follow one of two possible headings: **forward** or **backward**. The forward heading proceeds toward the end of the segment; while the backward heading proceeds back toward the start of the segment.

<figure>

<ThemedImage
  alt="Travel heading along a segment oriented due east."
  sources={{
    light: useBaseUrl('/img/transportation/heading-light.svg'),
    dark: useBaseUrl('/img/transportation/heading-dark.svg'),
  }}
/>

<figcaption>

*Travel heading along a segment.*

</figcaption>
</figure>

### Level (Z-order)

Segment geometry is two-dimensional. In the real, 3D, world, however the entities represented by segments can be above or below each other, as may happen with tunnels, bridges, overpasses, and stacked multi-level highway interchanges. To accurately render top-down 2D maps, it is important to know the relative stacking order, or Z-order, of segments.

Segment Z-order is given by the `level` property. A `level` value of `0` indicates visual level, with positive numbers indicating above visual level, negative numbers indicating below visual level, and in general, a lesser number indicating a lower position in the stacking order than a greater number.

<figure>

<ThemedImage
  alt="Level 0 segments stacked above level -1 segments."
  sources={{
    light: useBaseUrl('/img/transportation/level-light.png'),
    dark: useBaseUrl('/img/transportation/level-dark.png'),
  }}
/>

<figcaption>

*Ground level segments stacking above tunnel segments.*

</figcaption>
</figure>

Note that two segments with different `level` values may be physically connected, since `level` is an approximation for rendering and is not meant be a precise indication of elevation at different points along the segment.

### Destinations

The `destinations` property in the segment feature type supports routing use cases. It describes the transitions from one segment to another on the way to a specified location. In turn-by-turn routing applications, this is what is known as "follow signs for" — the human-readable directions and signposts along a road, highway, or interstate that get us from point A to point Z, by way of any number of paths in between. The `destinations` property has a flexible schema that will allow us to capture and model navigation data from many different sources.

## Linear referencing

Properties on a segment can vary along its length using normalized positions from `0.0` (start) to `1.0` (end), a technique called linear referencing. For full details on how linear references work, including calculation methods, code examples, and edge cases, see the [linear referencing](../linear-referencing) guide.

## Segmentation

The term segmentation describes the process of converting upstream source data into Overture transportation shape and connectivity data modeled as segments and connectors.

### Shape stability

A primary goal of Overture's segmentation process is to promote stability of segment shape across Overture data releases. For example, if a certain real-world stretch of Main Street is represented by a single segment with particular geometry in release 1, we will strive to avoid slicing the exact same geometry up into two, three, or four segments in release 2.

Aiming for segment shape stability categorically does not mean that Overture aims for a stable transportation dataset. On the contrary, we aim to continuously improve data accuracy and coverage, and expect the transportation network dataset to constantly evolve and grow as a result. Our goal is simply to minimize unnecessary, semantically meaningless, changes in how the geometry is sliced into segments across data releases.

Several features of the transportation theme schema were designed to allow the segmentation process to achieve its segment stability goal. These features include:

- [interior connectors](#interior-connectors)
- [geometrically scoped](#geometric-scoping) segment properties

### ID stability

Overture pursues shape stability to improve the ability to assess whether two segments from different points in time (or from different upstream data sources) represent the same real-world entity. Overture's success at this assessment directly feeds into the stability and precision of [GERS IDs](https://docs.overturemaps.org/gers) assigned to segments. In turn, higher GERS ID stability and precision makes transportation theme data more useful for conflation.

### Interior connectors

A key feature of the Overture transportation schema which enables shape stability is the ability of segments to support connectors at interior positions along their geometry, not only at their endpoints. The ability to add internal connectors prevents the segmentation process from having to blindly follow every split or join introduced in upstream source data.

For example, imagine a square city block bordered by road on all four sides has been mapped in the source data, but a back alley dividing the block along the east-west axis has not. If the back alley is subsequently mapped in the source data, the Overture segmentation process can connect to the transportation network without having to subdivide any existing segments by simply introducing internal connectors on the north-south road segments bordering the block to the east and west. As a result, the [Overture IDs](https://docs.overturemaps.org/gers) of the north-south road segments remain as they were and no data needs to be re-conflated.

<figure>

<ThemedImage
  alt="A city block without with back alley omitted."
  sources={{
    light: useBaseUrl('/img/transportation/interior-connectors-before-light.png'),
    dark: useBaseUrl('/img/transportation/interior-connectors-before-dark.png'),
  }}
/>

<ThemedImage
  alt="A city block after adding a new back alley segment."
  sources={{
    light: useBaseUrl('/img/transportation/interior-connectors-after-light.png'),
    dark: useBaseUrl('/img/transportation/interior-connectors-after-dark.png'),
  }}
/>

<figcaption>

*A square city block bordered by four roads before (left) and after (right) mapping the back alley using internal connectors.*

</figcaption>

</figure>

Note that in the above example, an official Overture data release would insert coordinates in the middle of the north-south segments, if they did not already exist, because Overture data releases will always ensure that every segment's geometry includes all of its connectors.

### Geometric scoping

Many segment properties may include a linear reference so that they apply only to a part of the segment geometry. We refer to these linearly-referenced property values as being geometrically scoped and discuss geometric scoping at greater length in the page on [scoped properties](../scoping-and-travel-modes).

Geometric scoping allows the segmentation algorithm to avoid introducing segment splits simply because a certain property has different values along different parts of the geometry. Like interior connectors, geometrically-scoped properties enable the segmentation process to make decisions that promote shape stability, ultimately resulting in more precise and stable [Overture IDs](https://docs.overturemaps.org/gers) and less churn in conflated data.

<figure>

<ThemedImage
  alt="A single segment with a geometrically-scoped speed limit"
  sources={{
    light: useBaseUrl('/img/transportation/geometrically-scoped-speed-limit-light.png'),
    dark: useBaseUrl('/img/transportation/geometrically-scoped-speed-limit-dark.png'),
  }}
/>

<figcaption>

*A single segment with multiple geometrically-scoped speed limit values.*

</figcaption>
</figure>

### Loops

Although it is technically possible to use the Overture schema to express a segment forming a connected loop, such loops are considered invalid and will never be produced by the segmentation algorithm.

An illegal loop where one end of a segment connects to the other end can be corrected by splitting the segment and introducing a second connector to maintain physical connectivity. An illegal self-crossing loop of degree *N* can be corrected by splitting the segment into N pieces.

<figure>

<ThemedImage
  alt="Illegal circular loop."
  sources={{
    light: useBaseUrl('/img/transportation/circle-looped-light.png'),
    dark: useBaseUrl('/img/transportation/circle-looped-dark.png'),
  }}
/>

<ThemedImage
  alt="One possible correction for illegal circular loop."
  sources={{
    light: useBaseUrl('/img/transportation/circle-unlooped-light.png'),
    dark: useBaseUrl('/img/transportation/circle-unlooped-dark.png'),
  }}
/>

<figcaption>

*An illegal loop connected at its endpoints (left) and a possible correction (right).*

</figcaption>
</figure>

<figure>

<ThemedImage
  alt="Illegal self-crossing loop."
  sources={{
    light: useBaseUrl('/img/transportation/crossing-looped-light.png'),
    dark: useBaseUrl('/img/transportation/crossing-looped-dark.png'),
  }}
/>

<ThemedImage
  alt="One possible correction to self-crossing loop."
  sources={{
    light: useBaseUrl('/img/transportation/crossing-unlooped-light.png'),
    dark: useBaseUrl('/img/transportation/crossing-unlooped-dark.png'),
  }}
/>

<figcaption>

*An illegal self-crossing loop (left) and a possible correction (right).*

</figcaption>
</figure>

---

## Schema Reference

# Overture Maps Schema

:::note
This section has been recently updated to reflect changes in our schema modeling. We welcome your feedback in [GitHub Discussions](https://github.com/OvertureMaps/data/discussions).
:::

The Overture Maps schema defines the structure, properties, and constraints for all features across six themes: addresses, base, buildings, divisions, places, and transportation. The reference pages in this section document the theme-based and shared modules in the schema.

The schema is authored as [Pydantic](https://docs.pydantic.dev/) models and the reference documentation is generated from those models. The source code lives in the [OvertureMaps/schema](https://github.com/OvertureMaps/schema) repository on GitHub.

## Why Use Pydantic to Define Data Schemas?

This project addresses a fundamental challenge in data consumption: bridging the semantic gap between raw data and human understanding while enabling machine-actionable workflows.

## Why Schema at All: Beyond Raw Data

Take a column like `pop_2020`. Is it total population? Population density per square kilometer? Working-age population? Without a schema, you're left sampling values and guessing from column names.

Compare this to OpenStreetMap's approach: features use well-known key-value pairs like `building=residential` or `addr:housenumber=42` that have semantic meaning and can be looked up on the OSM wiki. This creates a step toward a schema — shared vocabulary with documented semantics used across a vast dataset. However, OSM tags remain free-form: multiple valid ways to express the same concept, no built-in validation, and complex downstream validation because of undocumented keys that might have meaning to someone, somewhere. A schema provides the structured alternative: explicit types, clear validation rules, and semantic meaning that both humans and systems can rely on.

Data files containing only column names and values aren't fully documented. External metadata files typically focus on how data was collected and encoded, not on semantic meaning or validation rules. Data consumers struggle to understand what datasets contain and which columns they need for their goals.

## Why Pydantic Over JSON Schema: Solving Multiple Problems

We initially chose JSON Schema because it aligned with our mental model and promised to solve our problems as we understood them. But JSON Schema surfaced several pain points:

- **Authoring difficulty:** Hard to write correctly, difficult to verify, limited IDE support, no refactoring capabilities
- **Tooling gaps:** Generic tools can't tailor output for specific applications like ours
- **Development friction:** Schema changes required manual coordination across multiple artifacts

Pydantic addresses these systematically: author in Python with full IDE support, generate tailored documentation, and automatically produce the specific artifacts each workflow needs. Pydantic can also produce JSON Schema, so any application that requires it can use it while we gain all the Python benefits during authoring.

## The Result: Faster Understanding, Higher Quality

Instead of spending time deciphering what columns mean and whether data matches expectations, users can focus on their actual goals: analysis, visualization, integration. Quality improves because validation happens automatically rather than through manual inspection.

The fundamental approach — human-readable authoring that generates machine-actionable outputs — has broader applications beyond Overture and geospatial data. We hope others will adapt these patterns for linking with Overture data or modeling their own domains entirely.

## Schema Modules

Browse the schema reference in the sidebar. Modules are organized by theme and shared components:

**Themes:** Addresses, Base, Buildings, Divisions, Places, Transportation

**Shared:** Core (names, sources, cartographic hints), System (country codes, language tags, geometry primitives)

---

## Address


Addresses are structured labels for the geographic locations where businesses and individuals
reside.

While address formats around the world have some general points in common, the specifics vary
extensively from place to place. The rules for dividing an address up into parts or fields vary,
as do the names of those parts or fields.

The address schema uses a simplified approach to capture the common structure of addresses
worldwide while accommodating local variance. The schema is heavily based on the OpenAddresses
([www.openaddresses.io](https://www.openaddresses.io)) project.

For sub-country administrative levels (and non-administrative levels such as neighborhoods), the
schema provides the `address_levels` field. This is where the names of cities and towns,
provinces, state, and regions, and similar addressing units are found.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Position of the address. Addresses are point geometries.*Allowed geometry types: Point* |
| `theme` | `"addresses"` | |
| `type` | `"address"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `address_levels[]` | `list<`[`AddressLevel`](types/address_level.md)`>` (optional) | Names of the sub-country addressing areas the address belongs to, including the city or locality, in descending order of generality.The list is sorted so that the highest, or most general, level comes first (*e.g.*, region) and the lowest, or most particular level, comes last (*e.g.*, city or town).The number of items in this list and their meaning is country-dependent. For example, in the United States, we expect two items: the state, and the locality or municipality within the state. Other countries might have as few as one, or even three or more.When a specific level that is required for a country is not known. most likely because the data provider has not supplied it and we have not derived it from another source, the list item corresponding to that level must be present, but its `value` field should be omitted.*Minimum length: 1**Maximum length: 5* |
| `address_levels[].value` | [`StrippedString`](../system/stripped_string.md) (optional) | A string without leading or trailing whitespace |
| `country` | [`CountryCodeAlpha2`](../system/country_code_alpha2.md) | The country the address belongs to, as an ISO 3166-1 alpha-2 country code. |
| `number` | [`StrippedString`](../system/stripped_string.md) (optional) | The house number.This field does not necessarily contain an integer or even a number. Values such as "74B", "189 1/2", and "208.5", where the non-integer or non-number part is part of the house number, not a unit number, are in common use.*Minimum length: 1* |
| `postal_city` | [`StrippedString`](../system/stripped_string.md) (optional) | The postal authority designated city name, if applicable.In some countries or regions, a mailing address may need to specify a different city name than the city that actually contains the address coordinates. This optional field can be used to specify the alternate city name to use.For example:- The postal city for the US address *716 East County Road, Winchester, Indiana*   is Ridgeville. - The postal city for the Slovenian address *Tomaj 71, 6221 Tomaj, Slovenia* is   Dutovlje.*Minimum length: 1* |
| `postcode` | [`StrippedString`](../system/stripped_string.md) (optional) | The postal code.*Minimum length: 1* |
| `street` | [`StrippedString`](../system/stripped_string.md) (optional) | The street name.The street name can include a type (*e.g.*, "Street" or "St", "Boulevard" or "Blvd", *etc.*) and a directional (*e.g.*, "NW" or "Northwest", "S" or "Sud"). Both type and directional, if present, may be either a prefix or a suffix to the primary name. They may either be fully spelled-out or abbreviated.*Minimum length: 1* |
| `unit` | [`StrippedString`](../system/stripped_string.md) (optional) | The secondary address unit designator.In the case where the primary street address is divided into secondary units, which may be apartments, floors, or even buildings if the primary street address is a campus, this field names the specific secondary unit being addressed.*Minimum length: 1* |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `416ab01c-d836-4c4f-aedc-2f30941ce94d` |
| `bbox.xmin` | `-176.56381225585938` |
| `bbox.xmax` | `-176.56378173828125` |
| `bbox.ymin` | `-43.94719696044922` |
| `bbox.ymax` | `-43.94718933105469` |
| `geometry` | `POINT (-176.5637854 -43.9471955)` |
| `theme` | `addresses` |
| `type` | `address` |
| `version` | `1` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenAddresses/LINZ` |
| `sources[0].record_id` | `null` |
| `sources[0].update_time` | `null` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `address_levels[0].value` | `Chatham Islands` |
| `address_levels[1].value` | `Chatham Island` |
| `country` | `NZ` |
| `number` | `54` |
| `postal_city` | `null` |
| `postcode` | `null` |
| `street` | `Tikitiki Hill Road` |
| `unit` | `null` |

---

## AddressLevel


A sub-country addressing unit, such as a region, city, or neighborhood, that is less specific
than a street name and not a postal code.

In the following address, the terms `Montréal` and `QC` are address levels:

```
3998 Rue De Bullion, Montréal, QC H2W 2E4
```

The number of address levels per address is country-dependent.

Other addressing systems may use the terms "administrative level" or "admin level"  for the
same concept. We have chosen the term "address level" to communicate the fact that in some
countries and regions, address levels do not necessarily correspond to administrative units.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `value` | [`StrippedString`](../../system/stripped_string.md) (optional) | A string without leading or trailing whitespace*Minimum length: 1* |

## Used By

- [`Address`](../address.md)

---

## Bathymetry


Bathymetry features provide topographic representations of underwater areas, such as parts of
lake beds or ocean floors.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Shape of the underwater area, which may be a polygon or multi-polygon.*Allowed geometry types: MultiPolygon, Polygon* |
| `theme` | `"base"` | |
| `type` | `"bathymetry"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `depth` | [`Depth`](types/depth.md) | Depth below surface level of the feature in meters. |
| `cartography` | [`CartographicHints`](../core/cartographic_hints.md) (optional) | |
| `cartography.prominence` | [`Prominence`](../core/prominence.md) (optional) | Subjective scale of feature significance or importance, with 1 being the least, and 100 being the most, significant.This value can be used to help drive decisions about how and when to display a feature, and how to treat it relative to neighboring features.When populated by Overture, this value is derived from various factors including, but not limited to: feature and subtype, population, and capital status. |
| `cartography.min_zoom` | [`MinZoom`](../core/min_zoom.md) (optional) | Recommended minimum tile zoom level in which this feature should be displayed.It is recommended that the feature be hidden at zoom levels below this value.Zoom levels follow the Slippy Maps convention, documented in the following references: - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection |
| `cartography.max_zoom` | [`MaxZoom`](../core/max_zoom.md) (optional) | Recommended maximum tile zoom level in which this feature should be displayed.It is recommended that the feature be hidden at zoom levels above this value.Zoom levels follow the Slippy Maps convention, documented in the following references: - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection |
| `cartography.sort_key` | [`SortKey`](../core/sort_key.md) (optional) | Integer indicating the recommended order in which to draw features.Features with a lower number should be drawn "in front" of features with a higher number. |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `5d40bd6c-db14-5492-b29f-5e25a59032bc` |
| `bbox.xmin` | `-175.12791442871094` |
| `bbox.xmax` | `-170.05111694335938` |
| `bbox.ymin` | `-77.9718246459961` |
| `bbox.ymax` | `-75.64299774169922` |
| `geometry` | `MULTIPOLYGON (((-170.71296928 -76.744313428, -170.719841483 -76.757076376, -170.731061124 -76.761...` |
| `theme` | `base` |
| `type` | `bathymetry` |
| `version` | `0` |
| `sources[0].property` |  |
| `sources[0].dataset` | `ETOPO/GLOBathy` |
| `sources[0].record_id` | `2024-12-09T00:00:00.000Z` |
| `sources[0].update_time` | `null` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `depth` | `500` |
| `cartography.prominence` | `null` |
| `cartography.min_zoom` | `null` |
| `cartography.max_zoom` | `null` |
| `cartography.sort_key` | `12` |

---

## Infrastructure


Infrastructure features provide basic information about real-world infrastructure entitites
such as bridges, airports, runways, aerialways, communication towers, and power lines.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Geometry of the infrastructure feature, which may be a point, line string, polygon, or multi-polygon.*Allowed geometry types: LineString, MultiPolygon, Point, Polygon* |
| `theme` | `"base"` | |
| `type` | `"infrastructure"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `class` | [`InfrastructureClass`](types/infrastructure_class.md) | |
| `subtype` | [`InfrastructureSubtype`](types/infrastructure_subtype.md) | |
| `height` | [`Height`](types/height.md) (optional) | Height of the feature in meters. |
| `surface` | [`SurfaceMaterial`](types/surface_material.md) (optional) | |
| `names` | [`Names`](../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `level` | [`Level`](../core/level.md) (optional) | Z-order of the feature where 0 is visual level |
| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key-value pairs imported directly from the source data without change.This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. |
| `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `e9e3d506-89c0-3473-8cee-5e5ac6596d6c` |
| `bbox.xmin` | `-180.0` |
| `bbox.xmax` | `-179.99998474121094` |
| `bbox.ymin` | `-82.42408752441406` |
| `bbox.ymax` | `-82.42407989501953` |
| `geometry` | `POINT (-179.9999994 -82.42408)` |
| `theme` | `base` |
| `type` | `infrastructure` |
| `version` | `0` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `n7674174803@2` |
| `sources[0].update_time` | `2023-04-07T17:37:48.000Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `class` | `information` |
| `subtype` | `pedestrian` |
| `height` | `null` |
| `surface` | `null` |
| `names.primary` | `1306 km to South Pole` |
| `names.common` | `null` |
| `names.rules` | `null` |
| `level` | `null` |
| `source_tags` | `{"description": "1036 km to South Pole.", "information": "route_marker", "note": "The road contin...` |
| `wikidata` | `Q800558` |

---

## Land


Land features are representations of physical land surfaces.

In Overture data releases, land features are sourced from OpenStreetMap.
TODO. Finish this whenI get more info from Jennings.

Physical representations of land surfaces.

Global land derived from the inverse of OSM Coastlines. Translates `natural` tags from OpenStreetMap.

TODO: Update this description when the relationship to `land_cover` is better understood.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Geometry of the land feature, which may be a point, line string, polygon, or multi-polygon.*Allowed geometry types: LineString, MultiPolygon, Point, Polygon* |
| `theme` | `"base"` | |
| `type` | `"land"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `class` | [`LandClass`](types/land_class.md) (optional) | |
| `subtype` | [`LandSubtype`](types/land_subtype.md) (optional) | |
| `elevation` | [`Elevation`](types/elevation.md) (optional) | Elevation above sea level of the feature in meters. |
| `surface` | [`SurfaceMaterial`](types/surface_material.md) (optional) | |
| `names` | [`Names`](../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `level` | [`Level`](../core/level.md) (optional) | Z-order of the feature where 0 is visual level |
| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key-value pairs imported directly from the source data without change.This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. |
| `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `70fc3596-a987-3fea-820c-c016c0a2f0da` |
| `bbox.xmin` | `-178.7000274658203` |
| `bbox.xmax` | `-178.6999969482422` |
| `bbox.ymin` | `-85.45001220703125` |
| `bbox.ymax` | `-85.44999694824219` |
| `geometry` | `POINT (-178.7 -85.45)` |
| `theme` | `base` |
| `type` | `land` |
| `version` | `0` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `n11693475112@1` |
| `sources[0].update_time` | `2024-03-05T09:23:39.000Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `class` | `cliff` |
| `subtype` | `physical` |
| `elevation` | `null` |
| `surface` | `null` |
| `names.primary` | `Dismal Buttress` |
| `names.common` | `null` |
| `names.rules` | `null` |
| `level` | `null` |
| `source_tags` | `{"natural": "cliff", "ref:linz:place_id": "12318", "wikipedia": "en:Dismal Buttress"}` |
| `wikidata` | `Q5282342` |

---

## LandCover


Land cover features indicate the primary natural or artificial surface material covering a land
area on the earth, including vegetation types like forests and crops, built environments like
cities, and natural surfaces like wetlands or barren ground.

Land cover features relate to `LandUse` features in the following way: land cover is the
physical thing covering the land, while land use is the human use to which the land is being
put.

TODO: Explain relationship to `Land` features.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Shape of the covered land area, which may be a polygon or multi-polygon.*Allowed geometry types: MultiPolygon, Polygon* |
| `theme` | `"base"` | |
| `type` | `"land_cover"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `subtype` | [`LandCoverSubtype`](types/land_cover_subtype.md) | |
| `cartography` | [`CartographicHints`](../core/cartographic_hints.md) (optional) | |
| `cartography.prominence` | [`Prominence`](../core/prominence.md) (optional) | Subjective scale of feature significance or importance, with 1 being the least, and 100 being the most, significant.This value can be used to help drive decisions about how and when to display a feature, and how to treat it relative to neighboring features.When populated by Overture, this value is derived from various factors including, but not limited to: feature and subtype, population, and capital status. |
| `cartography.min_zoom` | [`MinZoom`](../core/min_zoom.md) (optional) | Recommended minimum tile zoom level in which this feature should be displayed.It is recommended that the feature be hidden at zoom levels below this value.Zoom levels follow the Slippy Maps convention, documented in the following references: - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection |
| `cartography.max_zoom` | [`MaxZoom`](../core/max_zoom.md) (optional) | Recommended maximum tile zoom level in which this feature should be displayed.It is recommended that the feature be hidden at zoom levels above this value.Zoom levels follow the Slippy Maps convention, documented in the following references: - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection |
| `cartography.sort_key` | [`SortKey`](../core/sort_key.md) (optional) | Integer indicating the recommended order in which to draw features.Features with a lower number should be drawn "in front" of features with a higher number. |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `c347312d-012b-5e73-8bd3-a10d04b2981d` |
| `bbox.xmin` | `-180.0001983642578` |
| `bbox.xmax` | `-179.99313354492188` |
| `bbox.ymin` | `65.95172119140625` |
| `bbox.ymax` | `65.96218872070312` |
| `geometry` | `POLYGON ((-179.99877531181616 65.95172539425603, -179.99740705536922 65.95265577758867, -179.9975...` |
| `theme` | `base` |
| `type` | `land_cover` |
| `version` | `0` |
| `sources[0].property` |  |
| `sources[0].dataset` | `ESA WorldCover` |
| `sources[0].record_id` | `null` |
| `sources[0].update_time` | `2024-11-07T00:00:00.000Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `subtype` | `barren` |
| `cartography.prominence` | `null` |
| `cartography.min_zoom` | `8` |
| `cartography.max_zoom` | `15` |
| `cartography.sort_key` | `3` |

---

## LandUse


Land use features specify the predominant human use of an area of land, for example commercial
activity, recreation, farming, housing, education, or military use.

Land use features relate to `LandCover` features in the following way: land use is the human
human activity being done with the land, while land cover is the physical thing that covers it.

TODO: Explain relationship to `Land` features.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Geometry of the land use area, which may be a point, line string, polygon, or multi-polygon.*Allowed geometry types: LineString, MultiPolygon, Point, Polygon* |
| `theme` | `"base"` | |
| `type` | `"land_use"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `class` | [`LandUseClass`](types/land_use_class.md) | |
| `subtype` | [`LandUseSubtype`](types/land_use_subtype.md) | |
| `elevation` | [`Elevation`](types/elevation.md) (optional) | Elevation above sea level of the feature in meters. |
| `surface` | [`SurfaceMaterial`](types/surface_material.md) (optional) | |
| `names` | [`Names`](../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `level` | [`Level`](../core/level.md) (optional) | Z-order of the feature where 0 is visual level |
| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key-value pairs imported directly from the source data without change.This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. |
| `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `1e1f6095-5bd2-3fdb-a422-41351b848e9d` |
| `bbox.xmin` | `-176.56825256347656` |
| `bbox.xmax` | `-176.56231689453125` |
| `bbox.ymin` | `-43.96001052856445` |
| `bbox.ymax` | `-43.95420837402344` |
| `geometry` | `POLYGON ((-176.5623454 -43.9567812, -176.5627644 -43.9561272, -176.5626898 -43.9557432, -176.5624...` |
| `theme` | `base` |
| `type` | `land_use` |
| `version` | `0` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `w56117029@3` |
| `sources[0].update_time` | `2010-04-24T22:35:13.000Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `class` | `golf_course` |
| `subtype` | `golf` |
| `elevation` | `null` |
| `surface` | `null` |
| `names.primary` | `Chatham Islands Golf Club` |
| `names.common` | `null` |
| `names.rules` | `null` |
| `level` | `null` |
| `source_tags` | `{"LINZ:source_version": "V16", "attribution": "http://wiki.osm.org/wiki/Attribution#LINZ", "leisu...` |
| `wikidata` | `null` |

---

## Depth


Depth below surface level of the feature in meters.

Underlying type: `int32`

## Constraints

- `≥ 0`
- `≥ -2147483648` (from [`int32`](../../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../../system/primitive/primitives.md))

## Used By

- [`Bathymetry`](../bathymetry.md)

---

## Elevation


Elevation above sea level of the feature in meters.

Underlying type: `int32`

## Constraints

- `≤ 9000`
- `≥ -2147483648` (from [`int32`](../../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../../system/primitive/primitives.md))

## Used By

- [`Land`](../land.md)
- [`LandUse`](../land_use.md)

---

## Height


Height of the feature in meters.

Underlying type: `float64`

## Constraints

- `> 0`

## Used By

- [`Infrastructure`](../infrastructure.md)

---

## InfrastructureClass


Further classification of the type of infrastructure.

The infrastructure class adds detail to the broad classification of `InfrastructureSubtype`.

## Values

- `aerialway_station`
- `airport`
- `airport_gate`
- `airstrip`
- `apron`
- `aqueduct`
- `artwork`
- `atm`
- `barrier`
- `bell_tower`
- `bench`
- `bicycle_parking`
- `bicycle_rental`
- `block`
- `boardwalk`
- `bollard`
- `border_control`
- `breakwater`
- `bridge`
- `bridge_support`
- `bump_gate`
- `bus_route`
- `bus_station`
- `bus_stop`
- `bus_trap`
- `cable`
- `cable_barrier`
- `cable_car`
- `cable_distribution`
- `camp_site`
- `cantilever`
- `catenary_mast`
- `cattle_grid`
- `chain`
- `chair_lift`
- `charging_station`
- `city_wall`
- `communication_line`
- `communication_pole`
- `communication_tower`
- `connection`
- `cooling`
- `covered`
- `crossing`
- `cutline`
- `cycle_barrier`
- `dam`
- `defensive`
- `ditch`
- `diving`
- `drag_lift`
- `drain`
- `drinking_water`
- `entrance`
- `fence`
- `ferry_terminal`
- `fire_hydrant`
- `fountain`
- `full-height_turnstile`
- `gasometer`
- `gate`
- `generator`
- `give_way`
- `gondola`
- `goods`
- `guard_rail`
- `hampshire_gate`
- `handrail`
- `hedge`
- `height_restrictor`
- `heliostat`
- `helipad`
- `heliport`
- `hose`
- `information`
- `insulator`
- `international_airport`
- `j-bar`
- `jersey_barrier`
- `kerb`
- `kissing_gate`
- `launchpad`
- `lift_gate`
- `lighting`
- `lightning_protection`
- `magic_carpet`
- `manhole`
- `milestone`
- `military_airport`
- `minaret`
- `minor_line`
- `mixed_lift`
- `mobile_phone_tower`
- `monitoring`
- `motorcycle_parking`
- `motorway_junction`
- `movable`
- `municipal_airport`
- `observation`
- `parking`
- `parking_entrance`
- `parking_space`
- `pedestrian_crossing`
- `picnic_table`
- `pier`
- `pipeline`
- `plant`
- `planter`
- `platform`
- `platter`
- `portal`
- `post_box`
- `power_line`
- `power_pole`
- `power_tower`
- `private_airport`
- `pylon`
- `quay`
- `radar`
- `railway_halt`
- `railway_station`
- `recycling`
- `regional_airport`
- `reservoir_covered`
- `retaining_wall`
- `roller_coaster`
- `rope_tow`
- `runway`
- `sally_port`
- `seaplane_airport`
- `sewer`
- `silo`
- `siren`
- `stile`
- `stop`
- `stop_position`
- `stopway`
- `storage_tank`
- `street_cabinet`
- `street_lamp`
- `substation`
- `subway_station`
- `swing_gate`
- `switch`
- `t-bar`
- `taxilane`
- `taxiway`
- `terminal`
- `toilets`
- `toll_booth`
- `traffic_signals`
- `transformer`
- `trestle`
- `utility_pole`
- `vending_machine`
- `viaduct`
- `viewpoint`
- `wall`
- `waste_basket`
- `waste_disposal`
- `watchtower`
- `water_tower`
- `weir`
- `zip_line`

## Used By

- [`Infrastructure`](../infrastructure.md)

---

## InfrastructureSubtype


Broadest classification of the type of infrastructure.

This broad classification can be refined by `InfrastructureClass`.

## Values

- `aerialway`
- `airport`
- `barrier`
- `bridge`
- `communication`
- `emergency`
- `manhole`
- `pedestrian`
- `pier`
- `power`
- `quay`
- `recreation`
- `tower`
- `transit`
- `transportation`
- `utility`
- `waste_management`
- `water`

## Used By

- [`Infrastructure`](../infrastructure.md)

---

## LandClass


Further classification of the land.

The land class adds detail to the broad classification of `LandSubtype`.

## Values

- `archipelago`
- `bare_rock`
- `beach`
- `cave_entrance`
- `cliff`
- `desert`
- `dune`
- `fell`
- `forest`
- `glacier`
- `grass`
- `grassland`
- `heath`
- `hill`
- `island`
- `islet`
- `land`
- `meadow`
- `meteor_crater`
- `mountain_range`
- `peak`
- `peninsula`
- `plateau`
- `reef`
- `ridge`
- `rock`
- `saddle`
- `sand`
- `scree`
- `scrub`
- `shingle`
- `shrub`
- `shrubbery`
- `stone`
- `tree`
- `tree_row`
- `tundra`
- `valley`
- `volcanic_caldera_rim`
- `volcano`
- `wetland`
- `wood`

## Used By

- [`Land`](../land.md)

---

## LandCoverSubtype


Primary or dominant material covering the land.

## Values

- `barren`
- `crop`
- `forest`
- `grass`
- `mangrove`
- `moss`
- `shrub`
- `snow`
- `urban`
- `wetland`

## Used By

- [`LandCover`](../land_cover.md)

---

## LandSubtype


Broadest classification of the land.

This broad classification can be refined by `LandClass`.

## Values

- `crater`
- `desert`
- `forest`
- `glacier`
- `grass`
- `land`
- `physical`
- `reef`
- `rock`
- `sand`
- `shrub`
- `tree`
- `wetland`

## Used By

- [`Land`](../land.md)

---

## LandUseClass


Further classification of the land use.

The land use class adds detail to the broad classification of `LandUseSubtype`.

## Values

- `aboriginal_land`
- `airfield`
- `allotments`
- `animal_keeping`
- `aquaculture`
- `barracks`
- `base`
- `beach_resort`
- `brownfield`
- `bunker`
- `camp_site`
- `cemetery`
- `clinic`
- `college`
- `commercial`
- `connection`
- `construction`
- `danger_area`
- `doctors`
- `dog_park`
- `downhill`
- `driving_range`
- `driving_school`
- `education`
- `environmental`
- `fairway`
- `farmland`
- `farmyard`
- `fatbike`
- `flowerbed`
- `forest`
- `garages`
- `garden`
- `golf_course`
- `grass`
- `grave_yard`
- `green`
- `greenfield`
- `greenhouse_horticulture`
- `highway`
- `hike`
- `hospital`
- `ice_skate`
- `industrial`
- `institutional`
- `kindergarten`
- `landfill`
- `lateral_water_hazard`
- `logging`
- `marina`
- `meadow`
- `military`
- `military_hospital`
- `military_school`
- `music_school`
- `national_park`
- `natural_monument`
- `nature_reserve`
- `naval_base`
- `nordic`
- `nuclear_explosion_site`
- `obstacle_course`
- `orchard`
- `park`
- `peat_cutting`
- `pedestrian`
- `pitch`
- `plant_nursery`
- `playground`
- `plaza`
- `protected`
- `protected_landscape_seascape`
- `quarry`
- `railway`
- `range`
- `recreation_ground`
- `religious`
- `residential`
- `resort`
- `retail`
- `rough`
- `salt_pond`
- `school`
- `schoolyard`
- `ski_jump`
- `skitour`
- `sled`
- `sleigh`
- `snow_park`
- `species_management_area`
- `stadium`
- `state_park`
- `static_caravan`
- `strict_nature_reserve`
- `tee`
- `theme_park`
- `track`
- `traffic_island`
- `training_area`
- `trench`
- `university`
- `village_green`
- `vineyard`
- `water_hazard`
- `water_park`
- `wilderness_area`
- `winter_sports`
- `works`
- `zoo`

## Used By

- [`LandUse`](../land_use.md)

---

## LandUseSubtype


Broadest classification of the land use.

This broad classification can be refined by `LandUseClass`.

## Values

- `agriculture`
- `aquaculture`
- `campground`
- `cemetery`
- `construction`
- `developed`
- `education`
- `entertainment`
- `golf`
- `grass`
- `horticulture`
- `landfill`
- `managed`
- `medical`
- `military`
- `park`
- `pedestrian`
- `protected`
- `recreation`
- `religious`
- `residential`
- `resource_extraction`
- `transportation`
- `winter_sports`

## Used By

- [`LandUse`](../land_use.md)

---

## SourceTags


Key-value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from
OpenStreetMap.

Underlying type: `map<string, Any>`

## Used By

- [`Infrastructure`](../infrastructure.md)
- [`Land`](../land.md)
- [`LandUse`](../land_use.md)
- [`Water`](../water.md)

---

## SurfaceMaterial


Material that makes up the surface of `Infrastructure` and `Land` features.

## Values

- `asphalt`
- `cobblestone`
- `compacted`
- `concrete`
- `concrete_plates`
- `dirt`
- `earth`
- `fine_gravel`
- `grass`
- `gravel`
- `ground`
- `paved`
- `paving_stones`
- `pebblestone`
- `recreation_grass`
- `recreation_paved`
- `recreation_sand`
- `rubber`
- `sand`
- `sett`
- `tartan`
- `unpaved`
- `wood`
- `woodchips`

## Used By

- [`Infrastructure`](../infrastructure.md)
- [`Land`](../land.md)
- [`LandUse`](../land_use.md)

---

## WaterClass


Further description of the type of water body.

The water class adds detail to the broad classification of `WaterSubtype`.

## Values

- `basin`
- `bay`
- `blowhole`
- `canal`
- `cape`
- `ditch`
- `dock`
- `drain`
- `fairway`
- `fish_pass`
- `fishpond`
- `geyser`
- `hot_spring`
- `lagoon`
- `lake`
- `moat`
- `ocean`
- `oxbow`
- `pond`
- `reflecting_pool`
- `reservoir`
- `river`
- `salt_pond`
- `sea`
- `sewage`
- `shoal`
- `spring`
- `strait`
- `stream`
- `swimming_pool`
- `tidal_channel`
- `wastewater`
- `water`
- `water_storage`
- `waterfall`

## Used By

- [`Water`](../water.md)

---

## WaterSubtype


The broad classification of water body such as river, ocean or lake.

This broad classification can be refined using `WaterClass`.

## Values

- `canal`
- `human_made`
- `lake`
- `ocean`
- `physical`
- `pond`
- `reservoir`
- `river`
- `spring`
- `stream`
- `wastewater`
- `water`

## Used By

- [`Water`](../water.md)

---

## Water


Water features represent ocean and inland water bodies.

In Overture data releases, water features are sourced from OpenStreetMap. There are two main
categories of water feature: ocean and inland water bodies.

Ocean
-----
The `subytpe` value `"ocean"` indicates an ocean area feature whose geometry represents the
surface area of an ocean or part of an ocean. Ocean area may be tiled into many small polygons
of consistent complexity to ensure manageable geometry. In Overture data releases, ocean area
features are created from OpenStreetMap coastlines data (`natural=coastline`) using a QA'd
version of the output from the OSMCoastline tool. In aggregate, all the ocean area features
represent the inverse of the land features with subtype `"land"` and class `"land"`.

The names and recommended label position for oceans and seas can be found in features with the
subtype `"physical"` and the class `"ocean"` or `"sea"`.

Inland Water
------------
Subtypes other than `"ocean"` (and `"physical"`) represent inland water bodies. In Overture data
releases, these features are sourced from the OpenStreetMap tag `natural=*` where the tag value
indicates a water body, as well as the tags `natural=water`,  `waterway=*`,
and `water=*`.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Geometry of the water feature, which may be a point, line string, polygon, or multi-polygon.*Allowed geometry types: LineString, MultiPolygon, Point, Polygon* |
| `theme` | `"base"` | |
| `type` | `"water"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `class` | [`WaterClass`](types/water_class.md) (optional) | |
| `subtype` | [`WaterSubtype`](types/water_subtype.md) (optional) | |
| `is_intermittent` | `boolean` (optional) | Whether the water body exists intermittently, not permanently*`strict=True`* |
| `is_salt` | `boolean` (optional) | Whether the water body contains salt water*`strict=True`* |
| `level` | [`Level`](../core/level.md) (optional) | Z-order of the feature where 0 is visual level |
| `names` | [`Names`](../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key-value pairs imported directly from the source data without change.This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. |
| `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `6bbb5fe5-bf26-3efa-b120-0a7079b60840` |
| `bbox.xmin` | `-177.03179931640625` |
| `bbox.xmax` | `-177.0317840576172` |
| `bbox.ymin` | `-84.93480682373047` |
| `bbox.ymax` | `-84.9347915649414` |
| `geometry` | `POINT (-177.031799 -84.934793)` |
| `theme` | `base` |
| `type` | `water` |
| `version` | `0` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `n11109190647@2` |
| `sources[0].update_time` | `2024-02-11T05:52:05.000Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `class` | `cape` |
| `subtype` | `physical` |
| `is_intermittent` | `null` |
| `is_salt` | `null` |
| `level` | `null` |
| `names.primary` | `Thanksgiving Point` |
| `names.common` | `null` |
| `names.rules` | `null` |
| `source_tags` | `{"natural": "cape", "ref:linz:place_id": "13433"}` |
| `wikidata` | `Q33140589` |

---

## Building


Buildings are man-made structures with roofs that exist permanently in one place.

A building's geometry represents the two-dimensional footprint of the building as viewed from
directly above, looking down. Fields such as `height` and `num_floors` allow the
three-dimensional shape to be approximated. Some buildings, identified by the `has_parts` field,
have associated `BuildingPart` features which can be used to generate a more representative 3D
model of the building.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | The building's footprint or roofprint (if traced from aerial/satellite imagery).*Allowed geometry types: MultiPolygon, Polygon* |
| `theme` | `"buildings"` | |
| `type` | `"building"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `subtype` | [`BuildingSubtype`](types/building_subtype.md) (optional) | A broad classification of the current use and purpose of the building.If the current use of the building no longer accords with the original built purpose, the current use should be specified. For example, a building built as a train station but later converted into a shopping mall would have the value `"commercial"` rather than `"transportation"`. |
| `class` | [`BuildingClass`](types/building_class.md) (optional) | A more specific classification of the current use and purpose of the building.If the current use of the building no longer accords with the original built purpose, the current use should be specified. |
| `has_parts` | `boolean` (optional) | Whether the building has associated building part features*`strict=True`* |
| `names` | [`Names`](../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `level` | [`Level`](../core/level.md) (optional) | Z-order of the feature where 0 is visual level |
| `height` | [`float64`](../system/primitive/primitives.md) (optional) | Height of the building or part in meters.This is the distance from the lowest point to the highest point.*`> 0`* |
| `is_underground` | `boolean` (optional) | Whether the entire building or part is completely below ground.The underground flag is useful for display purposes. Buildings and building parts that are entirely below ground can be styled differently or omitted from the rendered image.This flag is conceptually different from the `level` field, which indicates relative z-ordering and, notably, can be negative even if the building is entirely above-ground.*`strict=True`* |
| `num_floors` | [`int32`](../system/primitive/primitives.md) (optional) | Number of above-ground floors of the building or part.*`> 0`* |
| `num_floors_underground` | [`int32`](../system/primitive/primitives.md) (optional) | Number of below-ground floors of the building or part.*`> 0`* |
| `min_height` | [`float64`](../system/primitive/primitives.md) (optional) | Altitude above ground where the bottom of the building or building part starts.If present, this value indicates that the lowest part of the building or building part starts is above ground level. |
| `min_floor` | [`int32`](../system/primitive/primitives.md) (optional) | Start floor of this building or part.If present, this value indicates that the building or part is "floating" and its bottom-most floor is above ground level, usually because it is part of a larger building in which some parts do reach down to ground level. An example is a building that has an entry road or driveway at ground level into an interior courtyard, where part of the building bridges above the entry road. This property may sometimes be populated when `min_height` is missing and in these cases can be used as a proxy for `min_height`.*`> 0`* |
| `facade_color` | [`HexColor`](../system/hex_color.md) (optional) | Facade color in `#rgb` or `#rrggbb` hex notation |
| `facade_material` | [`FacadeMaterial`](types/facade_material.md) (optional) | Outer surface material of the facade |
| `roof_material` | [`RoofMaterial`](types/roof_material.md) (optional) | Outer surface material of the roof |
| `roof_shape` | [`RoofShape`](types/roof_shape.md) (optional) | Shape of the roof |
| `roof_direction` | [`float64`](../system/primitive/primitives.md) (optional) | Bearing of the roof ridge line in degrees*`≥ 0`**`< 360`* |
| `roof_orientation` | [`RoofOrientation`](types/roof_orientation.md) (optional) | Orientation of the roof shape relative to the footprint shape |
| `roof_color` | [`HexColor`](../system/hex_color.md) (optional) | The roof color in `#rgb` or `#rrggbb` hex notation |
| `roof_height` | [`float64`](../system/primitive/primitives.md) (optional) | Height of the roof in meters.This is the distance from the base of the roof to its highest point. |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `148f35b1-7bc1-4180-9280-10d39b13883b` |
| `bbox.xmin` | `-176.643798828125` |
| `bbox.xmax` | `-176.64349365234375` |
| `bbox.ymin` | `-43.9938850402832` |
| `bbox.ymax` | `-43.993709564208984` |
| `geometry` | `POLYGON ((-176.6435004 -43.9938042, -176.6435738 -43.9937107, -176.6437726 -43.9937913, -176.6436...` |
| `theme` | `buildings` |
| `type` | `building` |
| `version` | `1` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `w519166507@1` |
| `sources[0].update_time` | `2017-08-27T21:39:50.000Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `subtype` | `null` |
| `class` | `null` |
| `has_parts` | `false` |
| `names` | `null` |
| `level` | `null` |
| `height` | `null` |
| `is_underground` | `false` |
| `num_floors` | `null` |
| `num_floors_underground` | `null` |
| `min_height` | `null` |
| `min_floor` | `null` |
| `facade_color` | `null` |
| `facade_material` | `null` |
| `roof_material` | `null` |
| `roof_shape` | `null` |
| `roof_direction` | `null` |
| `roof_orientation` | `null` |
| `roof_color` | `null` |
| `roof_height` | `null` |

---

## BuildingPart


Building parts represent parts of larger building features. They allow buildings to be modeled
in rich detail suitable for creating realistic 3D models.

Every building part is associated with a parent `Building` feature via the `building_id` field.
In addition, a building part has a footprint geometry and may include additional details such as
its height, the number of floors, and the color and material of its facade and roof.

Building parts can float or be stacked on top of each other. The `min_height`, `min_floor`,
`height`, and `num_floors`, fields can be used to arrange the parts correctly along the
vertical dimension.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | The footprint or roofprint of the building part.*Allowed geometry types: MultiPolygon, Polygon* |
| `theme` | `"buildings"` | |
| `type` | `"building_part"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `building_id` | [`Id`](../system/ref/id.md) | The building to which this part belongs*References [`Building`](building.md) (belongs to)* |
| `names` | [`Names`](../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `level` | [`Level`](../core/level.md) (optional) | Z-order of the feature where 0 is visual level |
| `height` | [`float64`](../system/primitive/primitives.md) (optional) | Height of the building or part in meters.This is the distance from the lowest point to the highest point.*`> 0`* |
| `is_underground` | `boolean` (optional) | Whether the entire building or part is completely below ground.The underground flag is useful for display purposes. Buildings and building parts that are entirely below ground can be styled differently or omitted from the rendered image.This flag is conceptually different from the `level` field, which indicates relative z-ordering and, notably, can be negative even if the building is entirely above-ground.*`strict=True`* |
| `num_floors` | [`int32`](../system/primitive/primitives.md) (optional) | Number of above-ground floors of the building or part.*`> 0`* |
| `num_floors_underground` | [`int32`](../system/primitive/primitives.md) (optional) | Number of below-ground floors of the building or part.*`> 0`* |
| `min_height` | [`float64`](../system/primitive/primitives.md) (optional) | Altitude above ground where the bottom of the building or building part starts.If present, this value indicates that the lowest part of the building or building part starts is above ground level. |
| `min_floor` | [`int32`](../system/primitive/primitives.md) (optional) | Start floor of this building or part.If present, this value indicates that the building or part is "floating" and its bottom-most floor is above ground level, usually because it is part of a larger building in which some parts do reach down to ground level. An example is a building that has an entry road or driveway at ground level into an interior courtyard, where part of the building bridges above the entry road. This property may sometimes be populated when `min_height` is missing and in these cases can be used as a proxy for `min_height`.*`> 0`* |
| `facade_color` | [`HexColor`](../system/hex_color.md) (optional) | Facade color in `#rgb` or `#rrggbb` hex notation |
| `facade_material` | [`FacadeMaterial`](types/facade_material.md) (optional) | Outer surface material of the facade |
| `roof_material` | [`RoofMaterial`](types/roof_material.md) (optional) | Outer surface material of the roof |
| `roof_shape` | [`RoofShape`](types/roof_shape.md) (optional) | Shape of the roof |
| `roof_direction` | [`float64`](../system/primitive/primitives.md) (optional) | Bearing of the roof ridge line in degrees*`≥ 0`**`< 360`* |
| `roof_orientation` | [`RoofOrientation`](types/roof_orientation.md) (optional) | Orientation of the roof shape relative to the footprint shape |
| `roof_color` | [`HexColor`](../system/hex_color.md) (optional) | The roof color in `#rgb` or `#rrggbb` hex notation |
| `roof_height` | [`float64`](../system/primitive/primitives.md) (optional) | Height of the roof in meters.This is the distance from the base of the roof to its highest point. |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `19412d64-51ac-3d6a-ac2f-8a8c8b91bb60` |
| `bbox.xmin` | `-73.24630737304688` |
| `bbox.xmax` | `-73.24613952636719` |
| `bbox.ymin` | `-39.81101608276367` |
| `bbox.ymax` | `-39.81088638305664` |
| `geometry` | `POLYGON ((-73.2462509 -39.8108937, -73.2462755 -39.8109047, -73.246291 -39.8109182, -73.2463022 -...` |
| `theme` | `buildings` |
| `type` | `building_part` |
| `version` | `0` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `w223076787@2` |
| `sources[0].update_time` | `2014-10-31T22:55:36.000Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `building_id` | `bd663bd4-1844-4d7d-a400-114de051cf49` |
| `names` | `null` |
| `level` | `3` |
| `height` | `null` |
| `is_underground` | `false` |
| `num_floors` | `null` |
| `num_floors_underground` | `null` |
| `min_height` | `null` |
| `min_floor` | `null` |
| `facade_color` | `null` |
| `facade_material` | `null` |
| `roof_material` | `null` |
| `roof_shape` | `null` |
| `roof_direction` | `null` |
| `roof_orientation` | `null` |
| `roof_color` | `null` |
| `roof_height` | `null` |

---

## BuildingClass


Further classification of the type and purpose of a building.

The building class adds detail to the broad classification of `BuildingSubtype`.

## Values

- `agricultural`
- `allotment_house`
- `apartments`
- `barn`
- `beach_hut`
- `boathouse`
- `bridge_structure`
- `bungalow`
- `bunker`
- `cabin`
- `carport`
- `cathedral`
- `chapel`
- `church`
- `civic`
- `college`
- `commercial`
- `cowshed`
- `detached`
- `digester`
- `dormitory`
- `dwelling_house`
- `factory`
- `farm`
- `farm_auxiliary`
- `fire_station`
- `garage`
- `garages`
- `ger`
- `glasshouse`
- `government`
- `grandstand`
- `greenhouse`
- `guardhouse`
- `hangar`
- `hospital`
- `hotel`
- `house`
- `houseboat`
- `hut`
- `industrial`
- `kindergarten`
- `kiosk`
- `library`
- `manufacture`
- `military`
- `monastery`
- `mosque`
- `office`
- `outbuilding`
- `parking`
- `pavilion`
- `post_office`
- `presbytery`
- `public`
- `religious`
- `residential`
- `retail`
- `roof`
- `school`
- `semi`
- `semidetached_house`
- `service`
- `shed`
- `shrine`
- `silo`
- `slurry_tank`
- `sports_centre`
- `sports_hall`
- `stable`
- `stadium`
- `static_caravan`
- `stilt_house`
- `storage_tank`
- `sty`
- `supermarket`
- `synagogue`
- `temple`
- `terrace`
- `toilets`
- `train_station`
- `transformer_tower`
- `transportation`
- `trullo`
- `university`
- `warehouse`
- `wayside_shrine`

## Used By

- [`Building`](../building.md)

---

## BuildingSubtype


Broadest classification of the type and purpose of a building.

This broad classification can be refined by `BuildingClass`.

## Values

- `agricultural`
- `civic`
- `commercial`
- `education`
- `entertainment`
- `industrial`
- `medical`
- `military`
- `outbuilding`
- `religious`
- `residential`
- `service`
- `transportation`

## Used By

- [`Building`](../building.md)

---

## FacadeMaterial


The outer surface material of building facade.

## Values

- `brick`
- `cement_block`
- `clay`
- `concrete`
- `glass`
- `metal`
- `plaster`
- `plastic`
- `stone`
- `timber_framing`
- `wood`

## Used By

- [`Building`](../building.md)
- [`BuildingPart`](../building_part.md)

---

## RoofMaterial


The outermost material of the roof.

## Values

- `concrete`
- `copper`
- `eternit`
- `glass`
- `grass`
- `gravel`
- `metal`
- `plastic`
- `roof_tiles`
- `slate`
- `solar_panels`
- `tar_paper`
- `thatch`
- `wood`

## Used By

- [`Building`](../building.md)
- [`BuildingPart`](../building_part.md)

---

## RoofOrientation


Orientation of the roof shape relative to the footprint shape.

The members of this enumeration, `"across"` and `"along"`, are borrowed from the OpenStreetMap
`roof:orientation=*` tag and have the same meanings as they do in OSM.

## Values

- `across` - The roof ridge runs perpendicular to the longer of the two building edges, parallel to the shorter
- `along` - The roof ridge runs parallel to the longer of the two building edges

## Used By

- [`Building`](../building.md)
- [`BuildingPart`](../building_part.md)

---

## RoofShape


The shape of the roof.

## Values

- `dome`
- `flat`
- `gabled`
- `gambrel`
- `half_hipped`
- `hipped`
- `mansard`
- `onion`
- `pyramidal`
- `round`
- `saltbox`
- `sawtooth`
- `skillion`
- `spherical`

## Used By

- [`Building`](../building.md)
- [`BuildingPart`](../building_part.md)

---

## CartographicHints


Cartographic hints for optimal use of Overture features in map-making.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `prominence` | [`Prominence`](prominence.md) (optional) | Subjective scale of feature significance or importance, with 1 being the least, and 100 being the most, significant.This value can be used to help drive decisions about how and when to display a feature, and how to treat it relative to neighboring features.When populated by Overture, this value is derived from various factors including, but not limited to: feature and subtype, population, and capital status. |
| `min_zoom` | [`MinZoom`](min_zoom.md) (optional) | Recommended minimum tile zoom level in which this feature should be displayed.It is recommended that the feature be hidden at zoom levels below this value.Zoom levels follow the Slippy Maps convention, documented in the following references: - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection |
| `max_zoom` | [`MaxZoom`](max_zoom.md) (optional) | Recommended maximum tile zoom level in which this feature should be displayed.It is recommended that the feature be hidden at zoom levels above this value.Zoom levels follow the Slippy Maps convention, documented in the following references: - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection |
| `sort_key` | [`SortKey`](sort_key.md) (optional) | Integer indicating the recommended order in which to draw features.Features with a lower number should be drawn "in front" of features with a higher number. |

## Used By

- [`Bathymetry`](../base/bathymetry.md)
- [`Division`](../divisions/division.md)
- [`LandCover`](../base/land_cover.md)

---

## CommonNames


A mapping from language to the most commonly used or recognized name in that language.

Underlying type: `map<`[`LanguageTag`](../system/language_tag.md)`,`[`StrippedString`](../system/stripped_string.md)`>`

## Used By

- [`Division`](../divisions/division.md)
- [`Names`](names.md)

---

## ConfidenceScore


Confidence score between 0.0 and 1.0

Underlying type: `float64`

## Constraints

- `≥ 0.0`
- `≤ 1.0`

## Used By

- [`Place`](../places/place.md)
- [`SourceItem`](source_item.md)

---

## FeatureVersion


Underlying type: `int32`

## Constraints

- `≥ 0`
- `≥ -2147483648` (from [`int32`](../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../system/primitive/primitives.md))

## Used By

- [`Address`](../addresses/address.md)
- [`Bathymetry`](../base/bathymetry.md)
- [`Building`](../buildings/building.md)
- [`BuildingPart`](../buildings/building_part.md)
- [`Connector`](../transportation/connector.md)
- [`Division`](../divisions/division.md)
- [`DivisionArea`](../divisions/division_area.md)
- [`DivisionBoundary`](../divisions/division_boundary.md)
- [`Infrastructure`](../base/infrastructure.md)
- [`Land`](../base/land.md)
- [`LandCover`](../base/land_cover.md)
- [`LandUse`](../base/land_use.md)
- [`Place`](../places/place.md)
- [`Segment`](../transportation/segment.md)
- [`Water`](../base/water.md)

---

## LengthUnit


Unit of length.

## Values

- `in` - One inch in the imperial and US customary systems
- `ft` - One foot in the imperial and US customary systems (12 inches)
- `yd` - One yard in the imperial and US customary systems (three feet)
- `mi` - One mile in the imperial and US customary systems (1,760 yards)
- `cm` - One centimeter in the metric and SI systems
- `m` - One meter in the metric and SI systems
- `km` - One kilometer in the metric and SI systems

## Used By

- [`VehicleHeightSelector`](scoping/vehicle_height_selector.md)
- [`VehicleLengthSelector`](scoping/vehicle_length_selector.md)
- [`VehicleWidthSelector`](scoping/vehicle_width_selector.md)

---

## Level


Z-order of the feature where 0 is visual level

Underlying type: `int32`

## Constraints

- `≥ -2147483648` (from [`int32`](../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../system/primitive/primitives.md))

## Used By

- [`Building`](../buildings/building.md)
- [`BuildingPart`](../buildings/building_part.md)
- [`Infrastructure`](../base/infrastructure.md)
- [`Land`](../base/land.md)
- [`LandUse`](../base/land_use.md)
- [`LevelRule`](../transportation/types/level_rule.md)
- [`Water`](../base/water.md)

---

## MaxZoom


Recommended maximum tile zoom level in which this feature should be displayed.

It is recommended that the feature be hidden at zoom levels above this value.

Zoom levels follow the Slippy Maps convention, documented in the following
references:
- [https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)
- [https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection](https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection)

Underlying type: `int32`

## Constraints

- `≥ 0`
- `≤ 23`
- `≥ -2147483648` (from [`int32`](../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../system/primitive/primitives.md))

## Used By

- [`CartographicHints`](cartographic_hints.md)

---

## MinZoom


Recommended minimum tile zoom level in which this feature should be displayed.

It is recommended that the feature be hidden at zoom levels below this value.

Zoom levels follow the Slippy Maps convention, documented in the following
references:
- [https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)
- [https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection](https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection)

Underlying type: `int32`

## Constraints

- `≥ 0`
- `≤ 23`
- `≥ -2147483648` (from [`int32`](../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../system/primitive/primitives.md))

## Used By

- [`CartographicHints`](cartographic_hints.md)

---

## NameRule


A rule that can be evaluated to determine the name in advanced scenarios.

Name rules are used for cases where the primary name is not sufficient; the common name is not
the right fit for the use case and another variant is needed; or where the name only applies in
certain specific circumstances.

Examples might include:
- An official, alternate, or short name.
- A name that only applies to part of a linear path like a road segment (geometric range
  scoping).
- A name that only applies to the left or right side of a linear path like a road segment (side
  scoping).
- A name that is only accepted by some political perspectives.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `value` | [`StrippedString`](../system/stripped_string.md) | The actual name value.*Minimum length: 1* |
| `variant` | [`NameVariant`](name_variant.md) | The name variant for this name rule. |
| `language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `perspectives` | [`Perspectives`](perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `perspectives.mode` | [`PerspectiveMode`](perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `between` | [`LinearlyReferencedRange`](scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `side` | [`Side`](scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |

## Used By

- [`Names`](names.md)

---

## NameVariant


Name variant used in a `NameRule`.

## Values

- `common` - The most commonly used or recognized name for a feature in the specified language.

In a `Names` value, most common names will appear in the `Names.common` field and will
not need to be specified as `NameRule` values in `Names.rules`. This member of the
enumeration should only be used to construct a `NameRule` if the common name needs to
be scoped in some way and therefore cannot be accurately represented in `CommonNames`.
- `official` - The legally or administratively recognized name, often used by government agencies or
official documents.
- `alternate` - An alternative name, which may be a historical name, a local colloquial name, or some
other well-known name is not the common name.
- `short` - An abbreviated or shortened version of the name, which may be an acronym or some other
commonly-used short form. An example is "NYC" for New York City.

## Used By

- [`NameRule`](name_rule.md)

---

## Names


Multilingual names container.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name.*Minimum length: 1* |
| `common` | [`CommonNames`](common_names.md) (map, optional) | |
| `rules[]` | `list<`[`NameRule`](name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `rules[].variant` | [`NameVariant`](name_variant.md) | The name variant for this name rule. |
| `rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `rules[].perspectives` | [`Perspectives`](perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `rules[].perspectives.mode` | [`PerspectiveMode`](perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `rules[].between` | [`LinearlyReferencedRange`](scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `rules[].side` | [`Side`](scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |

## Used By

- [`Brand`](../places/types/brand.md)
- [`Building`](../buildings/building.md)
- [`BuildingPart`](../buildings/building_part.md)
- [`Division`](../divisions/division.md)
- [`DivisionArea`](../divisions/division_area.md)
- [`Infrastructure`](../base/infrastructure.md)
- [`Land`](../base/land.md)
- [`LandUse`](../base/land_use.md)
- [`Place`](../places/place.md)
- [`Segment`](../transportation/segment.md)
- [`Water`](../base/water.md)

---

## PerspectiveMode


Perspective mode for disputed names.

## Values

- `accepted_by`
- `disputed_by`

## Used By

- [`Perspectives`](perspectives.md)

---

## Perspectives


Political perspectives container.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `mode` | [`PerspectiveMode`](perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |

## Used By

- [`Division`](../divisions/division.md)
- [`DivisionBoundary`](../divisions/division_boundary.md)
- [`NameRule`](name_rule.md)

---

## Prominence


Subjective scale of feature significance or importance, with 1 being the least, and
100 being the most, significant.

This value can be used to help drive decisions about how and when to display a
feature, and how to treat it relative to neighboring features.

When populated by Overture, this value is derived from various factors including,
but not limited to: feature and subtype, population, and capital status.

Underlying type: `int32`

## Constraints

- `≥ 1`
- `≤ 100`
- `≥ -2147483648` (from [`int32`](../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../system/primitive/primitives.md))

## Used By

- [`CartographicHints`](cartographic_hints.md)

---

## Heading


Travel direction along an oriented path: forward or backward.

## Values

- `forward`
- `backward`

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`DestinationRule`](../../transportation/types/destination_rule.md)
- [`DestinationRule.When`](../../transportation/types/destination_rule.when.md)
- [`ProhibitedTransitionRule`](../../transportation/types/prohibited_transition_rule.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## LinearlyReferencedPosition


Represents a linearly-referenced position between 0% and 100% of the distance along a path such as a road segment or a river center-line segment.

Underlying type: `float64`

## Constraints

- `≥ 0.0`
- `≤ 1.0`

## Used By

- [`ConnectorReference`](../../transportation/types/connector_reference.md)
- [`LinearlyReferencedRange`](linearly_referenced_range.md)

---

## LinearlyReferencedRange


Represents a non-empty range of positions along a path as a pair linearly-referenced positions. For example, the pair [0.25, 0.5] represents the range beginning 25% of the distance from the start of the path and ending 50% of the distance from the path

Underlying type: `list<float64>`

## Constraints

- Linear reference range constraint (0.0 to 1.0). (`LinearReferenceRangeConstraint`)
- `≥ 0.0` (from [`LinearlyReferencedPosition`](linearly_referenced_position.md))
- `≤ 1.0` (from [`LinearlyReferencedPosition`](linearly_referenced_position.md))

## Used By

- [`AccessRestrictionRule`](../../transportation/types/access_restriction_rule.md)
- [`LevelRule`](../../transportation/types/level_rule.md)
- [`NameRule`](../name_rule.md)
- [`ProhibitedTransitionRule`](../../transportation/types/prohibited_transition_rule.md)
- [`RailFlagRule`](../../transportation/types/rail_flag_rule.md)
- [`RoadFlagRule`](../../transportation/types/road_flag_rule.md)
- [`RouteReference`](../../transportation/types/route_reference.md)
- [`SourceItem`](../source_item.md)
- [`SpeedLimitRule`](../../transportation/types/speed_limit_rule.md)
- [`SubclassRule`](../../transportation/types/subclass_rule.md)
- [`SurfaceRule`](../../transportation/types/surface_rule.md)
- [`WidthRule`](../../transportation/types/width_rule.md)

---

## OpeningHours


Time span or time spans during which something is open or active, specified in the OpenStreetMap
opening hours specification: [https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification](https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification).

Underlying type: `string`

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## PurposeOfUse


Reason why a person or entity travelling on the transportation network is using a particular
location.

## Values

- `as_customer`
- `at_destination`
- `to_deliver`
- `to_farm`
- `for_forestry`

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## RecognizedStatus


Status of the person or entity travelling as recognized by authorities controlling the particular
location.

## Values

- `as_permitted`
- `as_private`
- `as_disabled`
- `as_employee`
- `as_student`

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## Side


The side, left or right, on which something appears relative to a facing or heading direction
(*e.g.*, the side of a road relative to the road orientation), or relative to the direction of
travel of a person or vehicle.

## Values

- `left` - On the left relative to the facing direction
- `right` - On the right side relative to the facing direction

## Used By

- [`NameRule`](../name_rule.md)
- [`Norms`](../../divisions/types/division/norms.md)

---

## TravelMode


Enumerates possible travel modes.

Some modes represent groups of modes.

## Values

- `vehicle`
- `motor_vehicle`
- `car`
- `truck`
- `motorcycle`
- `foot`
- `bicycle`
- `bus`
- `hgv`
- `hov`
- `emergency`

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## VehicleAxleCountSelector


Selects vehicles based on the number of axles they have.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `dimension` | `"axle_count"` | |
| `comparison` | [`VehicleRelation`](vehicle_relation.md) | |
| `value` | [`uint8`](../../system/primitive/primitives.md) | Number of axles on the vehicle |

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## VehicleHeightSelector


Selects vehicles based on their height.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `dimension` | `"height"` | |
| `comparison` | [`VehicleRelation`](vehicle_relation.md) | |
| `value` | [`float64`](../../system/primitive/primitives.md) | Vehicle height selection threshold in the given `unit`*`≥ 0`* |
| `unit` | [`LengthUnit`](../length_unit.md) | Height unit in which `value` is expressed |

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## VehicleLengthSelector


Selects vehicles based on their length.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `dimension` | `"length"` | |
| `comparison` | [`VehicleRelation`](vehicle_relation.md) | |
| `value` | [`float64`](../../system/primitive/primitives.md) | Vehicle length selection threshold in the given `unit`*`≥ 0`* |
| `unit` | [`LengthUnit`](../length_unit.md) | Length unit in which `value` is expressed |

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## VehicleRelation


Relational operator, such as less than or equal to.

## Values

- `greater_than`
- `greater_than_equal`
- `equal`
- `less_than`
- `less_than_equal`

## Used By

- [`VehicleAxleCountSelector`](vehicle_axle_count_selector.md)
- [`VehicleHeightSelector`](vehicle_height_selector.md)
- [`VehicleLengthSelector`](vehicle_length_selector.md)
- [`VehicleWeightSelector`](vehicle_weight_selector.md)
- [`VehicleWidthSelector`](vehicle_width_selector.md)

---

## VehicleWeightSelector


Selects vehicles based on their weight.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `dimension` | `"weight"` | |
| `comparison` | [`VehicleRelation`](vehicle_relation.md) | |
| `value` | [`float64`](../../system/primitive/primitives.md) | Vehicle weight selection threshold in the given `unit`*`≥ 0`* |
| `unit` | [`WeightUnit`](../weight_unit.md) | Weight unit in which `value` is expressed |

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## VehicleWidthSelector


Selects vehicles based on their width.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `dimension` | `"width"` | |
| `comparison` | [`VehicleRelation`](vehicle_relation.md) | |
| `value` | [`float64`](../../system/primitive/primitives.md) | Vehicle width selection threshold in the given `unit`*`≥ 0`* |
| `unit` | [`LengthUnit`](../length_unit.md) | Width unit in which `value` is expressed |

## Used By

- [`AccessRestrictionRule.When`](../../transportation/types/access_restriction_rule.when.md)
- [`ProhibitedTransitionRule.When`](../../transportation/types/prohibited_transition_rule.when.md)
- [`SpeedLimitRule.When`](../../transportation/types/speed_limit_rule.when.md)

---

## SortKey


Integer indicating the recommended order in which to draw features.

Features with a lower number should be drawn "in front" of features with a higher
number.

Underlying type: `int32`

## Constraints

- `≥ -2147483648` (from [`int32`](../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../system/primitive/primitives.md))

## Used By

- [`CartographicHints`](cartographic_hints.md)

---

## SourceItem


Specifies the source of the data used for a feature or one of its properties.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `dataset` | `string` | Name of the dataset where the source data can be found. |
| `license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `update_time` | `datetime` (optional) | Last update time of the source data record. |
| `confidence` | [`ConfidenceScore`](confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `between` | [`LinearlyReferencedRange`](scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |

## Used By

- [`Address`](../addresses/address.md)
- [`Bathymetry`](../base/bathymetry.md)
- [`Building`](../buildings/building.md)
- [`BuildingPart`](../buildings/building_part.md)
- [`Connector`](../transportation/connector.md)
- [`Division`](../divisions/division.md)
- [`DivisionArea`](../divisions/division_area.md)
- [`DivisionBoundary`](../divisions/division_boundary.md)
- [`Infrastructure`](../base/infrastructure.md)
- [`Land`](../base/land.md)
- [`LandCover`](../base/land_cover.md)
- [`LandUse`](../base/land_use.md)
- [`Place`](../places/place.md)
- [`Segment`](../transportation/segment.md)
- [`Water`](../base/water.md)
- [`Sources`](sources.md)

---

## Sources


Information about the source data used to assemble the feature.

Underlying type: `list<`[`SourceItem`](source_item.md)`>`

## Constraints

- Minimum length: 1
- All items must be unique. (`UniqueItemsConstraint`)

## Used By

- [`Address`](../addresses/address.md)
- [`Bathymetry`](../base/bathymetry.md)
- [`Building`](../buildings/building.md)
- [`BuildingPart`](../buildings/building_part.md)
- [`Connector`](../transportation/connector.md)
- [`Division`](../divisions/division.md)
- [`DivisionArea`](../divisions/division_area.md)
- [`DivisionBoundary`](../divisions/division_boundary.md)
- [`Infrastructure`](../base/infrastructure.md)
- [`Land`](../base/land.md)
- [`LandCover`](../base/land_cover.md)
- [`LandUse`](../base/land_use.md)
- [`Place`](../places/place.md)
- [`Segment`](../transportation/segment.md)
- [`Water`](../base/water.md)

---

## SpeedUnit


Unit of speed.

## Values

- `mph` - Miles per hour
- `km/h` - Kilometers per hour

## Used By

- [`Speed`](../transportation/types/speed.md)

---

## WeightUnit


Unit of weight.

## Values

- `oz` - One ounce in the imperial and US customary systems
- `lb` - One pound in the imperial and US customary systems
- `st` - One short ton, or one ton in the US customary system (2,000 pounds)
- `lt` - One long ton, or one ton in the imperial system (2,400 pounds)
- `g` - One gram in the metric and SI systems
- `kg` - One kilogram in the metric and SI systems
- `t` - One tonne in the metric and SI systems

## Used By

- [`VehicleWeightSelector`](scoping/vehicle_weight_selector.md)

---

## Division


Divisions are recognized official or non-official organizations of people as seen
from a given political perspective.

Examples include countries, provinces, cities, towns, neighborhoods, etc.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `cartography` | [`CartographicHints`](../core/cartographic_hints.md) (optional) | |
| `cartography.prominence` | [`Prominence`](../core/prominence.md) (optional) | Subjective scale of feature significance or importance, with 1 being the least, and 100 being the most, significant.This value can be used to help drive decisions about how and when to display a feature, and how to treat it relative to neighboring features.When populated by Overture, this value is derived from various factors including, but not limited to: feature and subtype, population, and capital status. |
| `cartography.min_zoom` | [`MinZoom`](../core/min_zoom.md) (optional) | Recommended minimum tile zoom level in which this feature should be displayed.It is recommended that the feature be hidden at zoom levels below this value.Zoom levels follow the Slippy Maps convention, documented in the following references: - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection |
| `cartography.max_zoom` | [`MaxZoom`](../core/max_zoom.md) (optional) | Recommended maximum tile zoom level in which this feature should be displayed.It is recommended that the feature be hidden at zoom levels above this value.Zoom levels follow the Slippy Maps convention, documented in the following references: - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection |
| `cartography.sort_key` | [`SortKey`](../core/sort_key.md) (optional) | Integer indicating the recommended order in which to draw features.Features with a lower number should be drawn "in front" of features with a higher number. |
| `names` | [`Names`](../core/names.md) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Approximate location of a position commonly associated with the real-world entity modeled by the division feature.*Allowed geometry types: Point* |
| `theme` | `"divisions"` | |
| `type` | `"division"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `subtype` | [`PlaceType`](types/place_type.md) | *`admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`**`parent_division_id` is required when `subtype` ≠ `country`**`parent_division_id` is forbidden when `subtype` = `country`* |
| `country` | [`CountryCodeAlpha2`](../system/country_code_alpha2.md) | ISO 3166-1 alpha-2 country code of the country or country-like entity, that this division represents or belongs to.If the entity this division represents has a country code, the country property contains it. If it does not, the country property contains the country code of the first division encountered by traversing the parent_division_id chain to the root.For example:     - The country value for the United States is 'US'     - The country value for New York City is 'US'     - The country value for Puerto Rico, a dependency of the US,     is 'PR'.     - The country value for San Juan, Puerto Rico is 'PR'.If an entity has an internationally-recognized ISO 3166-1 alpha-2 country code, it should always be used. In cases where the schema requires the code but no internationally-recognized code is available, a synthetic code may be used provided it does not conflict with any internationally-recognized codes. |
| `hierarchies[][]` | `list<`[`Hierarchy`](types/hierarchy.md)`>` | Hierarchies in which this division participates.Every division participates in at least one hierarchy. Most participate in only one. Some divisions may participate in more than one hierarchy, for example if they are claimed by different parent divisions from different political perspectives; or if there are other real-world reasons why the division or one of its ancestors has multiple parents.The first hierarchy in the list is the default hierarchy, and the second-to-last entry in the default hierarchy (if there is such an entry) always corresponds to the `parent_division_id' property. The ordering of hierarchies after the first one is arbitrary.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `hierarchies[][].division_id` | [`DivisionId`](types/division_id.md) | ID of the division |
| `hierarchies[][].subtype` | [`PlaceType`](types/place_type.md) | |
| `hierarchies[][].name` | [`StrippedString`](../system/stripped_string.md) | Primary name of the division |
| `parent_division_id` | [`Id`](../system/ref/id.md) (optional) | Division ID of this division's parent division.Not allowed for top-level divisions (countries) and required for all other divisions.The default parent division is the parent division as seen from the default political perspective, if there is one, and is otherwise chosen somewhat arbitrarily. The hierarchies property can be used to inspect the exhaustive list of parent divisions.*Minimum length: 1**`parent_division_id` is required when `subtype` ≠ `country`**`parent_division_id` is forbidden when `subtype` = `country`* |
| `admin_level` | [`AdminLevel`](types/admin_level.md) (optional) | Integer representing the division's position in its country's administrative hierarchy, where lower numbers correspond to higher level administrative units.*`admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`* |
| `class` | [`DivisionClass`](types/division_class.md) (optional) | |
| `local_type` | [`CommonNames`](../core/common_names.md) (map, optional) | Local name for the subtype property, optionally localized.For example, the Canadian province of Quebec has the subtype 'region', but in the local administrative hierarchy it is referred to as a 'province'. Similarly, the Canadian Yukon territory also has subtype 'region', but is locally called a 'territory'.This property is localized using a standard Overture names structure. So for example, in Switzerland the top-level administrative subdivision corresponding to subtype 'region' is the canton, which is may be translated in each of Switzerland's official languages as, 'canton' in French, 'kanton' in German, 'cantone' in Italian, and 'chantun' in Romansh. |
| `region` | [`RegionCode`](../system/region_code.md) (optional) | ISO 3166-2 principal subdivision code of the subdivision-like entity this division represents or belongs to.If the entity this division represents has a principal subdivision code, the region property contains it. If it does not, the region property contains the principal subdivision code of the first division encountered by traversing the parent_division_id chain to the root.For example:     - The region value for the United States is omitted.     - The region value for the U.S. state of New York is 'US-NY'.     - The region value for New York City is 'US-NY', which it     inherits from the state of New York.     - The region value for Puerto Rico is 'US-PR'. |
| `perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which this division is considered to be an accurate representation.If this property is absent, then this division is not known to be disputed from any political perspective. Consequently, there is only one division feature representing the entire real world entity.If this property is present, it means the division represents one of several alternative perspectives on the same real-world entity.There are two modes of perspective:1. `accepted_by` means the representation of the division is accepted by the listed entities and would be included on a map drawn from their perspective.2. `disputed_by` means the representation of the division is disputed by the listed entities and would be excluded from a map drawn from their perspective.When drawing a map from the perspective of a given country, one would start by gathering all the undisputed divisions (with no `perspectives` property), and then adding to that first all divisions explicitly accepted by the country, and second all divisions not explicitly disputed by the country. |
| `perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `norms` | [`Norms`](types/division/norms.md) (optional) | Collects information about local norms and rules within the division that are generally useful for mapping and map-related use cases.If the norms property or a desired sub-property of the norms property is missing on a division, but at least one of its ancestor divisions has the norms property and the desired sub-property, then the value from the nearest ancestor division may be assumed. |
| `norms.driving_side` | [`Side`](../core/scoping/side.md) (optional) | Side of the road on which vehicles drive in the division. |
| `population` | [`int32`](../system/primitive/primitives.md) (optional) | Population of the division*`≥ 0`* |
| `capital_division_ids` | `list<`[`Id`](../system/ref/id.md)`>` (optional) | Division IDs of this division's capital divisions. If present, this property will refer to the division IDs of the capital cities, county seats, etc. of a division.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `capital_of_divisions[]` | `list<`[`CapitalOfDivisionItem`](types/capital_of_division_item.md)`>` (optional) | Division IDs and subtypes of divisions this division is a capital of.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `capital_of_divisions[].division_id` | [`DivisionId`](types/division_id.md) | ID of the division |
| `capital_of_divisions[].subtype` | [`PlaceType`](types/place_type.md) | |
| `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |

## Constraints

- `admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`
- `parent_division_id` is required when `subtype` ≠ `country`
- `parent_division_id` is forbidden when `subtype` = `country`

## Examples

| Column | Value |
| -------: | ------- |
| `cartography.prominence` | `29` |
| `cartography.min_zoom` | `null` |
| `cartography.max_zoom` | `null` |
| `cartography.sort_key` | `null` |
| `names.primary` | `Sia'atoutai` |
| `names.common` | `null` |
| `id` | `350e85f6-68ba-4114-9906-c2844815988b` |
| `bbox.xmin` | `-175.25515747070312` |
| `bbox.xmax` | `-175.255126953125` |
| `bbox.ymin` | `-21.1353702545166` |
| `bbox.ymax` | `-21.13536834716797` |
| `geometry` | `POINT (-175.2551522 -21.1353686)` |
| `theme` | `divisions` |
| `type` | `division` |
| `version` | `1` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `n3173231082@4` |
| `sources[0].update_time` | `2014-12-18T09:17:03Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `subtype` | `locality` |
| `country` | `TO` |
| `hierarchies[0][0].division_id` | `fef8748b-0c91-46ad-9f2d-976d8d2de3e9` |
| `hierarchies[0][0].subtype` | `country` |
| `hierarchies[0][0].name` | `Tonga` |
| `hierarchies[0][1].division_id` | `4d67561a-2292-41bd-8996-7853d276a42c` |
| `hierarchies[0][1].subtype` | `region` |
| `hierarchies[0][1].name` | `Tongatapu` |
| `hierarchies[0][2].division_id` | `8730f0cc-d436-4f11-a7d3-49085813ef44` |
| `hierarchies[0][2].subtype` | `county` |
| `hierarchies[0][2].name` | `Vahe Kolomotu'a` |
| `hierarchies[0][3].division_id` | `350e85f6-68ba-4114-9906-c2844815988b` |
| `hierarchies[0][3].subtype` | `locality` |
| `hierarchies[0][3].name` | `Sia'atoutai` |
| `parent_division_id` | `8730f0cc-d436-4f11-a7d3-49085813ef44` |
| `class` | `village` |
| `local_type` | `{"en": "village"}` |
| `region` | `TO-04` |
| `perspectives` | `null` |
| `norms` | `null` |
| `population` | `534` |
| `capital_division_ids` | `null` |
| `capital_of_divisions` | `null` |
| `wikidata` | `null` |
| `names.rules[0].variant` | `alternate` |
| `names.rules[0].language` | `null` |
| `names.rules[0].perspectives` | `null` |
| `names.rules[0].value` | `Nafualu` |
| `names.rules[0].between` | `null` |
| `names.rules[0].side` | `null` |

---

## DivisionArea


Division areas are polygons that represent the land or maritime area covered by a
division.

Each division area belongs to a division which it references by ID, and for which
the division area provides an area polygon. For ease of use, every division area
repeats the subtype, names, country, and region properties of the division it
belongs to.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `names` | [`Names`](../core/names.md) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | The area covered by the division with which this area feature is associated*Allowed geometry types: MultiPolygon, Polygon* |
| `theme` | `"divisions"` | |
| `type` | `"division_area"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `subtype` | [`PlaceType`](types/place_type.md) | *`admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`* |
| `class` | [`AreaClass`](types/division_area/area_class.md) | |
| `is_land` | `boolean` (optional) | A boolean to indicate whether or not the feature geometry represents the land-clipped, non-maritime boundary. The geometry can be used for map rendering, cartographic display, and similar purposes.*`strict=True`**Exactly one of `is_land`, `is_territorial` must be `true`* |
| `is_territorial` | `boolean` (optional) | A boolean to indicate whether or not the feature geometry represents Overture's best approximation of this place's maritime boundary. For coastal places, this would tend to include the water area. The geometry can be used for data processing, reverse-geocoding, and similar purposes.*`strict=True`**Exactly one of `is_land`, `is_territorial` must be `true`* |
| `division_id` | [`Id`](../system/ref/id.md) | Division ID of the division this area belongs to.*References [`Division`](division.md) (belongs to)* |
| `country` | [`CountryCodeAlpha2`](../system/country_code_alpha2.md) | ISO 3166-1 alpha-2 country code of the division this area belongs to. |
| `region` | [`RegionCode`](../system/region_code.md) (optional) | ISO 3166-2 principal subdivision code of the division this area belongs to. |
| `admin_level` | [`AdminLevel`](types/admin_level.md) (optional) | Integer representing the division's position in its country's administrative hierarchy, where lower numbers correspond to higher level administrative units.*`admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`* |

## Constraints

- Exactly one of `is_land`, `is_territorial` must be `true`
- `admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`

## Examples

| Column | Value |
| -------: | ------- |
| `names.primary` | `ʻEua` |
| `names.common` | `null` |
| `names.rules` | `null` |
| `id` | `eb9b112f-ec3c-47f7-b519-6f9f2e6fc2bd` |
| `bbox.xmin` | `-174.97535705566406` |
| `bbox.xmax` | `-174.90040588378906` |
| `bbox.ymin` | `-21.473018646240234` |
| `bbox.ymax` | `-21.283489227294922` |
| `geometry` | `MULTIPOLYGON (((-174.9553949 -21.4730179, -174.9514163 -21.4719978, -174.9520108 -21.4681253, -17...` |
| `theme` | `divisions` |
| `type` | `division_area` |
| `version` | `2` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `r7247527@3` |
| `sources[0].update_time` | `2020-12-30T18:41:56Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `subtype` | `region` |
| `class` | `land` |
| `is_land` | `true` |
| `is_territorial` | `false` |
| `division_id` | `21597af0-b564-463c-a356-42c29e712b7d` |
| `country` | `TO` |
| `region` | `TO-01` |

---

## DivisionBoundary


Boundaries represent borders between divisions of the same subtype.

Some boundaries may be disputed by the divisions on one or both sides.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Boundary line or lines*Allowed geometry types: LineString, MultiLineString* |
| `theme` | `"divisions"` | |
| `type` | `"division_boundary"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `subtype` | [`PlaceType`](types/place_type.md) | *`admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`**`country` is required when `subtype` ≠ `country`**`country` is forbidden when `subtype` = `country`* |
| `class` | [`BoundaryClass`](types/division_boundary/boundary_class.md) | |
| `is_land` | `boolean` (optional) | A boolean to indicate whether or not the feature geometry represents the land-clipped, non-maritime boundary. The geometry can be used for map rendering, cartographic display, and similar purposes.*`strict=True`**Exactly one of `is_land`, `is_territorial` must be `true`* |
| `is_territorial` | `boolean` (optional) | A boolean to indicate whether or not the feature geometry represents Overture's best approximation of this place's maritime boundary. For coastal places, this would tend to include the water area. The geometry can be used for data processing, reverse-geocoding, and similar purposes.*`strict=True`**Exactly one of `is_land`, `is_territorial` must be `true`* |
| `division_ids` | `list<`[`Id`](../system/ref/id.md)`>` | Identifies the two divisions to the left and right, respectively, of the boundary line. The left- and right-hand sides of the boundary are considered from the perspective of a person standing on the line facing in the direction in which the geometry is oriented, i.e. facing toward the end of the line.The first array element is the Overture ID of the left division. The second element is the Overture ID of the right division.*References [`Division`](division.md) (boundary of)**Minimum length: 2**Maximum length: 2**All items must be unique. (`UniqueItemsConstraint`)* |
| `country` | [`CountryCodeAlpha2`](../system/country_code_alpha2.md) (optional) | ISO 3166-1 alpha-2 country code of the country or country-like entity that both sides of the boundary share.This property will be present on boundaries between two regions, counties, or similar entities within the same country, but will not be present on boundaries between two countries or country-like entities.*`country` is required when `subtype` ≠ `country`**`country` is forbidden when `subtype` = `country`* |
| `region` | [`RegionCode`](../system/region_code.md) (optional) | ISO 3166-2 principal subdivision code of the subdivision-like entity that both sides of the boundary share.This property will be present on boundaries between two counties, localadmins or similar entities within the same principal subdivision, but will not be present on boundaries between different principal subdivisions or countries. |
| `admin_level` | [`AdminLevel`](types/admin_level.md) (optional) | Integer representing the division's position in its country's administrative hierarchy, where lower numbers correspond to higher level administrative units.*`admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`* |
| `is_disputed` | `boolean` (optional) | Indicator if there are entities disputing this division boundary. Information about entities disputing this boundary should be included in perspectives property.This property should also be true if boundary between two entities is unclear and this is "best guess". So having it true and no perspectives gives map creators reason not to fully trust the boundary, but use it if they have no other.*`strict=True`* |
| `perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which this division boundary is considered to be an accurate representation.If this property is absent, then this boundary is not known to be disputed from any political perspective. Consequently, there is only one boundary feature representing the entire real world entity.If this property is present, it means the boundary represents one of several alternative perspectives on the same real-world entity.There are two modes of perspective:  1. `accepted_by` means the representation of the boundary is accepted by the listed entities and would be included on a map drawn from their perspective.  2. `disputed_by` means the representation of the boundary is disputed by the listed entities and would be excluded from a map drawn from their perspective.When drawing a map from the perspective of a given country, one would start by gathering all the undisputed boundary (with no `perspectives` property), and then adding to that first all boundary explicitly accepted by the country, and second all boundary not explicitly disputed by the country. |
| `perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |

## Constraints

- Exactly one of `is_land`, `is_territorial` must be `true`
- `admin_level` is required when `subtype` is one of: `county`, `macrocounty`, `region`, `macroregion`, `dependency`, `country`
- `country` is required when `subtype` ≠ `country`
- `country` is forbidden when `subtype` = `country`

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `2bdf68e4-860d-3d8c-a472-ccf439a5302a` |
| `bbox.xmin` | `-147.06483459472656` |
| `bbox.xmax` | `-147.04847717285156` |
| `bbox.ymin` | `-15.4231538772583` |
| `bbox.ymax` | `-15.151169776916504` |
| `geometry` | `LINESTRING (-147.064823 -15.4231537, -147.0519131 -15.2885069, -147.048482 -15.1511701)` |
| `theme` | `divisions` |
| `type` | `division_boundary` |
| `version` | `1` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `r6063055@9` |
| `sources[0].update_time` | `2023-07-20T00:28:40Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `sources[1].property` |  |
| `sources[1].dataset` | `OpenStreetMap` |
| `sources[1].record_id` | `r6063063@12` |
| `sources[1].update_time` | `2023-07-20T00:28:40Z` |
| `sources[1].confidence` | `null` |
| `sources[1].between` | `null` |
| `subtype` | `county` |
| `class` | `maritime` |
| `is_land` | `false` |
| `is_territorial` | `true` |
| `division_ids` | `["ae266459-63a4-4508-8295-0101e27d039b", "d4a6873d-885a-4f2a-bc0f-37e9d9e874e4"]` |
| `country` | `PF` |
| `region` | `null` |
| `is_disputed` | `false` |
| `perspectives` | `null` |

---

## AdminLevel


Integer representing the division's position in its country's administrative hierarchy, where lower numbers correspond to higher level administrative units.

Underlying type: `uint8`

## Constraints

- `≥ 0` (from [`uint8`](../../system/primitive/primitives.md))
- `≤ 255` (from [`uint8`](../../system/primitive/primitives.md))

## Used By

- [`Division`](../division.md)
- [`DivisionArea`](../division_area.md)
- [`DivisionBoundary`](../division_boundary.md)

---

## CapitalOfDivisionItem


One division that has capital.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `division_id` | [`DivisionId`](division_id.md) | ID of the division |
| `subtype` | [`PlaceType`](place_type.md) | |

## Used By

- [`Division`](../division.md)

---

## Norms


Local norms and standards.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `driving_side` | [`Side`](../../../core/scoping/side.md) (optional) | Side of the road on which vehicles drive in the division. |

## Used By

- [`Division`](../../division.md)

---

## AreaClass


Area and boundary class designations.

## Values

- `land`
- `maritime`

## Used By

- [`DivisionArea`](../../division_area.md)

---

## BoundaryClass


## Values

- `land`
- `maritime`

## Used By

- [`DivisionBoundary`](../../division_boundary.md)

---

## DivisionClass


Division-specific class designations.

## Values

- `megacity`
- `city`
- `town`
- `village`
- `hamlet`

## Used By

- [`Division`](../division.md)

---

## DivisionId


ID of the division

Underlying type: `string`

## Constraints

- Minimum length: 1
- Minimum length: 1 (from [`Id`](../../system/ref/id.md))
- Allows only strings that contain no whitespace characters. (`NoWhitespaceConstraint`, pattern: `^\S+$`) (from [`NoWhitespaceString`](../../system/no_whitespace_string.md))

## Used By

- [`CapitalOfDivisionItem`](capital_of_division_item.md)
- [`HierarchyItem`](hierarchy_item.md)

---

## Hierarchy


A hierarchy of divisions, with the first entry being a country; each subsequent entry, if any, being a division that is a direct child of the previous entry; and the last entry representing the division that contains the hierarchy.

For example, a hierarchy for the United States is simply [United States]. A hierarchy for the U.S. state of New Hampshire would be [United States, New Hampshire], and a hierarchy for the city of Concord, NH would be [United States, New Hampshire, Merrimack County, Concord].

Underlying type: `list<`[`HierarchyItem`](hierarchy_item.md)`>`

## Constraints

- Minimum length: 1
- All items must be unique. (`UniqueItemsConstraint`)

## Used By

- [`Division`](../division.md)

---

## HierarchyItem


One division in a hierarchy.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `division_id` | [`DivisionId`](division_id.md) | ID of the division |
| `subtype` | [`PlaceType`](place_type.md) | |
| `name` | [`StrippedString`](../../system/stripped_string.md) | Primary name of the division*Minimum length: 1* |

## Used By

- [`Division`](../division.md)
- [`Hierarchy`](hierarchy.md)

---

## PlaceType


Category of the division from a finite, hierarchical, ordered list of categories (e.g., country,
region, locality, etc.) similar to a Who's on First placetype.

## Values

- `country`
- `dependency`
- `macroregion`
- `region`
- `macrocounty`
- `county`
- `localadmin`
- `locality`
- `borough`
- `macrohood`
- `neighborhood`
- `microhood`

## Used By

- [`CapitalOfDivisionItem`](capital_of_division_item.md)
- [`Division`](../division.md)
- [`DivisionArea`](../division_area.md)
- [`DivisionBoundary`](../division_boundary.md)
- [`HierarchyItem`](hierarchy_item.md)

---

## Place


Places are point representations of real-world facilities, businesses, services, or amenities.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Position of the place. Places are point geometries.*Allowed geometry types: Point* |
| `theme` | `"places"` | |
| `type` | `"place"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `operating_status` | [`OperatingStatus`](types/operating_status.md) | An indication of whether a place is: in continued operation, in a temporary operating hiatus, or closed permanently.This is not an indication of opening hours or that the place is open/closed at the current time-of-day or day-of-week.When `operating_status` is `"permanently_closed"`, the `confidence` field will be set to 0. |
| `categories` | [`Categories`](types/categories.md) (optional) | |
| `categories.primary` | [`SnakeCaseString`](../system/snake_case_string.md) | The primary or main category of the place. |
| `categories.alternate` | `list<`[`SnakeCaseString`](../system/snake_case_string.md)`>` (optional) | Alternate categories of the place.Some places might fit into two categories, e.g., a book store and a coffee shop. In these cases, the primary category can be augmented with additional categories. |
| `basic_category` | [`SnakeCaseString`](../system/snake_case_string.md) (optional) | The basic level category of a place.This field classifies places into categories at a level that most people find intuitive. The full list of possible values it may hold can be found at (TODO).The basic level category, or simply basic category, is based on a cognitive science model use in taxonomy and ontology development. The idea is to provide the category name at the level of generality that is preferred by humans in learning and memory tasks. This category to be roughly in the middle of the general-to-specific category hierarchy.The full list of basic level categories is available at https://docs.overturemaps.org/guides/places/ |
| `taxonomy` | [`Taxonomy`](types/taxonomy.md) (optional) | A structured representation of the place's category within the Overture taxonomy.Provides the primary classification, full hierarchy path, and alternate categories. |
| `taxonomy.primary` | [`SnakeCaseString`](../system/snake_case_string.md) | The primary, or most specific, category known about this place.The `primary` category value must always equal the last or rightmost entry in the `hierarchy` field. |
| `taxonomy.hierarchy` | `list<`[`SnakeCaseString`](../system/snake_case_string.md)`>` | The full primary hierarchy of categories known for this place, ordered from most general to most specific. An example hierarchy might be: `["food_and_drink", "restaurant", "casual_eatery", "gas_station_sushi"]`.The rightmost, or most specific, value in the `hierarchy` must always be equal to the `primary` field. The basic level category of the place will typically be found in the middle of the primary hierarchy. The primary hierarchy does not include any of the alternate categories found in the `alternates` field. |
| `taxonomy.alternates` | `list<`[`SnakeCaseString`](../system/snake_case_string.md)`>` (optional) | Unordered list of additional categories that are known for this place but that are not part of the primary category hierarchy.Alternate categories allow a more complete picture of the place to be surfaced when it fits multiple unconnected branches in the taxonomy. For example a gas station that also sells groceries might have primary category of "gas_station" with an alternate of "grocery_store".Alternate categories are not part of the primary hierarchy or another alternate category's hierarchy. In other words, if a category is a parent in the hierarchy of another category, that category can't be a primary or alternate category itself.Note as well that this field is an unordered list of extra categories and does not represent a hierarchy. |
| `confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | A score between 0 and 1 indicating how confident we are that the place exists.A confidence score of 0 indicates that we are certain the place doesn't exist anymore and will always be paired with an `operating_status` of `"permanently_closed"`.A confidence score of 1 indicates that we are certain the place does exist.If there is no value for confidence, it means we don't have enough information on which to estimate our confidence level. |
| `websites` | `list<`[`HttpUrl`](../pydantic/networks/http_url.md)`>` (optional) | The sites of the place.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `socials` | `list<`[`HttpUrl`](../pydantic/networks/http_url.md)`>` (optional) | The social media URLs of the place.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `emails` | `list<`[`EmailStr`](../pydantic/networks/email_str.md)`>` (optional) | The email addresses of the place.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `phones` | `list<`[`PhoneNumber`](../system/phone_number.md)`>` (optional) | The phone numbers of the place.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `brand` | [`Brand`](types/brand.md) (optional) | The brand associated with the place. |
| `brand.names` | [`Names`](../core/names.md) (optional) | |
| `brand.names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `brand.names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `brand.names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `brand.names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `brand.names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `brand.names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `brand.names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `brand.names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `brand.names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `brand.names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `brand.names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `brand.wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |
| `addresses[]` | `list<`[`Address`](types/address.md)`>` (optional) | The address or addresses of the place*Minimum length: 1* |
| `addresses[].freeform` | `string` (optional) | Free-form address that contains street name, house number and other address info |
| `addresses[].locality` | `string` (optional) | City, town, or neighborhood component of the place address |
| `addresses[].postcode` | `string` (optional) | Postal code component of the place address |
| `addresses[].region` | [`RegionCode`](../system/region_code.md) (optional) | An ISO 3166-2 principal subdivision code |
| `addresses[].country` | [`CountryCodeAlpha2`](../system/country_code_alpha2.md) (optional) | An ISO 3166-1 alpha-2 country code |
| `names` | [`Names`](../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `99003ee6-e75b-4dd6-8a8a-53a5a716c50d` |
| `bbox.xmin` | `-150.46875` |
| `bbox.xmax` | `-150.46875` |
| `bbox.ymin` | `-79.17134094238281` |
| `bbox.ymax` | `-79.17133331298828` |
| `geometry` | `POINT (-150.46875 -79.1713346)` |
| `theme` | `places` |
| `type` | `place` |
| `version` | `1` |
| `sources[0].property` |  |
| `sources[0].dataset` | `meta` |
| `sources[0].record_id` | `107663894904826` |
| `sources[0].update_time` | `2025-06-30T07:00:00.000Z` |
| `sources[0].confidence` | `0.7337175792507205` |
| `sources[0].between` | `null` |
| `operating_status` | `open` |
| `categories.primary` | `hotel` |
| `categories.alternate` | `null` |
| `confidence` | `0.7337175792507205` |
| `websites` | `["https://www.superhotel.co.jp/s_hotels/beppu/"]` |
| `socials` | `["https://www.facebook.com/107663894904826"]` |
| `emails` | `null` |
| `phones` | `["+81977009000"]` |
| `brand.wikidata` | `null` |
| `brand.names.primary` | `SUPER HOTEL` |
| `brand.names.common` | `null` |
| `brand.names.rules` | `null` |
| `addresses[0].freeform` | `秋田県横手市駅前町１３−８` |
| `addresses[0].locality` | `横手市` |
| `addresses[0].postcode` | `013-0036` |
| `addresses[0].region` | `null` |
| `addresses[0].country` | `JP` |
| `names.primary` | `スーパーホテル別府駅前` |
| `names.common` | `null` |
| `names.rules` | `null` |

---

## Address(Types)


An address associated with a place.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `freeform` | `string` (optional) | Free-form address that contains street name, house number and other address info |
| `locality` | `string` (optional) | City, town, or neighborhood component of the place address |
| `postcode` | `string` (optional) | Postal code component of the place address |
| `region` | [`RegionCode`](../../system/region_code.md) (optional) | An ISO 3166-2 principal subdivision code |
| `country` | [`CountryCodeAlpha2`](../../system/country_code_alpha2.md) (optional) | An ISO 3166-1 alpha-2 country code |

## Used By

- [`Place`](../place.md)

---

## Brand


A brand associated with a place.

A location with multiple brands is modeled as multiple separate places, each with its own brand.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `names` | [`Names`](../../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `wikidata` | [`WikidataId`](../../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |

## Used By

- [`Place`](../place.md)

---

## Categories


Categories a place belongs to.

Complete list is available on GitHub: [https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/overture_categories.csv](https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/overture_categories.csv)

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `primary` | [`SnakeCaseString`](../../system/snake_case_string.md) | The primary or main category of the place. |
| `alternate` | `list<`[`SnakeCaseString`](../../system/snake_case_string.md)`>` (optional) | Alternate categories of the place.Some places might fit into two categories, e.g., a book store and a coffee shop. In these cases, the primary category can be augmented with additional categories.*All items must be unique. (`UniqueItemsConstraint`)* |

## Used By

- [`Place`](../place.md)

---

## OperatingStatus


General indication of whether a place is: in continued operation, in a temporary operating
hiatus, or closed permanently.

Operating status should not be confused with opening hours or operating hours. In particular,
the status `"open"` does not mean the place is open *right now*, it means that in general the
place is continuing to operate normally, as opposed to being in an operating hiatus
(`"temporarily_closed"`) or shuttered (`"permanently_closed"`).

## Values

- `open`
- `permanently_closed`
- `temporarily_closed`

## Used By

- [`Place`](../place.md)

---

## Taxonomy(Types)


A structured representation of the place's category within the Overture taxonomy.

Provides the primary classification, full hierarchy path, and alternate categories.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `primary` | [`SnakeCaseString`](../../system/snake_case_string.md) | The primary, or most specific, category known about this place.The `primary` category value must always equal the last or rightmost entry in the `hierarchy` field. |
| `hierarchy` | `list<`[`SnakeCaseString`](../../system/snake_case_string.md)`>` | The full primary hierarchy of categories known for this place, ordered from most general to most specific. An example hierarchy might be: `["food_and_drink", "restaurant", "casual_eatery", "gas_station_sushi"]`.The rightmost, or most specific, value in the `hierarchy` must always be equal to the `primary` field. The basic level category of the place will typically be found in the middle of the primary hierarchy. The primary hierarchy does not include any of the alternate categories found in the `alternates` field.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `alternates` | `list<`[`SnakeCaseString`](../../system/snake_case_string.md)`>` (optional) | Unordered list of additional categories that are known for this place but that are not part of the primary category hierarchy.Alternate categories allow a more complete picture of the place to be surfaced when it fits multiple unconnected branches in the taxonomy. For example a gas station that also sells groceries might have primary category of "gas_station" with an alternate of "grocery_store".Alternate categories are not part of the primary hierarchy or another alternate category's hierarchy. In other words, if a category is a parent in the hierarchy of another category, that category can't be a primary or alternate category itself.Note as well that this field is an unordered list of extra categories and does not represent a hierarchy.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |

## Used By

- [`Place`](../place.md)

---

## EmailStr


See: [Pydantic docs](https://docs.pydantic.dev/latest/api/networks/#pydantic.networks.EmailStr)

## Used By

- [`Place`](../../places/place.md)

---

## HttpUrl


A type that will accept any http or https URL.

See: [Pydantic docs](https://docs.pydantic.dev/latest/api/networks/#pydantic.networks.HttpUrl)

## Used By

- [`Place`](../../places/place.md)

---

## CountryCodeAlpha2


An ISO-3166-1 alpha-2 country code.

Underlying type: `string`

## Constraints

- Allows only ISO 3166-1 alpha-2 country codes. (`CountryCodeAlpha2Constraint`, pattern: `^[A-Z]{2}$`)

## Used By

- [`Address`](../addresses/address.md)
- [`Address`](../places/types/address.md)
- [`Division`](../divisions/division.md)
- [`DivisionArea`](../divisions/division_area.md)
- [`DivisionBoundary`](../divisions/division_boundary.md)
- [`Perspectives`](../core/perspectives.md)

---

## HexColor


A color represented as an #RRGGBB or #RGB hexadecimal string.

For example:

- `"#ff0000"` or `#f00` for pure red 🟥
- `"#ffa500"` for bright orange 🟧
- `"#000000"` or `"#000"` for black ⬛

Underlying type: `string`

## Constraints

- Allows only hexadecimal color codes (e.g., #FF0000 or #FFF). (`HexColorConstraint`, pattern: `^#[0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?$`)

## Used By

- [`Building`](../buildings/building.md)
- [`BuildingPart`](../buildings/building_part.md)

---

## JsonPointer


A JSON Pointer

As described in `the JSON Pointer specification, RFC-6901`_.

.. _the JSON Pointer specification, RFC-6901: [https://rfc-editor.org/rfc/rfc6901.html](https://rfc-editor.org/rfc/rfc6901.html)

For example:

- `""` (root value)
- `"/connectors/"`
- `"/connectors/0/at"`

Underlying type: `string`

## Constraints

- Allows only valid JSON Pointer values (RFC 6901). (`JsonPointerConstraint`)

## Used By

- [`SourceItem`](../core/source_item.md)

---

## LanguageTag


A BCP-47 language tag.

As described in `Tags for Identifying Languages, BCP-47`_.

.. _Tags for Identifying Languages, BCP-47: [https://www.rfc-editor.org/rfc/bcp/bcp47.txt](https://www.rfc-editor.org/rfc/bcp/bcp47.txt)

For example:

- `"en"`
- `"en-US"`
- `"fr-CA"`
- `"zh-Hant-TW"`

Underlying type: `string`

## Constraints

- Allows only `BCP-47`_ language tags. (`LanguageTagConstraint`, pattern: `^(?:(?:[A-Za-z]{2,3}(?:-[A-Za-z]{3}){0,3}?)|(?:[A-Za-z]{4,8}))(?:-[A-Za-z]{4})?(?:-[A-Za-z]{2}|[0-9]{3})?(?:-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(?:-[A-WY-Za-wy-z0-9](?:-[A-Za-z0-9]{2,8})+)*$`)

## Used By

- [`Division`](../divisions/division.md)
- [`NameRule`](../core/name_rule.md)
- [`Names`](../core/names.md)
- [`CommonNames`](../core/common_names.md)

---

## NoWhitespaceString


A string that contains no whitespace characters.

Underlying type: `string`

## Constraints

- Allows only strings that contain no whitespace characters. (`NoWhitespaceConstraint`, pattern: `^\S+$`)

## Used By

- [`DivisionId`](../divisions/types/division_id.md)
- [`Id`](ref/id.md)

---

## PhoneNumber


An international phone number.

Underlying type: `string`

## Constraints

- Allows only international phone numbers. (`PhoneNumberConstraint`, pattern: `^\+\d{1,3}[\s\-\(\)0-9]+$`)

## Used By

- [`Place`](../places/place.md)

---

## Geometry Types


Spatial types for representing geographic features.

## Types

| Type | Description |
| -----: | ------------- |
| `Geometry` | GeoJSON geometry value (Point, LineString, Polygon, etc.) |
| `BBox` | Bounding box as 4 or 6 coordinate values: [west, south, east, north] or [west, south, min-altitude, east, north, max-altitude] |
| `GeometryType` | Enumeration of geometry types: `geometry_collection`, `line_string`, `multi_line_string`, `multi_point`, `multi_polygon`, `point`, `polygon` |

---

## Primitive Types


Numeric types used for schema field definitions.

## Integer Types

| Type | Range | Description |
| -----: | :-----: | ------------- |
| `int8` | -128 to 127 | Portable 8-bit signed integer. |
| `int16` | -32,768 to 32,767 | Portable 16-bit signed integer. |
| `int32` | -2,147,483,648 to 2,147,483,647 | Portable 32-bit signed integer. |
| `int64` | -2^63 to 2^63-1 | Portable 64-bit signed integer. |

## Unsigned Integer Types

| Type | Range | Description |
| -----: | :-----: | ------------- |
| `uint8` | 0 to 255 | Portable 8-bit unsigned integer. |
| `uint16` | 0 to 65,535 | Portable 16-bit unsigned integer. |
| `uint32` | 0 to 4,294,967,295 | Portable 32-bit unsigned integer. |

## Floating Point Types

| Type | Precision | Description |
| -----: | :---------: | ------------- |
| `float32` | ~7 decimal digits | Portable IEEE 32-bit floating point number. |
| `float64` | ~15 decimal digits | Portable IEEE 64-bit floating point number. |

---

## ID


A unique identifier.

Underlying type: `string`

## Constraints

- Minimum length: 1
- Allows only strings that contain no whitespace characters. (`NoWhitespaceConstraint`, pattern: `^\S+$`) (from [`NoWhitespaceString`](../no_whitespace_string.md))

## Used By

- [`Address`](../../addresses/address.md)
- [`Bathymetry`](../../base/bathymetry.md)
- [`Building`](../../buildings/building.md)
- [`BuildingPart`](../../buildings/building_part.md)
- [`Connector`](../../transportation/connector.md)
- [`ConnectorReference`](../../transportation/types/connector_reference.md)
- [`DestinationRule`](../../transportation/types/destination_rule.md)
- [`Division`](../../divisions/division.md)
- [`DivisionArea`](../../divisions/division_area.md)
- [`DivisionBoundary`](../../divisions/division_boundary.md)
- [`Infrastructure`](../../base/infrastructure.md)
- [`Land`](../../base/land.md)
- [`LandCover`](../../base/land_cover.md)
- [`LandUse`](../../base/land_use.md)
- [`Place`](../../places/place.md)
- [`Segment`](../../transportation/segment.md)
- [`SequenceEntry`](../../transportation/types/sequence_entry.md)
- [`Water`](../../base/water.md)
- [`DivisionId`](../../divisions/types/division_id.md)

---

## RegionCode


An ISO 3166-2 principal subdivision code.

Underlying type: `string`

## Constraints

- Allows only ISO 3166-2 principal subdivision codes. (`RegionCodeConstraint`, pattern: `^[A-Z]{2}-[A-Z0-9]{1,3}$`)

## Used By

- [`Address`](../places/types/address.md)
- [`Division`](../divisions/division.md)
- [`DivisionArea`](../divisions/division_area.md)
- [`DivisionBoundary`](../divisions/division_boundary.md)

---

## SnakeCaseString


A string that looks like a snake_case identifier, like a Python variable name (*e.g.*, `foo_bar`).

Underlying type: `string`

## Constraints

- Allows only strings that look like snake_case identifiers, *e.g.* `"foo_bar"`. (`SnakeCaseConstraint`, pattern: `^[a-z0-9]+(_[a-z0-9]+)*$`)

## Used By

- [`Categories`](../places/types/categories.md)
- [`Place`](../places/place.md)
- [`Taxonomy`](../places/types/taxonomy.md)

---

## StrippedString


A string without leading or trailing whitespace.

Underlying type: `string`

## Constraints

- Allows only strings that have no leading/trailing whitespace. (`StrippedConstraint`)

## Used By

- [`Address`](../addresses/address.md)
- [`AddressLevel`](../addresses/types/address_level.md)
- [`DestinationLabels`](../transportation/types/destination_labels.md)
- [`Division`](../divisions/division.md)
- [`HierarchyItem`](../divisions/types/hierarchy_item.md)
- [`NameRule`](../core/name_rule.md)
- [`Names`](../core/names.md)
- [`RouteReference`](../transportation/types/route_reference.md)
- [`SourceItem`](../core/source_item.md)
- [`CommonNames`](../core/common_names.md)

---

## WikidataId


A wikidata ID, as found on [https://www.wikidata.org/](https://www.wikidata.org/).

- `"Q42"`
- `"Q11643"`
- `"Q116257497"`

Underlying type: `string`

## Constraints

- Allows only Wikidata identifiers (Q followed by digits). (`WikidataIdConstraint`, pattern: `^Q\d+$`)

## Used By

- [`Brand`](../places/types/brand.md)
- [`Division`](../divisions/division.md)
- [`Infrastructure`](../base/infrastructure.md)
- [`Land`](../base/land.md)
- [`LandUse`](../base/land_use.md)
- [`RouteReference`](../transportation/types/route_reference.md)
- [`Water`](../base/water.md)

---

## Connector


Connectors create physical connections between segments.

Connectors are compatible with GeoJSON Point features.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Position of the connector*Allowed geometry types: Point* |
| `theme` | `"transportation"` | |
| `type` | `"connector"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `39542bee-230f-4b91-b7e5-a9b58e0c59b1` |
| `bbox.xmin` | `-176.54730224609375` |
| `bbox.xmax` | `-176.54727172851562` |
| `bbox.ymin` | `-43.96794891357422` |
| `bbox.ymax` | `-43.96794128417969` |
| `geometry` | `POINT (-176.5472979 -43.9679472)` |
| `theme` | `transportation` |
| `type` | `connector` |
| `version` | `1` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `null` |
| `sources[0].update_time` | `null` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |

---

## Segment


## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `id` | [`Id`](../system/ref/id.md) | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
| `bbox` | [`bbox`](../system/primitive/geometry.md) (optional) | An optional bounding box for the feature |
| `geometry` | [`geometry`](../system/primitive/geometry.md) | Segment centerline*Allowed geometry types: LineString* |
| `theme` | `"transportation"` | |
| `type` | `"segment"` | |
| `version` | [`FeatureVersion`](../core/feature_version.md) | |
| `sources[]` | [`Sources`](../core/sources.md) (list, optional) | Information about the source data used to assemble the feature. |
| `sources[].property` | [`JsonPointer`](../system/json_pointer.md) | A JSON Pointer identifying the property (field) that this source information applies to.The root document value `""` indicates that this source information applies to the entire feature, excepting properties (fields) for which a dedicated source information record exists.Any other JSON Pointer apart from `""` indicates that this source record provides dedicated source information for the property at the path in the JSON Pointer. As an example, the value `"/names/common/en"` indicates that the source information applies to the English common name of a named feature, while the value `"/geometry"` indicates that it applies to the feature geometry. |
| `sources[].dataset` | `string` | Name of the dataset where the source data can be found. |
| `sources[].license` | [`StrippedString`](../system/stripped_string.md) (optional) | Source data license name.This should be a valid SPDX license identifier when available.If omitted, contact the data provider for more license information. |
| `sources[].record_id` | `string` (optional) | Identifies the specific record within the source dataset where the source data can be found.The format of record identifiers is dataset-specific. |
| `sources[].update_time` | `datetime` (optional) | Last update time of the source data record. |
| `sources[].confidence` | [`ConfidenceScore`](../core/confidence_score.md) (optional) | Confidence value from the source dataset.This is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data. |
| `sources[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to. |
| `subtype` | [`Subtype`](types/subtype.md) | Broad category of transportation segment. |
| `access_restrictions[]` | [`AccessRules`](types/access_rules.md) (list, optional) | Rules governing access to this road segment |
| `access_restrictions[].access_type` | [`AccessType`](types/access_type.md) | |
| `access_restrictions[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing AccessRestrictionRule applies to. |
| `access_restrictions[].when` | [`AccessRestrictionRule.When`](types/access_restriction_rule.when.md) (optional) | Scopes for AccessRestrictionRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE |
| `access_restrictions[].when.heading` | [`Heading`](../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing AccessRestrictionRule applies to. |
| `access_restrictions[].when.during` | [`OpeningHours`](../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing AccessRestrictionRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification. |
| `access_restrictions[].when.mode` | `list<`[`TravelMode`](../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing AccessRestrictionRule applies to. |
| `access_restrictions[].when.using` | `list<`[`PurposeOfUse`](../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing AccessRestrictionRule applies to. |
| `access_restrictions[].when.recognized` | `list<`[`RecognizedStatus`](../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing AccessRestrictionRule applies to. |
| `access_restrictions[].when.vehicle` | [`VehicleAxleCountSelector`](../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing AccessRestrictionRule applies to. |
| `connectors[]` | `list<`[`ConnectorReference`](types/connector_reference.md)`>` (optional) | List of connectors which this segment is physically connected to and their relative location. Each connector is a possible routing decision point, meaning it defines a place along the segment in which there is possibility to transition to other segments which share the same connector.*Minimum length: 2**All items must be unique. (`UniqueItemsConstraint`)* |
| `connectors[].connector_id` | [`Id`](../system/ref/id.md) | A unique identifier |
| `connectors[].at` | [`LinearlyReferencedPosition`](../core/scoping/linearly_referenced_position.md) (optional) | The linearly-referenced position on the geometry, specified as a percentage displacement from the start of the geometry, that the containing ConnectorReference applies to. |
| `level_rules[]` | [`LevelRules`](types/level_rules.md) (list, optional) | Defines the Z-order, i.e. stacking order, of the road segment. |
| `level_rules[].value` | [`Level`](../core/level.md) | Z-order of the feature where 0 is visual level |
| `level_rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing LevelRule applies to. |
| `routes[]` | [`Routes`](types/routes.md) (list, optional) | Routes this segment belongs to |
| `routes[].name` | [`StrippedString`](../system/stripped_string.md) (optional) | Full name of the route |
| `routes[].network` | [`StrippedString`](../system/stripped_string.md) (optional) | Name of the highway system this route belongs to |
| `routes[].ref` | [`StrippedString`](../system/stripped_string.md) (optional) | Code or number used to reference the route |
| `routes[].symbol` | [`StrippedString`](../system/stripped_string.md) (optional) | URL or description of route signage |
| `routes[].wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |
| `routes[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing RouteReference applies to. |
| `subclass_rules[]` | [`SubclassRules`](types/subclass_rules.md) (list, optional) | Set of subclasses scoped along segment |
| `subclass_rules[].value` | [`Subclass`](types/subclass.md) | |
| `subclass_rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SubclassRule applies to. |
| `names` | [`Names`](../core/names.md) (optional) | |
| `names.primary` | [`StrippedString`](../system/stripped_string.md) | The most commonly used name. |
| `names.common` | [`CommonNames`](../core/common_names.md) (map, optional) | |
| `names.rules[]` | `list<`[`NameRule`](../core/name_rule.md)`>` (optional) | Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases. |
| `names.rules[].value` | [`StrippedString`](../system/stripped_string.md) | The actual name value. |
| `names.rules[].variant` | [`NameVariant`](../core/name_variant.md) | The name variant for this name rule. |
| `names.rules[].language` | [`LanguageTag`](../system/language_tag.md) (optional) | The language in which the name `value` is specified, if known, as an IETF BCP 47 language tag. |
| `names.rules[].perspectives` | [`Perspectives`](../core/perspectives.md) (optional) | Political perspectives from which a named feature is viewed. |
| `names.rules[].perspectives.mode` | [`PerspectiveMode`](../core/perspective_mode.md) | Whether the perspective holder accepts or disputes this name. |
| `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. |
| `names.rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. |
| `names.rules[].side` | [`Side`](../core/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. |
| `class` *(Road)* | [`RoadClass`](types/road_class.md) | |
| `destinations[]` *(Road)* | [`Destinations`](types/destinations.md) (list, optional) | Describes objects that can be reached by following a transportation segment in the same way those objects are described on signposts or ground writing that a traveller following the segment would observe in the real world. This allows navigation systems to refer to signs and observable writing that a traveller actually sees. |
| `destinations[].from_connector_id` | [`Id`](../system/ref/id.md) | Identifies the point of physical connection on this segment before which the destination sign or marking is visible. |
| `destinations[].to_connector_id` | [`Id`](../system/ref/id.md) | Identifies the point of physical connection on the segment identified by 'to_segment_id' to transition to for reaching the destination(s). |
| `destinations[].to_segment_id` | [`Id`](../system/ref/id.md) | Identifies the segment to transition to reach the destination(s) labeled on the sign or marking. |
| `destinations[].final_heading` | [`Heading`](../core/scoping/heading.md) | Direction of travel on the segment identified by 'to_segment_id' that leads to the destination. |
| `destinations[].labels[]` | `list<`[`DestinationLabels`](types/destination_labels.md)`>` (optional) | Labeled destinations that can be reached by following the segment. |
| `destinations[].labels[].value` | [`StrippedString`](../system/stripped_string.md) | Names the object that is reached |
| `destinations[].labels[].type` | [`DestinationLabelType`](types/destination_label_type.md) | |
| `destinations[].symbols` | `list<`[`DestinationSignSymbol`](types/destination_sign_symbol.md)`>` (optional) | A collection of symbols or icons present on the sign next to current destination label. |
| `destinations[].when` | [`DestinationRule.When`](types/destination_rule.when.md) (optional) | Scope for DestinationRule: |
| `destinations[].when.heading` | [`Heading`](../core/scoping/heading.md) | The heading, either forward or backward, that the containing DestinationRule applies to. |
| `prohibited_transitions[]` *(Road)* | [`ProhibitedTransitions`](types/prohibited_transitions.md) (list, optional) | Rules preventing transitions from this segment to another segment. |
| `prohibited_transitions[].sequence[]` | `list<`[`SequenceEntry`](types/sequence_entry.md)`>` | Ordered sequence of connector/segment pairs that it is prohibited to follow from this segment. |
| `prohibited_transitions[].sequence[].connector_id` | [`Id`](../system/ref/id.md) | Identifies the point of physical connection between the previous segment in the sequence and the segment in this sequence entry. |
| `prohibited_transitions[].sequence[].segment_id` | [`Id`](../system/ref/id.md) | Identifies the segment that the previous segment in the sequence is physically connected to via the sequence entry's connector. |
| `prohibited_transitions[].final_heading` | [`Heading`](../core/scoping/heading.md) | Direction of travel that is prohibited on the destination segment of the sequence. |
| `prohibited_transitions[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing ProhibitedTransitionRule applies to. |
| `prohibited_transitions[].when` | [`ProhibitedTransitionRule.When`](types/prohibited_transition_rule.when.md) (optional) | Scopes for ProhibitedTransitionRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE |
| `prohibited_transitions[].when.heading` | [`Heading`](../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing ProhibitedTransitionRule applies to. |
| `prohibited_transitions[].when.during` | [`OpeningHours`](../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing ProhibitedTransitionRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification. |
| `prohibited_transitions[].when.mode` | `list<`[`TravelMode`](../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing ProhibitedTransitionRule applies to. |
| `prohibited_transitions[].when.using` | `list<`[`PurposeOfUse`](../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing ProhibitedTransitionRule applies to. |
| `prohibited_transitions[].when.recognized` | `list<`[`RecognizedStatus`](../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing ProhibitedTransitionRule applies to. |
| `prohibited_transitions[].when.vehicle` | [`VehicleAxleCountSelector`](../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing ProhibitedTransitionRule applies to. |
| `road_flags[]` *(Road)* | [`RoadFlags`](types/road_flags.md) (list, optional) | Set of boolean attributes applicable to roads. May be specified either as a single flag array of flag values, or as an array of flag rules. |
| `road_flags[].values` | `list<`[`RoadFlag`](types/road_flag.md)`>` | |
| `road_flags[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing RoadFlagRule applies to. |
| `road_surface[]` *(Road)* | [`Surfaces`](types/surfaces.md) (list, optional) | Physical surface of the road. May either be specified as a single global value for the segment, or as an array of surface rules. |
| `road_surface[].value` | [`RoadSurface`](types/road_surface.md) | |
| `road_surface[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SurfaceRule applies to. |
| `speed_limits[]` *(Road)* | [`SpeedLimits`](types/speed_limits.md) (list, optional) | Rules governing speed on this road segment |
| `speed_limits[].max_speed` | [`Speed`](types/speed.md) (optional) | |
| `speed_limits[].max_speed.value` | [`SpeedValue`](types/speed_value.md) | Speed value |
| `speed_limits[].max_speed.unit` | [`SpeedUnit`](../core/speed_unit.md) | |
| `speed_limits[].min_speed` | [`Speed`](types/speed.md) (optional) | |
| `speed_limits[].min_speed.value` | [`SpeedValue`](types/speed_value.md) | Speed value |
| `speed_limits[].min_speed.unit` | [`SpeedUnit`](../core/speed_unit.md) | |
| `speed_limits[].is_max_speed_variable` | `boolean` (optional) | Indicates a variable speed corridor |
| `speed_limits[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SpeedLimitRule applies to. |
| `speed_limits[].when` | [`SpeedLimitRule.When`](types/speed_limit_rule.when.md) (optional) | Scopes for SpeedLimitRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE |
| `speed_limits[].when.heading` | [`Heading`](../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing SpeedLimitRule applies to. |
| `speed_limits[].when.during` | [`OpeningHours`](../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing SpeedLimitRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification. |
| `speed_limits[].when.mode` | `list<`[`TravelMode`](../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing SpeedLimitRule applies to. |
| `speed_limits[].when.using` | `list<`[`PurposeOfUse`](../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing SpeedLimitRule applies to. |
| `speed_limits[].when.recognized` | `list<`[`RecognizedStatus`](../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing SpeedLimitRule applies to. |
| `speed_limits[].when.vehicle` | [`VehicleAxleCountSelector`](../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing SpeedLimitRule applies to. |
| `subclass` *(Road)* | [`Subclass`](types/subclass.md) (optional) | |
| `width_rules[]` *(Road)* | [`WidthRules`](types/width_rules.md) (list, optional) | Edge-to-edge width of the road modeled by this segment, in meters.Examples: (1) If this segment models a carriageway without sidewalk, this value represents the edge-to-edge width of the carriageway, inclusive of any shoulder. (2) If this segment models a sidewalk by itself, this value represents the edge-to-edge width of the sidewalk. (3) If this segment models a combined sidewalk and carriageway, this value represents the edge-to-edge width inclusive of sidewalk. |
| `width_rules[].value` | [`Width`](types/width.md) | |
| `width_rules[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing WidthRule applies to. |
| `class` *(Rail)* | [`RailClass`](types/rail_class.md) | |
| `rail_flags[]` *(Rail)* | [`RailFlags`](types/rail_flags.md) (list, optional) | Set of boolean attributes applicable to railways. May be specified either as a single flag array of flag values, or as an array of flag rules. |
| `rail_flags[].values` | `list<`[`RailFlag`](types/rail_flag.md)`>` | |
| `rail_flags[].between` | [`LinearlyReferencedRange`](../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing RailFlagRule applies to. |

## Examples

| Column | Value |
| -------: | ------- |
| `id` | `1bc62f3b-08b5-42b8-89fe-36f685f60455` |
| `bbox.xmin` | `-176.5650177001953` |
| `bbox.xmax` | `-176.56361389160156` |
| `bbox.ymin` | `-43.954410552978516` |
| `bbox.ymax` | `-43.953250885009766` |
| `geometry` | `LINESTRING (-176.5636191 -43.954404, -176.5643637 -43.9538145, -176.5647264 -43.9535274, -176.564...` |
| `theme` | `transportation` |
| `type` | `segment` |
| `version` | `1` |
| `sources[0].property` |  |
| `sources[0].dataset` | `OpenStreetMap` |
| `sources[0].record_id` | `w53435546@6` |
| `sources[0].update_time` | `2021-05-03T06:37:03Z` |
| `sources[0].confidence` | `null` |
| `sources[0].between` | `null` |
| `subtype` | `road` |
| `access_restrictions` | `null` |
| `connectors[0].connector_id` | `15b2c131-9137-4add-88c6-2acd3fa61355` |
| `connectors[0].at` | `0.0` |
| `connectors[1].connector_id` | `23ae2702-ef77-4d2e-b39d-77360b696d20` |
| `connectors[1].at` | `0.523536154` |
| `connectors[2].connector_id` | `8e944ce1-4b81-49eb-a823-7d98779c855c` |
| `connectors[2].at` | `1.0` |
| `level_rules` | `null` |
| `routes` | `null` |
| `subclass_rules` | `null` |
| `names.primary` | `Meteorological Lane` |
| `names.common` | `null` |
| `destinations` | `null` |
| `prohibited_transitions` | `null` |
| `road_flags` | `null` |
| `road_surface[0].value` | `gravel` |
| `road_surface[0].between` | `null` |
| `speed_limits` | `null` |
| `subclass` | `null` |
| `width_rules` | `null` |
| `class` | `residential` |
| `rail_flags` | `null` |
| `names.rules[0].variant` | `common` |
| `names.rules[0].language` | `null` |
| `names.rules[0].perspectives` | `null` |
| `names.rules[0].value` | `Meteorological Lane` |
| `names.rules[0].between` | `null` |
| `names.rules[0].side` | `null` |

---

## AccessRestrictionRule


## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `access_type` | [`AccessType`](access_type.md) | |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing AccessRestrictionRule applies to. |
| `when` | [`AccessRestrictionRule.When`](access_restriction_rule.when.md) (optional) | Scopes for AccessRestrictionRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE |
| `when.heading` | [`Heading`](../../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing AccessRestrictionRule applies to. |
| `when.during` | [`OpeningHours`](../../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing AccessRestrictionRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification. |
| `when.mode` | `list<`[`TravelMode`](../../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing AccessRestrictionRule applies to. |
| `when.using` | `list<`[`PurposeOfUse`](../../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing AccessRestrictionRule applies to. |
| `when.recognized` | `list<`[`RecognizedStatus`](../../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing AccessRestrictionRule applies to. |
| `when.vehicle` | [`VehicleAxleCountSelector`](../../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing AccessRestrictionRule applies to. |

## Used By

- [`Segment`](../segment.md)
- [`AccessRules`](access_rules.md)

---

## AccessRestrictionRule.When


Scopes for AccessRestrictionRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `heading` | [`Heading`](../../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing AccessRestrictionRule applies to.*At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `during` | [`OpeningHours`](../../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing AccessRestrictionRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification.*At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `mode` | `list<`[`TravelMode`](../../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing AccessRestrictionRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `using` | `list<`[`PurposeOfUse`](../../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing AccessRestrictionRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `recognized` | `list<`[`RecognizedStatus`](../../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing AccessRestrictionRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `vehicle` | [`VehicleAxleCountSelector`](../../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing AccessRestrictionRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |

## Constraints

- At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set

## Used By

- [`AccessRestrictionRule`](access_restriction_rule.md)

---

## AccessRules


Rules governing access to this road segment

Underlying type: `list<`[`AccessRestrictionRule`](access_restriction_rule.md)`>`

## Constraints

- Minimum length: 1
- All items must be unique. (`UniqueItemsConstraint`)

## Used By

- [`Segment`](../segment.md)

---

## AccessType


## Values

- `allowed`
- `denied`
- `designated`

## Used By

- [`AccessRestrictionRule`](access_restriction_rule.md)

---

## ConnectorReference


Contains the GERS ID and relative position between 0 and 1 of a connector feature along the
segment.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `connector_id` | [`Id`](../../system/ref/id.md) | A unique identifier*References [`Connector`](../connector.md) (connects to)* |
| `at` | [`LinearlyReferencedPosition`](../../core/scoping/linearly_referenced_position.md) (optional) | The linearly-referenced position on the geometry, specified as a percentage displacement from the start of the geometry, that the containing ConnectorReference applies to. |

## Used By

- [`Segment`](../segment.md)

---

## DestinationLabelType


Indicates what special symbol/icon is present on a signpost, visible as road marking or
similar.

## Values

- `street`
- `country`
- `route_ref`
- `toward_route_ref`
- `unknown`

## Used By

- [`DestinationLabels`](destination_labels.md)

---

## DestinationLabels


The type of object of the destination label.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `value` | [`StrippedString`](../../system/stripped_string.md) | Names the object that is reached*Minimum length: 1* |
| `type` | [`DestinationLabelType`](destination_label_type.md) | |

## Used By

- [`DestinationRule`](destination_rule.md)

---

## DestinationRule


## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `from_connector_id` | [`Id`](../../system/ref/id.md) | Identifies the point of physical connection on this segment before which the destination sign or marking is visible. |
| `to_connector_id` | [`Id`](../../system/ref/id.md) | Identifies the point of physical connection on the segment identified by 'to_segment_id' to transition to for reaching the destination(s). |
| `to_segment_id` | [`Id`](../../system/ref/id.md) | Identifies the segment to transition to reach the destination(s) labeled on the sign or marking. |
| `final_heading` | [`Heading`](../../core/scoping/heading.md) | Direction of travel on the segment identified by 'to_segment_id' that leads to the destination. |
| `labels[]` | `list<`[`DestinationLabels`](destination_labels.md)`>` (optional) | Labeled destinations that can be reached by following the segment.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `labels`, `symbols` must be set* |
| `labels[].value` | [`StrippedString`](../../system/stripped_string.md) | Names the object that is reached |
| `labels[].type` | [`DestinationLabelType`](destination_label_type.md) | |
| `symbols` | `list<`[`DestinationSignSymbol`](destination_sign_symbol.md)`>` (optional) | A collection of symbols or icons present on the sign next to current destination label.*All items must be unique. (`UniqueItemsConstraint`)**At least one of `labels`, `symbols` must be set* |
| `when` | [`DestinationRule.When`](destination_rule.when.md) (optional) | Scope for DestinationRule: |
| `when.heading` | [`Heading`](../../core/scoping/heading.md) | The heading, either forward or backward, that the containing DestinationRule applies to. |

## Constraints

- At least one of `labels`, `symbols` must be set

## Used By

- [`Segment`](../segment.md)
- [`Destinations`](destinations.md)

---

## DestinationRule.When


Scope for DestinationRule: 

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `heading` | [`Heading`](../../core/scoping/heading.md) | The heading, either forward or backward, that the containing DestinationRule applies to. |

## Used By

- [`DestinationRule`](destination_rule.md)

---

## DestinationSignSymbol


Indicates what special symbol/icon is present on a signpost, visible as road marking or
similar.

## Values

- `motorway`
- `airport`
- `hospital`
- `center`
- `industrial`
- `parking`
- `bus`
- `train_station`
- `rest_area`
- `ferry`
- `motorroad`
- `fuel`
- `viewpoint`
- `fuel_diesel`
- `food`
- `lodging`
- `info`
- `camp_site`
- `interchange`
- `restrooms`

## Used By

- [`DestinationRule`](destination_rule.md)

---

## Destinations


Describes objects that can be reached by following a transportation segment in the same way those objects are described on signposts or ground writing that a traveller following the segment would observe in the real world. This allows navigation systems to refer to signs and observable writing that a traveller actually sees.

Underlying type: `list<`[`DestinationRule`](destination_rule.md)`>`

## Used By

- [`Segment`](../segment.md)

---

## LevelRule


A single level rule defining the Z-order, i.e. stacking order, applicable within a given scope
on the road segment.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `value` | [`Level`](../../core/level.md) | Z-order of the feature where 0 is visual level |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing LevelRule applies to. |

## Used By

- [`Segment`](../segment.md)
- [`LevelRules`](level_rules.md)

---

## LevelRules


Defines the Z-order, i.e. stacking order, of the road segment.

Underlying type: `list<`[`LevelRule`](level_rule.md)`>`

## Used By

- [`Segment`](../segment.md)

---

## ProhibitedTransitionRule


## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `sequence[]` | `list<`[`SequenceEntry`](sequence_entry.md)`>` | Ordered sequence of connector/segment pairs that it is prohibited to follow from this segment.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `sequence[].connector_id` | [`Id`](../../system/ref/id.md) | Identifies the point of physical connection between the previous segment in the sequence and the segment in this sequence entry. |
| `sequence[].segment_id` | [`Id`](../../system/ref/id.md) | Identifies the segment that the previous segment in the sequence is physically connected to via the sequence entry's connector. |
| `final_heading` | [`Heading`](../../core/scoping/heading.md) | Direction of travel that is prohibited on the destination segment of the sequence. |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing ProhibitedTransitionRule applies to. |
| `when` | [`ProhibitedTransitionRule.When`](prohibited_transition_rule.when.md) (optional) | Scopes for ProhibitedTransitionRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE |
| `when.heading` | [`Heading`](../../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing ProhibitedTransitionRule applies to. |
| `when.during` | [`OpeningHours`](../../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing ProhibitedTransitionRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification. |
| `when.mode` | `list<`[`TravelMode`](../../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing ProhibitedTransitionRule applies to. |
| `when.using` | `list<`[`PurposeOfUse`](../../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing ProhibitedTransitionRule applies to. |
| `when.recognized` | `list<`[`RecognizedStatus`](../../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing ProhibitedTransitionRule applies to. |
| `when.vehicle` | [`VehicleAxleCountSelector`](../../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing ProhibitedTransitionRule applies to. |

## Used By

- [`Segment`](../segment.md)
- [`ProhibitedTransitions`](prohibited_transitions.md)

---

## ProhibitedTransitionRule.When


Scopes for ProhibitedTransitionRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `heading` | [`Heading`](../../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing ProhibitedTransitionRule applies to.*At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `during` | [`OpeningHours`](../../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing ProhibitedTransitionRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification.*At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `mode` | `list<`[`TravelMode`](../../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing ProhibitedTransitionRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `using` | `list<`[`PurposeOfUse`](../../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing ProhibitedTransitionRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `recognized` | `list<`[`RecognizedStatus`](../../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing ProhibitedTransitionRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `vehicle` | [`VehicleAxleCountSelector`](../../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing ProhibitedTransitionRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |

## Constraints

- At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set

## Used By

- [`ProhibitedTransitionRule`](prohibited_transition_rule.md)

---

## ProhibitedTransitions


Rules preventing transitions from this segment to another segment.

Underlying type: `list<`[`ProhibitedTransitionRule`](prohibited_transition_rule.md)`>`

## Used By

- [`Segment`](../segment.md)

---

## RailClass


Captures the kind of rail segment.

## Values

- `funicular`
- `light_rail`
- `monorail`
- `narrow_gauge`
- `standard_gauge`
- `subway`
- `tram`
- `unknown`

## Used By

- [`Segment`](../segment.md)

---

## RailFlag


Simple flags that can be on or off for a railway segment.

Specifies physical characteristics and can overlap.

## Values

- `is_bridge`
- `is_tunnel`
- `is_under_construction`
- `is_abandoned`
- `is_covered`
- `is_passenger`
- `is_freight`
- `is_disused`

## Used By

- [`RailFlagRule`](rail_flag_rule.md)

---

## RailFlagRule


Rail-specific flag rule with geometric scoping only.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `values` | `list<`[`RailFlag`](rail_flag.md)`>` | *Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing RailFlagRule applies to. |

## Used By

- [`Segment`](../segment.md)
- [`RailFlags`](rail_flags.md)

---

## RailFlags


Set of boolean attributes applicable to railways. May be specified either as a single flag array of flag values, or as an array of flag rules.

Underlying type: `list<`[`RailFlagRule`](rail_flag_rule.md)`>`

## Constraints

- Minimum length: 1
- All items must be unique. (`UniqueItemsConstraint`)

## Used By

- [`Segment`](../segment.md)

---

## RoadClass


Captures the kind of road and its position in the road network hierarchy.

## Values

- `motorway`
- `primary`
- `secondary`
- `tertiary`
- `residential`
- `living_street`
- `trunk`
- `unclassified`
- `service`
- `pedestrian`
- `footway`
- `steps`
- `path`
- `track`
- `cycleway`
- `bridleway`
- `unknown`

## Used By

- [`Segment`](../segment.md)

---

## RoadFlag


Simple flags that can be on or off for a road segment.

Specifies physical characteristics and can overlap.

## Values

- `is_bridge`
- `is_link`
- `is_tunnel`
- `is_under_construction`
- `is_abandoned`
- `is_covered`
- `is_indoor`

## Used By

- [`RoadFlagRule`](road_flag_rule.md)

---

## RoadFlagRule


Road-specific flag rule with geometric scoping only.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `values` | `list<`[`RoadFlag`](road_flag.md)`>` | *Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)* |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing RoadFlagRule applies to. |

## Used By

- [`Segment`](../segment.md)
- [`RoadFlags`](road_flags.md)

---

## RoadFlags


Set of boolean attributes applicable to roads. May be specified either as a single flag array of flag values, or as an array of flag rules.

Underlying type: `list<`[`RoadFlagRule`](road_flag_rule.md)`>`

## Constraints

- Minimum length: 1
- All items must be unique. (`UniqueItemsConstraint`)

## Used By

- [`Segment`](../segment.md)

---

## RoadSurface


Physical surface of the road.

## Values

- `unknown`
- `paved`
- `unpaved`
- `gravel`
- `dirt`
- `paving_stones`
- `metal`

## Used By

- [`SurfaceRule`](surface_rule.md)

---

## RouteReference


Route reference with linear referencing support.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `name` | [`StrippedString`](../../system/stripped_string.md) (optional) | Full name of the route*Minimum length: 1* |
| `network` | [`StrippedString`](../../system/stripped_string.md) (optional) | Name of the highway system this route belongs to*Minimum length: 1* |
| `ref` | [`StrippedString`](../../system/stripped_string.md) (optional) | Code or number used to reference the route*Minimum length: 1* |
| `symbol` | [`StrippedString`](../../system/stripped_string.md) (optional) | URL or description of route signage*Minimum length: 1* |
| `wikidata` | [`WikidataId`](../../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing RouteReference applies to. |

## Used By

- [`Segment`](../segment.md)
- [`Routes`](routes.md)

---

## Routes


Routes this segment belongs to

Underlying type: `list<`[`RouteReference`](route_reference.md)`>`

## Used By

- [`Segment`](../segment.md)

---

## SequenceEntry


A segment/connector pair in a prohibited transition sequence.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `connector_id` | [`Id`](../../system/ref/id.md) | Identifies the point of physical connection between the previous segment in the sequence and the segment in this sequence entry. |
| `segment_id` | [`Id`](../../system/ref/id.md) | Identifies the segment that the previous segment in the sequence is physically connected to via the sequence entry's connector. |

## Used By

- [`ProhibitedTransitionRule`](prohibited_transition_rule.md)

---

## Speed


A speed value, i.e. a certain number of distance units travelled per unit time.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `value` | [`SpeedValue`](speed_value.md) | Speed value |
| `unit` | [`SpeedUnit`](../../core/speed_unit.md) | |

## Used By

- [`SpeedLimitRule`](speed_limit_rule.md)

---

## SpeedLimitRule


An individual speed limit rule.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `max_speed` | [`Speed`](speed.md) (optional) | *At least one of `max_speed`, `min_speed` must be set* |
| `max_speed.value` | [`SpeedValue`](speed_value.md) | Speed value |
| `max_speed.unit` | [`SpeedUnit`](../../core/speed_unit.md) | |
| `min_speed` | [`Speed`](speed.md) (optional) | *At least one of `max_speed`, `min_speed` must be set* |
| `min_speed.value` | [`SpeedValue`](speed_value.md) | Speed value |
| `min_speed.unit` | [`SpeedUnit`](../../core/speed_unit.md) | |
| `is_max_speed_variable` | `boolean` (optional) | Indicates a variable speed corridor*`strict=True`* |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SpeedLimitRule applies to. |
| `when` | [`SpeedLimitRule.When`](speed_limit_rule.when.md) (optional) | Scopes for SpeedLimitRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE |
| `when.heading` | [`Heading`](../../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing SpeedLimitRule applies to. |
| `when.during` | [`OpeningHours`](../../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing SpeedLimitRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification. |
| `when.mode` | `list<`[`TravelMode`](../../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing SpeedLimitRule applies to. |
| `when.using` | `list<`[`PurposeOfUse`](../../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing SpeedLimitRule applies to. |
| `when.recognized` | `list<`[`RecognizedStatus`](../../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing SpeedLimitRule applies to. |
| `when.vehicle` | [`VehicleAxleCountSelector`](../../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing SpeedLimitRule applies to. |

## Constraints

- At least one of `max_speed`, `min_speed` must be set

## Used By

- [`Segment`](../segment.md)
- [`SpeedLimits`](speed_limits.md)

---

## SpeedLimitRule.When


Scopes for SpeedLimitRule: Scope.HEADING, Scope.TEMPORAL, Scope.TRAVEL MODE, Scope.PURPOSE OF USE, Scope.RECOGNIZED STATUS and Scope.VEHICLE

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `heading` | [`Heading`](../../core/scoping/heading.md) (optional) | The heading, either forward or backward, that the containing SpeedLimitRule applies to.*At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `during` | [`OpeningHours`](../../core/scoping/opening_hours.md) (optional) | The recurring time span, in the OpenStreetMap opening hours format, that the containing SpeedLimitRule applies to. For the OSM opening hours specification, see https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification.*At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `mode` | `list<`[`TravelMode`](../../core/scoping/travel_mode.md)`>` (optional) | A list of one or more travel modes, such as car, truck, or foot, that the containing SpeedLimitRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `using` | `list<`[`PurposeOfUse`](../../core/scoping/purpose_of_use.md)`>` (optional) | A list of one or more usage purposes, such as delivery or arrival at final destination, that the containing SpeedLimitRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `recognized` | `list<`[`RecognizedStatus`](../../core/scoping/recognized_status.md)`>` (optional) | A list of one or more recognized status values, such as employee or student, that the containing SpeedLimitRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |
| `vehicle` | [`VehicleAxleCountSelector`](../../core/scoping/vehicle_axle_count_selector.md) \| [`VehicleHeightSelector`](../../core/scoping/vehicle_height_selector.md) \| [`VehicleLengthSelector`](../../core/scoping/vehicle_length_selector.md) \| [`VehicleWeightSelector`](../../core/scoping/vehicle_weight_selector.md) \| [`VehicleWidthSelector`](../../core/scoping/vehicle_width_selector.md) (list, optional) | A list of one or more vehicle parameters that limit the vehicles the containing SpeedLimitRule applies to.*Minimum length: 1**All items must be unique. (`UniqueItemsConstraint`)**At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set* |

## Constraints

- At least one of `heading`, `during`, `mode`, `using`, `recognized`, `vehicle` must be set

## Used By

- [`SpeedLimitRule`](speed_limit_rule.md)

---

## SpeedLimits


Rules governing speed on this road segment

Underlying type: `list<`[`SpeedLimitRule`](speed_limit_rule.md)`>`

## Constraints

- Minimum length: 1
- All items must be unique. (`UniqueItemsConstraint`)

## Used By

- [`Segment`](../segment.md)

---

## SpeedValue


Speed value

Underlying type: `int32`

## Constraints

- `≥ 1`
- `≤ 350`
- `≥ -2147483648` (from [`int32`](../../system/primitive/primitives.md))
- `≤ 2147483647` (from [`int32`](../../system/primitive/primitives.md))

## Used By

- [`Speed`](speed.md)

---

## Subclass


Refines expected usage of the segment, must not overlap.

## Values

- `link`
- `sidewalk`
- `crosswalk`
- `parking_aisle`
- `driveway`
- `alley`
- `cycle_crossing`

## Used By

- [`Segment`](../segment.md)
- [`SubclassRule`](subclass_rule.md)

---

## SubclassRule


Set of subclasses scoped along segment.

## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `value` | [`Subclass`](subclass.md) | |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SubclassRule applies to. |

## Used By

- [`Segment`](../segment.md)
- [`SubclassRules`](subclass_rules.md)

---

## SubclassRules


Set of subclasses scoped along segment

Underlying type: `list<`[`SubclassRule`](subclass_rule.md)`>`

## Used By

- [`Segment`](../segment.md)

---

## Subtype


Transportation segment subtype classification.

## Values

- `road`
- `rail`
- `water`

## Used By

- [`Segment`](../segment.md)

---

## SurfaceRule


## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `value` | [`RoadSurface`](road_surface.md) | |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SurfaceRule applies to. |

## Used By

- [`Segment`](../segment.md)
- [`Surfaces`](surfaces.md)

---

## Surfaces


Physical surface of the road. May either be specified as a single global value for the segment, or as an array of surface rules.

Underlying type: `list<`[`SurfaceRule`](surface_rule.md)`>`

## Constraints

- Minimum length: 1
- All items must be unique. (`UniqueItemsConstraint`)

## Used By

- [`Segment`](../segment.md)

---

## Width


Underlying type: `float64`

## Constraints

- `> 0`

## Used By

- [`WidthRule`](width_rule.md)

---

## WidthRule


## Fields

| Name | Type | Description |
| -----: | :----: | ------------- |
| `value` | [`Width`](width.md) | |
| `between` | [`LinearlyReferencedRange`](../../core/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing WidthRule applies to. |

## Used By

- [`Segment`](../segment.md)
- [`WidthRules`](width_rules.md)

---

## WidthRules


Edge-to-edge width of the road modeled by this segment, in meters.

Examples: (1) If this segment models a carriageway without sidewalk, this value represents the edge-to-edge width of the carriageway, inclusive of any shoulder. (2) If this segment models a sidewalk by itself, this value represents the edge-to-edge width of the sidewalk. (3) If this segment models a combined sidewalk and carriageway, this value represents the edge-to-edge width inclusive of sidewalk.

Underlying type: `list<`[`WidthRule`](width_rule.md)`>`

## Constraints

- Minimum length: 1
- All items must be unique. (`UniqueItemsConstraint`)

## Used By

- [`Segment`](../segment.md)

---

## CARTO

![Example of CARTO Builder map with Overture data](./assets/CARTO_overture_map.png)

## Access Overture data in CARTO

[CARTO](https://carto.com/) provides access to Overture data from different cloud data marketplaces as well as from its own [Data Observatory](https://carto.com/spatial-data-catalog/browser). In order to access Overture data in BigQuery, Snowflake or Databricks, please follow the guides available in the [Getting Overture Data](../../getting-data) section:

- Overture data in [Google BigQuery](/getting-data/data-mirrors/bigquery/)
- Overture data in [Snowflake](/getting-data/data-mirrors/snowflake/)
- Overture data in [Databricks](/getting-data/data-mirrors/databricks/)

Additionally, CARTO users have direct access to Overture data from the Data Observatory available in the platform. In order to access Overture data from there, you just have to navigate to the Data Observatory section, search for Overture data, and access the tables that you need in a matter of a few clicks.

![Overture data from CARTO DO](./assets/CARTO_DO.gif)

## Analyzing Overture data with CARTO Workflows

Once you have access to Overture data via one of your connections in CARTO, you can start using it with [Workflows](https://carto.com/workflows), a low-code tool for creating and automating data preparation and analysis pipelines. Just drag and drop your Overture data into the canvas and start building powerful geospatial workflows that will then run natively on your connected cloud data warehouse.

In the example below we illustrate a workflow that uses Overture's data to identify buildings in areas with a deficit of cell network antennas. This example leverages data from Overture and other publicly available sources that can be added to the workflow canvas. Then, the workflow uses geospatial techniques such as H3 spatial indexing, the creation of a composite score, and geostatistics techniques such as Getis-Ord Gi* to process the data and identify hot spots and cold spots of telco antenna coverage in different areas of a city.

You can access this [step-by-step tutorial](https://academy.carto.com/creating-workflows/step-by-step-tutorials/identify-buildings-in-areas-with-a-deficit-of-cell-network-antennas) available in [CARTO Academy](https://academy.carto.com/) in order to re-create this example on your own.

![Example of CARTO Workflows with Overture data](./assets/CARTO_Workflows.gif)

## Visualizing Overture data with CARTO Builder

With [CARTO Builder](https://carto.com/builder) users can create interactive dashboards in a matter of seconds. You can access your data instantly and start building interactive maps running natively on top of your data warehouse. Builder provides flexible styling options, access to different basemaps, and the possibility to add widgets and controls for data interactivity. Maps can then be shared with other users in your organization, publicly on the web, or embedded in your applications.

![Example of CARTO Builder with Overture data](./assets/CARTO_Builder.gif)

In this example, we are visualizing on a map the results from the workflow described in the previous section; there we can quickly identify that the busy city center of Madrid is well covered by cell towers, enough to satisfy the potential demand. Also, locations with little human activity (like El Pardo park) have also enough network capacity to provide a good service. However, the outskirts of the city seem to be lacking network infrastructure, based on the overall human activity and the cell tower presence patterns in Madrid.

<iframe width="740px" height="560px" src="https://clausa.app.carto.com/map/8b7754af-4810-471b-836c-d1b99742021c"></iframe>

You can also access this map directly from [here](https://clausa.app.carto.com/map/8b7754af-4810-471b-836c-d1b99742021c).

## Additional resources

- CARTO's [QGIS Plugin](https://docs.carto.com/data-and-analysis/carto-qgis-plugin) allows you to access, visualize, and edit spatial data from the leading cloud data warehouses directly within QGIS. You can also use this plugin to access Overture data in QGIS via CARTO.
- CARTO's [Application Development tools](https://docs.carto.com/carto-for-developers/overview) provides resources for developers creating top-class spatial apps with their location data. Have a look to our documentation if you'd like to include Overture data in your applications based on [deck.gl](https://deck.gl/).

---

## QGIS

# Load Overture data into QGIS

In this example, we'll show you how to get Overture data into [QGIS](https://www.qgis.org/), a powerful open GIS and mapping platform. 

## Method 1: Using the GeoParquet Downloader plugin (recommended)

You can load Overture data directly into QGIS using the [GeoParquet Downloader plugin](https://github.com/cholmes/qgis_plugin_gpq_downloader). This plugin treats cloud-hosted GeoParquet files like a data service, pulling only the features within your current map view. It uses DuckDB under the hood to query the data in Overture's cloud storage and automatically converts that data to your preferred format.

### Installation

The plugin is available through QGIS's standard plugin repository. To install it:

- Open QGIS Plugin Manager (`Plugins → Manage and Install Plugins`)
- Search for "GeoParquet Downloader"
- Install and restart QGIS if prompted

After installation, you'll find a new toolbar for accessing Overture data and other cloud-native geospatial datasets, from [Source Cooperative](https://source.coop/) and [OpenStreetMap](https://openstreetmap.us/our-work/layercake/). Most installations handle DuckDB automatically, though some systems may require additional setup, see these [installation instructions](https://github.com/cholmes/qgis_plugin_gpq_downloader/blob/main/README.md#installation) for more information. Note: To save the data as GeoParquet files, your QGIS installation needs GDAL version 3.8 or higher. For macOS, we recommend [using Pixi](https://github.com/cholmes/qgis_plugin_gpq_downloader/wiki/Installing-GeoParquet-Support-in-QGIS#osx) to install QGIS and the necessary dependencies in a separate environment. 

### Example

Let's add streets to our map of buildings in Florence, Italy:

1. **Zoom to your area**: Pan and zoom in QGIS to Florence
2. **Launch the downloader**: Click the plugin's toolbar icon
3. **Configure your download**:
   - Source: Overture Maps
   - Theme: Addresses, Base, Buildings, Divisions, Places or Transportation
   - Output: GeoParquet, GeoPackage, DuckDB, GeoJSON or FlatGeobuf
4. **Load the data**: The plugin queries Overture's cloud storage and downloads data in the bounding box defined by your current view in QGIS.

The entire process typically takes seconds to minutes depending on data density. You can change your view and reload to pull data in different areas. You can also load additional datasets in your map.

![GeoParquet Downloader in action](./assets/qgis-plugin.gif)   

## Method 2: Importing Overture data 

If you already have Overture data files stored locally, you can import them or drag and drop them into QGIS. GeoParquet files work as first-class vector data sources in QGIS, just like Shapefiles or GeoPackage. You have several options for loading them:

- **Drag and drop**: The fastest method—simply drag GeoParquet files from your file manager directly onto the QGIS map canvas
- **Batch import**: Select multiple Parquet files and drop them simultaneously to build multi-layer projects instantly
- **Data Source Manager**: Use `Layer → Add Layer → Add Vector Layer`, then browse to your Parquet files
- **Browser panel**: Navigate to your files in the QGIS Browser panel and double-click to add them

## Resources and next steps

- Explore the [GeoParquet Downloader plugin repository](https://github.com/cholmes/qgis_plugin_gpq_downloader) for updates and additional examples.
- Learn about [Overture's schema](https://docs.overturemaps.org/schema/) to better understand the properties available.
- Chat with the [Overture community](https://github.com/OvertureMaps/data/discussions) to share workflows and get help.

---

## Athena (AWS)

You can follow the steps belows to access and query Overture data directly in AWS. Note: you will need to create an account to use [Athena](https://aws.amazon.com/athena/) and other AWS services.

:::info
   Overture's S3 bucket is located in the us-west-2 AWS region, so you will need to set your region to `us-west-2`.
:::

## 1. Add Overture as a data source

Add Overture as a cross-account data source using [these instructions](https://docs.aws.amazon.com/athena/latest/ug/data-sources-glue-cross-account.html). The Catalog ID is `913550007193`.

  <details>
        <summary>AWS Glue Data Catalog</summary>
        
            ![AWS Glue Catalog](./assets/aws-glue-data-catalog-values.png)
        
    </details>

Depending on the permissions attached to your AWS user account/role, you may need to explicitly enable access to the Overture catalog. You can do that by [adding a new IAM policy](https://console.aws.amazon.com/iam/home?#/policies?type=customer) &mdash; we suggest calling it `OvertureGlueCatalogAccess` &mdash; with the following permissions:

<details>
  <summary>IAM policy for Overture Glue Data Catalog access</summary>
  
```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "glue:GetTable*",
        "glue:GetDatabase*",
        "glue:GetPartition*"
      ],
      "Resource": [
        "arn:aws:glue:us-west-2:913550007193:catalog",
        "arn:aws:glue:us-west-2:913550007193:database/release",
        "arn:aws:glue:us-west-2:913550007193:table/*"
      ]
    }
  ]
}
```
  
</details>

## 2. Inspect release tables

Each release is available as a table under the `release` database in the `overture` data source (note the `v` at the beginning of the table name). The `overture` data catalog will be updated with a new table for each new release.

 <details>
        <summary>Overture Maps release tables</summary>
        
            ![Release Tables](./assets/overture-release-tables.png)
        
    </details>

## 3. Access data from a release table

You can access Overture data in a particular release like this:

    <QueryBuilder query={AthenaSelectExample}></QueryBuilder>

 Here's an example query to get ~25k places in Seattle:

    <QueryBuilder query={SeattlePlaces}></QueryBuilder>

More information on using Athena is available in the [Amazon Athena User Guide](https://docs.aws.amazon.com/athena/latest/ug/what-is.html).

{/*--- ## Optional

### Add the table directly using the DDL

If you prefer to create the table in your own data catalog, you can run the complete DDL query in the Athena Query Console. This will create tables in your AWS account's data catalog pointing directly to data hosted on Overture's S3 bucket.

<details>
    <summary>DDL query statement</summary>
    
        <QueryBuilder query={CreateAthenaTable}></QueryBuilder>
    
</details>

After you run the set-up query, you can load the partitions by running `MSCK REPAIR TABLE overture` or choosing "Load Partitions" from the table options menu.

### Add a policy in your data catalog settings

If you want to share this catalog with other users and accounts, you'll need to add a policy enabling cross-account Glue catalog access. To do so, navigate to the [data catalog settings](https://console.aws.amazon.com/glue/home#/v2/security/settings) and add a catalog policy that looks this:

<details>
  <summary>Policy for sharing Overture Maps catalog</summary>
  

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": [
        "glue:GetTable*",
        "glue:GetDatabase*",
        "glue:GetPartition*"
      ],
      "Resource": [
        "arn:aws:glue:<region>:<account id>:catalog",
        "arn:aws:glue:<region>:<account id>:database/release",
        "arn:aws:glue:<region>:<account id>:table/*"
      ]
    }
  ]
}
```
`release` is the name of the database containing Overture tables.

</details>
*/}

---

## MapLibre

<Map></Map>

## Download and process only the data you need

Overture data is released in the cloud-native format [GeoParquet](https://geoparquet.org/). It is further partitioned by *theme* and *type*. Downloading the data through a tool like [DuckDB](https://duckdb.org/) can take advantage of these properties, giving the best performance. After downloading and converting the data to GeoJSON, we can use [tippecanoe](https://github.com/felt/tippecanoe) to create a [`PMTiles`](https://github.com/protomaps/PMTiles) archive for each theme.

<Tabs queryString="theme-data" >

{/* Places  */}
<TabItem value="places" label="Places" default>

The places data theme represents business and points of interest in the real world. Read more about the places data schema in the [documentation](https://docs.overturemaps.org/guides/places/).

1. The following DuckDB query downloads places data within a specific bounding box and writes a `GeoJSON` file.

    <QueryBuilder query={SeattlePlaces}></QueryBuilder>

2. Next, create a `pmtiles` archive from `seattle_places.geojson` with [tippecanoe](https://github.com/felt/tippecanoe).

    ```bash
    tippecanoe -fo places.pmtiles -Z13 -z13 -l places seattle_places.geojson
    ```

    <details>
        <summary>Tippecanoe flag explanation</summary>

    - `-fo places.pmtiles` The output file will be places.pmtiles. It will be overwritten if it exists.
    - `-Z13` and `-z13` will produce a tileset starting at zoom 13 and going up to zoom 13 (only 1 zoom level).
    - `-l places` names the layer "places"

   </details>

</TabItem>

{/* Placenames */}

<TabItem value="placenames" label="Placenames" default>
The [divisions theme](https://docs.overturemaps.org/guides/divisions/) contains named administrative units (countries, regions, counties, cities, etc.) and their boundaries. To add labels for populated places to the map, we query the divisions theme to get the primary name for each locality.

1. The following DuckDB queries downloads placenames from the divisions theme within the bounding box and saves it as `seattle_placenames.geojson`

    <QueryBuilder query={SeattlePlacenames}></QueryBuilder>

2. Run [tippecanoe](https://github.com/felt/tippecanoe) to produce a `pmtiles` archive from `seattle_placenames.geojson`

    ```bash
    tippecanoe -fo placenames.pmtiles -Z5 -z10 -l placenames seattle_placenames.geojson
    ```
    <details>
        <summary>Tippecanoe flag explanation</summary>

    - `-fo placenames.pmtiles` is our output file. It will be overwritten if it exists.
    - `-Z5` and `-z10` will produce a tileset starting at zoom 5 and going up to zoom 10.
    - `-l placenames` names the layer "placenames"

    </details>

</TabItem>

{/* Buildings */}

<TabItem value="buildings" label="Buildings" default>

Overture contains billions of buildings distributed across hundreds of GeoParquet files.

1. The following DuckDB query reads only the metadata of each file and then downloads *only* the buildings within our bounding box to a line-delimited `GeoJSONSeq` file.

    <QueryBuilder query={SeattleBuildings}></QueryBuilder>

2. Run [tippecanoe](https://github.com/felt/tippecanoe) to produce a `pmtiles` archive from `seattle_buildings.geojsonseq`

    ```bash
    tippecanoe -fo buildings.pmtiles -Z13 -z13 -l buildings -P seattle_buildings.geojsonseq
    ```

    <details>
        <summary>Tippecanoe flag explanation</summary>

    - `-fo buildings.pmtiles` is our output file. It will be overwritten if it exists.
    - `-Z13` and `-z13` will produce a tileset starting at zoom 13 and going up to zoom 13 (so only 1 zoom level).
    - `-l buildings` names the layer "buildings"
    - `-P` allows tippecanoe to read the file in parallel. Since we created a GeoJSON sequence file instead of a single GeoJSON Feature Collection, tippecanoe can process the input data more efficiently.

    </details>

</TabItem>

{/* Roads */}

<TabItem value="roads" label="Roads" default>

The Overture transportation theme has two types: `connectors` and `segments`. To extract and render the road lines, we will query for `type=segment`.

1. This DuckDB query downloads road segments from Overture to a `GeoJSONSeq` file.

    <QueryBuilder query={SeattleRoads}></QueryBuilder>

2. Run [tippecanoe](https://github.com/felt/tippecanoe) to produce a `pmtiles` archive from `seattle_roads.geojsonseq`

    ```bash
    tippecanoe -fo roads.pmtiles -Z10 -B10 -z13 -l roads -P seattle_roads.geojsonseq
    ```

    <details>
        <summary>Tippecanoe flag explanation</summary>

    - `-fo roads.pmtiles` is our output file. It will be overwritten if it exists.
    - `-Z10` and `-z13` will produce a tileset starting at zoom 10 and going up to zoom 13.
    - `-B10` will ensure that all featuers are present from zoom level 10.
    - `-l roads` names the layer "roads"
    - `-P` allows tippecanoe to read the file in parallel. Since we created a GeoJSON sequence file instead of a single GeoJSON Feature Collection, tippecanoe can process the input data more efficiently.

    </details>

</TabItem>

{/* Base */}

<TabItem value="base" label="Base (Land, Land Use & Water)" default>

1. The base theme contains five feature types: `infrastructure`, `land`,`land_cover`, `land_use`, and `water`. For this map, we want only the land, land use, and water features. We'll run three separate queries to obtain to obtain those features and combine them into a single pmtiles archive with different layers.

    <details>
        <summary>1. DuckDB query to produce `land.geojsonseq`</summary>

    <QueryBuilder query={SeattleLand}></QueryBuilder>

    </details>

    <details>
        <summary>2. DuckDB query to produce `land_use.geojsonseq`</summary>

    <QueryBuilder query={SeattleLanduse}></QueryBuilder>

    </details>

    <details>
        <summary>3. DuckDB query to produce `water.geojsonseq`</summary>

    <QueryBuilder query={SeattleWater}></QueryBuilder>

    Note: We use a slightly larger bounding box to capture the Ocean water polygons, too

    </details>

2. Run [tippecanoe](https://github.com/felt/tippecanoe) to produce a `pmtiles` archive with three `geojsonseq` file as input:

    ```bash
    tippecanoe -fo base.pmtiles -Z8 -z13 -P \
        --named-layer=land:seattle_land.geojsonseq \
        --named-layer=landuse:seattle_land_use.geojsonseq \
        --named-layer=water:seattle_water.geojsonseq
    ```

    <details>
        <summary>Tippecanoe flag explanation</summary>

    - `-fo tiles/base.pmtiles` is our output file. It will be overwritten if it exists.
    - `-Z8` and `-z13` will produce a tileset starting at zoom 8 going up to zoom 13.
    - `--named-layer=land:seattle_land.geojsonseq` creates the `land` layer from the contents of `seattle_land.geojson` (and similarly for the other files)
    - `-P` allows tippecanoe to read the file in parallel. Since we created a GeoJSON sequence file instead of a single GeoJSON Feature Collection, tippecanoe can process the input data more efficiently.

    </details>

</TabItem>

</Tabs>

## Create your map with Maplibre + PMTiles

At this point, we have created five PMTiles archives from five of the Overture themes:
1. `places.pmtiles`
2. `placenames.pmtiles`
3. `buildings.pmtiles`
4. `roads.pmtiles`
5. `base.pmtiles`

The map on this page combines a [react maplibre example](https://docs.maptiler.com/react/maplibre-gl-js/how-to-use-maplibre-gl-js/) with [PMTiles](https://codesandbox.io/s/black-dream-oycvf2?file=/src/App.js). You can [view the source](https://github.com/OvertureMaps/docs/blob/main/src/components/map.js) for the above map on github for a complete example using react, or, check out the [map based on July's release](https://labs.overturemaps.org/overture-with-daylight) for a non-react implementation of PMTiles.

Using PMTiles with react requires adding the [PMtiles protocol](https://docs.protomaps.com/pmtiles/maplibre):

```javascript

useEffect(() => {
  let protocol = new Protocol();
  maplibregl.addProtocol("pmtiles",protocol.tile);

  ... initialize your map here ...

  return () => {
    maplibregl.removeProtocol("pmtiles");
  }
}, []);
```
Then, reference the tile archives with a relative path when initializing the map:

```javascript
  style: {
    sources: {
      roads: {
        type: "vector",
        url: "pmtiles://../example-map/tiles/roads.pmtiles"
      },
      places: {
        type: "vector",
        url: "pmtiles://../example-map/tiles/places.pmtiles"
      },
    ...
```

## Style the layers
Each tab below contains the complete styles in the [Maplibre Style Spec](https://maplibre.org/maplibre-style-spec/) for the map on this page.

<Tabs queryString="map-layer" >
<TabItem value="places" label="Places" default>
    <CodeBlock language="json">{ JSON.stringify(Places, null, 2) }</CodeBlock>
</TabItem>
<TabItem value="placenames" label="Placenames" default>
    <CodeBlock language="json">{ JSON.stringify(Admins, null, 2) }</CodeBlock>
</TabItem>
<TabItem value="buildings" label="Buildings" default>
    <CodeBlock language="json">{ JSON.stringify(Buildings, null, 2) }</CodeBlock>
</TabItem>
<TabItem value="roads" label="Roads" default>
    <CodeBlock language="json">{ JSON.stringify(Transportation, null, 2) }</CodeBlock>
</TabItem>
<TabItem value="land" label="Land" default>
    <CodeBlock language="json">{ JSON.stringify(Land, null, 2) }</CodeBlock>
</TabItem>
<TabItem value="landuse" label="Landuse" default>
    <CodeBlock language="json">{ JSON.stringify(Landuse, null, 2) }</CodeBlock>
</TabItem>
<TabItem value="water" label="Water" default>
    <CodeBlock language="json">{ JSON.stringify(Water, null, 2) }</CodeBlock>
</TabItem>
</Tabs>

---

## Fused(Examples)

In these examples, we'll see ways to load and transform Overture data using Fused. The Fused Python library allows you to call predefined UDFs to load and process data into your Python environment.

## Examples

### Join Overture Buildings and NSI

This example shows how to join the Overture Buildings dataset with the [National Structures Inventory (NSI)](https://www.hec.usace.army.mil/confluence/nsi/technicalreferences/latest/technical-documentation) dataset. The NSI API provides point data on buildings in the U.S. that are relevant to hazard analyses. Joining the NSI data with Overture Buildings can be used to enrich Overture Building features with additional metadata.

We'll be loading Overture Buildings data using the Fused User Defined Function explained in [this](/getting-data/data-mirrors/fused) section of the docs.

First we import Fused.

```python

```

Now we can define a `GeoDataFrame` with a bounding box of our area of interest. We'll use it to load data for the same area of each dataset.

```python

bbox = gpd.GeoDataFrame(
    geometry=[shapely.box(-73.9847, 40.7666, -73.9810, 40.7694)],
    crs=4326
)
```

We use `fused.run` to run the predefined Overture UDF that loads Overture Buildings data for the given `bbox` area. We may specify the Overture `theme` with the `overture_type` parameter, and a subset of columns to fetch with the `use_columns` parameter.

```python
gdf_overture = fused.run(
    "UDF_Overture_Maps_Example",
    bbox=bbox,
    overture_type='building',
    use_columns=['geometry', 'names', 'sources']
)
```

To get the NSI data, we call the [NSI API](https://www.hec.usace.army.mil/confluence/nsi/technicalreferences/latest/api-reference-guide), defining the area using a GeoJSON derived from the `bbox` `GeoDataFrame`. After receiving the response, we convert it into a `GeoDataFrame`.

```python

# Convert to GeoJSON
bbox_geojson = json.loads(bbox.to_json())

# Make a request to the NSI API
response = requests.post(
    url="https://nsi.sec.usace.army.mil/nsiapi/structures?fmt=fc",
    json=bbox_geojson,
)

# Create a GeoDataFrame from the response
gdf_nsi = gpd.GeoDataFrame.from_features(response.json()["features"])
```

Now we can join the Overture and NSI data using a spatial join.

```python
gdf_overture.sjoin(gdf_nsi, how='inner', predicate='intersects')
```

### Create a Fused User Defined Function (UDF)

We can encapsulate the above code into a UDF that can be referenced and reused in other workflows.

In this code, the `@fused.udf` decorator indicates that the function is a UDF. The function defines the area of interest using the `bbox` parameter. Note how the UDF imports are included in the function body.

```python

@fused.udf
def udf(bbox):

    # 1. Load Overture Buildings
    gdf_overture = fused.run("UDF_Overture_Maps_Example", bbox=bbox, overture_type='building')

    # 2. Load NSI from API
    bbox_geojson = json.loads(bbox.to_json())
    response = requests.post(
        url="https://nsi.sec.usace.army.mil/nsiapi/structures?fmt=fc",
        json=bbox_geojson,
    )

    # 3. Create NSI gdf
    gdf_nsi = gpd.GeoDataFrame.from_features(response.json()["features"])

    # 4. Join Overture and NSI
    return gdf_overture.sjoin(gdf_nsi, how='inner', predicate='intersects')
```

Now we can run the UDF for an area specified by the bounding box.

```python
fused.run(udf, bbox=bbox)
```

By encapsulating the code into a UDF, a workflow or client application can dynamically pass different areas of interest to the `bbox` parameter to run the UDF and return its output table. A simple way to try this is to run a UDF equivalent to the one we just created in the [Fused UDF Builder](https://www.fused.io/workbench/catalog/Overture_Nsi-dd89972c-ce30-4544-ba0f-81fc09f5bbef) which renders the UDF outputs on a map.

## Next steps

- Explore [Fused Overture UDF](https://www.fused.io/workbench/catalog/Overture_Maps_Example-64071fb8-2c96-4015-adb9-596c3bac6787) on the Fused UDF Builder.
- Check out an example of the [Overture + NSI UDF](https://www.fused.io/workbench/catalog/Overture_Nsi-dd89972c-ce30-4544-ba0f-81fc09f5bbef) on the Fused UDF Builder.
- Browse the [Fused UDF Catalog](https://www.fused.io/workbench/catalog) to find other examples of reusable UDFs.

---

## Examples


Work with Overture Maps data using the tools and platforms you already know. These examples show how to access, query, visualize, and analyze Overture data across a range of environments.

- **[CARTO](/examples/CARTO)**
- **[Fused](/examples/fused)**
- **[Kepler.gl](/examples/kepler-gl)**
- **[Lonboard](/examples/lonboard)**
- **[Build a Map](/examples/build-a-map)**
- **[Pandas](/examples/pandas)**
- **[Overture Tiles](/examples/overture-tiles)**
- **[QGIS](/examples/QGIS)**
- **[Rapid](/examples/rapid)**
- **[Spark](/examples/spark)**
- **[Wherobots](/examples/wherobots)**

Have an example you'd like to share? We welcome contributions: [open a pull request](https://github.com/OvertureMaps/docs/pulls) or [start a discussion](https://github.com/OvertureMaps/data/discussions) on GitHub.

---

## Kepler.gl

In this example, we'll query the Overture buildings theme and download data for a specified bounding box. Then we'll load the data into [kepler.gl](https://kepler.gl/demo), an open-source tool for working with large map datasets, and visualize the buildings data by data source: [OpenStreetMap](https://wiki.openstreetmap.org/wiki/Key:building), [Microsoft ML Building Footprints](https://github.com/microsoft/GlobalMLBuildingFootprints), [Esri Community Maps](https://communitymaps.arcgis.com/home), and [Google Open Buildings](https://sites.research.google/open-buildings/).

Requirements: Install DuckDB or log into AWS to access Athena. You do not need an account on kepler.gl.

## Get only the data you need
Using DuckDB or Athena, query Overture data to get buildings for our area of interest, in this case a bounding box with Hyderabad, India.

<Tabs queryString="engine">
    <TabItem value="duckdb" label="DuckDB">
        <QueryBuilder query={HyderabadBuildingsDuckDB}></QueryBuilder>
    </TabItem>
    <TabItem value="athena" label="Athena">
        <QueryBuilder query={HyderabadBuildingsAthena}></QueryBuilder>
    </TabItem>
</Tabs>

## Explore the data in Kepler.gl
Drag and drop the GeoJSON file into [kepler.gl](https://kepler.gl/demo). Style the feature layer by choosing different colors based on the `primary_source` field. Then you can explore the multiple data sources that Overture has conflated to create the buildings theme.

![kepler.gl example](./assets/kepler-overture-hyderabad.png)

![kepler.gl gif](./assets/kepler_overture_buildings_hyderabad.gif)

## Next steps
- Make [your own interactive Overture map](/examples/build-a-map) with MapLibre and PMTiles!

---

## Lonboard

In this example, we'll walk through three ways to fetch, process, and visualize Overture data in a Jupyter notebook using [Lonboard](https://developmentseed.org/lonboard/latest/) and the [overturemaps-py](https://github.com/OvertureMaps/overturemaps-py) library. [Lonboard](https://developmentseed.org/lonboard/latest/) is a Python library that makes visualizing large map datasets in Jupyter notebooks fast and efficient. It's built on [GeoArrow](https://geoarrow.org/) and [GeoParquet](https://arrow.apache.org/docs/python/index.html), which creates an opportunity for a fully binary workflow with Overture data.

<details>

    <summary>
    **Installation requirements**

    </summary>
To follow along with these examples, you should have [JupyterLab or Jupyter Notebook](https://jupyter.org/) running and the following dependencies installed:

- [Lonboard](https://developmentseed.org/lonboard/latest/#install)
- [overturemaps-py](https://github.com/OvertureMaps/overturemaps-py)
- [GeoPandas](https://geopandas.org/en/stable/index.html)
- [Pandas](https://pandas.pydata.org/)
- [Shapely](https://shapely.readthedocs.io/en/stable/)

</details>

The examples below are available in [the notebooks directory](//github.com/OvertureMaps/docs/tree/main/static/notebooks) in our docs repository on GitHub.

## Examples

:::note
Lonboard now has support for `.from_duckdb()` which allows us to interface directly with Overture data as Arrow tables and skip the steps with Shapely.
:::

In the first and simplest example, we'll use the [record_batch_reader](https://github.com/OvertureMaps/overturemaps-py/blob/e9632d4d2481a472a22dfd2d0a47ec9798ced9ef/overturemaps/core.py#L17) method in the overturemaps-py library to load Overture GeoParquet data directly into a PyArrow table. Then we'll use lonboard's built-in visualization tools to create an interactive map.

### GeoArrow

 First, let's import our toolkit.

```python

from lonboard import Map, PathLayer
```

Next we'll get a bounding box for our area of interest.

```python
# specify bounding box in Milan
bbox = 9.125034,45.433352,9.245223,45.507116
```

The `record_batch_reader` function accepts an Overture feature type and a bounding box as arguments. **Note: `.read_all()` will load all of the requested bbox into memory, so it's wise to keep the bbox reasonably small.**

Let's grab some road data for Milan.

```python
# need feature type and bounding box as arguments
table = overturemaps.record_batch_reader("segment", bbox).read_all()
```

We can inspect shape of the data.

```python
table.shape
```

We can also dig into the complexity of the Overture transportation schema.

```python
table.schema
```

Lonboard includes many built-in tools for visualizing map data. Here we're using [PathLayer](https://developmentseed.org/lonboard/latest/api/layers/path-layer/) to render the segment features. Then we can set parameters for our interactive map display.

```python
layer = PathLayer(
    table=table.select(["id", "geometry", "subtype", "class", "names"]),
    get_color=[200, 0, 200],
    width_min_pixels=0.4,
)

view_state = {
    "longitude": 9.18831,
    "latitude": 45.464336,
    "zoom": 12,
}
m = Map(layer, view_state=view_state)
m
```

![roads in Milan](./assets/road-network-milan.png)

### GeoPandas

In the second example, we'll add a few steps in the notebook to convert the PyArrow table to a GeoPandas GeoDataFrame. Getting the data into a GeoDataFrame requires a few more tools, depending on which methods we use. Here's our expanded toolkit:

```python

from shapely import wkb
from lonboard import Map, PolygonLayer
```

We'll use the same bounding box for Milan.

``` python
# specify bounding box
bbox = 9.125034,45.433352,9.245223,45.507116
```

And we'll use the `record_batch_reader` method to pull the data into a PyArrow table. This time we'll grab buildings data.

``` python
# need feature type and bounding box as arguments
table = overturemaps.record_batch_reader("building", bbox).read_all()
table = table.combine_chunks()
```

Converting the table to a Pandas DataFrame is straightforward.

``` python
# convert to dataframe
df = table.to_pandas()
```

But we need an extra step to create the GeoDataFrame. Specifically we need to convert to the geometry to a [Shapely geometry](https://shapely.readthedocs.io/en/stable/geometry.html) as we load into a GeoDataFrame.

``` python
# DataFrame to GeoDataFrame, set crs
gdf = gpd.GeoDataFrame(
    df,
    geometry=df['geometry'].apply(wkb.loads),
    crs="EPSG:4326"
)
```

We'll use Lonboard's [PolygonLayer](https://developmentseed.org/lonboard/latest/api/layers/polygon-layer/) to render the buildings. The we'll set the parameters for our interactive map display.

``` python

layer = PolygonLayer.from_geopandas(
    gdf= gdf[['id', 'geometry', 'names']].reset_index(drop=True),
    get_fill_color=[93, 103, 157],
    get_line_color=[0, 128, 128],
)

view_state = {
    "longitude": 9.18831,
    "latitude": 45.464336,
    "zoom": 13,
    "pitch": 45,
}
m = Map(layer, view_state=view_state)
m
```

![buildings in Milan](./assets/buildings-milan.png)

### `geodataframe` method in overturemaps-py

In the last example, we'll use the [`geodataframe` method](https://github.com/OvertureMaps/overturemaps-py/blob/main/overturemaps/core.py#L51) in the overturemaps-py library to pull Overture data directly into a GeoDataFrame. This method handles all the conversions internally, making our lives easier and our notebooks cleaner.

Here's the toolkit:

```python

from overturemaps import core
from lonboard import Map, ScatterplotLayer
```

Once again, we'll use the bounding box in Milan.

```python
# specify bounding box
bbox = 9.125034,45.433352,9.245223,45.507116
```

Direct to GeoDataFrame using the `geodataframe` method!

```python
# read in Overture place feature type, direct to geodataframe
gdf = core.geodataframe("place", bbox=bbox)
```

Use [ScatterplotLayer](https://developmentseed.org/lonboard/latest/api/layers/scatterplot-layer/) to render the point data and create an interactive map display in the notebook.

```python
# create map layer
layer = ScatterplotLayer.from_geopandas(
    gdf,
    get_fill_color=[0, 128, 128],
    radius_min_pixels = 1.5,
)

view_state = {
    "longitude": 9.18831,
    "latitude": 45.464336,
    "zoom": 13,
    "pitch": 45,
}
m = Map(layer)
m
```

![places in Milan](./assets/places-milan.png)

## Next steps

- For a more complex example with Lonboard and Overture data, head over to the [Lonboard docs](https://developmentseed.org/lonboard/latest/examples/overture-maps/).
- Check out the example with land cover data and Lonboard on our engineering [blog](https://docs.overturemaps.org/blog/2024/05/16/land-cover/).

---

## PMTiles

Overture is primarily distributed in the [GeoParquet format](/getting-data). While GeoParquet is a compact format, **tiles** are essential for creating pannable, zoomable slippy maps for display on the web.

* Data is broken into **equal-sized square chunks** (tiles), to load only the visible data.
* Tiles are arranged in a pyramid by level of detail, enabling **zoomed-out overviews.**

## overture-tiles on GitHub

The [overture-tiles GitHub repository](http://github.com/overtureMaps/overture-tiles) contains scripts and programs to generate tilesets from Overture data. These tilesets are designed for an "X-ray" visualization like at **[explore.overturemaps.org](https://explore.overturemaps.org)** to aid in inspecting geometry and properties. **They are not designed to be a production-ready cartographic basemap.**

![explore.overturemaps.org](/img/overture-tiles-header.png)

Each Overture theme is stored as a separate [PMTiles](https://github.com/protomaps/PMTiles) archive.

The individual tiles contain geometry and tags in the open [MVT](https://github.com/mapbox/vector-tile-spec) vector tile format.

## Accessing Tiles

Overture Tiles are generated with each release. The current beta distribution of tiles are at this url:

`s3://overturemaps-tiles-us-west-2-beta/RELEASE/THEME.pmtiles`

Where `RELEASE` has the data minor version trimmed, e.g. `2024-08-20`, instead of `2024-08-20.0`.

These public S3 URLs can also be accessed via HTTP:

`https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com/RELEASE/THEME.pmtiles`

### Viewing Tiles

Local and remote HTTP URLs can be previewed at [pmtiles.io](https://pmtiles.io).

[View 2024-08-20/places.pmtiles on pmtiles.io](https://pmtiles.io/?url=https%3A%2F%2Foverturemaps-tiles-us-west-2-beta.s3.amazonaws.com%2F2024-08-20%2Fplaces.pmtiles)

### Area Extracts

To create a new tileset for only part of the world, use the `extract` command of the [`pmtiles` CLI](https://github.com/protomaps/go-pmtiles).

To get all `buildings` tiles around Ghent, Belgium:

```
pmtiles extract https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com/2024-08-20/buildings.pmtiles ghent.pmtiles --bbox=3.660507,51.004250,3.784790,51.065996
```

## On AWS

The `overture-tiles` scripts can be automated with [AWS Batch](https://docs.aws.amazon.com/batch/), which generates the largest global tilesets in ~90 minutes using `c7gd.16xlarge` Ec2 instances on demand. Costs incurred include on-demand instances and S3 storage + transaction costs.

### Prerequisites

* [AWS CLI](https://docs.aws.amazon.com/cli/)
* [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/) `npm install -g aws-cdk`
* Docker Desktop

### Setup

1. Modify `bin/overture-tiles-cdk.ts`, specifying a different S3 bucket name.

2. From the `overture-tiles-cdk` repository:

```
npm run cdk bootstrap
npm run cdk deploy
```

3. Authenticate your Docker client with the provisioned AWS Elastic Container Registry (ECR) in the web console. Use **View Push Commands** to build the `Dockerfile` in the `overture-tiles` repository and push to ECR:

![explore.overturemaps.org](/img/overture-tiles-view-push-commands.png)

4. Submit jobs from the [AWS Batch](https://console.aws.amazon.com/batch/home#jobs) console. 

![explore.overturemaps.org](/img/overture-tiles-job-definitions.png)

  * Select from the available **Job Definitions**. Each Definition is associated with a version and theme from an Overture release.

  * Select the **OvertureTilesQueue** as the Job queue.

  * Add three **Environment Variables**:

    * `OUTPUT`: The path to the output on S3, such as `s3://your-bucket-name/2026-02-18.0/`

    * `THEME`: e.g. `places`

    * `RELEASE`: The Overture release, e.g. `2026-02-18.0`

  * Once the job is complete, the tileset will be available at `OUTPUT/THEME.pmtiles`, e.g. `s3://your-bucket-name/2026-02-18.0/places.pmtiles`

## On Your Workstation

### Requirements

* a Java Runtime Environment, version 22+, to build the `addresses`, `base`, `buildings` and `transportation` themes, along with `planetiler.jar` from [onthegomap/planetiler Releases](https://github.com/onthegomap/planetiler/releases).
* the [felt/tippecanoe](https://github.com/felt/tippecanoe?tab=readme-ov-file#installation) tool and the [DuckDB CLI](https://duckdb.org/docs/installation/) for other themes.
* the [aws CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) for downloading Overture data.

### Scripts

* Copy the Overture Parquet dataset to your local machine
  [using these docs](https://github.com/OvertureMaps/data/blob/main/README.md#how-to-access-overture-maps-data). If you want to only run on a small sample of data, you can use only the first `.parquet` file instead of all in the directory.

* for the `base`, `buildings` and `transportation` themes, generate the tileset with java:

```sh
# --data indicates where your Overture data is (overture/theme=base/...)
java -cp planetiler.jar profiles/Base.java --data=overture
```

The above command outputs `base.pmtiles` in the `data` dir.

* for other themes, run the theme script in `themes/`:

```sh
scripts/2024-08-20/places.sh overture places.pmtiles
```

This reads from Overture data in `overture` and writes `places.pmtiles`.

## Customization

The tilesets accompanying Overture releases are primarily for powering explore.overturemaps.org. For your own application, you may want to:

* Limit or modify the properties of each feature, to reduce the tile sizes.
* Change what features or properties are included at generalized lower zoom levels.

In these examples we'll work with a small area extract of Boston in the `boston/` folder, but all tiling methods can scale to the full dataset.

```sh
mkdir -p boston/theme=buildings/type=building
mkdir -p boston/theme=places/type=place
overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston/theme=buildings/type=building/0.geoparquet
overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=place -o boston/theme=places/type=place/0.geoparquet
```

### Example: Places

The default `places.sh` script includes all Overture properties to aid inspection. To slim down the tile sizes, you can remove all the primary name in the `@name` field.

Modify [places.sh](https://github.com/OvertureMaps/overture-tiles/blob/main/scripts/2024-07-22/places.sh) for the release matching your Overture data:

```sql
  ...
  json_object(
      'id', id,
      '@name', json_extract_string(names, '$.primary')
  ) AS properties,
  ...
```

```sh
./scripts/2024-07-22/places.sh boston boston_places.pmtiles
```

Inspect the created `boston_places.pmtiles` on [pmtiles.io](https://pmtiles.io) to see the slimmed-down properties:

![customized places tileset](/img/overture-tiles-customize-places.png)

### Example: Buildings

To reduce the size of tiles, the default Buildings script includes all properties only at zoom 13. Your own application may need this data at a lower zoom level.

Modify [`profile/Buildings.java`](https://github.com/OvertureMaps/overture-tiles/blob/main/profiles/Buildings.java) to populate all Overture properties on zoom 12 instead of zoom 13:

```java
...
OvertureProfile.addFullTags(source, polygon, 12);
...
```

```sh
java -cp planetiler.jar profiles/Buildings.java --data=boston
```

Inspect the created `data/buildings.pmtiles` on [pmtiles.io](https://pmtiles.io) to see the additional properties on zoom level 12:

![customized buildings tileset](/img/overture-tiles-customize-buildings.png)

---

## Pandas

In this example, we'll show you how to use [DuckDB](https://duckdb.org/) and [Pandas](http://pandas.pydata.org/) to extract and manipulate Overture data in a Jupyter notebook. We're using a Pandas DataFrame as an ideal structure for handling a small to medium amount of data and [GeoPandas](https://geopandas.org/en/stable/index.html) to extend Pandas for operations on geometric types. DuckDB allows us to fetch only the data we need from Overture's GeoParquet files stored on Microsoft Azure or AWS S3.

<details>

    <summary>
    **Installation requirements**

    </summary>
To follow along with these examples, you should have [JupyterLab or Jupyter Notebook](https://jupyter.org/) running and the following dependencies installed:

- [Pandas](https://pandas.pydata.org/)
- [GeoPandas](https://geopandas.org/en/stable/index.html)
- [DuckDB](https://duckdb.org/), [DuckDB spatial extension](https://duckdb.org/docs/extensions/spatial.html), and [DuckDB AWS extension](https://duckdb.org/docs/extensions/aws.html) or [DuckDB azure extension](https://duckdb.org/docs/extensions/azure.html).
- [JupySQL](https://jupysql.ploomber.io/en/latest/quick-start.html) (optional)
- [duckdb-engine](https://github.com/Mause/duckdb_engine) (optional)

</details>
A executable version of this notebook is available on [Notebook Sharing Space](https://notebooksharing.space/view/1d0d72d24ed82d22a8101377ca811ab7365b6a67dac98f3add034719c44b537f#displayOptions=). More examples are available in [the notebooks directory](https://docs.overturemaps.org/) in our docs repository on GitHub.

## Example

Let's start by importing our toolkit.

```python
# import our toolkit

from shapely import wkt
```

```python
# no need to import duckdb_engine, JupySQL will auto-detect driver
# load (or reload) jupysql Jupyter extension to create SQL cells
%reload_ext sql
```

The DuckDB documentation offers tips and examples for [running DuckDB queries in Jupyter notebooks](https://duckdb.org/docs/guides/python/jupyter.html). In this example, we're using duckdb-engine and JupySQL. You can also connect to DuckDB natively.

```python
# DuckDB in-memory database
%sql duckdb://
```

Next, we'll install and load DuckDB extensions to work with spatial data and connect to AWS. (Or you can use the Azure extension to connect to the Overture data stores on Azure.)

```python
%sql INSTALL spatial;
%sql INSTALL httpfs;
%sql LOAD spatial;
%sql LOAD httpfs;
%sql SET s3_region='us-west-2'
```
 We can set the configurations on JupySQL to directly output data to Pandas and to simplify the output that is printed to the notebook.

```python
%config SqlMagic.autopandas = True
%config SqlMagic.feedback = False
%config SqlMagic.displaycon = False
```

Now we're going to extract data from Overture's base theme for an area along the Gulf Coast. The magic %%sql command turns the notebook cell into a SQL cell and allows us to dump our query results in a Pandas DataFrame. Note: this query takes about a minute run.

```python
%%sql gulf_water <<
SELECT
    id,
    names.primary AS primary_name,
    ST_AsText(geometry) as geometry
FROM
    read_parquet('s3://overturemaps-us-west-2/release/2024-09-18.0/theme=base/type=water/*', filename=true, hive_partitioning=1)
WHERE
    bbox.xmin >= -91.3994
        and bbox.xmax <= -89.3864
        and bbox.ymin >= 29.152
        and bbox.ymax <= 30.5161
```

DuckDB 1.1.0 is able to interpret the geometry stored as a binary object in the GeoParquet file as a Shapely `geometry` type.

```python
# dataframe to geodataframe, set crs
gulf_water_gdf = gpd.GeoDataFrame(
    gulf_water,
    geometry=gulf_water['geometry'].apply(wkt.loads),
    crs="EPSG:4326"
)
```
Let's work with just the water polygons and lines, not the points.

```python
# Apply a lambda to remove point geometries
gulf_water_gdf = gulf_water_gdf[gulf_water_gdf['geometry'].apply(lambda x : x.geom_type!='Point' )]
```

Let's make a quick plot of the data. Voilà!

```python
gulf_water_gdf.plot(facecolor="#628290", edgecolor="#006064", lw=0.05)
```

![gulf bay](./assets/gulf-water.png)

## Next steps

- Want to speed things up and work with larger extracts of Overture data? Check out our [Lonboard tutorial](../lonboard).

---

## Rapid

## Places

In this example, we will load Overture Places data into Rapid so that we can visualize and inspect the geometries and their properties.

To open Rapid v2, navigate to [https://rapideditor.org/edit](https://rapideditor.org/edit).

Zoom in using the + or - hotkeys, the mouse scroll wheel, etc. to an area where you want to see Overture Places data.

Click the 'Map Data' sidebar button or hit the 'F' hotkey. Then, click the three dots icon next to 'Custom Data'.

![Map Data Panel in Rapid](./assets/rapid-visualizing-places.png)

You will see the Custom Data dialog. Paste this URL:

 <QueryBuilder query="https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com/__PMTILES_OVERTURE_RELEASE/places.pmtiles" language="text"></QueryBuilder>

into the text input and hit 'OK'.

Wait a few moments, and you should see some places data start to show up on the map. These places are clickable and inspectable:

![Rapid with Places Data Overlay](./assets/rapid-places-data.png)

Alternatively, Rapid can load the data automatically if the URL is formatted like this.

 <QueryBuilder query="https://rapideditor.org/edit#data=https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com/__PMTILES_OVERTURE_RELEASE/places.pmtiles" language="text"></QueryBuilder>

## Buildings

Rapid can also load polygon or line features in addition to point features.

 <QueryBuilder query="https://rapideditor.org/edit#data=https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com/__PMTILES_OVERTURE_RELEASE/buildings.pmtiles" language="text"></QueryBuilder>

![Rapid with Buildings Data Overlay](./assets/rapid-buildings-data.png)

---

## Sedona / Spark

As a series of GeoParquet files, Overture data is already optimized for distributed computing environments. The following example shows you how to work with Overture data in [Sedona](https://sedona.apache.org/), a cluster computing system for spatial data.

For this example, you can spin up a single-node Sedona Docker image from [Apache Software Foundation DockerHub](https://hub.docker.com/r/apache/sedona). In production, Sedona can be deployed to nearly any cloud environment (Databricks, AWS EMR, etc.), or check out [Wherobots](https://www.wherobots.com) to learn more about hosted  Sedona environments.

## Example
To get started with the single-node docker image, ensure your [docker](https://www.docker.com/) client is started, and then run:

```bash
docker pull apache/sedona
docker run -p 8888:8888 apache/sedona:latest
```

A Jupyter Lab and notebook examples is now available in your browser at [http://localhost:8888](http://localhost:8888/).

Create a new Python notebook with the following first cell:

```python
from sedona.spark import *

config = SedonaContext.builder().config(
    "fs.s3a.aws.credentials.provider",
    "org.apache.hadoop.fs.s3a.AnonymousAWSCredentialsProvider"
    ).getOrCreate()
sedona = SedonaContext.create(config)
```

After initializing your PySpark/Sedona environment, you can load theme data directly from S3. The following examples leverage Sedona's understanding of GeoParquet, so we can take full advantage of spatial queries:

<Tabs queryString="theme">
<TabItem value="places" label="Places">

<QueryBuilder query={`places = sedona.read.format("geoparquet").load(
    "s3a://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=places/type=place/")`} lang="python">
</QueryBuilder>

For example, to find all of the places in Seattle, you can apply a spatial filter with the bounding box for Seattle:

```python
places.filter("""ST_Contains(
    ST_GeomFromWKT('POLYGON((-122.459681 47.734124, -122.224433 47.734124, -122.224433 47.481002, -122.459681 47.481002, -122.459681 47.734124))'),
    geometry)""").limit(100).show()
```

Or, find all of the places within 1km of the Space Needle with the following query:

```python
places.filter("""ST_DistanceSpheroid(
    ST_GeomFromWKT('POINT(-122.3493 47.6204)'),
    geometry) < 1000
""")
```

</TabItem>

<TabItem value="buildings" label="Buildings">

<QueryBuilder query={`buildings = sedona.read.format("geoparquet").load(
    "s3a://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=buildings/type=building/")`} lang="python">
</QueryBuilder>

</TabItem>

<TabItem value="divisions" label="Divisions">

<QueryBuilder query={`divisions = sedona.read.format("geoparquet").load(
    "s3a://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=divisions/type=division_area/")`} lang="python">
</QueryBuilder>

</TabItem>

<TabItem value="transportation" label="Transportation">

<QueryBuilder query={`roads = sedona.read.format("geoparquet").load(
    "s3a://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=transportation/type=segment/")`} lang="python">
</QueryBuilder>

</TabItem>
</Tabs>

---

:::tip
These are just examples to show you how to interface with Overture data in Sedona. Running locally on a single-node docker image doesn't offer any performance benefits, but when deployed in a distributed cloud environment, you can operate on the entire Overture dataset.
:::

For more examples from wherobots, check out their Overture-related [Notebook examples](https://github.com/wherobots/OvertureMaps).

---

## Spark

In this example, we'll show you how to use [Spark](https://spark.apache.org/) in Python to extract and manipulate Overture data in a Jupyter notebook.

## Why Spark?
Spark is a robust distributed compute engine designed for scalable, fault-tolerant data processing across clusters. It provides a powerful mix of in-memory computation, lazy evaluation, and a declarative programming model, allowing users to build complex data pipelines that are automatically optimized for performance. Spark integrates seamlessly with common storage systems like S3 and supports multiple languages including Python, Java, Scala, and R, as well as SQL.

## Why Spark with Overture?
* **Scales to big data**: Overture queries can contain millions of records, and Spark’s distributed architecture scales compute and memory to process them efficiently.
* **Leverages declarative programming paradigms and lazy evaluation**: Spark builds execution plans and defers running operations until actions like `display()`, `print()`, `count()`, or `.write` collect data to memory. This enables complex transformations on Overture data to be optimized without overwhelming your system's memory.
* **Enables efficient predicate pushdown with parquet**: Spark intelligently applies filters at the file scan level using Parquet metadata, so even complex filters on Overture data only read the necessary rows. Given Overture is stored in [GeoParquet](https://geoparquet.org/), Spark is a great fit.
* **Integrates easily with S3**: Spark treats S3 paths like local filesystem paths, making it simple to load Overture datasets directly without manual file handling or custom connectors.

<details>

    <summary>
    **Installation requirements**
    
    </summary>
To follow along with these examples, you should have [JupyterLab or Jupyter Notebook](https://jupyter.org/) running and the following dependencies installed:

- [PySpark](https://spark.apache.org/docs/latest/api/python/getting_started/install.html)
 
</details>

## Example

First, let's install pyspark.

```bash
pip install pyspark
```

With our newest dependency installed, let's start by defining our configuration.

```python

from pyspark.sql import SparkSession

# Define our spark session
# For more, visit the spark docs: https://spark.apache.org/docs/latest/sql-getting-started.html
spark = SparkSession.builder.getOrCreate()

# Define constants for our read
OVERTURE_RELEASE = "2025-01-22.0"
COUNTRY_CODES_OF_INTEREST = ["US", "GH"]
SOURCE_DATA_URL = f"s3a://overturemaps-us-west-2/release/{OVERTURE_RELEASE}/theme=places/type=place"
OUTPUT_FILE = "my_super_cool_data.parquet"
```

Next, let's define a simple lazily-evaluated filter. Note that this filter on `COUNTRY_CODES_OF_INTEREST` will be pushed down to parquet. If there is relevant metadata in the parquet file, spark will be able to skip entire row groups and sometimes even entire parquet files when scanning for the criteria in the filter.

```python
country_overlap_condition = F.arrays_overlap(
    F.col("addresses.country"),
    F.array(*[F.lit(x.upper()) for x in COUNTRY_CODES_OF_INTEREST]),
)
```

With our filter defined, let's define our read and some additional metadata columns.

```python
source_df = (
    spark.read.format("parquet")
    .load(SOURCE_DATA_URL)
    .filter(country_overlap_condition)
    .withColumn("_overture_release_version", F.lit(OVERTURE_RELEASE))
    .withColumn("_ingest_timestamp", F.current_timestamp())
)
```

With eagerly evaluated frameworks, such as [Pandas](https://pandas.pydata.org/), the above step would immediately load data into memory. However, Spark is lazily evaluated, so transformations are planned but not executed until an action like `.write()` or `.show()` triggers a distributed computation.

To actually run a transformation, let's write this new dataset to another Parquet file on our local system.

```python
source_df.write.mode("append").format("parquet").save(OUTPUT_FILE)
```

And that's it! You've successfully used Spark to extract and transform Overture data.

## Next steps

* To run scalable ML algorithms on Spark, explore [Spark MLib](https://spark.apache.org/docs/latest/ml-guide.html), which offers a range of distributed machine learning models and tools. 
* For efficient execution of arbitrary columnar operations in Python, start with a [Pandas UDF](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.functions.pandas_udf.html). 
* For broader parallelism beyond Spark’s native model, consider [Ray on Spark](https://docs.ray.io/en/latest/ray-more-libs/raydp.html) or standalone Ray to orchestrate distributed execution of arbitrary Python code.

---

## Synapse (Azure)

You will need to create an account to use [Synapse](https://azure.microsoft.com/en-us/products/synapse-analytics/) and other Microsoft Azure services.

In your Azure account, create a [Synapse workspace](https://learn.microsoft.com/en-us/azure/synapse-analytics/get-started-create-workspace). You can then run this example query to get places in Seattle:

<QueryBuilder query={MicrosoftSynapseExample}></QueryBuilder>

More information is available at ["Query files using a serverless SQL pool"](https://learn.microsoft.com/en-us/training/modules/query-data-lake-using-azure-synapse-serverless-sql-pools/3-query-files) on Microsoft Learn.

---

## Wherobots(Examples)

[Wherobots](https://wherobots.com/) provides a cloud-native environment for geospatial data analysis, powered by [Apache Sedona](https://sedona.apache.org/latest/), allowing you to work with massive geospatial datasets at scale. Wherobots, an Overture Maps Foundation member, maintains a mirror of the Overture Maps data catalog on its platform.

In this example, we'll show you two ways to work with Overture Maps data in the Wherobots platform: loading and querying the Overture Maps data tables that already exist in the Wherobots cloud; and accessing and querying GeoParquet files directly from Overture Map's own Amazon S3 buckets. 

:::info
Before you get started you need to create a Wherobots account. You can create a **free** [Wherobots Community Edition Organization](https://cloud.wherobots.com/auth/register) or you can sign up for a **paid** Wherobots Professional Organization on [AWS marketplace](https://aws.amazon.com/marketplace/pp/prodview-ndy62v6hhwrne).
:::

## Part 1: Working with Overture Maps data tables in the Wherobots platform

### Setting up your notebook 

In your Wherobots account, go to the [notebooks section](https://cloud.wherobots.com/notebooks) and create a “Tiny” instance. This will spin up a Sedona Spark cluster with a Jupyter notebook environment. You'll notice that you have several [example notebooks](https://docs.wherobots.com/latest/get-started/start-notebook/) available to you. For this exercise, you'll need to create a new notebook with a Python 3 kernel. Run the following code in a notebook cell to import the necessary dependencies and create a `SedonaContext` that provides access to powerful spatial operations.

```python
from sedona.spark import *
from pyspark.sql import functions as f
from pyspark.sql.functions import col

config = (SedonaContext.builder().getOrCreate())
sedona = SedonaContext.create(config)
```

### Available datasets

In your notebook, you can use the following line of code to list the available Overture Maps data tables. 

```python
# List all available Overture datasets
sedona.sql("SHOW TABLES IN wherobots_open_data.overture_maps_foundation").show(truncate=False)
```

When you run that query you’ll get a list of all the available datasets under `tableName`:

```
+------------------------+---------------------------+-----------+
|namespace               |tableName                  |isTemporary|
+------------------------+---------------------------+-----------+
|overture_maps_foundation|geocodes                   |false      |
|overture_maps_foundation|places_place               |false      |
|overture_maps_foundation|transportation_segment     |false      |
|overture_maps_foundation|transportation_connector   |false      |
|overture_maps_foundation|buildings_building         |false      |
|overture_maps_foundation|divisions_division_area    |false      |
|overture_maps_foundation|buildings_building_part    |false      |
|overture_maps_foundation|base_land_cover            |false      |
|overture_maps_foundation|base_land_use              |false      |
|overture_maps_foundation|base_infrastructure        |false      |
|overture_maps_foundation|divisions_division_boundary|false      |
|overture_maps_foundation|base_land                  |false      |
|overture_maps_foundation|base_water                 |false      |
|overture_maps_foundation|divisions_division         |false      |
|overture_maps_foundation|addresses_address          |false      |
|overture_maps_foundation|base_bathymetry            |false      |
+------------------------+---------------------------+-----------+
```

To call any of these datasets, use the following syntax for the table name: `wherobots_open_data.overture_maps_foundation.{tableName}`.

### Loading Overture data

You can load Overture Maps data into your notebook using either the DataFrame API or SQL API:

<Tabs>
<TabItem value="DataFrame API" label="DataFrame API" default>
Here's how to create a Wherobots dataframe with of the Overture Places dataset:

```python
# Load Places dataset
places_df = sedona.table("wherobots_open_data.overture_maps_foundation.places_place")

# Display sample data
places_df.show(5)
```
</TabItem>
<TabItem value="SQL API" label="SQL API" default>
You can also use spatial SQL syntax with the SQL API:
```python
# Load Overture Places data
places_df = sedona.sql("""
    SELECT * FROM wherobots_open_data.overture_maps_foundation.places_place
""")

# Create a temporary view
places_df.createOrReplaceTempView("places")

# Display sample data
places_df.show(5)
```
</TabItem>
</Tabs>

### Example query: filtering by geography

Let's run a query to get a count of all the Overture Maps places in San Francisco. 

```python
# Define an area of interest (e.g., San Francisco bounding box)
sf_bbox = "POLYGON((-122.512 37.708, -122.512 37.810, -122.357 37.810, -122.357 37.708, -122.512 37.708))"

# Find places within San Francisco
sf_places = sedona.sql(f"""
    SELECT *
    FROM places
    WHERE ST_Intersects(geometry, ST_GeomFromWKT('{sf_bbox}'))
""")

# Show result count
print(f"Found {sf_places.count()} places in the specified area")
sf_places.show()
```

## Part 2: Access and query Overture Maps data directly from Amazon S3 

While Wherobots provides its own hosted version of the Overture dataset, the next part of this example explains how to perform Spatial SQL queries directly on the [Overture Maps data stored on Amazon S3](https://docs.overturemaps.org/getting-data/). We'll demonstrate a simple ETL pipeline: extract GeoParquet data from S3, transform it through geographic filtering and schema refinement, and load it into a clean dataframe in your Jupyter notebook.

### Get the Amazon S3 path for the Overture Maps data you want to query

Review the [getting started page in the Overture Maps documentation](https://docs.overturemaps.org/getting-data/) to determine the Amazon S3 Path of the data that you wish to query. This example will query the `building` type from the `buildings` theme and the `segment` type from the `transportation` theme.

### Setting up your notebook environment
On the Wherobots Cloud landing page, select an available runtime to launch a new notebook. Once the runtime has loaded, open the notebook. In a notebook cell, import the necessary dependencies and initialize the Sedona Context.

```python
from sedona.spark import *
from pyspark.sql import functions as f
from pyspark.sql.functions import col

config = (SedonaContext.builder().getOrCreate())
sedona = SedonaContext.create(config)
```

### Querying Overture Maps data in Wherobots
Once you have the correct S3 path, you can query the Overture Maps data. The code example below takes two separate, siloed datasets (`buildings` and `transportation`) and merges them into a single, unified table.

Define your area of interest (in this case, Golden Gate Park) and a reusable helper function to load, filter, and combine the buildings and transportation data. Click `Run > Run Selected Cell` to execute the query and see the results.

```python
# Define the region of interest as San Francisco's Golden Gate Park
region_wkt = "POLYGON ((-122.5106 37.7736, -122.4549 37.7788, -122.4491 37.7656, -122.5103 37.7606, -122.5106 37.7736))"

# Define the release version as a variable for configurability
RELEASE_VERSION = "2025-06-25.0"  # Update this value when a new release is available

def process_overture_layer(theme, type, region_wkt):
    """
    Loads an Overture theme from S3, filters it by a geographic region,
    and selects the required columns.
    """
    s3_path = f"s3://overturemaps-us-west-2/release/{RELEASE_VERSION}/theme={theme}/type={type}"
    print(f"Processing {theme} in Golden Gate Park...")

    df = (
        sedona.read.parquet(s3_path)
        .withColumn("geometry", f.expr("ST_GeomFromWKB(geometry)"))
        .where(f.expr(f"ST_Intersects(geometry, ST_GeomFromText('{region_wkt}'))"))
        .select(
            "geometry",
            f.lit(theme).alias("layer"),
            f.element_at(f.col("sources"), 1)["dataset"].alias("source")
        )
    )
    return df

# Process each layer using the function
buildings_df = process_overture_layer("buildings", "building", region_wkt)
roads_df = process_overture_layer("transportation", "segment", region_wkt)

# Union the processed dataframes and get the final count
combined_df = buildings_df.unionByName(roads_df)

print("\n--- Analysis Complete ---")
print(f"Found {combined_df.count()} total features in Golden Gate Park.")
combined_df.show(10)
```

## Resources
For more on using the Wherobots platform, see the official [Wherobots documentation](https://docs.wherobots.com/).

---

## Bridge Files

With each data release, Overture generates **bridge files** that connect GERS IDs to the IDs from the [source data](/attribution). These files are a key component of GERS and offer two critical capabilities: reverse lookup of source features and insight into Overture's conflation process.

Here's how to get the bridge files:

| Provider                     | Location                                                                  |
| ---------------------------- | ------------------------------------------------------------------------- |
| Amazon S3                    | `s3://overturemaps-us-west-2/bridgefiles/<RELEASE>`                       |
| Microsoft Azure Blob Storage | `https://overturemapswestus2.blob.core.windows.net/bridgefiles/<RELEASE>` |

The latest Overture data `<RELEASE>` is:

<QueryBuilder query="__OVERTURE_RELEASE/" language="text"></QueryBuilder>

:::note
Currently, Overture only generates bridge files for these source datasets: Esri Community Maps, geoBoundaries, Instituto Geográfico Nacional (España), Meta Places, Microsoft Places, OpenStreetMap, PinMeTo.
:::

## Partitioning and schema

Bridge files are released as Parquet files, partitioned by `dataset`, `theme`, and `type` and structured in this way:

```
\bridgefiles
    \<RELEASE>
        \dataset=OpenStreetMap
            \theme=divisions
                \type=division
                \type=division_area
            \theme=buildings
                 \type=building
            \theme=transportation
                 \type=segment
        \dataset=Esri Community Maps
            \theme=buildings
                 \type=building
        \dataset=PinMeTo
            \theme=places
                 \type=places
        \dataset=meta
            \theme=places
                \type=places
        \dataset=Microsoft
            \theme=places
                \type=places
        \dataset=Instituto Geográfico Nacional (España)
            \theme=buildings
                \type=building
        \dataset=geoBoundaries
            \theme=divisions
                \type=division
                \type=division_area

```

The bridge file schema includes the following columns:

| Column            | Data type | Description                                                                                                                                                           |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | string    | represents the GERS ID and is populated from the id column in the Overture data schema                                                                                |
| `record_id`       | string    | represents the id of the feature as it is in the source data provider (e.g. n2757802019@9) and is populated by parsing the sources column in the Overture data schema |
| `update_time`     | string    | represents the time the feature or dataset was updated, depending on the data provider; also populated by parsing the sources column in the Overture schema           |
| `dataset`         | string    | represents the name of the dataset the feature has been provided in; also populated by parsing the sources column in the Overture data schema                         |
| `theme`           | string    | represents the theme the feature is a part of, provided by the creator of the bridge file itself                                                                      |
| `type`            | string    | represents the type of the feature, either derived from the data or provided by the creator of the bridge file                                                        |
| `between`         | array     | represents the portion of the normalized length of the GERS feature the dataset way takes, represented by a range between 0 and 1                                     |
| `dataset_between` | array     | represents the portion of the normalized length of the dataset way the GERS feature takes, represented by a range between 0 and 1                                     |

## Example: examining the source data for the `building` dataset

In this example, we'll trace the buildings data in the latest release back to the underlying source datasets. We'll examine an area near the US-Mexico border outside San Diego. First, let's get the buildings in our area of interest:

```sql
CREATE TABLE IF NOT EXISTS border_buildings AS
(SELECT
    *
FROM read_parquet('s3://overturemaps-us-west-2/release/2025-05-21.0/theme=buildings/type=building/*')
WHERE
bbox.xmin > -117.048198 AND bbox.xmax < -117.044608
    AND bbox.ymin > 32.535068 AND bbox.ymax < 32.600154);
```

You'll notice the table has 4367 `building` features. Now let's look at the `building` count by data source:

```sql
SELECT
   sources[1].dataset AS source,
   count(*)
FROM border_buildings
GROUP BY source;
```

```
┌────────────────────────┬──────────────┐
│         source         │ count_star() │
│        varchar         │    int64     │
├────────────────────────┼──────────────┤
│ Esri Community Maps    │          412 │
│ OpenStreetMap          │         1539 │
│ Google Open Buildings  │         1751 │
│ Microsoft ML Buildings │          665 │
└────────────────────────┴──────────────┘
```

Now we'll use the latest bridge file to find additional information about data in the Overture corpus that didn't make it into the release. We'll join the table we created from the release data with the bridge file data to create a new table that has detailed view of the source mappings. _Remember: we only have bridge files for Esri Community Maps data and OpenStreetMap data._

```sql
CREATE TABLE IF NOT EXISTS border_buildings_corpus AS
(SELECT
  border_buildings.id AS gers_id,
  dataset,
  record_id AS dataset_record_id
FROM
  border_buildings
JOIN
  read_parquet('s3://overturemaps-us-west-2/bridgefiles/2025-05-21.0/dataset=*/theme=buildings/type=building/*') bridge
ON border_buildings.id = bridge.id
ORDER BY border_buildings.id, bridge.dataset);
```

You might notice this new table created from our join has only 2,021 records compared to 4,367 `building` records in our original query of the latest release data. This is because we have incomplete bridge file coverage for buildings; we don't generate bridge files for Microsoft ML Buildings and Google Open Buildings because those sources don't have meaningful IDs for reverse lookup. However the bridge files that do exist for buildings reveal important patterns:

- Multiple sources per building: a single Overture building may be conflated from multiple source datasets
- One-to-many mapping: each source contribution gets its own bridge file record

Let's dig into this a bit more. We can identify the `building` features in the release that have multiple source mappings.

```sql
-- Identify buildings conflated from multiple sources
SELECT gers_id,
       COUNT(DISTINCT dataset) as source_count,
       STRING_AGG(DISTINCT dataset, ', ') as datasets
FROM border_buildings_corpus
GROUP BY gers_id
HAVING COUNT(DISTINCT dataset) > 1;
```

There are 70 buildings with that are mapped to two data sources. Here's a snippet of the query result:

```
┌──────────────────────────────────┬──────────────┬────────────────────────────────────┐
│             gers_id              │ source_count │              datasets              │
│             varchar              │    int64     │              varchar               │
├──────────────────────────────────┼──────────────┼────────────────────────────────────┤
│ 08b29a4c428ebfff02002b827866f466 │            2 │ OpenStreetMap, Esri Community Maps │
│ 08b29a4c428c3fff0200bb4d5defac52 │            2 │ Esri Community Maps, OpenStreetMap │
│ 08b29a4c428e5fff0200cddeda1c3c68 │            2 │ OpenStreetMap, Esri Community Maps │
│ 08b29a4c4280bfff0200729b26aa9ec7 │            2 │ Esri Community Maps, OpenStreetMap │
│ 08b29a4c428c9fff0200cc521ce08155 │            2 │ OpenStreetMap, Esri Community Maps │
│ 08b29a4c428cbfff0200df6833fcb919 │            2 │ Esri Community Maps, OpenStreetMap │
│ 08b29a4c428cbfff0200d5d23faeeec7 │            2 │ Esri Community Maps, OpenStreetMap │
│ 08b29a4c42809fff02000729055d0147 │            2 │ Esri Community Maps, OpenStreetMap │
│ 08b29a4c428ccfff02002cbabfaf31e0 │            2 │ Esri Community Maps, OpenStreetMap │
│ 08b29a4c4280bfff02003a1e8ccaeb68 │            2 │ Esri Community Maps, OpenStreetMap │

...
```

Let's pull out one example:

| gers_id                          | dataset             | dataset_record_id      | update_time              |
| -------------------------------- | ------------------- | ---------------------- | ------------------------ |
| 08b29a4c428ebfff02002b827866f466 | Esri Community Maps | esri_ChulaVistaCA13510 | 2024-10-15T00:00:00.000Z |
| 08b29a4c428ebfff02002b827866f466 | OpenStreetMap       | w1182486582@1          | 2023-06-16T14:22:10.000Z |

This shows that building `08b29a4c428ebfff02002b827866f466` was created by a conflation process that included data from OpenStreetMap (way 1182486582, version 1) and Esri Community Maps (esri*ChulaVistaCA13510). The conflation process \_may* have included other data sources that have not been mapped to GERS and released as bridge files.

## Next steps

- Examine the source data for building `08b29a4c428ebfff02002b827866f466` by looking up the OSM ID in [OpenStreetMap](https://www.openstreetmap.org/)
- Explore the other components of GERS: registry, [changelog](../changelog), and [reference map](https://explore.overturemaps.org/#15/38.90678/-77.03649)
- Follow our [GERS tutorial](../gers-tutorial)

---

## Data Changelog

With each data release, Overture publishes a **changelog** that capture changes in the data from the previous release to the current release. This information can be used to guide decisions about data matching, better understand data stability, and help detect data errors.

The data changelog is available as Parquet files, partitioned by `theme`, `type`, and `change_type` and sorted geospatially with a unique index on `id`. The changelog files are available at the following locations:

| Provider | Location |
| ------ | -------- |
| Amazon S3 | `s3://overturemaps-us-west-2/changelog/<RELEASE>` |
| Microsoft Azure | `wasbs://changelog@overturemapswestus2.blob.core.windows.net/<RELEASE>` |

The latest path is:
<QueryBuilder query="__OVERTURE_RELEASE/" language="text"></QueryBuilder>

## Types of changes

The `change_type` property in the changelog includes these types of changes to the entities:

- **added**: the entity with this ID is new in the current release and was not present in the previous release
- **removed**: the entity with this ID is not present in the current release but was present in the previous release
- **data_changed**: the entity with this ID in the current release contains a change in geometry or properties from the entity with this ID that was in the previous release
- **unchanged**: the entity with this ID in the current release matches the geometry and properties of the entity with this ID that was in the previous release

## Querying the data changelog

We can query the changelog to get a quick look at changes in data from the last release to the current release. In this example, we're using DuckDB to grab the `id`, `type`, and `change_type` for buildings in several towns across the [Amhara Region](https://en.wikipedia.org/wiki/Amhara_Region) in Ethiopia.

<QueryBuilder query={changelog_buildings_churn}></QueryBuilder>

We can also get a count of building features by `change_type` for our area of interest.

<QueryBuilder query={changelog_buildings_feature_by_change_type}></QueryBuilder>

Taking this one step further, this time using Athena to run our query, we can join the changelog and data via the `id` to connect the `change_type` and entity properties.

<QueryBuilder query={changelog_buildings_join}></QueryBuilder>

Finally we can use the results of our query to visualize building features by `change_type` and inspect the properties for each feature. The example below, created using [kepler.gl](https://kepler.gl/), shows buildings in [Finote Selam](https://en.wikipedia.org/wiki/Finote_Selam), a city in the Amhara Region of Ethiopia. The data is from Overture's `2024-06-13-beta.0` release, to which we added 100 million new buildings, many of them derived from satellite imagery by Microsoft.

![Buildings By Change Type](/img/gers/buildings-change-type-amhara-region.png)

---

## GERS Tutorial

## Why associate your data with GERS identifiers?

The Overture Maps Foundation doesn’t just produce a collection of open datasets, it defines a reference system for exchanging and enriching geospatial data. This reference system, called GERS (Global Entity Reference System), provides persistent unique identifiers for each map feature in Overture’s datasets.

By matching your data to Overture’s and attaching GERS identifiers to your datapoints, you can share and connect your data with other GERS-associated datasets. 

## Process overview

To associate your data with GERS identifiers, we need to:

1. Perform an initial association between your data and a relevant Overture theme.
2. Add GERS identifiers to your dataset as a column or produce your own “bridge file” mapping your data identifiers to their corresponding GERS identifiers.
3. Perform a regular maintenance match, usually with every monthly Overture release.

Joining geospatial datasets is a highly context dependent task. Sometimes you want very precise matches, with little risk of false positives. And other times you want greedy, loose matches, with wide coverage. To demonstrate this context dependency, we’ll be adopting the following use case to frame our decisions:

*We’re building a hyperlocal mobile application that allows people to browse restaurants in Alameda County. Users can search for, browse, bookmark, and share restaurants. We will be using [Overture’s Places theme](../../guides/places) as our foundational dataset, but we want to bring in additional datasets to add details to our restaurant listings.*

One dataset we want to add is [Alameda County’s restaurant inspection reports](https://data.acgov.org/datasets/e95ff2829e9d4ea0b3d8266aac37ff14_0/explore), a dataset detailing the health and safety scores for each restaurant. This data will allow our users to filter restaurants by their health scores and present these health scores in our restaurant profiles.

The following tutorial walks through how to join this dataset to Overture's places, both as a one-off connection and an ongoing match process.

## Performing an initial match 

### Planning our match
Alameda County produces and publishes a dataset detailing restaurant inspections. These records are regularly updated and specify the current “health score” of a given venue. The county publishes these records in a variety of formats; today we’ll be using their GeoJSON distribution.

In the GeoJSON file, records are stored as features. For example:

```javascript
{
           "type": "Feature",
           "id": 3,
           "geometry": {
               "type": "Point",
               "coordinates": [
                   -122.056105500269,
                   37.6374869997196
               ]
           },
           "properties": {
               "OBJECTID": 3,
               "Facility_ID": "FA0319719",
               "ExternalID": 827161,
               "Facility_Name": "LALO'S TAQUERIA",
               "Address": "28293 MISSION BLVD",
               "City": "HAYWARD",
               "State": "CA",
               "Zip": "94544",
               "Activity_Date": "2024-01-18",
               "Service": "111",
               "Violation_Description": "Food in good condition, safe and unadulterated",
               "Grade": "G",
               "Longitude": -122.0561055,
               "Latitude": 37.637487
           }
       }
```

If you’re following along, go ahead and download [the GeoJSON data from Alameda County’s portal](https://data.acgov.org/datasets/e95ff2829e9d4ea0b3d8266aac37ff14_0/explore?location=37.676900%2C-122.008949%2C10.04).

Inspection records are associated with restaurants and eateries, so it makes sense to associate these records with Overture’s Places theme. 

In the Overture places dataset, the record which matches the inspection example above looks like this, in GeoJSON form:

```javascript
{
   "type": "Feature",
   "geometry": {
       "type": "Point",
       "coordinates": [
           -122.056054,
           37.63755
       ]
   },
   "properties": {
       "id": "08f28346e8ca018503160340e65ac7b6",
       "type": "place",
       "version": 0,
       "sources": [
           {
               "property": "",
               "dataset": "meta",
               "record_id": "103711722756889",
               "update_time": "2025-02-24T08:00:00.000Z",
               "confidence": 0.9793990828827596
           }
       ],
       "names": {
           "primary": "Lalo's Taqueria",
           "common": null,
           "rules": null
       },
       "categories": {
           "primary": "mexican_restaurant",
           "alternate": [
               "restaurant",
               "eat_and_drink"
           ]
       },
       "confidence": 0.9793990828827596,
       "socials": [
           "https://www.facebook.com/103711722756889"
       ],
       "phones": [
           "+15109400137"
       ],
       "addresses": [
           {
               "freeform": "28293 Mission Blvd",
               "locality": "Hayward",
               "postcode": "94544-4853",
               "region": "CA",
               "country": "US"
           }
       ]
   }
}
```

Comparing the schema of each, we can see there are a few elements we can reference during our match:

![schema-comparison](/img/gers/schema-comparison.png)

Using these common properties, and a bit of SQL, we can spin up a quick matcher using DuckDB.

### Staging our datasets

With our inspection data saved as `inspection_records.geojson`, let’s boot up [DuckDB](/getting-data/duckdb/), specifying a local database as a cache.

```bash
$ duckdb inspection_match.ddb
```

We’ll load DuckDB's `spatial` and `httpfs` plug-ins, then load our inspections into a local table.

```sql
D install spatial;
D load spatial;
D install httpfs;
D load httpfs;
D CREATE TABLE IF NOT EXISTS inspections AS SELECT * FROM ST_Read('inspection_records.geojson');
```

Since there are multiple inspections for each venue, and we want to match each venue to an Overture place, we’re going to create a separate table just for the facilities.

```sql
D CREATE TABLE IF NOT EXISTS facilities AS 
  SELECT Facility_ID, Facility_Name, Address, City, State, Zip, geom
  FROM inspections
  GROUP BY Facility_ID, Facility_Name, Address, City, State, Zip, geom;
  ```

:::note
We’re only pulling in each facility's ID and the columns which overlap with Overture’s places.
:::

Geospatial matching processes can get quite complex, so we’re going to load the Overture data we need in a local table before attempting any joins. 

```sql
D CREATE TABLE IF NOT EXISTS places AS 
  WITH bounding_box AS (
    SELECT max(ST_Y(geom)) as max_lat, 
           min(ST_Y(geom)) as min_lat, 
           max(ST_X(geom)) as max_lon, 
           min(ST_X(geom)) as min_lon
    FROM facilities
  )
  SELECT 
    id, 
    upper(names['primary']) as Facility_Name, 
    upper(addresses[1]['freeform']) as Address, 
    upper(addresses[1]['locality']) as City, 
    upper(addresses[1]['region']) as State, 
    left(addresses[1]['postcode'], 5) as Zip, 
    geometry as geom, 
    categories,
    confidence 
  FROM (
    SELECT * 
    FROM read_parquet('s3://overturemaps-us-west-2/release/2025-04-23.0/theme=places/type=place/*', filename=true, hive_partitioning=1),
      bounding_box
    WHERE addresses[1] IS NOT NULL 
      AND bbox.xmin BETWEEN (bounding_box.min_lon - 0.01) AND (bounding_box.max_lon + 0.01)
      AND bbox.ymin BETWEEN (bounding_box.min_lat - 0.01) AND (bounding_box.max_lat + 0.01)
  );
```

We’re doing several things here that are worth breaking down:

1. We create a bounding box by computing the maximum and minimum latitude and longitude values of our inspections. This ensures we’re only pulling Overture Places relevant to our input dataset.
2. Our following `SELECT` statement prepares the Places data to more closely align with the conventions of our inspections data: the `addresses` column is broken down into component columns and we use only the primary name from the `names` column and label it to match `Facility_Name`.
3. Finally, we obtain the data from the Overture S3 bucket by remotely reading the parquet. A `WHERE` statement limits our request to a slightly buffered bounding box (buffered to ensure we’re capturing places near those facilities on the edges of our dataset).

We now have three tables: `inspections` with 27,515 records, `facilities` with 4,340 records, and `places` with 73,985 records.

Before we work on connecting them, we’ll add some spatial indexes to each table, making our lookups much faster:

```sql
D CREATE INDEX IF NOT EXISTS idx_places_geometry ON places USING RTREE (geom);
D CREATE INDEX IF NOT EXISTS idx_facilities_geometry ON facilities USING RTREE (geom);
```

### Matching our data

Geospatial matching can be a simple or very complicated process. A simple join might just be a couple `WHERE` statements, while a complicated process might employ a compound pipeline with  Bayesian comparisons, vector search, LLMs, and/or human reviewers. It all depends on your use case. 

Geospatial matching can also be *greedy* or *cautious*. A greedy matching routine will have less stringent standards and err towards making mismatches, whereas a cautious match will apply strict standards and err towards missing a correct match.

What type of match you employ &mdash; simple or complicated, greedy or cautious &mdash; requires you to understand how your data is being used, the cost of a false positive, and more. This is to say: it’s a decision beyond the scope of this tutorial.

For our example, we will be constructing a *simple cautious* matcher. We’ve chosen to build a cautious matcher because our data describes inspection scores and violations; the cost of a false match is *high*. It is safer for us to show *no* health score than show a *failing* one for a restaurant that did not fail.

But to get started, we will write a join using three conditions with very loose thresholds. We’ll break down each condition below.

```sql
D SELECT 
    f.Facility_ID as input_id, 
    f.Facility_Name as input_name, 
    f.Address as input_address, 
    p.id as match_id, 
    p.Facility_Name as match_name, 
    p.Address as match_address,
    p.confidence as overture_confidence,
    ST_Distance_Sphere(f.geom, p.geom) as distance, 
    jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) as name_similarity, 
    jaro_winkler_similarity(f.Address, p.Address) as address_similarity
  FROM facilities f
  JOIN places p
    ON ST_DWithin(f.geom, p.geom, 0.001)
    AND jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) > 0.7
    AND jaro_winkler_similarity(f.Address, p.Address) > 0.8
  ORDER BY f.Facility_ID, distance;
```

Scanning down to the `JOIN` statement, we are using three comparisons to associate our records:

1. **Is it close by?** `ST_DWithin(f.geom, p.geom, 0.005)`: This matches records if they’re within ~100 meters from each other (this is what 0.001 roughly equates to in our [SRID](https://en.wikipedia.org/wiki/Spatial_reference_system))

2. **Do the names match?** `jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) > 0.7`: This is a [string comparison function](https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance) that generates a score from 0.0 to 1.0, with 1.0 being an exact match. Here we’re comparing the listed name for each record. We’ve chosen the Jaro-Winkler metric because it weights the beginning of strings higher than the end of strings, which tends to work well here.

3. **Do the addresses match?** `jaro_winker_similarity(f.Address, p.Address) > 0.8`: We’re using the same function as the previous comparison, just with a slightly higher threshold, to compare our addresses.

With just this query, we can get pretty far. There are three levers &mdash; the values specified for each of the three statements above &mdash; that we can tweak until we’re close to good.

At this point, it’s helpful to look at the data yourself. I usually use [DuckDB’s CSV export function](https://duckdb.org/docs/stable/guides/file_formats/csv_export.html) and scan the results, looking for patterns to inform tweaking our parameters.

For example, here are 3 candidate Overture Places which match with “Thornhill Coffee Shop”, located at 5772 Thornhill Drive.

| Name | Address | Distance | Name Similarity | Address Similarity |
| ---------- | ---------- | ---------- | ---------- | ---------- |
| THORNHILL COFFEE HOUSE | 5772 THORNHILL DR | 35.52 | 0.96 | 1.00 |
| THORNHILL SALON | 5736 THORNHILL DR | 41.46 | 0.85 | 0.93 |
| THORNHILL PET HOSPITAL | 5745 THORNHILL DR | 70.93 | 0.87 | 0.93 |

Here, everything is functioning as it should be. Even though our matcher is looser (it’s letting in the two wrong candidates), the distance, name similarity, and address similarity metrics allow us to easily order our results and allow the correct record to bubble up.

But elsewhere, this is not the case. Consider this example for matches with “West Oakland Senior Center”, 1724 Adeline Street:

| Name | Address | Distance | Name Similarity | Address Similarity |
| ---------- | ---------- | ---------- | ---------- | ---------- |
| WEST OAKLAND BRANCH | 1801 ADELINE ST | 55.85 | 0.87 | 0.88 |
| WEST OAKLAND JOB RESOURCE CENTER | 1801 ADELINE ST | 56.17 | 0.90 | 0.88 |
| WEST OAKLAND SENIOR CENTER | 1724 ADELINE ST | 64.24 | 1.0 | 1.0 |

In this example, ranking in descending order of distance puts the correct match at the bottom. This cluster of match candidates suggests a perfect match for name and address should overrule slight distance differences.

Reviewing these cluster candidates is essential work when building a matcher. As you plot and peruse them, patterns will emerge, enabling you to better tune your parameters. 

For larger matches &mdash; beyond the scale of ~4,000 restaurants in a single county &mdash; we recommend building evaluation test sets: human-verified correct and incorrect match pairs for a sample of your data. With an evaluation test set, one can more systematically tweak their matcher and quantitatively measure their performance.

But for our restaurant app scenario, we’re fine with a quick match to populate our listings. After reviewing the data and running a few adjusted queries, we landed on an effective *simple conservative* matcher query:

```sql
WITH ranked_matches AS (
SELECT 
    f.Facility_ID as input_id, 
    f.Facility_Name as input_name, 
    f.Address as input_address, 
    p.id as match_id, 
    p.Facility_Name as match_name, 
    p.Address as match_address,
    p.confidence as overture_confidence,
    ST_Distance_Sphere(f.geom, p.geom) as distance, 
    jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) as name_similarity, 
    jaro_winkler_similarity(f.Address, p.Address) as address_similarity,
    ROW_NUMBER() OVER (
      PARTITION BY f.Facility_ID
      ORDER BY jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) DESC
    ) as rank
  FROM facilities f
  JOIN places p
    ON ST_DWithin(f.geom, p.geom, 0.001)
    AND jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) > 0.89
    AND jaro_winkler_similarity(f.Address, p.Address) > 0.75
)
SELECT * FROM ranked_matches WHERE rank = 1
```

This query yields 2,358 correct matches and no false positives, for a match rate of 55%. By adding more conditionals and stages, we could get much higher results (if you’d like the details about that, [check out a longer exploration here](https://www.dbreunig.com/2024/09/27/conflating-overture-points-of-interests-with-duckdb-ollama-and-more.html)), but for our restaurant listing app, this suits our needs. 

## Enriching your data with GERS IDs & producing your own bridge file

### Enriching our table

With our matcher written and tuned, let’s add a column to our `facilities` table named `gers_id` and populate it with our join query above:

```sql
ALTER TABLE inspections ADD COLUMN geometry VARCHAR;
ALTER TABLE inspections ADD COLUMN gers_id VARCHAR;
WITH ranked_matches AS (
    SELECT 
        f.Facility_ID as input_id, 
        f.Facility_Name as input_name, 
        f.Address as input_address, 
        p.id as match_id, 
        p.Facility_Name as match_name, 
        p.Address as match_address,
        p.confidence as overture_confidence,
        ST_Distance_Sphere(f.geom, p.geom) as distance, 
        jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) as name_similarity, 
        jaro_winkler_similarity(f.Address, p.Address) as address_similarity,
        ROW_NUMBER() OVER (
            PARTITION BY f.Facility_ID
            ORDER BY jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) DESC
        ) as rank
    FROM facilities f
    JOIN places p
        ON ST_DWithin(f.geom, p.geom, 0.001)
        AND jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) > 0.89
        AND jaro_winkler_similarity(f.Address, p.Address) > 0.75
),
selected_matches AS (
    SELECT input_id, match_id FROM ranked_matches WHERE rank = 1
)
UPDATE inspections i SET gers_id = sm.match_id FROM selected_matches sm WHERE i.Facility_ID = sm.input_id;
```

Our `facilities` table is now enriched with GERS identifiers. 

We can use this association to connect county health scores with our Overture Places basemap, then display them to our app users.

Further, if we can share our association with others, allowing them to benefit from the hard work we’ve done matching this data and easily connect it to their GERS-associated datasets using only a column join. One way to facilitate this is a bridge file.

### Producing a bridge file

A bridge file is essentially a join table, connecting GERS identifiers with another set of identifiers. Overture produces [bridge files](../bridge-files) with each data release for the data sources we use to produce our datasets, allowing others to understand the provenance of our data and to quickly enrich their own data with Overture datasets, if they’re currently using one of our input data sources.

Once you’ve enriched your dataset with GERS identifiers, you can produce a bridge file like this:

```sql
SELECT Facility_ID, gers_id FROM inspections WHERE gers_id IS NOT NULL GROUP BY Facility_ID, gers_id;
```

Output this query as a CSV or parquet file and you’re done. It looks like this:

```bash
Facility_ID,gers_id
FA0319719,08f28346e8ca018503160340e65ac7b6
FA0319719,08f28346e8ca018503160340e65ac7b6
FA0319719,08f28346e8ca018503160340e65ac7b6
FA0002404,08f283098d6527200394e5ac0b19dbf5
FA0002404,08f283098d6527200394e5ac0b19dbf5
```

## Performing a maintenance match

### Associating with every monthly release

Overture currently releases a new version of its data every month. Our [releases page](https://docs.overturemaps.org/release/latest/) specifies its location and provides release notes.

**Geospatial data never sleeps**. The real world is constantly changing, and in our case, restaurants are continually being opened and closed. Further, as Overture onboards new sources of data, the quality and coverage of our releases improves. 

:::tip
Regularly associating your data with Overture’s is considered best practice.
:::

While rerunning a match for our ~4,000 restaurants is relatively quick, larger dataset associations can be quite costly. Thankfully, there are a few things we can take advantage of to make this process easier. 

### Overture data changelog

With each data release, Overture generates a [data changelog](https://docs.overturemaps.org/gers/changelog/) to capture changes in the data tied to the GERS ID for each feature. This information can be used to help reduce the scope of our maintenance match by identifying associated GERS IDs which have changed.

Using our same DuckDB database, we can remotely query the current changelog using a bounding box defined by our inspections dataset. 

But wait &mdash; using the current April changelog won’t yield very interesting results, since we’ve already matched against the April data. For this exercise we’ll redo our work above, this time referencing the previous, March, Overture release.

### Finding a subset of records that need matching

Matching against the March data, we connect 2,366 of our facility IDs to GERS IDs. Let’s see how the April changelog can help during our maintenance match.

First, we’ll cache the changelog in a table, filtered again by a bounding box:

```sql
CREATE TABLE IF NOT EXISTS changes AS
WITH bounding_box AS (
    SELECT max(ST_Y(geom)) as max_lat, min(ST_Y(geom)) as min_lat, max(ST_X(geom)) as max_lon, min(ST_X(geom)) as min_lon
    FROM facilities
)
SELECT 
    * 
FROM (
    SELECT id, bbox, filename, change_type, theme 
    FROM read_parquet('s3://overturemaps-us-west-2/changelog/2025-03-19.1/theme=places/type=place/change_type=*/*', filename=true, hive_partitioning=1),
            bounding_box
    WHERE 
        bbox.xmin BETWEEN (bounding_box.min_lon - 0.01) AND (bounding_box.max_lon + 0.01) AND
        bbox.ymin BETWEEN (bounding_box.min_lat - 0.01) AND (bounding_box.max_lat + 0.01)
);
```

This loads 87,229 records, which we’ll now intersect with our existing, associated GERS IDs:

```sql
SELECT Facility_ID, gers_id, change_type FROM inspections i 
JOIN changes c
ON i.gers_id = c.id
GROUP BY Facility_ID, gers_id, change_type;
```

Of our 2,366 associated GERS, 61% are `unchanged`. 37% have had `data_changed`, in some form or another, but Overture’s matchers have determined their GERS ID should persist, indicating that the record refers to the same entity. 

But ~1.5% of our matched GERS IDs &mdash; or 37 records &mdash; have been `removed`. This could indicate a business has closed or a data record was identified as incorrect. Either way, this is a very small subset of records that we should rematch.

Given our use case and our desire to produce a cautious match, we will also be rematching against the `data_changed` records. There are many cases where a data update could correct an over-eager match based on incorrect input data.

For our county restaurant inspection use case, our data volumes aren’t of a sufficient size to really bother with this nuance (it’s easier to just rematch against the new release and quickly compare the output to make sure nothing is breaking). But for much larger datasets, where matching routines might take hours, this list of `removed` and `data_changed` records is valuable. 

Let’s build a new query which finds the subset of the facilities IDs we should rematch. It’s similar to our last one:

```sql
SELECT Facility_ID, gers_id, change_type FROM inspections i 
LEFT JOIN changes c
ON i.gers_id = c.id
WHERE change_type IS NULL OR change_type IN ['removed', 'data_changed']
GROUP BY Facility_ID, gers_id, change_type;
```

We’re using a `LEFT JOIN` in this query to find the `Facility_ID`s which don’t have associated GERS IDS (hence, they might match with a new Overture release) and only selecting those matched records where the associated GERS ID has been removed.

This gives us 2,804 facilities we need to match.

To simplify our SQL, we’ll save the results from the above query as `facilities_to_match`.

#### Matching unmatched records to the latest release

Armed with a shopping list of unmatched facilities, we can now drop our `places` table and refresh it with the April Overture data, then create our spatial index.

```sql
D DROP TABLE places;
D CREATE TABLE places AS 
  WITH bounding_box AS (
    SELECT max(ST_Y(geom)) as max_lat, min(ST_Y(geom)) as min_lat, max(ST_X(geom)) as max_lon, min(ST_X(geom)) as min_lon
    FROM facilities
  )
  SELECT 
    id, 
    upper(names['primary']) as Facility_Name, 
    upper(addresses[1]['freeform']) as Address, 
    upper(addresses[1]['locality']) as City, 
    upper(addresses[1]['region']) as State, 
    left(addresses[1]['postcode'], 5) as Zip, 
    geometry as geom, 
    confidence,
    categories 
  FROM (
    SELECT * 
    FROM read_parquet('s3://overturemaps-us-west-2/release/2025-04-23.0/theme=places/type=place/*', filename=true, hive_partitioning=1),
            bounding_box
    WHERE addresses[1] IS NOT NULL AND
        bbox.xmin BETWEEN (bounding_box.min_lon - 0.01) AND (bounding_box.max_lon + 0.01) AND
        bbox.ymin BETWEEN (bounding_box.min_lat - 0.01) AND (bounding_box.max_lat + 0.01) AND
        confidence > 0.3
);
D CREATE INDEX IF NOT EXISTS idx_places_geometry ON places USING RTREE (geom);
```

Finally, we run our match query again, limiting it to only those facilities in `facilities_to_match`.

```sql
WITH ranked_matches AS (
    SELECT 
        f.Facility_ID as input_id, 
        f.Facility_Name as input_name, 
        f.Address as input_address, 
        p.id as match_id, 
        p.Facility_Name as match_name, 
        p.Address as match_address,
        p.confidence as overture_confidence,
        ST_Distance_Sphere(f.geom, p.geom) as distance, 
        jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) as name_similarity, 
        jaro_winkler_similarity(f.Address, p.Address) as address_similarity,
        ROW_NUMBER() OVER (
            PARTITION BY f.Facility_ID
            ORDER BY jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) DESC
        ) as rank
    FROM facilities f
    JOIN places p
        ON ST_DWithin(f.geom, p.geom, 0.001)
        AND jaro_winkler_similarity(f.Facility_Name, p.Facility_Name) > 0.89
        AND jaro_winkler_similarity(f.Address, p.Address) > 0.75
    WHERE f.Facility_ID IN (SELECT Facility_ID FROM facilities_to_match)
),
selected_matches AS (
    SELECT input_id, match_id FROM ranked_matches WHERE rank = 1
)
UPDATE inspections i SET gers_id = sm.match_id FROM selected_matches sm WHERE i.Facility_ID = sm.input_id;
```

907 records were matched with this query, resulting in 2,358 total GERS associations.

## Summary

**Geospatial matching is a pain**. However, by matching against Overture data once through a polished script or pipeline, you can seamlessly join with any other Global Entity Reference System (GERS) associated datasets. This integration makes your data more accessible, accelerates onboarding processes, and expands usability across teams that have also matched against GERS.

By leveraging GERS associations, teams can share the results of complex matching efforts and significantly enhance data value through simplified connections to additional datasets.

---

## What is GERS?

## Global Entity Reference System

The Global Entity Reference System (GERS) is a universal framework for structuring and matching map data across systems. GERS, coupled with Overture datasets, is a potential standard for identifying and referencing the physical and conceptual entities we've defined in our world. It's also a mechanism that can simplify the integration and exchange of data layers.

GERS provides stable identifiers called GERS IDs for real-world geospatial entities across data releases and maintains consistency when entities appear in multiple source datasets.

## GERS is a system

The "S" in GERS stands for a *system*, with the following components:

| Component | Description |
| ---------- | ---------- | 
| [Overture reference map](/getting-data/cloud-sources/) | consists of the canonical datasets Overture releases each month |
| [Global registry of GERS IDs](./registry) | catalogs all GERS IDs ever published |
| [Data changelog](./changelog) | describes changes to entities across releases |
| [Bridge files](./bridge-files) | connects the GERS IDs in a release to the IDs from the underlying source data |

## How does GERS work?

1. Overture assigns a **unique ID** to discrete entities. These could be buildings, road segments, places, or addresses. These IDs are intended to be **stable** across Overture releases. 

2. Overture maintains open-source **matching and conflation libraries** to ensure that the ID remains stable across releases.

3. Each Overture release is the latest **reference map** for these IDs.

4. The reference map is **global** and **open**.

## Using GERS

We envision the Overture ecosystem using GERS in the following ways:

### Matching and associating data
You can independently associate your own data (or a third-party dataset) with Overture data. For example, you might want to link real-time traffic data to Overture road segments, insurance data to Overture buildings, restaurant reviews to features in Overture's places dataset, and socioeconomic data features in Overture's divisions dataset. When third-party data is matched to an Overture feature it picks up that feature's GERS ID and becomes "GERS-enabled" data, ready to be associated via ID to any other GERS-enabled dataset in the Overture ecosystem.

### Contributing data
You can contribute data to the Overture Maps Foundation, and we will use Overture's matching algorithms to match the features in your dataset to features in Overture. Matched features may be assigned an existing GERS ID, and we may generate new GERS IDs for new features.

---

## Registry

With each data release, Overture publishes a **GERS Registry** that serves as the single source of truth for all entities that are part of the Global Entity Reference System. It serves as a comprehensive catalog that tracks every stable ID ever published across all Overture data releases.

There is only ever one GERS Registry. It's not versioned. We update it with each release by comparing the last published GERS Registry with the current Overture data release. 

The registry is available as Parquet files at the following locations:

| Provider | Location |
| ----------- | -------- |
| Amazon S3 | `s3://overturemaps-us-west-2/registry/` |
| Microsoft Azure Blob Storage | `az://overturemapswestus2.blob.core.windows.net/registry/` |

## Registry schema

The GERS Registry files have the following schema:

| Column | Data type | Description |
|-------|------|-------------|
| `id` | string | GERS identifier (UUID) |
| `version` | integer | current version number |
| `first_seen` | string | release when entity first appeared |
| `last_seen` | string | most recent release containing entity |
| `last_changed` | string | last release the entity was changed, sourced from changelog |
| `path` | string | relative path to feature in release data |
| `bbox` | struct(xmin float, xmax float, ymin float, ymax float) | bounding box coordinates | 

## Supported themes and types

The following feature types are included in the GERS registry:

- `building`
- `division`
- `division_area`
- `division_boundary`
- `place`
- `segment`
- `connector`

Inclusion in the GERS Registry signifies Overture's long-term commitment to entity matching and stability for those types. We may add additional feature types to the GERS Registry in future releases.

## Example

You can use the GERS Registry to verify that an entity exists in Overture, track the history of that entity, and find new entities that have been added. For example, you might ask, "Is `fea28f69-7afa-460c-b270-61ef74cd340c` part of GERS?" You can query the GERS Registry to find out.  

```
SELECT 
    *
FROM read_parquet('s3://overturemaps-us-west-2/registry/*.parquet')
WHERE id='fea28f69-7afa-460c-b270-61ef74cd340c';
```

We can see that `fea28f69-7afa-460c-b270-61ef74cd340c` is a building first released by Overture in June 2025 and last seen in August 2025 (`2025-08-20.1`), the current release. The exact bounding box of the feature is `{'xmin': 80.67177, 'xmax': 80.67182, 'ymin': 26.619795, 'ymax': 26.619843}` and the relative path to the feature is `/theme=buildings/type=building/part-00149-8a741876-e04d-4e66-bc96-0171910fa1b1-c000.zstd.parquet`. You can directly access the Parquet file that contains this feature by appending the relative path to the current release path: `s3://overturemaps-us-west-2/release/2025-08-20.1`. Since you know the exact bounding box of the feature, you can optimize your query and you should be able to fetch this feature directly from the data release in seconds.

---

## Attribution and Licensing

If you are the author of a publication or research report that uses Overture data, you may choose to add the following citation, including the date the data were accessed: `Overture Maps Foundation, overturemaps.org`.

Some of the data sources we use in Overture datasets require their own attribution, according to their licenses. For example, our [Explore tool](https://explore.overturemaps.org/) displays several datasets that are made wholly or in part from OpenStreetMap data, so we added the following line of attribution to adhere to the requirements of the [Open Database License](https://opendatacommons.org/licenses/odbl/):
`© OpenStreetMap contributors, Overture Maps Foundation`.

![Explore screenshot](/img/explore-attribution.jpg)

<details>
    <summary>
### Addresses
    </summary>
**License for theme:** The addresses data comes from a variety of sources. All carry permissive open licenses. Some have special terms or require attribution. These terms are outlined below.
#### Australia
- G-NAF © [Geoscape Australia](https://geoscape.com.au/) licensed by the Commonwealth of Australia. Available under the [Open Geo-coded National Address File End User Licence Agreement](https://geoscape.com.au/wp-content/uploads/2024/08/EULA-G-NAF-Core-1.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Austria
- © [Austrian Address Register](https://geometadatensuche.inspire.gv.at/metadatensuche/srv/ger/catalog.search#/metadata/bd28c2b0-4ea5-41c2-8847-b7e8711a6512). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Belgium
- Wallonia data from [ICAR](https://opendata.bosa.be/index.fr.html). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Accessed: 2026-03-08.
- Flanders data from [AR (Adressenregister)](https://opendata.bosa.be/index.fr.html). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Accessed: 2026-03-08.
- Brussels data from [UrbiS](https://opendata.bosa.be/index.fr.html). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Accessed: 2026-03-08.
#### Brazil
- [IBGE (Instituto Brasileiro de Geografia e Estatística)](https://www.ibge.gov.br/). Available under [CC0](https://creativecommons.org/public-domain/cc0/). Distributed by AddressForAll. Accessed: 2024-10-13
#### Canada
- [Statistics Canada, National Address Register](https://www150.statcan.gc.ca/n1/pub/46-26-0002/462600022022001-eng.htm), 2024. Reproduced and distributed on an "as is" basis with the permission of Statistics Canada. Available under [OGL - Statistics Canada Open Licence](https://www.statcan.gc.ca/en/reference/licence). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Yukon data from [Government of Yukon](https://map-data.service.yukon.ca/GeoYukon/People_and_Structures/Civic_Address_Point/). Available under [Open Government Licence - Yukon](https://open.yukon.ca/open-government-licence-yukon). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Quebec data from [Government of Le ministère des Ressources naturelles et des Forêts](https://mrnf.gouv.qc.ca/repertoire-geographique/adresses-referentiel-quebecois-adresses/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Chile
- © [Instituto Nacional de Estadísticas](https://www.ine.es/). Available under CC BY 4.0. Distributed by AddressForAll. Accessed: 2026-03-08.
#### Colombia
- [Departamento Administrativo Nacional de Estadística (DANE)](https://www.dane.gov.co/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Croatia
- [Državna geodetska uprava](https://inspire-geoportal.ec.europa.eu/srv/eng/catalog.search#/datasetdetails?resourceId=d3104048-688a-4305-9471-77288cc6e350). Available under an [Open License](https://data.gov.hr/otvorena-dozvola). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Czechia
- Contains data from [Český úřad zeměměřický a katastrální (ČÚZK)](https://vdp.cuzk.cz). Available under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Denmark
- Contains data from the [Danish Agency for Data Supply and Infrastructure](https://dawadocs.dataforsyningen.dk/). [Terms of use for free geographic data](https://dataforsyningen.dk/asset/PDF/rettigheder_vilkaar/Vilk%C3%A5r%20for%20brug%20af%20frie%20geografiske%20data.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Estonia
- Data courtesy of [Estonian Land Board (MAA-AMET)](https://geoportaal.maaamet.ee/eng/). Available under [CC0](https://creativecommons.org/public-domain/cc0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Faroe Islands
- [The Faroese Environment Agency, Umhvørvisstovan](https://www.foroyakort.fo/vevtaenastur). Available under [Terms and conditions](https://www.foroyakort.fo/um-foeroyakort/terms-and-conditions-in-english). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Finland
- [Syke](https://www.syke.fi/en/environmental-data/open-web-services/web-map-services#addresses). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### France
- Data from [The national address site of the French Republic](https://adresse.data.gouv.fr/). Available under [LICENCE OUVERTE / OPEN LICENCE V2 - Etalab 2.0](https://www.etalab.gouv.fr/wp-content/uploads/2017/04/ETALAB-Licence-Ouverte-v2.0.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Germany
- Baden-Württemberg data from [LGL](https://www.lgl-bw.de/Produkte/Liegenschaftskataster/Hauskoordinaten/). Available under [DL-DE->BY-2.0](https://www.govdata.de/dl-de/by-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Berlin data from [Geoportal Berlin](https://gdi.berlin.de/geonetwork/srv/eng/catalog.search#/metadata/796582aa-dbfc-3fa5-9aa6-2846306fc185). [DL-DE->Zero-2.0](https://www.govdata.de/dl-de/zero-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Brandenburg data from [GeoBasis-DE/LGB](https://geobasis-bb.de/lgb/de/geodaten/liegenschaftskataster/georeferenzierte-adresse/). Available under [DL-DE->BY-2.0](https://www.govdata.de/dl-de/by-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Bremen data from [Landesamt GeoInformation Bremen](https://www.geo.bremen.de/produkte/katasterprodukte/auszuege-aus-dem-liegenschaftskataster-12272). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Hamburg data from [Freie und Hansestadt Hamburg, Landesbetrieb Geoinformation und Vermessung](http://suche.transparenz.hamburg.de/dataset/alkis-adressen-hamburg6). Available under [DL-DE->BY-2.0](https://www.govdata.de/dl-de/by-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Hesse data from [Hessischen Verwaltung für Bodenmanagement und Geoinformation](https://gds.hessen.de/INTERSHOP/web/WFS/HLBG-Geodaten-Site/de_DE/-/EUR/ViewDownloadcenter-Start?path=Liegenschaftskataster/Hauskoordinaten%20ohne%20Postalische%20Angaben%20(txt)). Available under [DL-DE->Zero-2.0](https://www.govdata.de/dl-de/zero-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Mecklenburg data from [Landesamt für innere Verwaltung Mecklenburg-Vorpommern](https://laiv.geodaten-mv.de/afgvk/Liegenschaftskataster/Beschreibung?produkt=ALKIS). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Niedersachsen data from [Landesamt für Geoinformation und Landesvermessung Niedersachsen](https://ni-lgln-opengeodata.hub.arcgis.com/apps/lgln-opengeodata::alkis/about). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- North Rhine-Westphalia data from [Geobasis NRW](https://www.opengeodata.nrw.de/produkte/geobasis/lk/akt/gebref_txt/). Available under [DL-DE->Zero-2.0](https://www.govdata.de/dl-de/zero-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Rhineland-Palatinate data from [GeoBasis-DE/LVermGeo RP](https://lvermgeo.rlp.de/geodaten-geoshop/open-data). Available under [DL-DE->BY-2.0](https://www.govdata.de/dl-de/by-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Saarland data from [GeoBasis-DE/LVermGeo SL](https://geoportal.saarland.de/mapbender/php/mod_iso19139ToHtml.php?url=https%3A%2F%2Fgeoportal.saarland.de%2Fmapbender%2Fphp%2Fmod_dataISOMetadata.php%3FoutputFormat%3Diso19139%26id%3Dcfc63fce-d914-4486-8f4f-c3c0973ddb64). Available under [DL-DE->BY-2.0](https://www.govdata.de/dl-de/by-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Saxony data from [Staatsbetrieb Geobasisinformation und Vermessung Sachsen](https://www.geodaten.sachsen.de/downloadbereich-hauskoordinaten-4172.html). Available under [DL-DE->BY-2.0](https://www.govdata.de/dl-de/by-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Saxony-Anhalt data from [GeoBasis-DE/LVermGeo ST](https://www.lvermgeo.sachsen-anhalt.de/de/gdp-open-data.html). Available under [DL-DE->BY-2.0](https://www.govdata.de/dl-de/by-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Schleswig-Holstein data from [©GeoBasis-DE/LVermGeo SH](https://geodaten.schleswig-holstein.de/gaialight-sh/_apps/dladownload/lizenz.html). Available under [CC BY 4.0](https://geodaten.schleswig-holstein.de/gaialight-sh/_apps/dladownload/lizenz.html). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Thuringia data from [Freistaat Thüringen](https://geoportal.thueringen.de/gdi-th/download-offene-geodaten). Available under [DL-DE->BY-2.0](https://www.govdata.de/dl-de/by-2-0). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Greenland
- Contains data from [Asiaq, Greenland Survey](https://www.asiaq.gl/). Available under [TERMS OF USE FOR ASIAQ GEODATA](https://kortforsyning.asiaq.gl/Downloads/EN_Terms%20of%20use.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Hong Kong
- [Hong Kong Digital Policy Office](https://portal.csdi.gov.hk/geoportal/#metadataInfoPanel). Available under [Terms and Conditions of Use](https://portal.csdi.gov.hk/csdi-webpage/doc/TNC). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Iceland
- [Stadfangaskra/Byggðastofnun](https://fasteignaskra.is/). Available under [Guidelines regarding the reuse of public information](https://web.archive.org/web/20241116140612/https://opingogn.is/pages/notkunarleidbeiningar). Accessed: 2026-03-08.
#### Italy
- [Archivio Nazionale dei Numeri Civici delle Strade Urbane (ANNCSU)](https://www.anncsu.gov.it/it/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Japan
- [Japanese Ministry of Land, Infrastructure and Transport](https://nlftp.mlit.go.jp/isj/index.html). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Latvia
- [Valsts digitālās attīstības aģentūra](https://data.gov.lv/dati/eng/dataset/adreses-inspire/resource/22e0163f-b107-4f5b-9588-26a065f01c45). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Liechtenstein
- Contains data from [Liechtensteinische Landesverwaltung](https://service.geo.llv.li/download//getfile.php?theme=officialAdress). Available under [OGD v2](https://service.geo.llv.li/download//officialAdress/AbiOGDLizenz.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Lithuania
- [State Enterprise Centre of Registers](https://www.registrucentras.lt/en/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Luxembourg
- [The Luxembourg open data platform](https://data.public.lu/fr/). Available under [CC0](https://creativecommons.org/public-domain/cc0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Mexico
- [INEGI, Censos Económicos](https://en.www.inegi.org.mx/default.html). [TÉRMINOS DE LIBRE USO DE LA INFORMACIÓN DEL INEGI](https://www.inegi.org.mx/contenidos/inegi/doc/terminos_info.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Netherlands
- [Nationaal Georegister](https://www.nationaalgeoregister.nl/geonetwork/srv/dut/catalog.search#/home). Available under [PDM 1.0](https://creativecommons.org/publicdomain/mark/1.0/deed.nl). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### New Zealand
- [Land Information New Zealand (LINZ)](https://www.linz.govt.nz/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Norway
- [Kartverket](https://kartkatalog.geonorge.no/metadata/matrikkelen-adresse-leilighetsnivaa/365b0591-b536-42a6-a20d-22e404fbfe55). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Accessed: 2026-03-08.
#### Poland
- Poland data from [Polish Law on Geodesy and Cartography](https://inspire-geoportal.ec.europa.eu/srv/eng/catalog.search#/datasetdetails?resourceId=a3990e57-5f0f-4bd6-94c9-47d46b692087). Available under [No conditions to access and use](https://inspire.ec.europa.eu/metadata-codelist/ConditionsApplyingToAccessAndUse/noConditionsApply). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Portugal
- [Instituto Nacional de Estatística](https://www.ine.pt/xportal/xmain?xpgid=ine_main&xpid=INE). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Serbia
- [Republički geodetski zavod](https://data.gov.rs/sl/datasets/adresni-registar/). Available under [Terms of use](https://data.gov.rs/sr/terms/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Singapore
- Singapore data from [Singapore Land Authority](https://www.onemap.gov.sg/). Available under [Singapore Open Data Licence](https://www.onemap.gov.sg/legal/opendatalicence.html). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Slovenia
- [GURS](https://ipi.eprostor.gov.si/jgp/data). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Accessed: 2026-03-08.
#### Slovakia
- [Ministerstvo vnútra Slovenskej republiky / Ministry of Interior of the Slovak Republic](https://data.gov.sk/dataset/register-adries-register-vchodov). Available under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Spain
- [scne.es](https://centrodedescargas.cnig.es/CentroDescargas/buscadorCatalogo.do). Available under [CC BY 4.0](http://www.ign.es/resources/licencia/Condiciones_licenciaUso_IGN.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Switzerland
- [SwissTopo](https://www.swisstopo.admin.ch). [Terms of use for free geodata](https://www.swisstopo.admin.ch/de/nutzungsbedingungen-kostenlose-geodaten-und-geodienste). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### Taiwan
- [Changhua County Government Civil Affairs Office](https://data.gov.tw/dataset/170727). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Hsinchu City Civil Affairs Office](https://data.gov.tw/dataset/157547). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Hsinchu County Civil Affairs Office](https://data.gov.tw/dataset/172380). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Kaohsiung City Government Civil Affairs Bureau](https://data.gov.tw/dataset/167131). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Keelung City Government Civil Affairs Bureau](https://www.klcg.gov.tw/tw/civil/2209-292163.html). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Kinmen County Civil Affairs Office](https://data.gov.tw/dataset/171571). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Miaoli Civil Affairs Office](https://opendata.miaoli.gov.tw/OpenDataDetail.aspx?n=9404&sms=0&s=1550). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [New Taipei City Government Civil Affairs Bureau](https://data.gov.tw/dataset/168887). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Penghu County Government](https://data.gov.tw/dataset/170852). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Pingtung County Government](https://data.gov.tw/dataset/170847). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Taichung City Government Civil Affairs Bureau](https://data.gov.tw/dataset/169806). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Tainan City Government Civil Affairs Bureau](https://data.gov.tw/dataset/120044). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Taipei City Government Civil Affairs Bureau](https://data.gov.tw/dataset/155472). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Taoyuan City Government Civil Affairs Bureau](https://data.gov.tw/dataset/157689). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Yunlin County Government](https://data.gov.tw/dataset/166201). Available under [CC BY 4.0](https://data.gov.tw/license). Distributed by OpenAddresses. Accessed: 2026-03-08.
#### United States
- [National Address Database (NAD)](https://www.transportation.gov/gis/national-address-database) from the U.S. Department of Transportation and the individual states that contribute to the database. [National Address Database (NAD) Disclaimer](https://www.transportation.gov/mission/open/gis/national-address-database/national-address-database-nad-disclaimer). The National Address Database is licensed under the National Address Database Access and Usage License. Accessed: 2026-03-08.
##### California
- [Alameda County](https://data.acgov.org/datasets/4610acbf49364583986d45ee4106cc3f_0/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Amador County](https://services9.arcgis.com/Z65sx307Hunxj6eq/ArcGIS/rest/services/ParcelData_Public/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Butte County](https://gisportal.buttecounty.net/portal/home/item.html?id=9144daa8e8744ebe80e587d859c0a0fe). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Calaveras County](https://gisportal.calaverascounty.gov/server/rest/services/Hosted/ADDRESSING_DATA_ADDRESSING_POINTS/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [City and County of San Francisco](https://data.sfgov.org/api/views/ramy-di5m/rows.csv?accessType=DOWNLOAD&api_foundry=true). Available under [Public Domain Dedication and License (PDDL) v1.0](https://opendatacommons.org/licenses/pddl/1-0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Colusa County](https://www.countyofcolusa.org/index.aspx?NID=710). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Contra Costa County](https://www.contracosta.ca.gov/1818/GIS). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Del Norte County](https://www.co.del-norte.ca.us/departments/information-technology/geographic-information-services-gis). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [El Dorado County](https://www.edcgov.us/Government/Surveyor/FAQs/G_I_S__FAQs.aspx). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Fresno County](https://datasharing-cofgisonline.hub.arcgis.com/datasets/aec096ac4c1543c0bb3598523634db33_1/explore). Available under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Glenn County](https://gis.gcppwa.net/arcgis/rest/services/Districts/GCDistricts/MapServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Humboldt County](https://cty-gis-web.co.humboldt.ca.us/server/rest/services/Parcels/Parcels_no_labels/MapServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Imperial County](https://services7.arcgis.com/RomaVqqozKczDNgd/ArcGIS/rest/services/Parcels_Oct_2023/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Inyo County](https://inyocounty.us/gis/GISPage_Data.htm). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Kern County](https://maps.co.kern.ca.us/arcgis/rest/services/Accela_Base/MapServer/5). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Kings County](https://services3.arcgis.com/24gLq1DBBzDfd0cZ/ArcGIS/rest/services/Address_Kings_County/FeatureServer/4). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Lake County](https://gis.co.lake.ca.us/). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Lassen County](https://lassencounty.org/govt/dept/assessor/default.asp). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Los Angeles County](https://lacounty.maps.arcgis.com/sharing/rest/content/items/fa47b95a2f704df094cc19b834f4fb07/data). Available under [CC0 ](https://creativecommons.org/public-domain/cc0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Madera County](https://www.maderacounty.com/government/geographic-information-system-gis). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Marin County](https://gisopendata.marincounty.gov/datasets/marincounty::situs-address-points/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Mariposa County](https://services2.arcgis.com/wEula7SYiezXcdRv/ArcGIS/rest/services/Address_Points/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Mendocino County](https://gis.mendocinocounty.org/). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Merced County](https://geostack-mercedcounty.opendata.arcgis.com/datasets/MercedCounty::merced-county-site-address-points/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Modoc County](https://gis2.cdfa.ca.gov/server/rest/services/Parcel_DM/MapServer/24/). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Mono County](https://gis-monomammoth.opendata.arcgis.com/datasets/MonoMammoth::address-points/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Monterey County](https://gis-montereyco.opendata.arcgis.com/datasets/MontereyCo::addresses/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OikpenAddresses. Accessed: 2026-03-08.
- [Napa County](https://gisdata.countyofnapa.org/datasets/napacounty::addresses-all/about). Available under [Public Domain Dedication and License (PDDL) v1.0](https://opendatacommons.org/licenses/pddl/1-0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Nevada County](https://maps-nevcounty.opendata.arcgis.com/datasets/nevcounty::parcel-situs-address/about). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Orange County](https://www.ocgis.com/arcpub/rest/services/Map_Layers/Address_Point_Final_Planning_Addressing/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Placer County](https://services6.arcgis.com/PArfeTGcwA9RGNzN/ArcGIS/rest/services/Address_Points/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Plumas County](https://plumascounty.us/2199/Interactive-GIS-Data-to-Download-Page). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Riverside County](https://gisopendata-countyofriverside.opendata.arcgis.com/datasets/CountyofRiverside::address-points/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Sacramento County](https://services1.arcgis.com/5NARefyPVtAeuJPU/ArcGIS/rest/services/Address/FeatureServer/0). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [San Benito County](https://cosb.maps.arcgis.com/home/item.html?id=f7dd7210ee114965aeeac18e9886daec). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [San Bernardino County](https://open.sbcounty.gov/datasets/sbcounty::countywide-parcels/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [San Diego County](https://geo.sandag.org/portal/home/item.html?id=b1c2fd749f6847ccae6040cf0f803647). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [San Joaquin County](https://sjmap.org/GISDataDownload.htm). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [San Luis Obispo County](https://opendata.slocounty.ca.gov/datasets/SLOCounty::address-points/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [San Mateo County](https://gis.smcgov.org/maps/rest/services/Common/SMC_GIS/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Santa Barbara County](https://services8.arcgis.com/s7n9cRiugyMCsR0U/ArcGIS/rest/services/Parcel_layers_ArcGISonline_LUZO/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Santa Clara County](https://data.sccgov.org/Government/AddressPoint/k4vk-5ggi). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Santa Cruz County](https://www.santacruzcountyca.gov/departments/geographicinformationsystems(gis).aspx). Available under [CC0 (assumed)](https://creativecommons.org/public-domain/cc0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Shasta County](https://data-shasta.opendata.arcgis.com/datasets/Shasta::addresspoints-2/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Sierra County](https://www.sierracounty.ca.gov/249/Geographic-Information-System-GIS-Map). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Siskiyou County](https://siskiyou.maps.arcgis.com/home/item.html?id=710e1a6aa9c949b0ab110b88b1647bc1). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Solano County](https://solanocountygis.com/portal/home/item.html?id=e6dda522cedd4544940baf0c98bfa0ca). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Sonoma County](https://gis-sonomacounty.hub.arcgis.com/datasets/sonomacounty::addresses/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Stanislaus County](https://gis2.stancounty.com/portal/home/item.html?id=2d32837e108940fca1be9c20993e2d75). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Sutter County](https://www.co.sutter.ca.us/doc/government/depts/cs/ps/cs_planning_services). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Tehama County](https://tehamartpa.org/gis/). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Trinity County](https://services2.arcgis.com/32siQkg0O6da8zFF/ArcGIS/rest/services/Address_Locations/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Tulare County](https://services2.arcgis.com/bYBANhmQGwSSLC0l/ArcGIS/rest/services/Tulare_County_Address_Points/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Tuolumne County](https://services3.arcgis.com/afQpMaliVrwHS7Ud/ArcGIS/rest/services/Parcels_WithSiteAddress_View/FeatureServer/0). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Ventura County](https://venturacountydatadownloads-vcitsgis.hub.arcgis.com/datasets/vcitsgis::master-address-points/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Yolo County](https://yodata-yolo.opendata.arcgis.com/datasets/47a04e578bbe4d738569e335749d15ba_0/about). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Yuba County](https://www.yuba.org/departments/information_technology/geographic_information_systems_(gis)/gis_data_catalog.php). Available under [Public domain by judicial interpretation of the Public Records Act](https://casetext.com/case/county-of-santa-clara-v-superior-court-10). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Colorado
- [Governor's Office of Information Technology](https://geodata.colorado.gov/datasets/b6e244650e7c472ba53667f19ee01181/about). Available under public data. Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Florida
- [Alachua County](https://services1.arcgis.com/MiBZ4u97DWldovjI/ArcGIS/rest/services/AddressPoints/FeatureServer/0). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Baker County](https://services6.arcgis.com/HSWu3dhzHf7nZfIa/ArcGIS/rest/services/911_Addresses_Website2/FeatureServer/0). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Bay County](https://gis.baycountyfl.gov/bayview/). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Bradford County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Brevard County](https://www.bcpao.us/PublicData.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Broward County](https://geohub-bcgis.opendata.arcgis.com/datasets/40a2da92e1fc48a3a86984be0238764f_0/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Calhoun County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Charlotte County](https://www.charlottecountyfl.gov/services/gis/Pages/Shapefile-Gallery.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Citrus County](https://gis.citrusbocc.com/data-downloads.html). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Clay County](https://ccpao.com/certified-data/). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Collier County](https://hub-collierbcc.opendata.arcgis.com/datasets/CollierBCC::address-points/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Columbia County](https://gis.columbiacountyfla.com/hosting/rest/services/Addresses/FeatureServer/1). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Desoto County](https://skyview.hornershifrin.com/DesotoCoFL/). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Dixie County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Duval County](https://maps.coj.net/coj/rest/services/ERAT/EratDashboard_3000/MapServer/41). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Escambia County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Flagler County](https://data-fcmaps.opendata.arcgis.com/datasets/FCMAPS::flagler-county-address-points/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Franklin County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Gadsden County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Gilchrist County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Glades County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Gulf County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Hamilton County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Hardee County](https://gis.hardeecounty.net/arcgis/rest/services/Addressing/MapServer/3). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Hendry County](https://gis.hendryfla.net/datasets/a84275b4f69d468a883d4715c98c29bc/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Hernando County](https://server.hernandopa-fl.us/server/rest/services/Basemap/MapServer/1). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Highlands County](https://hcbcc.maps.arcgis.com/home/item.html?id=f20fc360487d4b73a55bf5930a988c53). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Hillsborough County](https://gis2017-01-10t133755357z-hillsborough.opendata.arcgis.com/datasets/hillsborough::siteaddresspoint/about). Available under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Holmes County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Indian River County](https://gisportal.ircgov.com/server3/rest/services/Addressing/IRC_Address_Points_woLabels_MS/MapServer/0). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Jackson County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Jefferson County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Lafayette County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Lake County](https://gis.lakecountyfl.gov/gisweb/). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Lee County](https://maps.leegov.com/datasets/ng911-address-points-file-geodatabase/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Leon County](https://geodata-tlcgis.opendata.arcgis.com/datasets/tlcgis::site-address-points-tallahassee-leon-county/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Levy County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Liberty County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Madison County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Manatee County](https://public-manateegis.opendata.arcgis.com/datasets/manateegis::address-points-1/about). Available under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Marion County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Martin County](https://geoweb.martin.fl.us/arcgis/rest/services/geocoding/address_points/MapServer/0). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Miami-Dade County](https://gis-mdc.opendata.arcgis.com/datasets/MDC::address-1/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Monroe County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Nassau County](https://maps.nassauflpa.com/ncflpa_arcgis/rest/services/nassau/TaxMap4_CitrixV2/MapServer/231). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Okaloosa County](https://myokaloosa.com/gis_data). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Okeechobee County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Orange County](https://ocgis-datahub-ocfl.hub.arcgis.com/datasets/ocfl::address-point/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Osceola County](https://gis.osceola.org/hosting/rest/services/Address_Points/FeatureServer/0). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Palm Beach County](https://opendata2-pbcgov.opendata.arcgis.com/datasets/situs-addresses/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Pasco County](https://services6.arcgis.com/Mo4MddfRHpFwT7UF/ArcGIS/rest/services/Addressing/FeatureServer/16). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Pinellas County](https://new-pinellas-egis.opendata.arcgis.com/maps/site-address-points-911/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Polk County](https://gis.polk-county.net/hosting/rest/services/Accela/APO_Layer_Map/MapServer/6). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Putnam County](https://putnam-pcgis.hub.arcgis.com/datasets/6006770008e44a56ac751f042043b8d2_0/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Santa Rosa County](https://data1-santarosagis.opendata.arcgis.com/datasets/structures). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Sarasota County](https://data-sarco.opendata.arcgis.com/datasets/sarco::addresspoint/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Seminole County](https://www.seminolecountyfl.gov/departments-services/information-services/gis-geographic-information-systems/gis-data.stml). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [St. Johns County](https://data-sjcfl.hub.arcgis.com/datasets/5c6b300e4fda4964ac0694f7a266be08_0/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [St. Lucie County](https://data-slc.opendata.arcgis.com/datasets/slc::addressmaster/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Sumter County](https://sumtercountyfl.gov/105/GIS). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Suwannee County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Taylor County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Union County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Volusia County](https://opendata-volusiacountyfl.hub.arcgis.com/datasets/VolusiaCountyFL::address-situs/about). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Wakulla County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Walton County](https://www.co.walton.fl.us/910/GIS-Data). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
- Washington County data from [Florida Department of Revenue](https://pointmatch.floridarevenue.com/General/AddressFiles.aspx). Available under [Public domain by judicial decision](https://www.myfloridalegal.com/ag-opinions/records-license-agreements-for-county-maps). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Georgia
- Clarke County data from [Athens-Clarke County GIS](https://data-athensclarke.opendata.arcgis.com/datasets/AthensClarke::acc-address-point/about). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [DeKalb County](https://dekalbinsights-dekalbgis.opendata.arcgis.com/datasets/DeKalbGIS::address-6/about). Available under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Idaho
- [City of Boise](https://city-of-boise.opendata.arcgis.com/search?q=addresses). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Massachusetts
- [MassGIS](https://arcgisserver.digital.mass.gov/arcgisserver/rest/services/AGOL/MassGIS_Master_Address_Points/MapServer/0). Available under [Public Domain](https://creativecommons.org/public-domain/cc0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Michigan
- [Reproduced with permission granted by the County of Allegan, Michigan. Some information has been provided subject to a non-exclusive, limited, and revocable license granted by the County of Allegan, Michigan](https://www.allegancounty.org/online-services/gis). Available under [ALLEGAN COUNTY GEOSPATIAL DATA LICENSE AGREEMENT](https://www.allegancounty.org/home/showpublisheddocument/402/637684270478730000). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Reproduced with permission granted by the County of Kent, Michigan. Some information has been provided subject to a non-exclusive, limited, and revocable license granted by the County of Kent, Michigan.](https://gis.kentcountymi.gov/agisportal/apps/sites/#/kent-county-open-data-hub). Available under [KENT COUNTY GEOSPATIAL DATA LICENSE AGREEMENT](https://www.kentcountymi.gov/DocumentCenter/View/6837/Terms-and-Conditions-of-Use-PDF). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Reproduced with permission granted Muskegon County, Michigan. Some information has been provided subject to a non-exclusive, limited, and revocable license granted by Muskegon County, Michigan.](https://maps.muskegoncountygis.com/portal/apps/sites/#/gis-home). Available under [DATA DOWNLOAD / USE AGREEMENT](https://maps.muskegoncountygis.com/open_data/documents/MCGIS_Data_Download_Use_Agreement.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Oakland County](https://accessoakland.oakgov.com/datasets/oakgov::oc-site-address/about). Available under [Open Data](https://accessoakland.oakgov.com/datasets/oakgov::oc-site-address/about). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Minnesota
- [Department of Public Safety](https://dps.mn.gov/divisions/ecn/contact-ecn/submit-ecn-data-request). Available under public data. Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Mississippi
- [MARIS](https://maris.mississippi.edu/HTML/DATA/Cadastral.html#gsc.tab=0). Available under [Open Data](https://maris.mississippi.edu/HTML/DATA/data_Cadastral/DataDisclaimer.pdf). Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Desoto County](https://desotocounty-dcms-gis.hub.arcgis.com/datasets/DCMS-GIS::addresses/about). Available with no commercial usage restrictions or attribution requirements. Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Nevada
- [Carson City, NV](https://data-carsoncity.opendata.arcgis.com/datasets/CarsonCity::address-points/about). Available under [License](https://data-carsoncity.opendata.arcgis.com/datasets/CarsonCity::address-points/about). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### New York
- [Open Data Terms of Use](https://opendata.cityofnewyork.us/overview/) for NYC Open Data. Address data from the NYC Department of City Planning. Accessed: 2026-03-08.
##### Oregon
- Oregon data from [National Address Database (NAD) r8](https://www.transportation.gov/gis/national-address-database) from the U.S. Department of Transportation and the individual states that contribute to the database. [National Address Database (NAD) Disclaimer](https://www.transportation.gov/mission/open/gis/national-address-database/national-address-database-nad-disclaimer). The National Address Database is licensed under the National Address Database Access and Usage License. Distributed by OpenAddresses. Accessed: 2026-03-08.
- [Jackson County, OR](https://gis.jacksoncountyor.gov/datasets/JCGIS::address-point/about). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Pennsylvania
- Lackawanna County data from [City of Scranton GIS](https://scranton-open-data-scrantonplanning.hub.arcgis.com/datasets/6eb6dbd15aef44a0a2c2b388d893f906/about). Available under [PDDL 1.0](https://opendatacommons.org/licenses/pddl/summary/). Distributed by OpenAddresses. Accessed: 2026-03-08.
##### Wisconsin
- [Waupaca County](https://public1.co.waupaca.wi.us/arcgis/rest/services/Public/OpenData/MapServer/24). Available under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.

#### Uruguay
- Contains data from [Infraestructura de Datos Espaciales](https://dl.digital-guard.org/out/a4a_uy_geoaddress_85800000202101_csv.zip). Available under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). Distributed by OpenAddresses. Accessed: 2026-03-08.
</details>

<details>
    <summary>
### Base
    </summary>
**License for theme:** [ODbL](https://opendatacommons.org/licenses/odbl/)
- © OpenStreetMap contributors. Available under the [Open Database License](https://www.openstreetmap.org/copyright).
- Data from the [Daylight Map Distribution](https://daylightmap.org/)
- [ESA WorldCover](https://esa-worldcover.org/en/data-access). Available under [CC BY 4.0 DEED](https://creativecommons.org/licenses/by/4.0/).
- Data products from [ETOPO1](https://www.ncei.noaa.gov/products/etopo-global-relief-model). Available under [Open Data Commons Public Domain Dedication and License](https://www.nature.com/articles/s41597-022-01132-9).
- Data from [GLOBathy](https://www.nature.com/articles/s41597-022-01132-9). Available under [CC0 1.0 (assumed)](https://www.nature.com/articles/s41597-022-01132-9).
</details>

<details>
    <summary>
### Buildings
    </summary>
**License for theme:** [ODbL](https://opendatacommons.org/licenses/odbl/)
- © OpenStreetMap contributors. Available under the [Open Database License](https://www.openstreetmap.org/copyright).
- [Esri Community Maps contributors](https://communitymaps.arcgis.com/home/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
- [Global ML Building Footprints](https://github.com/microsoft/GlobalMLBuildingFootprints). Licensed by Microsoft under the [Open Database License](https://opendatacommons.org/licenses/odbl/).
- [Google Open Buildings](https://arxiv.org/abs/2107.12283). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
- [USGS 3D Elevation Program Digital Elevation Program](https://www.usgs.gov/3d-elevation-program).
- Qian Shi, et al. A First High-quality Vector Data of Buildings in East Asian Countries Based on a Comprehensive Large-scale Mapping Framework. Zenodo, 22 July 2023, [doi:10.5281/zenodo.8174931](https://doi.org/10.5281/zenodo.8174931). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
- Work derived from BTN 2024 [ign.es](https://www.ign.es/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)

</details>

<details>
    <summary>
### Divisions
    </summary>
**License for theme:** [ODbL](https://opendatacommons.org/licenses/odbl/)
- © OpenStreetMap contributors. Available under the [Open Database License](https://www.openstreetmap.org/copyright).
- [geoBoundaries](https://www.geoboundaries.org/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
- [Esri Community Maps contributors](https://communitymaps.arcgis.com/home/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
- [Land Information New Zealand (LINZ)](https://www.linz.govt.nz/). Available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
</details>

<details>
    <summary>
### Places
    </summary>
- Data from [Meta](https://about.meta.com/). Available under [CDLA Permissive 2.0](https://cdla.dev/permissive-2-0/).
- Data from [Microsoft](https://www.microsoft.com/en-us/). Available under [CDLA Permissive 2.0](https://cdla.dev/permissive-2-0/).
- Data from [PinMeTo](https://www.pinmeto.com/). Available under [CDLA Permissive 2.0](https://cdla.dev/permissive-2-0/).
- Data from [Krick](https://www.krick.com/). Available under [CDLA Permissive 2.0](https://cdla.dev/permissive-2-0/).
- Data from [RenderSEO](https://www.renderseo.com/). Available under [CDLA Permissive 2.0](https://cdla.dev/permissive-2-0/).
- Data from [DAC](https://www.dacgroup.com/). Available under [CDLA Permissive 2.0](https://cdla.dev/permissive-2-0/).
- Data from [Foursquare](https://foursquare.com/). Copyright 2024 Foursquare Labs, Inc. All rights reserved. Available under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). Foursquare data was transformed to the Overture schema. Changed: 2026-03-18. [NOTICE.txt](https://opensource.foursquare.com/places-notice-txt/).
- Data from [AllThePlaces](https://alltheplaces.xyz/). Available under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/deed.en).
</details>

<details>
    <summary>
### Transportation
    </summary>
**License for theme:** [ODbL](https://opendatacommons.org/licenses/odbl/)
- © OpenStreetMap contributors. Available under the [Open Database License](https://www.openstreetmap.org/copyright).
- Data from [TomTom](https://www.tomtom.com/).
</details>

---

## Index

Hero,
  HeroHeadline,
  HeroSubtext,
  HeroCTAs,
  PrimaryButton,
  SecondaryButton,
  ExplorerEmbed,
} from '@site/src/components/home';

<Hero>
  <HeroHeadline />

<HeroSubtext>
  A platform for bringing together tech companies, mapping organizations, government agencies, open
  data communities, and researchers to build open, reliable, and interoperable map data
  infrastructure.
</HeroSubtext>

  <HeroCTAs>
    <PrimaryButton to="/getting-data/">Quickstart</PrimaryButton>
    <SecondaryButton href="https://explore.overturemaps.org">
      Explore the data and schema →
    </SecondaryButton>
  </HeroCTAs>
</Hero>

<ExplorerEmbed />

---

## Releases

This page provides information about Overture's data and schema releases, including upcoming release dates, our versioning and schema change policies, data retention practices, and a complete history of past releases with links to release notes.

## Current release

The latest Overture data release is:

<QueryBuilder query="__OVERTURE_RELEASE/" language="text"></QueryBuilder>

## Release schedule

Our planned release schedule is below. Release dates and schema versions are subject to change.

| Date             | Data version                                                                   | Schema version                                                           |
| ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| 15 April 2026    | [`2026-04-15.0`](https://docs.overturemaps.org/blog/2026/04/15/release-notes/) | [`v1.16.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0) |
| 20 May 2026      | `2026-05-20.0`                                                                 | TBD                                                                     |
| 17 June 2026\*   | `2026-06-17.0`                                                                 | TBD                                                                      |

\*reserved for quarterly major breaking change release

## Versioning and schema changes

### Versioning

Overture uses a three-component `<major>.<minor>.<patch>` version number, i.e. `v1.1.0`, that effectively follows the [semantic versioning specification](https://semver.org/spec/v2.0.0.html). In general, a “major” change is expected to have a larger impact on data consumers, while a “minor” change is expected to have a lesser impact. Our monthly data releases are tagged with the date of the release, in the format `yyyy-mm-dd.x`, with x indicating a patch or hotfix to the data.

### Minor schema changes

Minor schema changes may occur in any month, meaning that the next monthly data release may follow a new schema version that contains minor schema changes. We typically do not announce minor changes in advance unless they are part of an overarching schema update that involves related major changes. Minor changes include:

- adding feature types;
- adding top-level properties (columns);
- adding nested properties;
- changing constraints on property values either by relaxing or tightening them, e.g. adding or subtracting allowed values for enumerated value properties such as `class`.

### Major schema changes

Major schema changes will only occur once per quarter, during the designated **major change months of March, June, September, and December**. We will strive to announce upcoming major changes as far in advance as possible, along with the reasons behind the change. If there are no major changes in a designated major change month, the schema version for that month’s release will reflect minor changes or no changes. Major changes include:

- deleting feature types;
- deleting top-level properties (columns);
- deleting nested properties;
- changing data types, e.g. an integer value to a structured object.

## Data retention policy

Overture maintains publicly available data releases for a maximum of 60 days (two monthly releases) to comply with data protection regulations, including GDPR "right to be forgotten" requirements. Files are automatically removed from public distribution after this period using cloud storage lifecycle policies on AWS and Azure. Versioned changelogs and bridgefiles remain publicly available for all releases where they were provided. Release notes from past releases also remain publicly available.

## Release history

Overture has been releasing data monthly since October 2023. Past releases are listed below. Only the last two months of releases available in our public buckets on AWS and Azure. The release notes for all past releases are available at the links below.

| Date              | Data version                                                                   | Schema version                                                           |
| ----------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| 18 March 2026     | [`2026-03-18.0`](https://docs.overturemaps.org/blog/2026/03/18/release-notes/) | [`v1.16.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0) |  
| 18 February 2026  | [`2026-02-18.0`](https://docs.overturemaps.org/blog/2026/02/18/release-notes/) | [`v1.16.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0) |
| 21 January 2026   | [`2026-01-21.0`](https://docs.overturemaps.org/blog/2026/01/21/release-notes/) | [`v1.15.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.15.0) |
| 17 December 2025  | [`2025-12-17.0`](https://docs.overturemaps.org/blog/2025/12/17/release-notes/) | [`v1.15.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.15.0) |
| 19 November 2025  | [`2025-11-19.0`](https://docs.overturemaps.org/blog/2025/11/19/release-notes/) | [`v1.14.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.14.0) |
| 22 October 2025   | [`2025-10-22.0`](https://docs.overturemaps.org/blog/2025/10/22/release-notes/) | [`v1.13.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.13.0) |
| 24 September 2025 | [`2025-09-24.0`](https://docs.overturemaps.org/blog/2025/09/24/release-notes/) | [`v1.12.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.12.0) |
| 20 August 2025    | [`2025-08-20.0`](https://docs.overturemaps.org/blog/2025/08/20/release-notes/) | [`v1.11.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.11.0) |
| 23 July 2025      | [`2025-07-23.0`](https://docs.overturemaps.org/blog/2025/07/23/release-notes/) | [`v1.11.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.11.0) |
| 25 June 2025      | [`2025-06-25.0`](https://docs.overturemaps.org/blog/2025/06/25/release-notes/) | [`v1.10.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.10.0) |
| 21 May 2025       | [`2025-05-21.0`](https://docs.overturemaps.org/blog/2025/05/21/release-notes/) | [`v1.9.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.9.0)   |
| 23 April 2025     | [`2025-04-23.0`](https://docs.overturemaps.org/blog/2025/04/23/release-notes/) | [`v1.8.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.8.0)   |
| 20 March 2025     | [`2025-03-19.1`](https://docs.overturemaps.org/blog/2025/03/19/release-notes/) | [`v1.7.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.7.0)   |
| 19 March 2025     | [`2025-03-19.0`](https://docs.overturemaps.org/blog/2025/03/19/release-notes/) | [`v1.7.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.7.0)   |
| 19 February 2025  | [`2025-02-19.0`](https://docs.overturemaps.org/blog/2025/02/19/release-notes/) | [`v1.6.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.6.0)   |
| 22 January 2025   | [`2025-01-22.0`](https://docs.overturemaps.org/blog/2025/01/22/release-notes/) | [`v1.5.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.5.0)   |
| 18 December 2024  | [`2024-12-18.0`](https://docs.overturemaps.org/blog/2024-12-18.0/)             | [`v1.4.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.4.0)   |
| 13 November 2024  | [`2024-11-13.0`](https://docs.overturemaps.org/blog/2024-11-13.0/)             | [`v1.3.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.3.0)   |
| 23 October 2024   | [`2024-10-23.0`](https://docs.overturemaps.org/blog/2024-10-23.0/)             | [`v1.2.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.2.0)   |
| 18 September 2024 | [`2024-09-18.0`](https://docs.overturemaps.org/blog/2024-09-18.0/)             | [`v1.1.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.1.0)   |
| 20 August 2024    | [`2024-08-20.0`](https://docs.overturemaps.org/blog/2024-08-20.0/)             | [`v1.1.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.1.0)   |
| 22 July 2024      | [`2024-07-22.0`](https://docs.overturemaps.org/blog/2024-07-22.0/)             | [`v1.0.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.0.0)   |
| 24 June 2024      | `2024-06-13-beta.1`                                                            | `v0.12.0-beta`                                                           |
| 13 June 2024      | `2024-06-13-beta.0`                                                            | `v0.12.0-beta`                                                           |
| 16 May 2024       | `2024-05-16-beta.0`                                                            | `v0.11.0-beta`                                                           |
| 16 April 2024     | `2024-04-16-beta.0`                                                            | `v0.10.0-beta`                                                           |
| 12 March 2024     | `2024-03-12-alpha.0`                                                           | `v0.9.0`                                                                 |
| 15 February 2024  | `2024-02-15-alpha.0`                                                           | `v0.8.0`                                                                 |
| 17 January 2024   | `2024-01-17-alpha.0`                                                           | `v0.7.0`                                                                 |
| 14 December 2023  | `2023-12-14-alpha.0`                                                           | `v0.7.0`                                                                 |
| 14 November 2023  | `2023-11-14-alpha.0`                                                           | `v0.6.0`                                                                 |
| 19 October 2023   | `2023-10-19-alpha.0`                                                           | `v0.5.0`                                                                 |
| 26 July 2023      | `2023-07-26-alpha.0`                                                           | `v0.4.0`                                                                 |

---

## Support

## Community support

We welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps). 

### Support channels

Use [GitHub Discussions](https://github.com/orgs/OvertureMaps/discussions) for general questions, workflow help, feature suggestions, or broader conversations about Overture.

For specific bug reports (missing entities, geometry problems, duplicate records, country-specific data concerns, or tool issues), file a GitHub Issue in the relevant repository:

- [Data](https://github.com/OvertureMaps/data)
- [Schema](https://github.com/OvertureMaps/schema)
- [Explorer](https://github.com/OvertureMaps/explore-site)
- [Python library](https://github.com/OvertureMaps/overturemaps-py)

**Filing a good issue.** When reporting a data problem, please include: the Overture release version you're using, a query or code snippet that reproduces the issue, specific entity IDs or bounding boxes where you see the problem, and any relevant screenshots or map views. If you can share a minimal reproducible example, that goes a long way.

### What to expect
We review incoming issues and discussions regularly, but **we cannot guarantee a response or resolution timeline**. Issues that affect data integrity or block common workflows get higher priority.

## Custom support

If you are interested in more than the free community support, please [contact us](https://overturemaps.org/about/contact-us/) to discuss.

---

## 2023-07-26-alpha.0 release notes

### Highlights
Overture `2023-07-26-alpha.0` is a first release version of open map data, establishing a baseline for future releases by the Overture Maps Foundation. The data is available for use under the designated licenses for each theme.  Users should note that while Overture intends to release open map data on a regular cadence in the future, the date of subsequent releases has not been established yet.

{/* truncate */}

We would like feedback on the data, its usefulness and how it could be improved.  Please use this Github repo for discussions and feedback related to this data release.

Overture `2023-07-26-alpha.0` is formatted in the Overture Maps schema described here. It is available in cloud-native Parquet and stored on AWS and Azure.

### Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases/tag/v0.4.0) here.

### Theme-specific updates
Overture `2023-07-26-alpha.0` is being released in four themes:

**Places Theme**
The Places theme includes Point of Interest (POI) Data on approximately 59M places worldwide. Place records include the name, address, pin location, category and social media handles to the extent these are available.  The data also includes a confidence score for each record. The sources of the Places theme include Meta and Microsoft places data. The Places data is formated in the Overture Maps schema for Places.

Data in the Places theme is licensed under CDLA Permissive 2.0.

**Buildings Theme**
The Buildings theme includes building footprint and height data as available.  It includes approximately 785M building outlines worldwide.  The sources include OpenStreetMap, Microsoft Building footprints and Esri Community Partners. Some building heights have also been derived using lidar from USGS 3DEP. The Building data is in the Overture Maps data schema for Buildings.

Data in the Buildings theme is licensed under ODbL.

**Transportation Theme**
The transportation theme includes road networks data based on OpenStreetMap.  This release is a demonstration of our Shape and Connectivity model of the transportation network, and also showcases how Geometric Scoping (LR) interacts with a subset of the final properties. The data has been put into the Overture Maps data schema for transportation.  As such, the data has been re-segmented and structured with some conditional attributes. For example, scoping dimensions related to speed limits have geometric scoping when speed limits change along a road segment.

:::note
The data includes some provisional Global Entity Reference System (GERS) data which is used to express relationships between road segments. This may not be representative of the final GERS format and should not be the basis for long term development work.
:::

There are several missing properties in this data release that will be added in future releases:
- Only includes road segments made from Ways that include a 'highway' tag
- Non-geometric scoping properties are not included
- Turn and Access restrictions are not included
- Lane information is not included
- Some language/scripts are not included in names properties

Data is the Transportation theme is licensed under ODbL.

**Administrative Boundaries (Admins) Theme**
The Admins theme includes administrative boundaries for Level 2 (country-level) and Level 4 (first-level subdivisions under the country) worldwide. Admin records include the translated names for regions in ~40 languages, Context and Sources and placeholder GERS IDs. The sources of the admin theme are Esri and TomTom. The Administrative Boundary data is in the Overture Maps data schema for Admin.

:::note
Placeholder GERS IDs are populated in the data. These are needed to populate the Context property which points to another admin entity. For example, the Context property of Washington state feature has GERS ID of United States entity as value. This may not be representative of the final GERS format and should not be the basis for long term development work.
:::

Data in the Admins theme is licensed under CDLA Permissive 2.0.

### Attribution
- © OpenStreetMap contributors available under the Open Database License (www.openstreetmap.org/copyright)
- U.S. Geological Survey, 2019, USGS 3D Elevation Program Digital Elevation Program
- Building data © OpenStreetMap contributors, Microsoft, Esri Community Maps contributors

---

## 2023-10-19-alpha.0 release notes

### Highlights
Overture `2023-10-19-alpha.0` is now available. This release includes several improvements to the data quality and coverage as well as updates for data currency.  There are two new additions of note:

- **Base Theme**: A new Base theme that provides three context data subtypes. These can be used with the other themes to allow developers to build complete maps using any Overture release.
- **Buildings Theme**: Stable identifiers have been added to 1.6M buildings in 8 cities to demonstrate how Overture will implement stable identifiers (named Global Entity Reference System or GERS).

More information about these additions is available in the relevant sections below.

{/* truncate */}

This data is formatted in the Overture Data Schema unless otherwise noted.

This data is available for use under the designated licenses for each theme. While Overture intends to release open map data on a regular cadence in the future, the date of subsequent releases has not yet been established.

We would like feedback on the data, its usefulness, and how it could be improved. Please use this Github repo for discussions and feedback related to this data release.

Overture `2023-10-19-alpha.0` is formatted in the Overture Maps schema described here. It is available in cloud-native Parquet and stored on AWS and Azure.

### Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases/tag/v0.5.0) here.

### Theme-specific updates
Overture `2023-10-19-alpha.0` is released in five themes.

**Base Theme**
The Base theme is an entirely new theme with 3 subTypes: land, landUse, and water. The overall purpose of this new theme is to allow users to create a complete map using any Overture release. Descriptions of the subTypes for Base are:
- land: Physical representations of land surfaces. Derived from the inverse of OSM Coastlines.
- landUse: Classifications of the human use of a section of land. Mostly derived from the key landuse in OpenStreetMap
- water: Physical representations of inland and ocean marine surfaces. Derived from OSM Coastlines, and the keys natural and waterway in OpenStreetMap.

All of the features in the base theme are from OpenStreetMap, sourced via the Daylight Map Distribution. Original OSM tags remain on all features. Some tags become top-level properties, such as the surface or wikidata tags.

Data in the Base theme is licensed under ODbL.

**Buildings Theme**
The dataset includes 1.39B conflated building footprints from OSM, Esri Community Maps, and Microsoft ML Building Footprints. This is an increase of ~700M building footprints from the July Alpha release by including the complete Microsoft ML Building footprint dataset.

The order of conflation is OpenStreetMap > Esri Community Maps > Microsoft ML Building Footprints. For example, if Esri has a building that does not exist in OSM, we take that building, then, we "fill-in" the rest of the map with any Microsoft ML buildings that do not intersect with either OSM or Esri.

:::note
A sample set of 1.6M buildings from OpenStreetMap and Esri have been assigned an initial GERS ID for demonstration purposes. These IDs are 32 character strings. By referencing these other datasets to this data release, we can match GERS IDs to external datasets and demonstrate how GERS can enable ID-based joins between two geospatial datasets. These are located in the following cities:
- United States: Seattle, Washington; Macon, Georgia; Charleston, South Carolina; Spokane, Washington
- Canada: Kingston, Ontario
- Netherlands: Leeuwarden, Friesland
- Germany: Berlin
- Brazil: Rio De Janeiro

For a deeper look at how GERS is used to link datasets on this data, see [this blog post from Deane Kensok at Esri](https://www.esri.com/arcgis-blog/products/arcgis-online/mapping/enriching-overture-data-with-gers/).
:::

The sources include OpenStreetMap, Microsoft Building footprints, and Esri Community Partners. Some building heights have also been derived using lidar from USGS 3DEP. The Building data is in the Overture Maps data schema for Buildings.

Data in the Buildings theme is licensed under ODbL.

**Administrative Boundaries (Admins) Theme**
The Admins theme includes multiple locality types:
- Countries formed from OpenStreetMap relations, primarily admin_level=2, with few exceptions such as admin_level=3 French Polynesia.
- First-level subdivisions under the country which was mapped from OpenStreetMap admin_level depending on country, in most countries admin_level=4.
- Second-level subdivisions under the country which was mapped from OpenStreetMap admin_level depending on country, in most countries admin_level=6.
- Cities, Town, Villages, Neighborhoods... based on place=* tag. In most cases these are just points. When relation with place=* tag exist we provide polygon geometry.

It also includes administrative boundaries representing borders of countries, first-level subdivisions and second-level subdivisions. The Administrative Boundary data is in the Overture Maps data schema for Admin.
Second-level subdivision did not undergo worldwide inspection of quality so some missing or wrong data is expected. All first-level subdivisions have `type=state` and all second-level subdivisions have `type=county` which is not always true; we plan to address this issue in future releases. We plan to use admin_level=8,9,10 to add polygons to cities, town, villages and other localities when available depending on individual country mapping.

Data in the Admin theme is licensed under ODbL. The sources of the admin theme are OpenStreetMap and Esri.

**Places Theme**
This release has over 57M place records. The Places theme in this release includes several modifications to improve the accuracy and quality of the dataset:
- Increased deduplication on significant landmarks by revising the screening criteria for signals based on check-ins only
- Removal of places determined to be non-existent
- Address normalization bug fix that was yielding incorrect pin locations. In addition, support for website, phone and category was added to the Microsoft sourced data.
- Some additional place records were added as a result of tuning of the algorithms.

Data in the Places theme is licensed under CDLA Permissive 2.0.

**Transportation Theme**
The Transportation theme includes the following improvements:
- Collective OSM changes through September 15th, updated and converted to Overture's Schema.
- Addition of Linear Referenced features, enabling the description of properties that apply along only portions of a segment.
- Over 1.3 million turn restrictions worldwide
- Additional scoping types populated in the Transportation data, including Travel Modes, Temporal Scoping, Geometric Scoping, and Heading
- Additional properties populated in the Transportation data, including Speed Limits, surface, and road flags.

:::note
There are several missing properties in this data release that will be added in future releases:
- Only includes road segments made from Ways that include a ‘highway’ tag
- Non-geometric scoping properties are not included
- Turn and Access restrictions are not included
- Lane information is not included
- Some language/scripts are not included in names properties
:::

:::note
The data includes some provisional Global Entity Reference System (GERS) data which is used to express relationships between road segments. This may not be representative of the final GERS format and should not be the basis for long-term development work.
:::

Data in the Transportation theme is licensed under ODbL.

### Attribution
- © OpenStreetMap contributors available under the Open Database License (www.openstreetmap.org/copyright)
- U.S. Geological Survey, 2019, USGS 3D Elevation Program Digital Elevation Program
- Building data © OpenStreetMap contributors, Microsoft, Esri Community Maps contributors

---

## 2023-11-14-alpha.0 release notes

### Highlights
Overture `2023-11-14-alpha.0` is now available. This is an incremental release that includes several improvements to the data quality and coverage as well as updates for data currency. More information about these additions is available in the relevant sections below.

{/* truncate */}

This data is formatted in the Overture Data Schema unless otherwise noted.

This data is available for use under the designated licenses for each theme. While Overture intends to release open map data on a regular cadence in the future, the date of subsequent releases has not yet been established.

We would like feedback on the data, its usefulness, and how it could be improved. Please use this Github repo for discussions and feedback related to this data release.

Overture `2023-11-14-alpha.0` is available in cloud-native Parquet and stored on AWS and Azure.

### Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases/tag/v0.6.0) here.

### Theme-specific updates
Overture `2023-11-14-alpha.0` is released in five themes. Updated to Geo Parquet format for this release:

**Transportation Theme**
The Transportation theme includes the following improvements:
- Collective OSM changes through October 15th, updated and converted to Overture’s Schema.
- Over 1.5 million turn restrictions worldwide.

:::note
The data includes some provisional Global Entity Reference System (GERS) data which is used to express relationships between road segments. This may not be representative of the final GERS format and should not be the basis for long-term development work.
:::

Data in the Transportation theme is licensed under ODbL.

**Base Theme**
All of the features in the base theme are from OpenStreetMap, sourced via the Daylight Map Distribution. Most original OSM tags remain on all features. Some tags become normalized and added as top-level properties, such as the surface or wikidata tags.

Data in the Base theme is licensed under ODbL.

**Buildings Theme**
The dataset includes 1.4B conflated building footprints from OSM, Esri Community Maps, and Microsoft ML Building Footprints. Similar to the previous release, the order of conflation is OpenStreetMap -> Esri Community Maps -> Microsoft ML Building Footprints. For example, if Esri has a building that does not exist in OSM, we take that building, then, we “fill-in” the rest of the map with any Microsoft ML buildings that do not intersect with either OSM or Esri.

We've made some incremental improvements to further ensure the data conforms to the buildings layer schema.

The sources of the buildings theme include OpenStreetMap, Microsoft Building footprints, and Esri Community Partners. Some building heights have also been derived using lidar from USGS 3DEP.

Data in the Buildings theme is licensed under ODbL.

**Places Theme**
This release has over 57M place records. The Places theme in this release includes incremental improvements to improve the accuracy and quality of the dataset:
- Corrected missing postal codes from the previous release (2023-10-19-alpha.0).
- New data has been included to improve category coverage.

Data in the Places theme is licensed under CDLA Permissive 2.0.

**Administrative Boundaries (Admins) Theme**
The Admins theme in this release includes several modifications to improve schema of the dataset:
- We added ability for admins to have point and area, in future multiple areas like landmass and maritime area
- Fixed issue with invalid format of updateTime property

:::note
Known issues:
- Second-level subdivision did not undergo worldwide inspection of quality so some missing or wrong data is expected.
- All first-level subdivisions have type=state and all second-level subdivisions have type=county which is not always true, we plan to address this issue in following releases.
- We plan to use admin_level=8,9,10 to add polygons to cities, towns, villages and other localities when available depending on individual country mapping.
:::

The sources of the admin theme are OpenStreetMap and Esri. The Administrative Boundary data is in the Overture Maps data schema for Admin.

Data in the Admin theme is licensed under ODbL.

### Attribution
- © OpenStreetMap contributors available under the Open Database License (www.openstreetmap.org/copyright)
- U.S. Geological Survey, 2019, USGS 3D Elevation Program Digital Elevation Program
- Building data © OpenStreetMap contributors, Microsoft, Esri Community Maps contributors

---

## 2023-12-14-alpha.0 release notes

### Highlights
Overture `2023-12-14-alpha.0` is now available. This release includes several incremental improvements, the conflation of Google Open Buildings into the Building theme and expansion of GERS IDs across several themes. More information about these additions is available in the relevant sections below.

{/* truncate */}

This data is formatted in the Overture Data Schema unless otherwise noted.

This data is available for use under the designated licenses for each theme.

We would like feedback on the data, its usefulness, and how it could be improved. Please use this Github repo for discussions and feedback related to this data release.

Overture Overture `2023-12-14-alpha.0` is available in cloud-native Parquet (updated to Geo Parquet format for this release) and stored on AWS and Azure.

### Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases/tag/v0.7.0) here.

### Theme-specific updates
Overture `2023-12-14-alpha.0` is released in five themes.

```
+--------------+----------------------+----------+
|theme         |type                  |count     |
+--------------+----------------------+----------+
|admins        |administrativeBoundary|59281     |
|admins        |locality              |3817886   |
|admins        |localityArea          |422245    |
|base          |land                  |62239589  |
|base          |landUse               |43818585  |
|base          |water                 |42556151  |
|buildings     |building              |2339547325|
|buildings     |part                  |2850221   |
|places        |place                 |57619504  |
|transportation|connector             |340035621 |
|transportation|segment               |300834113 |
+--------------+----------------------+----------+
```

**Buildings Theme**
The dataset includes 2.4B conflated building footprints from OSM, Esri Community Maps, Microsoft ML Building Footprints, and Google Open Buildings.
The order of conflation is OpenStreetMap → Esri Community Maps → high precision Google Open Buildings → Microsoft ML Building Footprints → lower precision Google Open Buildings. For example, if Esri has a building that does not exist in OSM, we take that building, then we “fill-in” the rest of the map with any ML buildings that do not intersect with either OSM or Esri.

We use the 90% precision confidence threshold to delineate between high and lower precision for Google Open Buildings, which varies per s2 cell.
Google Open Building coverage is primarily in the southern hemisphere and the m3 release adds nearly 1.1B buildings from the Google Open Buildings Dataset, replacing existing MSFT ML buildings where Google was found to have higher quality data.

We've introduced a new 3d part type to support 3d building renderings. This is the first release of this dataset and sourced from OpenStreetMap.
We've made incremental improvements to further ensure the data conforms to the buildings layer schema.

The sources of the buildings theme include OpenStreetMap, Esri Community Maps, Microsoft Building footprints, and Google Open Buildings. Some building heights have also been derived using lidar from USGS 3DEP.

Data in the Buildings theme is licensed under ODbL.

**Transportation Theme**
- Refreshed Data to include OSM data up to Nov 27
- Added two additional road classes for pedestrians: sidewalk and crosswalk
- Features previously classified as footway will now be reassigned to one of: footway, sidewalk, or crosswalk
- Speed-limit properties that apply to the entire segment are now captured as an array with one element instead of an enum
- This is a simplification of the schema to reduce cases where there is different typing based on scoping conditions

:::note
GERS ID format updated to match Schema definition
:::

Data in the Transportation theme is licensed under ODbL.

**Base Theme**
All of the features in the base theme are from OpenStreetMap, sourced via the latest Daylight Map Distribution (v1.35). Data validation improvements fixed the classification of 400k landUse features and added 620k new land features and 295k new water features. Most original OSM tags remain on all features. Some tags become normalized and added as top-level properties, such as the surface or wikidata tags.

Data in the Base theme is licensed under ODbL.

**Places Theme**
This release has over 57M place records.
The Places theme in this release includes incremental improvements to improve the accuracy and quality of the dataset.
New data has been included to improve category coverage.
Updated to computation of confidence scores.
Minor updates to formatting for categories.

Data in the Places theme is licensed under CDLA Permissive 2.0.

**Administrative Boundaries (Admins) Theme**
The Admins theme in this release includes only minor fix to not set adminLevel on namedLocalities

Known issues:
- Second-level subdivision did not undergo worldwide inspection of quality so some missing or wrong data is expected.
- All first-level subdivisions have type=state and all second-level subdivisions have type=county which is not always true, we plan to address this issue in following releases.
- We plan to use admin_level=8,9,10 to add polygons to cities, towns, villages and other localities when available depending on individual country mapping.

The sources of the admin theme are OpenStreetMap and Esri. The Administrative Boundary data is in the Overture Maps data schema for Admin.

Data in the Admin theme is licensed under ODbL.

### Attribution
- © OpenStreetMap contributors available under the Open Database License (www.openstreetmap.org/copyright)
- U.S. Geological Survey, 2019, USGS 3D Elevation Program Digital Elevation Program
- Building data © OpenStreetMap contributors, Microsoft, Esri Community Maps contributors, Google Open Buildings

---

## 2024-07-22.0 release notes

## Overview

**Overture's `2024-07-22.0` data release and `v1.0.0` of the schema are now available.** The base, buildings, divisions, and places themes have reached General Availability (GA). The transportation theme remains in beta, and users can anticipate additional breaking changes to the transportation schema. Also in this release, we launched a new theme called addresses, available in alpha. We will be making significant changes to the addresses schema and updating and adding to the addresses data over the next several months.

The datasets are available as GeoParquet files stored on AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2024-07-22.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2024-07-22.0
```

{/* truncate */}

You can access the datasets by following the process outlined [here](https://docs.overturemaps.org/getting-data/). We encourage users to report bugs and provide feedback on the data, schema, and GERS on one of our Overture GitHub repositories:

- [Schema](https://github.com/OvertureMaps/schema)
- [Data](https://github.com/OvertureMaps/data)
- [Docs](https://github.com/OvertureMaps/docs)
- [Python command-line tool](https://github.com/OvertureMaps/overturemaps-py)
- [Explore site](https://github.com/OvertureMaps/io-site)

## New theme: addresses

In this release, we added a new theme called [addresses](/schema/reference/addresses/address) that includes over 200 million address features for 14 countries. We are releasing this theme in alpha and anticipate significant changes over the next several releases. We invite the Overture community to test the addresses schema and data and offer feedback via the [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repos.

## Breaking changes

In the divisions theme, we changed the `boundary` feature type to `division_boundary`. Feature types in Overture must be distinct and unique across all themes, and `boundary` did not meet those conditions. We realize that changing the name of a feature type is a major change, and we do not anticipate doing this again without giving our users plenty of advance notice. 

Also in the divisions theme, we changed the `divisions` property to `divisions_ids` to fix relationship modeling in the schema. The logic is that a property or nested sub-property that contains a foreign key reference to another feature by Overture ID must end in the suffix `_id`. More information about this change here: https://github.com/OvertureMaps/schema/pull/215

We removed `update_time` from a top-level schema property to a property within the sources structure. For example, the Microsoft buildings `update_time` comes from Microsoft's imagery capture data:
```
[{property=, dataset=Microsoft ML Buildings, record_id=709fc8cf0b55, update_time=2023-06-23T00:00:00.000Z, confidence=null}]
```

## Deprecations

In the transportation theme, we deprecated the `road` JSON column in the June release and removed it in the current release. We replaced the `road` JSON column with structured Parquet columns for road attributes.

In April, we deprecated the admins theme and offered the divisions theme as a replacement. We removed admins in this release and are no longer supporting it. You can still access the admins data and schema in previous Overture releases.

## Theme-specific updates

:::info
The base, buildings, divisions, and places themes are now in the General Availability (GA) phase. The transportation theme is in beta, and the addresses theme is in alpha.
:::

### Addresses
- added over 200 million addresses for 14 countries, pulling data from many [sources](https://docs.overturemaps.org/attribution/)

### Base

- made incremental updates from OSM, based on Daylight v1.50

### Buildings

- made regular updates to buildings, including adding the latest open data from OSM, Esri Community Maps, and Microsoft
- removed `update_time` from top level buildings schema
- added `update_time` to the sources structure
- added `update_time` to the sources structure for building parts
- capped `height` and `roof_height` at 850 meters and discarded values over that limit
- added a test to check that building `min_height` is less than `height`
- included building parts inside building relation outline even when part is not an explicit member
- resolved issue with building and building_part polygons having identical geometries
- added classification for bridge structures to schema
- added `is_underground` to all buildings

### Divisions

:::warning
**BREAKING CHANGES** 
- changed the name of the `boundary` feature type to `division_boundary` 
- changed the `divisions` property to `division_id`
:::
- added the `dependency` subtype to the division and division_area feature types
- added the `microhood` subtype to the division feature type
- added to the division feature type a [`capital_of_divisions` property](https://github.com/OvertureMaps/schema/pull/225), an object that will refer to the division IDs of the countries, regions, counties, etc
- made incremental improvements to the data

### Places

- changed the schema to allow for NULL categories

**Transportation**

- removed deprecated road column
- added rail segments (just geometries for now)
- resolved most schema validation issues
- added language tag filtering and normalizing
- fixed missing LR values for `road_flags`
- fixed bugs in vehicle constraint and max speed properties
- made incremental improvements to the data

## Global Entity Reference System (GERS) changelog

The GERS changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2024-07-22.0
```
```
s3://overturemaps-us-west-2/changelog/2024-07-22.0
```

The types of feature changes in the changelog include:

- `added`: Feature with this ID is new (was not present in the previous release).
- `removed`: Feature with this ID was present in the previous release, but not this release.
- `data_changed`: The feature with this ID contains a change in attributes (geometry or otherwise) from the feature with this ID in the previous release.
- `unchanged`: The feature with this ID in this release matches the geometry and attributes of the feature with this ID in the previous release.

## Attribution

You'll find information about attribution and licensing [here](https://docs.overturemaps.org/attribution/).

---

## 2024-08-20.0 release notes

## Overview

**Overture's `2024-08-20.0` data release is now available.** The base, buildings, divisions, and places themes are stable, which means the only changes this month are data improvements and bug fixes. The transportation theme remains in beta and we have made several significant changes to the schema in this release. The addresses theme is in alpha.

The datasets are available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2024-08-20.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2024-08-20.0
```

{/* truncate */}

You can access the datasets by following the process outlined [here](https://docs.overturemaps.org/getting-data/). We encourage users to report bugs and provide feedback on the data, schema, and GERS on one of our Overture GitHub repositories:

- [Schema](https://github.com/OvertureMaps/schema)
- [Data](https://github.com/OvertureMaps/data)
- [Docs](https://github.com/OvertureMaps/docs)
- [Python command-line tool](https://github.com/OvertureMaps/overturemaps-py)
- [Explore site](https://github.com/OvertureMaps/io-site)

## Breaking changes

Changes were made to the transportation theme in this release to better support a variety of routing use cases. A summary of those changes, below:

- we added a `subclass` property that refines the descriptions of segments by:
  - clearly specifying the usage of a length of road and using linear referencing, instead of further segmentation, to pinpoint a change in how the road is used
  - properly classifying information from OpenStreetMap

- to better support routing use cases, we added to the segment feature type a new property called `connectors`: an array of IDs with pre-computed linear reference values that explicitly link segment geometry with connector coordinates. This new property—a replacement for the existing `connector_ids` property—will reduce complexity and improve accuracy as we calculate the intersections between segments and connectors.

- we added a `destinations` property to the segment feature type. This property describes the transitions from one segment to another on the way to a specified location

You can read more about these changes on the [engineering blog](https://docs.overturemaps.org/blog/2024/08/15/preview-august-release/).

## Deprecations

In this release, we deprecated the `connector_ids` property in the transportation schema and plan to remove it by the October release. It will be replaced by the new `connectors` property, introduced in the schema this month.

## Theme-specific updates

:::info
The base, buildings, divisions, and places themes are in GA. The transportation theme is in beta, and the addresses theme is in alpha.
:::

### Addresses

- 3.15M new address features were added in Switzerland.
- addresses in 15 countries are now available.

### Base

- made incremental changes to improve the accuracy and quality of the dataset. Built from [Daylight v1.52](https://daylightmap.org/2024/08/12/daylight-v152-released.html)

### Buildings

- removed 60M buildings over water and transportation segments.

### Divisions

- added 12 features at the region subtype in the country of Georgia.

### Places

- made incremental changes to improve the accuracy and quality of the dataset

### Transportation

- we added a new [`subclass` property](https://github.com/OvertureMaps/schema/pull/180) that refines the descriptions of segments.
- to better support routing use cases, we added to the segment feature type a new property called `connectors`, replacing the  existing `connector_ids` property.
- we added a `destinations` property to the segment feature type.
- our transportation splitter tool was made available in [a public GitHub repository](https://github.com/OvertureMaps/transportation-splitter).
- fixed a bug that caused segments to be missing sources or other attributes, affecting ~100K segments.
- fixed name filtering to avoid including names with an invalid BCP-47 tag.

## Global Entity Reference System (GERS) changelog

The GERS changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files - partitioned by theme, type, and change type - at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2024-08-20.0
```
```
s3://overturemaps-us-west-2/changelog/2024-08-20.0
```

You can find more information about [using the GERS Changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema Changelog

There are no schema changes this month, other than minor improvements to the schema documentation. The schema changelog is [here](https://github.com/OvertureMaps/schema/releases). 

## Attribution

You'll find information about attribution and licensing [here](https://docs.overturemaps.org/attribution/).

---

## 2024-09-18.0 release notes

## Overview

**The `2024-09-18.0` release of Overture data is now available.**  We are still on `v.1.1.0` of the Overture schema, as we did not cut a new schema version with this data release. The base, buildings, divisions, and places themes are stable, which means the only changes to these themes are data improvements and bug fixes. We added new road data from TomTom, mostly in Saudi Arabia, to the transportation theme (beta). To the addresses theme (alpha) we added new data for Finland and Chile, and we replaced NAD-sourced address features in New York City with addresses from NYC Open Data. 

The datasets are available as GeoParquet files stored on both AWS and Azure. 
The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2024-09-18.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2024-09-18.0
```
{/* truncate */}

:::note
Overture's GeoParquet files are now released according to the [GeoParquet v1.1.0 specification](https://geoparquet.org/releases/v1.1.0/), with the `covering` metadata included.
:::

You can access the datasets by following the process outlined [here](https://docs.overturemaps.org/getting-data/). We encourage users to report bugs and provide feedback on the data, schema, and GERS on one of our Overture GitHub repositories:

- [Schema](https://github.com/OvertureMaps/schema)
- [Data](https://github.com/OvertureMaps/data)
- [Docs](https://github.com/OvertureMaps/docs)
- [Python command-line tool](https://github.com/OvertureMaps/overturemaps-py)
- [Explore site](https://github.com/OvertureMaps/io-site)

## Breaking changes

There are no breaking changes this month. 

## Deprecations

In the `2024-08-20.0` release notes, we announced the deprecation of the `connector_ids` property in the transportation schema. We plan to remove that property by the October release. It has been replaced by the new `connectors` property, introduced in the schema last month.

## Theme-specific updates

:::info
The base, buildings, divisions, and places themes are in GA. The transportation theme is in beta, and the addresses theme is in alpha.
:::

### Addresses

- added 3,897,449 new addresses in Finland.
- added 4,042,071 new addresses in Chile.
- completed “cut and replace” work in NYC, which entailed removing NAD-sourced address features and replacing them with addresses from NYC Open Data.

### Base

- made incremental changes to improve the accuracy and quality of the dataset.
- refreshed data with [Daylight v1.54](https://daylightmap.org/2024/09/09/daylight-v154-released.html). 

### Buildings

- made incremental changes to improve the accuracy and quality of the dataset.
- refreshed data with [Daylight v1.54](https://daylightmap.org/2024/09/09/daylight-v154-released.html).

### Divisions

- rolled back to the August version of the `divisions` data because a bug fix in the latest version caused a regression in `local_type` property coverage.

### Places

- made incremental changes to improve the accuracy and quality of the dataset.

### Transportation

- added more than 1000km of non-OSM road segments from TomTom to improve data in Saudi Arabia and fix a coverage gap. 
- added OSM source version and update time for all applicable features.
- added more precise length calculation for linearly referenced values.
- removed invalid `connector_id` segment references.
- increased precision on `connectors` at LR value.

## Global Entity Reference System (GERS) changelog

The GERS changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files - partitioned by theme, type, and change type - at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2024-09-18.0
```
```
s3://overturemaps-us-west-2/changelog/2024-09-18.0
```

You can find more information about [using the GERS Changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema Changelog

There are no schema changes this month, other than minor improvements to the schema documentation. The schema changelog is [here](https://github.com/OvertureMaps/schema/releases). 

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2024-10-23.0 release notes

## Overview

**The `2024-10-23.0` release of Overture data and `v1.2.0` of the Overture schema are now available.** As part of Overture's mission to improve data quality and coverage and to expand the number of sources we use to make our datasets, 
we added in this release address data for several new countries, transportation data in Saudi Arabia and Italy from TomTom, and building height data from Microsoft and Esri Community Maps contributors. 

The October release is available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2024-10-23.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2024-10-23.0
```
{/* truncate */}

:::note
We are now releasing Overture's GeoParquet files in accordance with the [GeoParquet v1.1.0 specification](https://geoparquet.org/releases/v1.1.0/), with the covering metadata included.
:::

You can access the datasets by following the process outlined [here](https://docs.overturemaps.org/getting-data/). We encourage you to ask questions, report bugs, and provide feedback via our [data](https://github.com/OvertureMaps/data) and [schema](https://github.com/OvertureMaps/schema) repositories on GitHub. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at **data AT overturemaps.org**. We’d love to hear from you.

## Breaking changes

We removed the `connector_ids` property from the schema and replaced it with a new `connectors` property. You'll find more information about this change [here](https://docs.overturemaps.org/blog/2024/08/15/preview-august-release/#connectors).

## Deprecations

In the `2024-08-20.0` [release notes](https://docs.overturemaps.org/blog/2024-08-20.0/), we announced the deprecation of the `connector_ids` property in the transportation schema. We have removed that property in this release. 

## Theme-specific updates

:::info
The base, buildings, divisions, and places themes are in GA. The transportation theme is in beta, and the addresses theme is in alpha.
:::

### Addresses
- added new address features in the following countries:
    - **89.9 million** in Brazil
    - **1.7 million** in Croatia
    - **5.9 million** in German[y](https://youtu.be/WBpDs-BfwO0?feature=shared)
    - **19.6 million** in Japan
    - **2.6 million** in Norway
    - **7.7 million** in Poland
    - **1.6 million** in Slovakia
- updated the [US National Address Database](https://www.transportation.gov/gis/national-address-database) to v17
- added data from the [NYC Open Data](https://opendata.cityofnewyork.us/) portal
- fixed a bug that resulted in both the US National Address Database and NYC Open Data being included for Queens
- fixed a typo in the Geoscape Australia source name
- changed the data source name for Chile to CL-INE and Portugal to PT-INE to distinguish the two

### Base
- fixed lake features in Manitoba, Canada

### Buildings
- fixed building features with class but no subtype property
- fixed building height data missing in September release 
- fixed building height data derived from lidar
- fixed ML buildings in water 
- added new data from OSM (2024-10-05)
- added new data from Microsoft (2024-09-24)
- added new from Esri Community Maps contributors (2024-10-15)

### Divisions
- updated the subtype of 38 dependencies, e.g. Puerto Rico
- fixed microhood/neighborhood discrepancy between feature types
- updated regions in North Macedonia
- moved features with a suburbs tag into a new macrohood subtype

### Places
- no updates

### Transportation
- removed `connector_ids` property; more information [here](https://docs.overturemaps.org/blog/2024/08/15/preview-august-release/#connectors) 
- removed duplicate coordinates for 100 segment geometries
- fixed most remaining schema mismatch issues, primarily for turn restrictions
- filtered out abandoned/disused railways until they can be properly flagged, affecting 336K segments

## Global Entity Reference System (GERS) changelog

The GERS changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2024-10-23.0
```
```
s3://overturemaps-us-west-2/changelog/2024-10-23.0
```

You can find more information about [the GERS Changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog
The changelog for Overture schema `v1.2.0` is [here](https://github.com/OvertureMaps/schema/releases). 

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2024-11-13.0 release notes

## Overview

**The `2024-11-13.0` release of Overture data and `v1.3.0` of the Overture schema are now available.** This release includes more than 66 unique address datasets from many new [sources](/attribution). We added a new `postal_city` column to the addresses schema to support address formatting. In the transportation schema, we dropped the unutilized `lanes` column in preparation for transportation's GA release in the near future.

The November release is available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2024-11-13.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2024-11-13.0
```

{/* truncate */}

:::note
We are now releasing Overture's GeoParquet files in accordance with the [GeoParquet v1.1.0 specification](https://geoparquet.org/releases/v1.1.0/), with the covering metadata included.
:::

You can access the datasets by following the process outlined [here](https://docs.overturemaps.org/getting-data/). We encourage you to ask questions, report bugs, and provide feedback via our [data](https://github.com/OvertureMaps/data) and [schema](https://github.com/OvertureMaps/schema) repositories on GitHub. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at **data AT overturemaps.org**. We’d love to hear from you.

## Breaking changes

We removed the `lanes` column from the transportation schema, as we have not had the data to populate it since its implementation many months ago. It's unlikely this will be a breaking change for most users, but we are erring on the side of caution and including this information here. We intend to introduce a reimagined, data-rich lanes property in 2025. 

## Deprecations

 None.

## Theme-specific updates

:::info
The base, buildings, divisions, and places themes are in GA. The transportation theme is in beta, and the addresses theme is in alpha. 
:::

### Addresses
- added a new `postal_city` column to support address formatting
- added the following countries to the address theme:
    - Belgium
    - [Ice](https://youtu.be/1HU7ocv3S2o?feature=shared)land
    - Italy
    - Latvia
    - Slovenia
    - Spain
    - Taiwan
- added new data and new sources for several countries

### Base
- added more detailed features at higher latitudes in the land cover feature type
- added new `crater` subtype and associated classes in the land feature type
- added new classes in the infrastructure feature type

### Buildings
- made incremental updates
- added a new roof class to the building feature type

### Divisions
- made minor fixes and incremental updates

### Places
- no updates

### Transportation
- removed `lanes` column
- added 2.6M connectors for crosswalks on roads that don't yet have an intersecting segment

## Global Entity Reference System (GERS) changelog

The GERS changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2024-11-13.0
```
```
s3://overturemaps-us-west-2/changelog/2024-11-13.0
```

You can find more information about [the GERS Changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog
The changelog for Overture schema `v1.3.0` is [here](https://github.com/OvertureMaps/schema/releases). 

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2024-12-18.0 release notes

## Overview

**The `2024-12-18.0` release of Overture data and `v1.4.0` of the Overture schema are now available.** This month [our transportation theme is going to GA](/blog), we're launching a [bathymetry feature type](/schema/reference/base/bathymetry) in our base theme, and we're at 400 million address records and counting in our [addresses theme](/guides/addresses). What a way to end the year!

The datasets are available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2024-12-18.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2024-12-18.0
```
{/* truncate */}

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions, report bugs, and provide feedback via our [data](https://github.com/OvertureMaps/data) and [schema](https://github.com/OvertureMaps/schema) repositories on GitHub. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## Breaking changes

None. 

## Deprecations

 None.

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses
- reached a milestone of 400 million address records
- added new data for:
    - Czechia
    - Liechtenstein
    - Uruguay
    - various counties in [Ca](https://youtu.be/lWQ4IPPXz2k?feature=shared)lifornia
- replaced NAD data in Massachusetts with open data from MassGIS

### Base
- added `bathymetry` feature type with 60,000 new features
- added new classes to `land`, `land_use`, and `water` feature types, including `fatbike`, `hike`, and `nordic`

### Buildings
- made incremental updates to data

### Divisions
- made incremental updates to data

### Places
- no updates

### Transportation
- released the transportation theme in GA!
- added new roads in the US, UK, and FR 
- added non-OSM roads in:
    - France: 172.87 kms
    - United Kingdom: 20.21 kms 
    - Italy: 1099.86 kms 
    - Saudi Arabia: 29793.48 kms 
    - United States: 215.51 kms
- merged adjacent route values
- fixed access restrictions that were not populating with data
- fixed class value that was not populating with data for 3K segments

## Global Entity Reference System (GERS) changelog

The GERS changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2024-12-18.0
```
```
s3://overturemaps-us-west-2/changelog/2024-12-18.0
```

You can find more information about [the GERS Changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog
The changelog for Overture schema `v1.4.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.4.0). 

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## Welcome to the Overture Maps engineering blog!

Welcome to the Overture Maps engineering blog!
We're excited to tell the technical stories behind this big, exciting, ambitious, intensely collaborative project we’ve been [working on for more than a year](https://overturemaps.org/looking-forward-to-2024/).
The engineers building Overture Maps are eager to connect with our developer community.
In the posts we publish in the coming months, you’ll hear from team members who work at Amazon, Meta, Microsoft, TomTom, Esri, Development Seed, Precisely, and more.

{/* truncate */}

And we’d like to hear from you: [feedback and contributions](https://github.com/OvertureMaps/data/discussions) from folks working with our data and schema are crucial to our success.
Thanks for joining us on this journey.
We’re glad you’re here.

---

## Exploring our beta release

Last week Overture Maps [announced the beta release](https://overturemaps.org/overture-maps-foundation-releases-beta-of-its-first-open-map-dataset/) of our schema and data. After months of hard work and steady improvements, we are nearing production-level stability. In a series of posts over the next few weeks -- starting with this one -- we’ll unpack the highlights and improvements you'll see in this release and beyond.

{/* truncate */}

## Making geospatial fast

The first thing you'll notice is how much faster you can [pull Overture Maps data out of the cloud](https://docs.overturemaps.org/getting-data/locally/). We made this possible by working closely with open-source collaborators on the repartitioning and [spatial optimization](https://cloudnativegeo.org/blog/2024/03/coming-soon-geoparquet-1.1/) of our GeoParquet files. Meanwhile, our friends at DuckDB, one of our favorite SQL tools, [added a feature](https://github.com/duckdb/duckdb/pull/10314) that improves the performance of queries with bounding boxes.

<details>

<summary>
  Query speeds have improved significantly from our February release to the April beta release. This
  example compares DuckDB queries for buildings in Philadelphia. [See here for more information
  about our performance
  testing](https://github.com/opengeospatial/geoparquet/discussions/188#discussioncomment-8909348).
</summary>

    <Tabs>
        <TabItem value="february" label="2024-02-15-alpha.0 release" default>
            ```
            SELECT
            *
            FROM
                read_parquet('s3://overturemaps-us-west-2/release/2024-02-15-alpha.0/theme=buildings/type=building/*', filename=true, hive_partitioning=1)
            WHERE
                bbox.minx > -75.60154
                AND bbox.maxx < -74.955763
                AND bbox.miny > 39.867004
                AND bbox.maxy < 40.137992;
            ```
            820,915 buildings
            ~120s
        </TabItem>

        <TabItem value="april" label="2024-04-16-beta.0 release" default>
            ```
            SELECT
            *
            FROM
                read_parquet('s3://overturemaps-us-west-2/release/2024-04-16-beta.0/theme=buildings/type=building/*', filename=true, hive_partitioning=1)
            WHERE
                bbox.xmin > -75.60154
                AND bbox.xmax < -74.955763
                AND bbox.ymin > 39.867004
                AND bbox.ymax < 40.137992
            ```
            852,487 buildings
            ~25s
        </TabItem>
    </Tabs>

</details>

We're continuing to make things faster and easier for users. Along with the folks at Development Seed, an [Overture Maps Foundation member](https://overturemaps.org/about/members/), we're [building special tools for Overture Maps data on top of lonboard](https://developmentseed.org/lonboard/latest/examples/overture-maps/), their Python library for visualizing large geospatial datasets in Jupyter. And recently our friends at Wherobots [took a comprehensive look](https://wherobots.com/overture-maps-data-cloud-native-geoparquet-apache-sedona/) at how our use of GeoParquet makes querying and analyzing our data with Apache Sedona very efficient.

As you can see, we're moving forward with the community to iterate on data, software, and specifications with the shared goal of making geospatial **_fast_**.

## Easier-to-use schema

Another highlight of the beta release is the transition to an easier-to-use schema for our administrative boundary data. We first [explored this idea](https://github.com/OvertureMaps/schema/discussions/117) with the Overture Maps community in February, and after two short months of work, the [new divisions schema and data](https://docs.overturemaps.org/guides/divisions/) are ready to go. Here's a query to `divisions` that grabs geometries for all the countries in the world:

```
SELECT *
   FROM read_parquet('s3://overturemaps-us-west-2/release/2024-04-16-beta.0/theme=divisions/type=division_area/*', filename=true, hive_partitioning=1)
WHERE subtype = 'country';
```

You can see that the `divisions` query above is much simpler than a comparable query to `admins`:

```
WITH admins AS (
    SELECT *
    FROM read_parquet('s3://overturemaps-us-west-2/release/2024-04-16-beta.0/theme=admins/type=*/*', filename=true, hive_partitioning=1)
  )

  SELECT *
    FROM admins country_locality
    JOIN admins country_area
      ON country_area.locality_id = country_locality.id
   WHERE country_locality.locality_type = 'country';

```

We plan to [deprecate admins](https://docs.overturemaps.org/release-notes/) by the July release. In the meantime, both `admins` and `divisions` will be available to users.

## Bridges, islands, waterfalls, and more!

We added more rich detail to our `base` layer in this release, including an `infrastructure` type with familiar features from [Facebook’s Daylight map distribution](https://daylightmap.org/). We also added new subtypes and classes for the `land`, `land_use`, and `water` feature types. You'll find a comprehensive listing of the subtypes and classes for each feature type in our [schema reference docs](https://docs.overturemaps.org/schema/reference/base/infrastructure). Ready to make your own map? We have a [tutorial to help you get started](https://docs.overturemaps.org/examples/build-a-map/#13/47.6/-122.33/0/45).

## Stay tuned for more highlights

We'll be back soon with more posts that explore our path from the beta release to production. In the meantime, we invite you to [get started with our data](https://docs.overturemaps.org/getting-data/) and share with us your [comments and feedback](https://github.com/OvertureMaps/data/discussions).

---

## Land cover is live

<video autoPlay loop muted playsInline style={{ width: '100%' }}>
  <source src={useBaseUrl('/img/blog/lc.mp4')} type="video/mp4" />
</video>

## Mapmakers rejoice!

The [May release](https://docs.overturemaps.org/release/latest) of Overture Maps includes new high-resolution land cover data _and_ new cartographic schema properties.

{/* truncate */}

Our `land_cover` layer is vectorized data derived from the [European Space Agency’s 2020 WorldCover (10m) rasters](https://esa-worldcover.org/en). It's similar to the land cover layer in the [Daylight](https://daylightmap.org/2023/10/11/landcover.html) map distribution, but Overture Maps added higher-resolution data (zoom level 15) with more detail and land cover classes. You'll find 10 subtypes in the new data: snow, forest, urban, grass, crop, barren, wetland, moss, mangrove, and shrub.

Our May release also includes [schema properties](https://docs.overturemaps.org/schema/reference/base/land_cover/) that offer cartographic "hints" for optimal use of Overture Maps data in mapmaking. We added `min_zoom` and `max_zoom` to define the recommended zooms for each resolution of land cover, using the common “slippy maps” zoom level specification. This is a first step toward improving the user experience for mapmakers. We plan to expand these properties in future releases of Overture Maps data.

## Exploring land cover

In the notebook example below, we'll show you how to extract, process, and visualize land cover data for an area of interest using [lonboard](https://developmentseed.org/lonboard/latest/) and the [Overture Maps Python command-line tool](https://github.com/OvertureMaps/overturemaps-py). We recommend that you consult [this example](https://developmentseed.org/lonboard/latest/examples/overture-maps/) in the lonboard docs to better understand the methods used here. You can view and download the complete notebook on [Notebook Sharing Space](https://notebooksharing.space/view/b63f6b3dda1da99c45caf53284fbc508aaae0a43480b43bb0316db636c5e6677).

![land cover](/img/blog/notebook-overture-lc.png)

To follow along, you'll need to have [JupyterLab or Jupyter Notebook](https://jupyter.org/) running and the following dependencies installed:

- [lonboard](https://developmentseed.org/lonboard/latest/#install)
- [overturemaps-py](https://github.com/OvertureMaps/overturemaps-py)
- [pandas](https://pandas.pydata.org/)
- [GeoPandas](https://geopandas.org/en/stable/index.html)
- [Shapely](https://shapely.readthedocs.io/en/stable/index.html)

```python

from shapely import wkb
from lonboard import Map, PolygonLayer
from lonboard.colormap import apply_categorical_cmap
```

```python
# specify bounding box
bbox =  -78.6429, 39.463, -73.7806, 41.6242
```

```python
# read in Overture Maps land_cover data type
table = overturemaps.record_batch_reader("land_cover", bbox).read_all()
table = table.combine_chunks()
```

```python
# convert to dataframe
df = table.to_pandas()
```

```python
# filter for higher resolution land_cover features
df_h = df[df.cartography.apply(lambda x: x['min_zoom'] == 8)]
```

```python
# create color map for land_cover subtypes, loosely based on natural-color palette: https://www.shadedrelief.com/shelton/c.html
color_map = {
    "urban": [167, 162, 186],
    "forest": [134, 178, 137],
    "barren": [245, 237, 213],
    "shrub": [239, 218, 182],
    "grass": [254, 239, 173],
    "crop": [222, 223, 154],
    "wetland": [158, 207, 195],
    "mangrove": [83, 171, 128],
    "moss": [250, 230, 160],
    "snow": [255, 255, 255],
}
```

```python
# apply color map to land_cover subtypes
colors = apply_categorical_cmap(df_h.subtype, color_map)
```

```python
# dataframe to geodataframe, set crs
gdf = gpd.GeoDataFrame(
    df_h,
    geometry=df_h['geometry'].apply(wkb.loads),
    crs="EPSG:4326"
)
```

```python
# create map layer
layer = PolygonLayer.from_geopandas(
    gdf= gdf[['id','subtype', 'cartography', 'geometry']].reset_index(drop=True),
    get_fill_color=colors,
    get_line_color=colors,
)
```

```python
#render map
view_state = {
    "longitude": -76.2,
    "latitude": 39.6,
    "zoom": 8,
    "pitch": 65,
    "bearing": 5,
}
m = Map(layer, view_state=view_state)
m
```

---

## Exploring Overture data, no SQL required

Overture has launched a new browser-based tool to give users a no-code option to interact with our data. The Explore website is now the quickest way to get started with Overture, no SQL required: [https://explore.overturemaps.org](https://explore.overturemaps.org/#13.01/39.95692/-75.15583)

<figure>
  <video autoPlay loop muted playsInline style={{ width: '100%' }}>
    <source src={useBaseUrl('/img/blog/explore-philadelphia2.mp4')} type="video/mp4" />
  </video>
  <figcaption style={{ textAlign: 'center' }}>
    
      Checking out{' '}
      
        "Lion Crushing a Serpent"
      {' '}
      in Philadelphia's Rittenhouse Park
    
  </figcaption>
</figure>

{/* truncate */}

## Not a map

The Explore tool might look like a map, but we prefer to think of it as an x-ray data inspector. We’ve punted on making cartographic decisions in favor of displaying all of Overture’s themes, all at once: addresses, base, buildings, divisions, places, and transportation. Our users are coming at the data with different perspectives and goals, and we want to provide as much information as possible. We also want to stoke your curiosity and inspire you to ask new questions of Overture data.

Seeing all the data all at once might be a bit overwhelming. We recommend zooming to an area of interest, hovering over the layers icon in the upper left corner of the map, and toggling the data themes off and on. You can click on an individual map feature, like the famous ["Lion Crushing a Serpent"](https://youtu.be/rTl2ewUc6bA?feature=shared) statue, to inspect its properties. Want to download the data? In the upper right corner of the Explore site, you can click on the Download Visible button to generate a GeoJSON file containing all the data visible in the browser.

The [Explore site](https://explore.overturemaps.org/#13.01/39.95692/-75.15583) is currently in beta, and your feedback will inform the features we add in the coming months. If you have questions about the data, or if you want to report a problem with data quality or a glitch in the website, please click on the bug icon and [file an issue on GitHub](https://github.com/OvertureMaps/io-site/issues). (Note: we are actively working on fixing known issues with the downloaded data.)

## Build with us

This project grew out of the diverse experiences and skill sets of the engineers working on Overture. We’re using [WebAssembly](https://webassembly.org/) and Rust, specifically [geoarrow-rs](https://geoarrow.org/geoarrow-rs/), to query and download [Overture’s GeoParquet files](https://docs.overturemaps.org/getting-data/). The front end is React and [Maplibre](https://maplibre.org/), and we’re generating [PMTiles](https://docs.protomaps.com/pmtiles/) to visualize the data. It’s a serverless site, using all cloud-native data storage formats. We also plan to make [PMTiles available with each Overture release](https://github.com/OvertureMaps/overture-tiles). Special thanks to Kyle Barron from [Development Seed](https://developmentseed.org/) and Brandon Liu from [Protomaps](https://protomaps.com/) for collaborating with Overture's Developer Advocacy team on this project.

[Explore is open source](https://github.com/OvertureMaps/io-site), under an MIT license, and we welcome contributions from the Overture community. Our goal is to give you the basic building blocks for creating your own tools around Overture data. Let us know what you make and we’ll happily share it on our [community projects page](https://docs.overturemaps.org/community/).

---

## What to expect in Overture's August release

Last month we released [v1.0.0 of the Overture schema and “general availability” versions of four themes](https://overturemaps.org/overture-maps-foundation-releases-general-availability-of-its-open-maps-datasets/):
base, buildings, divisions, and places. Our [addresses theme](https://docs.overturemaps.org/guides/addresses/) launched in alpha with 200 million addresses
for 14 countries; we anticipate adding more address data each month, country by country, starting with
Switzerland in the August release.

{/* truncate */}

The [transportation theme](https://docs.overturemaps.org/guides/transportation/) remains in beta and we expect to make significant changes over the next couple
months. In this post, we'll give you a preview of three key improvements to the transportation schema in the August
release, **which will be available next week**.

## Transportation schema changes
The schema changes we plan to implement over the next few releases will better support routing and map
display use cases, and make it easier for our users to integrate Overture transportation data into their
pipelines and products. These improvements are necessary if we are to achieve our goal of a GA release in October.
Here are the steps we're taking in the August release to move us toward that goal.

### Subclasses

| ![Diagram of class and subclass structures](/img/blog/class-subclass-diagram.png) |
|:--:|
| *A diagram of the new class and subclass structures* |

We [added a new `subclass` property](https://github.com/OvertureMaps/schema/pull/180) that refines the descriptions of segments by:

- clearly specifying the usage of a length of road, and using linear referencing instead of further segmentation to pinpoint a change in how the road is used
- properly classifying detailed information from OpenStreetMap

Subclasses require non-overlapping geometries, which will make it easier for routing engines to consume our
road data and generate turn-by-turn directions. The new class and subclass structures allow us to capture more
information about roads from our data sources. For example, we’ve been able
to move more than 30 million “unknown” road segments from OSM into the new subclasses, laying the groundwork
for richer and more detailed map displays with Overture data.

Here's how class, subclasses, and flags are modeled in the [Overture schema](https://github.com/OvertureMaps/schema/blob/main/schema/transportation/segment.yaml):

```yaml
class: footway
subclass_rules:
  - value: sidewalk
    between: [0, 0.6]
  - value: crosswalk
    between: [0.6, 1.0]
road_flags:
  - values: [is_bridge]
    between: [0.2, 0.3]
  - values: [is_under_construction]
    between: [0.3, 0.5]

class: service
subclass_rules:
  - value: driveway
    between: [0, 0.5]

class: primary
subclass: link
subclass_rules:
  - value: link
```

### Connectors
To better support routing use cases, we added to the segment feature type [a new property](https://github.com/OvertureMaps/schema/pull/257) called
`connectors`: an array of IDs with pre-computed linear reference values that explicitly link segments and
[connector features](https://docs.overturemaps.org/schema/reference/transportation/connector/) via coordinates. The `connectors` property contains a list of connector features to which a segment feature is physically connected and the relative location of those connector features along the segment. Each connector is a possible routing decision point, meaning it defines a place along the segment in which there is possibility to transition to other segments that share the same connector.

This new property &mdash; a replacement for the existing `connector_ids`
property &mdash; will reduce complexity and improve accuracy as we calculate the intersections between segment and connector features. We plan to deprecate the `connector_ids` property in the August release and remove it from the schema in the October release.

Here are examples from the Overture schema comparing the new and deprecated features:
<Tabs>
<TabItem value="connectors" label="new connectors property" default>
```yaml
id: overture:transportation:segment:123
type: Feature
geometry:
  type: LineString
  coordinates: [[0, 0], [0.03, 0], [0.10, 0]]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: secondary
  connectors:
    - connector_id: fooConnector
      at: 0
    - connector_id: barConnector
      at: 0.3
    - connector_id: bazConnector
      at: 1
  road_surface:
    - value: paved
```
</TabItem>
<TabItem value="connector_ids" label="deprecated connector_ids property" default>
```yaml
id: overture:transportation:segment:123
type: Feature
geometry:
  type: LineString
  coordinates: [[0, 0], [0.03, 0], [0.10, 0]]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: secondary
  connector_ids: [fooConnector, barConnector, bazConnector]
  road_surface:
    - value: paved
```
</TabItem>
</Tabs>

### Destinations

| ![Highway signs](/img/blog/highway-signs.png) |
|:--:|
| *Highway signs help us get from point A to Green Bay* |

Also in support of routing use cases, we [added a `destinations` property](https://github.com/OvertureMaps/schema/pull/176) to the segment feature type.
This property describes the transitions from one segment to another on the way to a specified location.
In turn-by-turn routing applications, this is what is known as “follow signs for” &mdash; the human-readable
directions and signposts along a road, highway, or interstate that get us from point A to point Z, by way
of any number of paths in between. We designed `destinations` with a flexible schema that will allow us to
capture and model navigation data from many different sources.

Here's an example of how highway sign information in the picture above is modeled in the `destinations` schema:

```yaml
destinations:
  - when:
    heading: forward
    from_connector_id: 08f274370d59a8840436ff3bad31c60e
    to_connector_id: 08f274370d59a8840436ff3bad31c60e
    to_segment_id: 08a274370d59ffff043fff3b802d7aa5
    final_heading: forward
    labels:
     - value: Green Bay
      type: unknown
     - value: I 43 North
      type: route_ref
    symbols:
     - NULL
```

## Transportation splitter tool
Recently we made our [transportation splitter tool](https://github.com/OvertureMaps/transportation-splitter)
available in a public GitHub repository. The tool is an experimental PySpark script and Jupyter notebook that offers
multiple ways to split Overture’s transportation features into smaller and simpler segments. Our new transportation guide includes [several examples of how to use it](https://docs.overturemaps.org/guides/transportation/#transportation-splitter). Please
take it for a test drive and [let us know](https://github.com/OvertureMaps/transportation-splitter/issues) what you think!

---

## What to expect in Overture's October release

This week Overture is [releasing](https://docs.overturemaps.org/release/latest/) datasets that include new
addresses across ten countries, new road features in Saudi Arabia and Italy from TomTom,
and new building height data from Microsoft and Esri Community Maps contributors. Here's a preview of what you'll find in our October release.

## Addresses around the world

| ![H3 cells addresses](/img/blog/address-coverage-h3-october.png) |
| :--------------------------------------------------------------: |
|             _H3 coverage map of Overture addresses_              |

{/*truncate*/}

In July, Overture [launched](https://docs.overturemaps.org/release/2024-07-22.0/#new-theme-addresses) our addresses theme
with 200 million features in 14 countries. Since then,
we’ve added data for ten additional countries, bringing the total feature count to over 344 million.
We’re building on great work by the open data community, including folks on the [OpenAddresses](https://openaddresses.io/)
and [AddressForAll](https://www.addressforall.org/en/) projects.

And now we're excited to include another new source of open data for addresses in the U.S. Previously, Overture pulled all address data
in the United States from the [Department of Transportation’s National
Address Database (NAD)](https://www.transportation.gov/gis/national-address-database).
Over the September and October releases, we developed a cut-and-replace workflow to swap NAD data in New York City
with data from [NYC Open Data](https://opendata.cityofnewyork.us/). Local data FTW! This is a process
we will continue to refine so that we can more
easily fold in new data across all [Overture themes](https://docs.overturemaps.org/guides/).

## Roads and building heights

| ![TomTom roads](/img/blog/roads-tomtom-october.png) |
| :-------------------------------------------------: |
|    _Roads from TomTom in Italy and Saudi Arabia_    |

Also in the October release, you’ll find new data from [TomTom](https://www.tomtom.com/), representing more than 30,000 kilometers of roads in Saudi Arabia
and Italy. We also added new building height data from both Microsoft and [Esri Community Maps contributors](https://communitymaps.arcgis.com/home/).
These updates highlight Overture’s goal to improve data quality and coverage by incorporating new data into each release,
with a focus on [data sources](https://docs.overturemaps.org/attribution/) that have permissive open-source licenses.

Please [reach out to us on GitHub](https://github.com/OvertureMaps/data/discussions) with questions and feedback about our data.
If you have a suggestion for a new dataset or if you have data you'd like to contribute, you can email us at **data AT overturemaps.org**. We’d love to hear from you.

---

## Transportation theme navigates to GA

Over the past several releases, Overture has been laying the groundwork to transition our transportation theme from beta to general availability (GA). This post provides a brief roadmap of the work we’ve done to reach that goal, along with a request for our community to continue testing the data and providing valuable feedback.

{/* truncate */}

First, let’s talk about what GA means for the transportation theme. We have a few guiding principles:

1. There are no "trust violations" in the schema and data. It needs to "just work" when a developer writes code based on our schema and documentation.
2. The road geometry and attributes should be on par with the roads in OSM.
3. Roads have stable GERS IDs and those IDs can be references for attaching additional data.
4. The road features we capture should support our core use cases: rendering for display, GERS referencing, and basic routing capabilities.

Most of our work over the past few months has been around #1 and #2. We've been resolving data-schema violations by fixing inconsistencies in our schema and issues with the data transformation steps in our pipeline. To satisfy #3, we’ve been monitoring changes in GERS IDs from release to release, and our metrics show the vast majority of roads are maintaining stable IDs.

We've had to break a few things in our schema to make way for improvements:

- To better support routing use cases, we added to the segment feature type a new property called `connectors`: an array of IDs with pre-computed linear reference values that explicitly link segments and connector features via coordinates. Each connector is a possible routing decision point, meaning it defines a place along the segment in which there is possibility to transition to other segments that share the same connector. This new property — a replacement for the old `connector_ids` property — will reduce complexity and improve accuracy as we calculate the intersections between segment and connector features. You can read more about this improvement [here](https://docs.overturemaps.org/blog/2024/08/15/preview-august-release/#transportation-schema-changes).

- In the [November release](https://docs.overturemaps.org/release/2024-11-13.0/), we removed `lanes` from the schema to eliminate a significant trust violation. The `lanes` property has existed in the schema for months but we never populated it with data in our releases, which is a poor experience for our community. We intend to redesign `lanes` in the coming months.

With these changes, we are confident we’ve met our requirements for general availability (GA). We'll continue refining our schema and improving our data throughout 2025. We encourage our community to keep the feedback coming, particularly around data quality and our core use cases of map display, routing, and matching data via GERS.

Here are some specific ways you can help:

1. Examine Overture transportation data in your areas of interest and compare it to local sources of data. Bonus: combine transportation data with Overture places, buildings, and base data to make a map. Here are some suggestions for downloading data using [Overture's Python CLI](https://docs.overturemaps.org/getting-data/overturemaps-py/).

Philadelphia area

```
overturemaps download --bbox=-75.8264,39.7032,-74.5213,40.444 -f geoparquet --type=segment -o overture-segments-philadelphia.geoparquet
```

Riyadh Province, Saudia Arabia

```
overturemaps download --bbox=38.97,21.33,48.66,25.98 -f geoparquet --type=segment -o overture-segments-riyadh.geoparquet
```

Campobasso, Italy

```
overturemaps download --bbox=13.8152,40.8473,15.6336,42.0773 -f geoparquet --type=segment -o overture-segments-campobasso.geoparquet
```

2. Test our [transportation spitter tool](https://github.com/OvertureMaps/transportation-splitter) and help us improve it. PRs are welcome!

3. Feed our data into a routing engine and let us know how it goes. Paul Ramsey from Crunchy Data shared [a vehicle routing example using PostGIS and Overture data](https://www.crunchydata.com/blog/vehicle-routing-with-postgis-and-overture-data). We'd like to see our users trying [Valhalla](https://valhalla.github.io/valhalla/) and [Graphhopper](https://github.com/graphhopper/graphhopper-maps) too. We are considering building a native Overture router and/or adding support to an existing open source router, such as Valhalla and Grasshopper, so that Overture consumers can easily use transportation data out of the box.

4. Reach out to us at community@overturemaps.org if you have a specific use case that you'd like to discuss with us.

---

## 2024-01-17-alpha.0 release notes

### Highlights
Overture `2024-01-17-alpha.0` is now available. This release includes several incremental improvements, addition of geopolitical boundary information in the Admins Theme and expansion of GERS IDs across several themes. More information about these additions is available in the relevant sections below.

{/* truncate */}

This data is formatted in the Overture Data Schema unless otherwise noted.

This data is available for use under the designated licenses for each theme.

We would like feedback on the data, its usefulness, and how it could be improved. Please use this Github repo for discussions and feedback related to this data release.

Overture `2024-01-17-alpha.0` is available in GeoParquet and stored on AWS and Azure.

### Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases/tag/v0.8.0) here.

### Theme-specific updates
Overture `2024-01-17-alpha.0` is released in five themes.

**Buildings Theme**
The dataset includes 2.35B conflated building footprints from OSM, Esri Community Maps, Microsoft ML Building Footprints, and Google Open Buildings.
The order of conflation is OpenStreetMap → Esri Community Maps → high precision Google Open Buildings → Microsoft ML Building Footprints → lower precision Google Open Buildings. For example, if Esri has a building that does not exist in OSM, we take that building, then we “fill-in” the rest of the map with any ML buildings that do not intersect with either OSM or Esri.
We use the 90% precision confidence threshold to delineate between high and lower precision for Google Open Buildings, this threshold varies per s2 cell.

We've made incremental improvements to further ensure the data conforms to the buildings layer schema.

3d attributes from OSM, such as roof shape, are now available.

The sources of the buildings theme include OpenStreetMap, Esri Community Maps, Microsoft Building footprints, and Google Open Buildings. Some building heights have also been derived using lidar from USGS 3DEP.

Data in the Buildings theme is licensed under ODbL.

**Transportation Theme**
Refreshed data to include OSM data up to Dec 19

:::note
GERS IDs for connectors and segments should now be considered stable for future releases
:::

Data in the Transportation theme is licensed under ODbL.

**Base Theme**
All of the features in the base theme are from OpenStreetMap, sourced via the latest Daylight Map Distribution (v1.38).

Includes 43M water features, 63M land features, and 44M land use features.

Most original OSM tags remain on all features. Some tags become normalized and added as top-level properties, such as the surface or wikidata tags.

Data in the Base theme is licensed under ODbL.

**Places Theme**
This release has over 57M place records.

The Places theme in this release includes incremental improvements to improve the accuracy and quality of the dataset.

Data in the Places theme is licensed under CDLA Permissive 2.0.

**Administrative Boundaries (Admins) Theme**
Minor improvements on second-level subdivision of countries.
Data from OSM is updated to 15th of January.

This is first release with "geopolDisplay" property set on boundaries.

Known issues:
- Second-level subdivision are still not complete world-wide, as we search for data sources that are compatible with ODbL.
- All first-level subdivisions have type=state and all second-level subdivisions have type=county which is not always true, we plan to address this issue in following release.
- We plan to use admin_level=8,9,10 to add polygons to cities, towns, villages and other localities when available depending on individual country mapping.

The sources of the admin theme are OpenStreetMap and Esri. The Administrative Boundary data is in the Overture Maps data schema for Admin.

Data in the Admin theme is licensed under ODbL.

### Attribution
- © OpenStreetMap contributors available under the Open Database License (www.openstreetmap.org/copyright)
- U.S. Geological Survey, 2019, USGS 3D Elevation Program Digital Elevation Program
- Building data © OpenStreetMap contributors, Microsoft, Esri Community Maps contributors, Google Open Buildings

---

## 2024-02-15-alpha.0 release notes

### Highlights
Overture `2024-02-15-alpha.0` is now available. This release includes several incremental improvements, addition of geopolitical boundary information in the Admins Theme and expansion of GERS IDs across several themes. More information about these additions is available in the relevant sections below.

{/* truncate */}

This data is formatted in the Overture Data Schema unless otherwise noted.

This data is available for use under the designated licenses for each theme.

We would like feedback on the data, its usefulness, and how it could be improved. Please use this Github repo for discussions and feedback related to this data release.

Overture `2024-02-15-alpha.0` is available in GeoParquet and stored on AWS and Azure.

### Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases/tag/v0.8.0) here.

### Theme-specific updates
Overture `2024-02-15-alpha.0` is released in five themes.

**Buildings Theme**
The dataset includes 2.35B conflated building footprints from OSM, Esri Community Maps, Microsoft ML Building Footprints, and Google Open Buildings.
The order of conflation is OpenStreetMap → Esri Community Maps → high precision Google Open Buildings → Microsoft ML Building Footprints → lower precision Google Open Buildings. For example, if Esri has a building that does not exist in OSM, we take that building, then we “fill-in” the rest of the map with any ML buildings that do not intersect with either OSM or Esri.
We use the 90% precision confidence threshold to delineate between high and lower precision for Google Open Buildings, this threshold varies per s2 cell.

We've made incremental improvements to further ensure the data conforms to the buildings layer schema.

3d attributes from OSM, such as roof shape, are now available.

The sources of the buildings theme include OpenStreetMap, Esri Community Maps, Microsoft Building footprints, and Google Open Buildings. Some building heights have also been derived using lidar from USGS 3DEP.

Data in the Buildings theme is licensed under ODbL.

**Transportation Theme**
- Refreshed data to include OSM data up to Feb 5
- Segment names are now a top-level property with a unified schema
- Access restrictions are now populated for most simple cases
- OSM source IDs are now included for all segments

:::note
GERS IDs for connectors and segments should now be considered stable for this and future releases
:::

Data in the Transportation theme is licensed under ODbL.

**Base Theme**
- All of the features in the base theme are from OpenStreetMap, sourced via the latest Daylight Map Distribution (v1.40).
- Includes 44M water features, 63M land features, and 34M land use features.
Most original OSM tags remain on all features. Some tags become normalized and added as top-level properties, such as the surface or wikidata tags.

Data in the Base theme is licensed under ODbL.

**Places Theme**
This release has roughly 54M place records. The Places theme in this release includes incremental improvements to improve the accuracy and quality of the dataset.

:::note
For the first time, this release includes GERS stableids propagated from the previous release. Roughly 50M of the ids are propagated and 4M of the ids are new.
:::

Data in the Places theme is licensed under CDLA Permissive 2.0.

**Administrative Boundaries (Admins) Theme**
- First version where all countries have second-level subdivisions.
- In 37 countries we used geoBoundaries as data source for second-level subdivisions where OpenStreetMap data is missing or is incomplete.
- Data from OSM is updated to 8th of February.
- `AdminLevel` property value changed from 2 for Country, 4 for State and 6 for County to be 1 for Country, 2 for State and 3 for County.
- Added Wikidata and Population properties.
- All administrative localities now have `isoCountryCodeAlpha2` set for easier filtering to specific country.

:::note
Known issue: All first-level subdivisions have type=state and all second-level subdivisions have type=county which is not always true, we plan to address this issue in following release. Will be fixed in March release.
:::

The sources of the admin theme are OpenStreetMap, geoBoundaries and Esri.

The Administrative Boundary data is in the Overture Maps data schema for Admin.

Data in the Admin theme is licensed under ODbL.

**Documentation**
Updated schema, reference and GERS technical documentation.
Integrated https://labs.overturemaps.org/how-to/ with core documentation.
Added new guides and tutorials for accessing, exploring  and visualizing data.

### Attribution
- © OpenStreetMap contributors available under the Open Database License (www.openstreetmap.org/copyright)
- U.S. Geological Survey, 2019, USGS 3D Elevation Program Digital Elevation Program
- Building data © OpenStreetMap contributors, Microsoft, Esri Community Maps contributors, Google Open Buildings
- Administrative Boundaries from geoBoundaries.

---

## 2024-03-12-alpha.0 release notes

### Highlights
Here are the highlights of what's new and updated in Overture's `2024-03-12-alpha.0` release. This release includes a schema change from `camelCase` to `snake_case` for all property names and enumeration member names, an expansion of stable GERS IDs and incremental updates to the schema and datasets.

{/* truncate */}

### Breaking changes
We changed `camelCase` to `snake_case` in the schema for properties to be more compatible with some SQL engines. This may break existing code and queries:

In previous releases of Overture data, we used `camelCase` for attribute names throughout the schema. A duckdb query to find Pennsylvania in our admins dataset might have looked like this:

```sql
LOAD spatial;
LOAD httpfs:

SELECT
   id,
   isoSubCountryCode,
   contextId,
   names.primary,
   ST_GeomFromWKB(geometry) as geometry
FROM
   read_parquet('s3://overturemaps-us-west-2/release/2024-02-15-alpha.0/theme=admins/type=*/*', filename=true, hive_partitioning=1)
WHERE type='locality'
   AND subType='administrativeLocality'
   AND adminLevel=2
   AND names.primary LIKE 'Pennsylvania';
```

In the March release, we changed all property names and enumeration member names to `snake_case`. This is a big one-time churn to improve SQL compatibility. That same query to find Pennsylvania now looks like this:

```sql
LOAD spatial;
LOAD httpfs:

SELECT
   id,
   iso_sub_country_code,
   context_id,
   names.primary,
   ST_GeomFromWKB(geometry) as geometry
FROM
   read_parquet('s3://overturemaps-us-west-2/release/2024-03-12-alpha.0/theme=admins/type=*/*', filename=true, hive_partitioning=1)
WHERE type='locality'
   AND subtype='administrative_locality'
   AND admin_level=2
   AND names.primary LIKE 'Pennsylvania';
```
```
┌──────────────────────────────────┬──────────────────────┬──────────────────────────────────┬──────────────┬────────────────────────────────┐
│                id                │ iso_sub_country_code │            context_id            │   primary    │            geometry            │
│             varchar              │       varchar        │             varchar              │   varchar    │            geometry            │
├──────────────────────────────────┼──────────────────────┼──────────────────────────────────┼──────────────┼────────────────────────────────┤
│ 0857b2b73fffffff01914c596abbfacd │ US-PA                │ 0850c861bfffffff01aeb407d56d3441 │ Pennsylvania │ POINT (-77.7278831 40.9699889) │
└──────────────────────────────────┴──────────────────────┴──────────────────────────────────┴──────────────┴────────────────────────────────┘
```

### Deprecations
In the April 2024 release, Overture will implement a refactor of the `Admins` theme called `Divisions`. Admins and Divisions will coexist for three releases, at which point Divisions will fully replace Admins. More information on this change [here](https://github.com/OvertureMaps/schema/discussions/117).

### Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases/tag/v0.9.0) here.

### Theme-specific updates

**Transportation**
- Refreshed to include OSM data up to 2024-03-03.
- Added ferry and alley segments.
- Included 125K previously unsupported turn restrictions.
- Added support for max weight, height, width and length access restrictions.
- Added one-way road access restrictions.
- Added road widths property to segments.
- Acheived stability of GERS IDs for connectors and segments for this and future releases.
- Note: data in the transportation theme is licensed under ODbL.

**Administrative Boundaries (Admins)**
- Refreshed to include OSM data up to 2024-03-07.
- Adapted schema to use `snake_case` to make attribute names more compatible with some SQL engines.
- Correctly set locality types.
- Made minor fixes:
     - All country localities now have ISO codes.
     - All non-country localities now have context property set.
- Note: data in the Admin theme is licensed under ODbL.

**Places**
- Achieved roughly 54 million place records.
- Propagated stable GERS IDs from the previous release.
- Made incremental improvements to accuracy and data quality.
- Note: data in the Places theme is licensed under CDLA Permissive 2.0.

**Buildings**
- Exposed the logic Overture uses to transform OSM tags into building attributes.
- Made incremental improvements to further ensure the data conforms to the buildings schema.
- Note: data in the Buildings theme is licensed under ODbL.

**Base**
- Exposed the logic Overture uses to transform OSM tags into attributes in the land use, land and water data types.
- Made incremental improvements to further ensure the data conforms to the base schema.
- Note: data in the Base theme is licensed under ODbL.

### Attribution
The data sources for each theme are cited [here](//attribution).

---

## 2024-04-16-beta.0 release notes

### Highlights
Here are the highlights for what's new and updated in the Overture Maps `2024-04-16-beta.0` release. The "beta" designation indicates the data and schema are largely stable.

Overture Maps `2024-04-16-beta.0` is available in GeoParquet and stored on AWS and Azure. Users can select the data of interest and download it by following the process outlined [here](https://docs.overturemaps.org/getting-data/).

We encourage developers wishing to adopt Overture Maps base layers to begin evaluating and providing [feedback on the data, schema, and GERS IDs](https://github.com/OvertureMaps/data/discussions). Depending on the feedback from this release and subsequent releases, we anticipate moving to a production release in the next few months.

{/* truncate */}

### Breaking changes
We renamed the `bbox` column fields to align with the upcoming [GeoParquet](https://geoparquet.org/) 1.1 spec.

```
minx → xmin
miny → ymin
maxx → xmax
maxy → ymax
```

The fields are all now [Parquet Float (32-bit)](https://parquet.apache.org/docs/file-format/types/) where as they had previously been distributed as Double (64-bit).

### Deprecations
In this release, we implemented a refactor of the `admins` theme called `divisions`. The `divisions` schema and data are [now available](/guides/divisions). The two themes will coexist for two subsequent releases (May 2024 and June 2024), at which point `divisions` will fully replace `admins`. More information on why we made this change [here](https://github.com/OvertureMaps/schema/discussions/117).

### Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases) here.

### Theme-specific updates
See [here](//attribution) for information about licensing and data attribution for each theme.

**Administrative Boundaries Admins/Divisions**
- Included OSM data up to 4/8.
- Implemented the schema for the `divisions` theme, which has a better defined schema supporting perspectives, different types of polygons, and other new features.
- Note: see information above about the deprecation of `admins`.

**Base**
- Included OSM data up to 3/16 (sourced via Daylight Map Distribution v1.44).
- Included 46M water features, 55M land features, 40M land use features, and 48M infrastructure features.
- Maintained the original OSM tags remain on all features.
- Normalized and added `elevation`, `surface`, and `wikidata` as top-level properties.

**Buildings**
- Included OSM data up to 3/16 (sourced via Daylight Map Distribution v1.44).
- Included 2.35B conflated building footprints from OSM, Esri Community Maps, Microsoft ML Building Footprints, and Google Open Buildings.
- Made incremental improvements to further ensure the data conforms to the buildings layer schema.
- Added 3d attributes from OSM, such as roof shape.
- Note: The order of conflation is OpenStreetMap → Esri Community Maps → high precision Google Open Buildings → Microsoft ML Building Footprints → lower precision Google Open Buildings. For example, if Esri has a building that does not exist in OSM, we take that building, then we “fill-in” the rest of the map with any ML buildings that do not intersect with either OSM or Esri. We use the 90% precision confidence threshold to delineate between high and lower precision for Google Open Buildings, this threshold varies per s2 cell.

**Places**
- Included ~53 million place records.
- Included stable GERS IDs propagated from the previous release; roughly 51 million of the IDs are propagated and 2 million are new.
- Made incremental changes to improve the accuracy and quality of the dataset.

**Transportation**
- Included OSM data up to 4/7.
- Classified 12.2M segments as path.
- Added `is_covered` flag to denote partially enclosed segments.
- Improved scope merging; fewer access restrictions entries are now required.
- Fixed a projection issue affecting segment length calculation and linear referencing
- Promoted `class` to a top-level property.
- Moved `level` property into `road` property to allow linear referencing. 84% of all segments which had previously dropped `level` will now have that information.
- Renamed `at` to `between` for ranged linear referencing.
- Removed `mode_not` scoping.

### Attribution
The data sources for each theme are cited [here](//attribution).

---

## 2024-05-16-beta.0 release notes

Here's what's new and updated in the Overture Maps `2024-05-16-beta.0` release. The "beta" designation indicates the data and schema are largely stable.

Overture Maps `2024-05-16-beta.0` is available in GeoParquet and stored on AWS and Azure. Users can select the data of interest and download it by following the process outlined [here](https://docs.overturemaps.org/getting-data/). We encourage developers wishing to adopt Overture Maps base layers to begin evaluating and providing [feedback on the data, schema, and GERS IDs](https://github.com/OvertureMaps/data/discussions). Depending on the feedback from this release and subsequent releases, we anticipate moving to a production release in the next few months.

{/* truncate */}

### Breaking changes

In the `buildings` theme, we promoted `class` to `subtype` and introduced new `class` values. This allows for more detail in a feature. Parking garages, for example, now have the attributes: `subtype=transportation` and `class=parking`.

### Deprecations
Last month, we announced the deprecation of our `admins` theme and launched its replacement, `divisions`. Because of issues with missing data in `divisions`, we have extended the life of `admins`. Here is the new deprecation schedule: the two themes will coexist in the May, June, and July 2024 releases; in the August 2024 release, we will fully remove `admins` from our schema and data. More information on why we made this change [here](https://github.com/OvertureMaps/schema/discussions/117).

### Schema Changelog
See our [changelog](https://github.com/OvertureMaps/schema/releases) here.

### Theme-specific updates

**Divisions/Admins**

- refreshed data with OpenStreetMap snap on 10 May 2024
- populated `region` field for `division_area` type
- populated `local_type` field `division` type
- known issue: the `capital_division_id` field in `division` type is missing data

:::warning
See information above about the deprecation of `admins` schema and data
:::

**Base**

- added `land_cover` schema and data derived from ESA WorldCover high-resolution Earth observation imagery
- added new subtypes in `infrastructure` type: `barrier`, `pedestrian`, `utility`, `waste_management`, `water`
- added `min_zoom` and `max_zoom` attributes for cartographic purposes

**Buildings**

- promoted `class` to `subtype` and introduced new class values for buildings. Where relevant, the class tag is the value of the building key in OSM. This allows anyone to use previous class types as subtype (backwards compatible) and introduces new class values that allow for more detail, like parking. Parking garages, for example, now have the attributes: `subtype=transportation`, `class=parking`; example of new subtypes, promoted from class: `agricultural`, `civic`, `commercial`, `education`, `entertainment`, `industrial`, `medical`, `military`, `outbuilding`, `religious`, `residential`, `service`, `transportation`
- made incremental updates from OSM since the previous release

**Places**

- made incremental changes to improve the accuracy and quality of the dataset

**Transportation**

- added missing vehicle travel mode
- added missing `is_covered` road flag
- populated `is_abandoned` flag when relevant abandoned or disused tags are present
- added OSM source ids for connectors
- fixed null linear referencing for names in some cases

### Attribution

You'll find information about attribution and licensing [here](https://docs.overturemaps.org/attribution/).

---

## 2024-06-13-beta.1 release notes

:::info

_24 June 2024_  

Today Overture released a patch to fix data issues in the June release. This hotfix addressed the following regressions:
- in the transportation theme, a bug in one of our automated processes inadvertently caused the conversion of unicode characters to ASCII. This affected roughly 10% of `segment` features that contained characters outside of the ASCII range, primarily names but possibly things like speed limit/weight restrictions if those properties contained values with characters outside that range.
- in the buildings theme, the `roof_height` property was not fully populated; the hotfix adds 143k `roof_height` values to the release. 

The new release paths are:
```
Azure path: wasbs://release@overturemapswestus2.blob.core.windows.net/2024-06-13-beta.1

AWS path: s3://overturemaps-us-west-2/release/2024-06-13-beta.1
```
:::

{/* truncate */}

Overture's `2024-06-13-beta.0` release is available in GeoParquet and stored on AWS and Azure. You can access the datasets by following the process outlined [here](https://docs.overturemaps.org/getting-data/). We encourage users to report bugs and provide feedback on the data, schema, and GERS via any publicly-available Overture Maps repository on GitHub: 

- [Schema](https://github.com/OvertureMaps/schema)
- [Data](https://github.com/OvertureMaps/data)
- [Docs](https://github.com/OvertureMaps/docs)
- [Python command-line tool](https://github.com/OvertureMaps/overturemaps-py)
- [Explore site](https://github.com/OvertureMaps/io-site)

Depending on feedback, we anticipate moving to a general availability (GA) release soon.

### New data: GERS changelog

You'll find in this release a new GERS changelog that captures feature changes from the previous release to the current release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and `change_type` &mdash; at the following locations:
```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2024-06-13-beta.0

s3://overturemaps-us-west-2/changelog/2024-06-13-beta.0
```
Valid values for the `change_type` include:
- added: Overture ID is new and was not in the previous release
- removed: Overture ID is not in the current release and was in the previous release
- data_changed: Overture ID is in the current release and was in the previous release and the feature's attributes or geometry have changed
- unchanged: Overture ID is in the current release and was in the previous release, and the feature's attributes and geometry have not changed 

### Breaking changes

In response to feedback from developers and data analysts in the Overture ecosystem, we simplified ("flattened") the structure of our road data to make it easier to query road attributes. To make this transition easier for users, we included the now deprecated road JSON column in this release. We will remove the road JSON column in the next release. 

<details>
        <summary>Breaking change in structure of road data</summary>
        

| old JSON path	| new Parquet column | 
| ------------- | ------------------ |
| road.restrictions.speed_limits |	speed_limits |
| road.restrictions.access	| access_restrictions |
| road.restrictions.prohibited_transitions | prohibited_transitions |
| road.surface | road_surface |
| road.flags | road_flags |
| road.width | width_rules |
| road.lanes | lanes |
| road.level | level_rules |

</details>

Also in this release, we simplified the non-geometry vehicle scoping block.

<details>
        <summary>Breaking change in structure of vehicle scoping block</summary>
        
<Tabs>
<TabItem value="old speed_limits structure" label="old speed_limits structure" default>
```
speed_limits:
  when:
    ...
    vehicle:
      axle_count:
        is_more_than:
          value:
          unit:
        is_less_than:
          ...
        ...
        ...
      height:
        ...
      length:
        ...
      weight:
        ...
      width:
        ...
```
</TabItem>
<TabItem value="new speed_limits structure" label="new speed_limits structure" default>

```
speed_limits:
  when:
    ...
    vehicle:
      - dimension: <axle_count, height, length, weight, width>
        comparison: <greater_than, greater_than_equal, equal, less_than, less_than_equal>
        value: str
        unit: str
```
</TabItem>

</Tabs>

</details>

### Deprecations

In the transportation theme, we deprecated the road JSON column and will remove it in the next release. We replaced the road JSON column with structured Parquet columns for road attributes.

We deprecated the admins theme and replaced it with the divisions theme. This will be the last supported release for the admins schema and data. In the next release, admins will be available in an archive but not supported. 

### Schema changelog

See our schema [changelog](https://github.com/OvertureMaps/schema/releases) here.

### Theme-specific updates

**Divisions/Admins**

- added support for MultiLineString geometries to improve the stability of Overture IDs for boundary features
- extended the schema to support multiple capitals of a division
- added the option to include or exclude boundaries based on perspectives
- updated OpenStreetMap data to 2024.06.05
- changed modeling of municipalities/cities in Brazil from counties to localities, which we believe better reflects ground truth
- made improvements to the names data and fixed several bugs 

**Base**

- added the `surface` attribute to infrastructure and land feature types
- made incremental updates from OSM, based on Daylight v1.48
- added to the land_cover feature type a new cartographic property `cartography.sort_key`: an ascending number signifying the importance of a feature in relation to other features. 

**Buildings**

- made regular updates to buildings, including adding the latest open data from OSM, Esri Community Maps, and Microsoft 
- expanded the previous definition of class for buildings to include specific amenity tags that are either already an official Overture place category or can be matched to one

**Places**

- began a comprehensive audit of data quality
- worked on calibrating confidence values

**Transportation**

:::warning
- Breaking change: transformed road properties from JSON to structured Parquet columns
- Breaking change: restructured vehicle constraint property
:::
- updated speed limit min/max values 
- added 19K previously filtered segments which contained self-intersecting lines that are still OGC-valid
- fixed OSM source ids for connectors
- known issue: in `road_flags` a value of 0 or 1 on the linear referencing between property can be null in some cases

### Attribution

You'll find information about attribution and licensing [here](https://docs.overturemaps.org/attribution/).

---

## 2025-01-22 release notes

## Overview

**The `2025-01-22.0` release of Overture data and `v1.5.0` of the Overture schema are now available.** 

The datasets are available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2025-01-22.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2025-01-22.0
```

{/* truncate */}

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions, report bugs, and provide feedback via our [data](https://github.com/OvertureMaps/data) and [schema](https://github.com/OvertureMaps/schema) repositories on GitHub. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## Breaking changes

None. 

## Deprecations

None.

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses
- added five new data sources in Taiwan
- made minor fixes and updates

### Base
- made minor fixes and updates

### Buildings
- added 228.5M buildings from a [new ML-derived building dataset of East Asian countries](https://zenodo.org/records/8174931)
- made minor fixes and updates

### Divisions
- new cartography column in the schema that has not yet been populated with data
- added `is_land` and `is_territorial` properties to `division_area` and `division_boundary` feature types
- refreshed data on 17 January 2025

### Places
A statement from the Places engineering team: _“The places data has remained unchanged since the September 2024 release while we work on substantial pipeline upgrades. We anticipate releasing a new dataset in the coming months.”_

### Transportation
- added approximately 4000km of new TomTom-sourced roads in the US
- refreshed data on 18 December 2024
  
## Global Entity Reference System (GERS) changelog

The GERS changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2025-01-22.0
```
```
s3://overturemaps-us-west-2/changelog/2025-01-22.0
```

You can find more information about [the GERS Changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog
The changelog for Overture schema `v1.5.0` is [here](https://github.com/OvertureMaps/schema/releases). 

## Attribution  

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-02-19 release notes

## Overview

**The `2025-02-19.0` release of Overture data and `v1.6.0` of the Overture schema are now available.** 

The datasets are available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2025-02-19.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2025-02-19.0
```

{/* truncate */}

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussions forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## Breaking changes

None. 

## Deprecations

None.

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses
- added new data in the following US counties:
	- Hillsbough County, FL
	- Manatee County, FL
	- Dekalb County, GA
	- Oakland County, MI
- added new data in Yukon Territory, Canada
- updated the NAD source to v18
- removed erroneous address data in BE

### Base
- minor data fixes and updates
- refreshed data with 15 February 2025 OSM update

### Buildings
- fixed geometries from the Zenodo dataset
- refreshed data with 5 February 2025 OSM update 

### Divisions
- added county boundaries in Colombia and Uruguay
- added ~12k new division_boundary features
- refreshed data with January 2025 GeoBoundaries update
- migrated pipeline to Apache Spark implementation which resulted in improved names, capitals and parenting properties

### Places
- released the first data update since September 2024, from a new and re-worked places conflation pipeline within Overture. This should result in more stable places releases moving forward
- added new places data, resulting in a ~12% increase in the total number of places
- removed a small number of places without a primary name or primary category

### Transportation
- added ~40000km of new TomTom-sourced roads in France, Germany, Italy, Jordan, Kuwait, Mexico, Monaco, Saudi Arabia, Switzerland, United Arab Emirates, United Kingdom, United States, and Yemen
- refreshed data with 5 February 2025 OSM update 
  
## Global Entity Reference System (GERS) changelog

The GERS changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2025-02-19.0
```
```
s3://overturemaps-us-west-2/changelog/2025-02-19.0
```

You can find more information about [the GERS Changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog
The changelog for Overture schema `v1.6.0` is [here](https://github.com/OvertureMaps/schema/releases). 

## Attribution  

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-03-19 release notes

:::info

March 20, 2025

Today Overture released a patch for the March data. There was an issue with a data pipeline process that caused `theme` and `type` columns to show up in some of the Parquet files. This issue likely had minimal, if any, impact on users.

The new release paths are:

#### Amazon S3 
```
s3://overturemaps-us-west-2/release/2025-03-19.1
```

#### Microsoft Azure 
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2025-03-19.1
```

:::

{/* truncate */}

## Overview

**The `2025-03-19.0` release of Overture data and `v1.7.0` of the Overture schema are now available.** 

The datasets are available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2025-03-19.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2025-03-19.0
```

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussions forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## Breaking changes

None.

## Deprecations

None.

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- added new data sources for all California counties, aside from Sierra County
- added new county-level and state-level data sources in Florida
	- coverage now includes all but four counties
- added a new data source for Hong Kong
- added a new data source in Oregon

| theme | type | change type | feature count |
| -------- | -------- | ------- | ------- |
| addresses | address | added | 428,821,683 |
| addresses | address | removed | 407,936,328 |

### Base

- minor data fixes and updates

| theme | type | change type | feature count |
| -------- | -------- | ------- | ------- |
| base | bathymetry | unchanged | 60,060 |
| base | infrastructure | added | 715,297 |
| base | infrastructure | data_changed | 326,313 |
| base | infrastructure | removed | 65,623 |
| base | infrastructure | unchanged | 118,573,035 |
| base | land | added | 355,006 |
| base | land | data_changed | 145,877 |
| base | land | removed | 34,300 |
| base | land | unchanged | 63,364,140 |
| base | land_cover | unchanged | 123,302,114 |
| base | land_use | added | 218,946 |
| base | land_use | data_changed | 663,489 |
| base | land_use | removed | 41,562 |
| base | land_use | unchanged | 47,065,761 |
| base | water | added | 603,639 |
| base | water | data_changed | 58,313 |
| base | water | removed | 31,885 |
| base | water | unchanged | 54,706,153 |

### Buildings

- added ~13M new buildings from [Instituto Geográfico Nacional, Spain](https://www.ign.es)

| theme | type | change type | feature count |
| -------- | -------- | ------- | ------- |
| buildings | building | added | 20,895,759 |
| buildings | building | data_changed | 10,104,299 |
| buildings | building | removed | 9,188,886 |
| buildings | building | unchanged | 2,598,324,355 |
| buildings | building_part | added | 32,568 |
| buildings | building_part | data_changed | 56,729 |
| buildings | building_part | removed | 3,101 |
| buildings | building_part | unchanged | 3,136,373 |

### Divisions

- corrected format of OSM source ids, which now include the @version format, as seen in other themes
- removed an incorrect Argentina perspective field value
- the `local_type` value is set on regions in the US and India
- all division boundary GERS IDs have changed since the February release

| theme | type | change type | feature count |
| -------- | -------- | ------- | ------- |
| divisions | division | added | 40,462 |
| divisions | division | data_changed | 621,942 |
| divisions | division | removed | 33,684 |
| divisions | division | unchanged | 3,699,466 |
| divisions | division_area | added | 26,620 |
| divisions | division_area | data_changed | 46,748 |
| divisions | division_area | removed | 23,266 |
| divisions | division_area | unchanged | 945,111 |
| divisions | division_boundary | added | 86,684 |
| divisions | division_boundary | data_changed | 2 |
| divisions | division_boundary | removed | 86,756 |
| divisions | division_boundary | unchanged | 27 |

### Places

- minor data fixes and updates

| theme | type | change type | feature count |
| -------- | -------- | ------- | ------- |
| places | place | added | 17,185,352 |
| places | place | data_changed | 16,596,848 |
| places | place | removed | 12,857,805 |
| places | place | unchanged | 32,815,899 |

### Transportation

- added an [is_indoor road flag](https://github.com/OvertureMaps/schema/pull/327#event-16716730346) to the schema
- re-included 88,005 segments flagged as ‘indoor’, which had previously been filtered out

| theme | type | change type | feature count |
| -------- | -------- | ------- | ------- |
| transportation | connector | added | 1,774,872 |
| transportation | connector | data_changed | 815,586 |
| transportation | connector | removed | 311,378 |
| transportation | connector | unchanged | 370,644,827 |
| transportation | segment | added | 1,698,190 |
| transportation | segment | data_changed | 4,171,164 |
| transportation | segment | removed | 635,288 |
| transportation | segment | unchanged | 314,306,310 |

  
## Data changelog

The data changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2025-03-19.0
```
```
s3://overturemaps-us-west-2/changelog/2025-03-19.0
```

You can find more information about [the data changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog
The changelog for Overture schema `v1.7.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.7.0). 

## Attribution  

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-04-23 release notes

## Overview

**The `2025-04-23.0` release of Overture data and `v1.8.0` of the Overture schema are now available.** This month we fixed several data issues and made small schema changes, notably to the `divisions` theme, where we added `country` and `region` properties to the `division_boundary` feature type and populated the `local_type` property with set values.

The datasets are available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2025-04-23.0
```

#### Amazon S3:
```
s3://overturemaps-us-west-2/release/2025-04-23.0
```
{/* truncate */}

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussions forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## Breaking changes

none

## Deprecations

none

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

#### Data changes

- fixed overlapping datasets in two Florida counties
- added data for Lee and Marion counties in Florida

### Base

#### Data changes

- added golf course data from OpenStreetMap
- explicitly specified the data type of the `class` property for `water` features as `string` (very minor schema change)

### Buildings

#### Data changes

- made minor data fixes and updates

#### Stats

| feature type | change type | feature count |
| ---------- | ---------- | ---------- |
| building | added | 5,409,438 |
| building | data_changed | 2,608,368,718 |
| building | removed | 20,955,173 |
| building | unchanged | 522 |
| building_part | added | 16,060 |
| building_part | data_changed | 3,181,177 |
| building_part | removed | 2,343 |
| building_part | unchanged | 42,150 |

### Divisions

#### Data changes

- added `country` and `region` properties to `division_boundary` (minor schema change)
- calculated `cartography.prominence` values for `subtype=locality`
- populated `local_type` with set values; the default value is the same as `subtype`

#### Stats

| feature type | change type | feature count |
| ---------- | ---------- | ---------- |
| division | added | 19,641 |
| division | data_changed | 3,648,319 |
| division | removed | 11,719 |
| division | unchanged | 701,832 |
| division_area | added | 6,647 |
| division_area | data_changed | 175,984 |
| division_area | removed | 9,247 |
| division_area | unchanged | 833,248 |
| division_boundary | added | 698 |
| division_boundary | data_changed | 86,105 |
| division_boundary | removed | 142 |
| division_boundary | unchanged | 466 |

### Places

#### Data changes

- made minor data fixes and updates

#### Stats

| feature type | change type | feature count |
| ---------- | ---------- | ---------- | 
| place | added | 7,461,890 |
| place | data_changed | 19,546,689 |
| place | removed | 8,015,519 |
| place | unchanged | 39,035,891 |

### Transportation

#### Data changes

- made minor data fixes and updates

#### Stats

| feature type | change type | feature count |
| ---------- | ---------- | ---------- |
| connector | added | 2,440,563 |
| connector | data_changed | 1,167,874 |
| connector | removed | 428,404 |
| connector | unchanged | 371,639,007 |
| segment | added | 2,220,972 |
| segment | data_changed | 5,306,151|
| segment | removed | 867,666 |
| segment | unchanged | 314,001,847 |

  
## Data changelog

The data changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2025-04-23.0
```
```
s3://overturemaps-us-west-2/changelog/2025-04-23.0
```

You can find more information about [the data changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog

The changelog for Overture schema `v1.8.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.8.0). 

## Attribution  

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-05-21 release notes

## Overview

**The `2025-05-21.0` release of Overture data and `v1.9.0` of the Overture schema are now available.** This month we added [PinMeTo](/attribution/#places) as a new data provider for `places`, improved the taxonomy of the `categories` property, added new data sources for `addresses`, and fixed bugs. Also in this release, we're introducing bridge files and announcing a major change to how we generate GERS IDs starting with the June release.

The datasets are available as GeoParquet files stored on both AWS and Azure. The release paths are:

#### Microsoft Azure:

```
wasbs://release@overturemapswestus2.blob.core.windows.net/2025-05-21.0
```

#### Amazon S3:

```
s3://overturemaps-us-west-2/release/2025-05-21.0
```

{/* truncate */}

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## What's new? Bridge files!

Overture is now releasing bridge files alongside our monthly data releases. Bridge files map GERS IDs to source data IDs, providing a mechanism to trace the origin of data in the Overture corpus, including data that doesn't appear in our published releases.

Overture's approach to conflation is to handle the complexity internally and deliver fully conflated, interoperable data products. We publish this conflated data every month but we haven't previously made our internal GERS ID matching available. Bridge files change this by sharing our conflation results, making it easier for you to understand data provenance and giving you an opportunity to be more provider-agnostic.

You can find the latest bridge files here, partitioned by dataset, theme, and type:

```
wasbs://bridgefiles@overturemapswestus2.blob.core.windows.net/2025-05-21.0
```

```
s3://overturemaps-us-west-2/bridgefiles/2025-05-21.0
```

## GERS IDs will become UUIDs in June

In next month's release (late June), Overture is standardizing the [`id` property](/schema/) across all themes by adopting [UUIDs](https://www.rfc-editor.org/rfc/rfc9562.html), stored as strings.

Currently the structure of our IDs varies slightly across datasets, with some themes embedding metadata (e.g. [H3](https://h3geo.org/)) in the `id` property. The new UUIDs will be randomly-generated identifiers with no encoded information. Moving to UUIDs enables consistent ID generation and registration across our data pipelines, which is necessary for the successful implementation of [GERS](/gers).

This is a **one-time** breaking change for our ID system. We plan to support our users by providing a file that maps the old IDs to the new UUIDs.

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha.
:::

### Addresses

- added new data sources for Waupaca County, WI and Sierra County, CA
- added a new data source for Italy that will replace the existing regional/municipal datasets

  
    
      
      
        <code>added</code>
      
      
        <code>data_changed</code>
      
      
        <code>removed</code>
      
      
        <code>unchanged</code>
      
    
  
  
    
      
        
          <code>address</code>
        
      
      446,766,672
      0
      429,683,781
      0
    
  

### Base

- improved coverage of state park, forest, and taxiline `class` values
- improved processing of `bathymetry` geometries

  
    
      
      
        <code>added</code>
      
      
        <code>data_changed</code>
      
      
        <code>removed</code>
      
      
        <code>unchanged</code>
      
    
  
  
    
      
        
          <code>bathymetry</code>
        
      
      0
      60,057
      0
      3
    
    
      
        
          <code>infrastructure</code>
        
      
      122,924,152
      0
      121,608,805
      0
    
    
      
        
          <code>land</code>
        
      
      65,191,767
      0
      64,726,006
      0
    
    
      
        
          <code>land_cover</code>
        
      
      0
      0
      0
      123,302,114
    
    
      
        
          <code>land_use</code>
        
      
      49,625,405
      0
      49,366,015
      0
    
    
      
        
          <code>water</code>
        
      
      57,802,549
      0
      56,753,269
      0
    
  

### Buildings

- fixed an issue with duplicate IDs on IGN Spain buildings
- added `names` property to the `building_part` type

  
    
      
      
        <code>added</code>
      
      
        <code>data_changed</code>
      
      
        <code>removed</code>
      
      
        <code>unchanged</code>
      
    
  
  
    
      
        
          <code>building</code>
        
      
      16,659,007
      10,851,887
      8,205,143
      2,594,721,648
    
    
      
        
          <code>building_part</code>
        
      
      86,713
      3,184,622
      8,949
      45,816
    
  

### Divisions

- generated the point geometries for the `division` type from OpenStreetMap nodes instead of using centroids calculated from of `division_area` polygons
- fixed a bug in `capital_of_divisions` ID assignments

  
    
      
      
        <code>added</code>
      
      
        <code>data_changed</code>
      
      
        <code>removed</code>
      
      
        <code>unchanged</code>
      
    
  
  
    
      
        
          <code>division</code>
        
      
      40,068
      263,440
      16,238
      4,090,114
    
    
      
        
          <code>division_area</code>
        
      
      19,582
      57,077
      11,716
      947,086
    
    
      
        
          <code>division_boundary</code>
        
      
      475
      2,895
      44
      84,330
    
  

### Places

- added [PinMeTo](/attribution/#places) as a new provider for places data
- improved the taxonomy of the `categories` property by fixing inconsistencies in the hierarchy
- made improvements to the data matching tools

  
    
      
      
        <code>added</code>
      
      
        <code>data_changed</code>
      
      
        <code>removed</code>
      
      
        <code>unchanged</code>
      
    
  
  
    
      
        
          <code>place</code>
        
      
      6,490,353
      18,049,066
      10,853,004
      37,142,400
    
  

### Transportation

- released the same data that was in the `2025-04-23.0` release; stats reflect changes from `2025-03-19.1` to `2025-04-23.0`

  
    
      
      
        <code>added</code>
      
      
        <code>data_changed</code>
      
      
        <code>removed</code>
      
      
        <code>unchanged</code>
      
    
  
  
    
      
        
          <code>segment</code>
        
      
      0
      1,592,251
      1
      319,936,718
    
    
      
        
          <code>connector</code>
        
      
      0
      0
      0
      375,247,444
    
  

## Data changelog

The data changelog captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
wasbs://changelog@overturemapswestus2.blob.core.windows.net/2025-05-21.0
```

```
s3://overturemaps-us-west-2/changelog/2025-05-21.0
```

You can find more information about [the data changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog

The changelog for Overture schema `v1.9.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.9.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## Using the GERS "system"

In the June release, we introduced new components of GERS, including a [new format for GERS IDs](https://github.com/orgs/OvertureMaps/discussions/390) and a [GERS Registry](https://docs.overturemaps.org/gers/registry/). In this blog post, we'll walk you through the GERS "system" and show you how to ask probing questions of the Overture datasets.

## Understanding GERS IDs
First, let's look at the new ID format for GERS. As of the June 2025 release, all GERS IDs are UUIDs: 128-bit, randomly-generated identifiers ([UUID v4](https://datatracker.ietf.org/doc/html/rfc4122)) that Overture keeps stable across data releases and updates. These IDs are stored as strings with dashes: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.

For this release only, we're providing Parquet files that map GERS IDs from the May release to the new GERS UUIDs in June release. These files are partitioned by `theme` and 'type' and can be accessed here: `s3://overturemaps-extras-us-west-2/june_to_may_id_mapping/`.

{/* truncate */}

## Exploring Overture data with GERS

 Let's start our exploration by examining how GERS IDs work in one Overture dataset. The [`divisions` theme](https://docs.overturemaps.org/guides/divisions/) contains administrative boundaries and points for global administrative areas. In this example, we'll use DuckDB to connect to Azure and read the Parquet files from Azure blob storage. You can also [access the files](https://docs.overturemaps.org/getting-data/) on Amazon S3.

```sql
CREATE TABLE slc AS (
    SELECT
        *
    FROM
        read_parquet('az://overturemapswestus2.blob.core.windows.net/release/2025-06-25.0/theme=divisions/type=division/*')
    WHERE
    -- ID for Salt Lake City, Utah
        id = 'c85948de-26de-4c4a-8479-1dac33fa8b04'
);
```

When we query that table, we can see the `divisions` hierarchy: Salt Lake City is a locality in Salt Lake County, which is in the region of Utah, within the country of the United States.

```sql
SELECT
    h.name,
    h.subtype,
    h.division_id
FROM
    slc
CROSS JOIN UNNEST(hierarchies[1]) AS t(h);
```
```
┌──────────────────┬──────────┬──────────────────────────────────────┐
│       name       │ subtype  │             division_id              │
│     varchar      │ varchar  │               varchar                │
├──────────────────┼──────────┼──────────────────────────────────────┤
│ United States    │ country  │ f39eb4af-5206-481b-b19e-bd784ded3f05 │
│ Utah             │ region   │ 506017c0-8932-44b5-b82c-92f9dcffdcf1 │
│ Salt Lake County │ county   │ 53d671bc-c294-44fb-a767-169bffedc5cb │
│ Salt Lake City   │ locality │ c85948de-26de-4c4a-8479-1dac33fa8b04 │
└──────────────────┴──────────┴──────────────────────────────────────┘

```

To retrieve the actual polygons for these entities, we can query the `division_area` type of the `divisions` theme, using `division_id` as the foreign key that links the datasets. _Note: This query will take a few minutes to run._

```sql
COPY(
    SELECT
        names.primary AS name,
        subtype,
        id,
        geometry
    FROM
        read_parquet('az://overturemapswestus2.blob.core.windows.net/release/2025-06-25.0/theme=divisions/type=division_area/*') areas
    WHERE
        division_id IN (
            SELECT
                h.division_id
            FROM
                slc
            CROSS JOIN UNNEST(hierarchies[1]) AS t(h)
            )
    ) TO 'slc_hierarchies.geojson' WITH (FORMAT GDAL, DRIVER GeoJSON);
    ```

Next we'll load `slc_hierarchies.geojson` into [KeplerGL](https://kepler.gl/) so that we can see the complete hierarchy of divisions.

 ![Salt lake City Hierarchies](/img/blog/slc_hierarchy.jpg)

:::info
GERS IDs are intended to be the key to unlock interoperability both inside and outside of Overture data. This example showed how Overture features within the same theme can reference one-another via GERS.
:::

## Looking up IDs in the GERS Registry

Let's grab a GERS ID for an important place in Salt Lake City and see if it exists in the GERS Registry. The UUID for the Utah State Capitol is `d724e74f-017a-4902-9031-bc784ffc1789`. Is that part of GERS? We can search the GERS Registry with this query:

```sql
SELECT
    *
FROM
    read_parquet('s3://overturemaps-us-west-2/registry/*')
WHERE
    id='d724e74f-017a-4902-9031-bc784ffc1789';
```

We can see that `d724e74f-017a-4902-9031-bc784ffc1789` is a `place` type that was first seen by the [GERS Registry](https://docs.overturemaps.org/gers/registry/) in the `2025-06-25.0` release. (This makes sense because the GERS Registry didn't exist to _see_ any features before then!) It has a `bbox ` of `{'xmin': -111.888214, 'xmax': -111.8882, 'ymin': 40.777214, 'ymax': 40.77722}` and it lives in this Parquet file: `/theme=places/type=place/part-00001-f6d803dd-3ff7-47d7-a58f-7af6e054e9c4-c000.zstd.parquet`.

## Using the data changelog

:::note
For the next part of this tutorial, we're using the data changelog from the May release (`2025-05-21.0`) to examine new places in Salt Lake City. Because of the switch to UUIDs in June, we did not generate a changelog in June. The next changelog will be published with the July release.
:::

Every Overture release (except the June 2025 release) includes a [changelog](https://docs.overturemaps.org/gers/changelog/) with a high-level overview of data added, removed, or changed, based on the ID. The changelog is partitioned by `theme`, `type`, and `change_type`. Let's query the changelog to identify all of the features added in Salt Lake City in Overture's May release.

Let's do query that dumps to the terminal all the new places in the May release for our area of interest.

```sql
SELECT
    id
FROM
    read_parquet('s3://overturemaps-us-west-2/changelog/2025-05-21.0/theme=places/*/*/*.parquet')
WHERE
    change_type = 'added'
    AND bbox.xmin > -112.461 AND bbox.xmax < -111.073
    AND bbox.ymin > 40.296 AND bbox.ymax < 40.955;
```

This gives us 5,727 new places in the Salt Lake City area added to the May release. Now let's write a query to join this list of new places to the full May data release by `id` and write out a new Parquet file:

```sql
COPY(
    SELECT
        places.id as id,
        names.primary as name,
        categories.primary as category,
        confidence,
        CAST(sources AS JSON) as sources,
        geometry
    FROM
        read_parquet('s3://overturemaps-us-west-2/release/2025-05-21.0/theme=places/type=place/*') places
    JOIN (
        SELECT
            id
        FROM
            read_parquet('s3://overturemaps-us-west-2/changelog/2025-05-21.0/theme=places/*/*/*.parquet')
        WHERE
            change_type = 'added'
            AND bbox.xmin > -112.461 AND bbox.xmax < -111.073
            AND bbox.ymin > 40.296 AND bbox.ymax < 40.955
            ) changelog
        ON places.id = changelog.id
        ORDER BY places.id ASC
    ) TO 'new_places_slc_may.parquet';
```

 Let's go one step further and query the one-time May to June ID mapping to translate the May IDs in our list of new places to the new UUID system. Here's how we would do that:

```sql
COPY(
    SELECT
        newUUIDs.id
     FROM
         read_parquet('new_places_slc_may.parquet') oldIDs
     JOIN (
     SELECT
        *
     FROM read_parquet('s3://overturemaps-extras-us-west-2/june_to_may_id_mapping/theme=places/type=place/*')) newUUIDs
     ON newUUIDs.previous_id = oldIDs.id
     ) TO 'new_places_slc_may_UUIDs.parquet';
```

This tells us that all 5,727 new places in Salt Lake City that appeared in the May release were assigned new UUIDs before the June data release. Can we find all of those UUIDs in the June release? Let's take a look. _Note: this query take several minutes to run._

```sql
COPY(
     SELECT
            june_places_UUID.id,
            names.primary as name,
            categories.primary as category,
            confidence,
            CAST(sources AS JSON) as sources,
            geometry
        FROM
            read_parquet('s3://overturemaps-us-west-2/release/2025-06-25.0/theme=places/type=place/*') june_places_UUID
        JOIN(
            SELECT
                id
            FROM
                read_parquet('new_places_slc_may_UUIDs.parquet')) may_places_UUID
            ON
                june_places_UUID.id = may_places_UUID.id
    ) TO new_places_slc_may_to_june_UUIDs.parquet;
```
Only 1,546 of new places that appeared in the May release show up in the June release with their newly- assigned UUIDs. This is a known quality issue with our source datasets. As tedious as this process might be, it demonstrates how we can use the GERS tools to track features across releases and gauge churn and data quality from one release to another. Overture is aware that some of our source data providers have significant churn in their data _before_ the data is ingested in Overture pipelines each month. We're working hard to improve these issues. Transparency is the first step.

## Using bridge files

Now what? Let's move forward with our smaller-than-expected dataset of new places in the June release and see if we can find the Facebook pages for some of them. How might we do that? [Bridge files](https://docs.overturemaps.org/gers/bridge-files/) are published mappings of GERS ID to source IDs for the datasets that Overture ingests before each release. We only create bridge files for established datasets with a meaningful `record_id` properites. ML-Derived buildings, for example, do not have stable meaningful input IDs, but place records from Meta have corresponding IDs that reference public Facebook pages.

The `sources` property in each Overture data release lists the original source of the data and any additional properties that Overture has added. We can use the bridge file for Meta's places data to map the GERS ID back to the source ID. Then we can look up the Facebook pages for the new places in Salt Lake City:

```sql
COPY(
    SELECT
        'https://facebook.com/' || cast(bridge.record_id as varchar) AS facebook_page,
            slc_places.*
    FROM read_parquet('new_places_slc_may_to_june_UUIDs.parquet') slc_places
    JOIN(
        SELECT
            id,
            record_id
        FROM
            read_parquet('s3://overturemaps-us-west-2/bridgefiles/2025-06-25.0/dataset=meta/theme=places/type=place/*')
        ) bridge ON slc_places.id = bridge.id
    ) TO 'new_places_slc_with_fb_pages.geojson' WITH (FORMAT GDAL, Driver GeoJSON);
    ```

One new place of note is the "Bootlegged Barber" in Sandy, Utah. On their [Facebook page](https://www.facebook.com/bootleggedbarbersandy/), the proprietors advertise themselves as a "NeoTraditional Barbershop | Where tradition and style meet."

![Bootleg Barbershop](/img/blog/bootleg.jpg)

## Next steps
- Checkout our [GERS tutorial](https://docs.overturemaps.org/gers/gers-tutorial/)
- Read more about the components of GERS in our [docs](https://docs.overturemaps.org/gers/)
- Read our ["GERS Deep Dive"](https://overturemaps.org/blog/2025/understanding-overtures-global-entity-reference-system/) and ["Introducing Bridge Files"](https://overturemaps.org/blog/2025/introducing-bridge-files/) blog posts

---

## 2025-06-25 release notes

## Overview

**The `2025-06-25.0` release of Overture data and `v1.10.0` of the Overture schema are now available.** We're pleased to annouce that GERS is now in GA! This means we've launched and updated several components of the "system" to make it production-ready.

The datasets and release artifacts are available as GeoParquet files stored on both AWS and Azure. The paths are:

### Release data

**Microsoft Azure:**

```
az://overturemapswestus2.blob.core.windows.net/release/2025-06-25.0/
```

**Amazon S3:**

```
s3://overturemaps-us-west-2/release/2025-06-25.0/
```

### Data changelog

No changelog for the June release

### Bridge files

**Microsoft Azure:**

```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2025-06-25.0/
```

**Amazon S3:**

```
s3://overturemaps-us-west-2/bridgefiles/2025-06-25.0/
```

### GERS Registry

**Microsoft Azure:**

```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**

```
s3://overturemaps-us-west-2/registry/
```

{/* truncate */}

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## What's new? Big changes to GERS.

In this release, Overture has standardized the [`id` property](/schema/) across all themes by adopting [UUIDs](https://www.rfc-editor.org/rfc/rfc9562.html), stored as strings. This is a **one-time** breaking change for our ID system. For this release only, we are offering Parquet files, partioned by `theme` and `type` that map the old May IDs to the new June UUIDs. You can find that file here: `s3://overturemaps-extras-us-west-2/june_to_may_id_mapping/`.

Overture is now producing [bridge files](https://docs.overturemaps.org/gers/bridge-files/) with each release. You can find the latest bridge files here, partitioned by `dataset`, `theme`, and `type`:

```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2025-06-25.0
```

```
s3://overturemaps-us-west-2/bridgefiles/2025-06-25.0
```

The newest component of GERS is the [GERS Registry](https://docs.overturemaps.org/gers/registry/), which will also be updated with each release. The GERS Registry files are here:

```
az://overturemapswestus2.blob.core.windows.net/registry/
```

```
s3://overturemaps-us-west-2/registry/
```

## Breaking changes

- added `perspectives` to the top-level `names` property
- added `between` to the top-level `sources` property
- added `rail` subtype to the transportation theme
- ensured no array is empty on `place` properties
- migrated GERS IDs to new GERS UUIDs

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. All themes have 100% ID churn this release because of the switch to UUIDs.
:::

### Addresses

- added new Greenland data source: OpenAddresses/Asiaq, Greenland Survey
- added new Singapore data source: OpenAddresses/Singapore Land Authority
- added several new data sources in the United States
  - Clarke County, GA: OpenAddresses/GA/Athens-Clarke County GIS
  - State of Minnesota: OpenAddresses/MN/Department of Public Safety
  - State of Colorado: OpenAddresses/CO/Governor's Office of Information Technology
  - Lackawanna County, PA: OpenAddresses/PA/City of Scranton GIS
- made improvements to existing Mexico and Australia address data
- made improvements to existing US data and Australia address data

### Base

- increased number of features with `names` property populated with data
- increased coverage of certain classes, especially within `land_use` and `infrastructure`. Examples: `communication_pole`, `pedestrian_crossing`, `plaza`, `street_lamp`, `cable_barrier`, `fire_hydrant`
- addded all upstream source tages from OSM to the `source_tags` property

### Buildings

- added a new data provider: City of Vancouver, CA

### Divisions

- added new "land" polygons (`is_land=TRUE`) for regions that have access to oceans

### Places

- 64.37M total places compared to 61.68M in May
- added a new data provider: Krick
- made improvements made to neurologist category mappings

### Transportation

- added `rail_flags` and `class` properties: railway segments now have classes (e.g. standard_gauge, tram, subway) and linear-referenced flags (is_abandoned, is_freight, etc.)
- added linear references to `sources`, making it possible to trace exactly how a segment was constructed from its sources
- added new TomTom-sourced segments, improving coverage in Turkey

## Data changelog

:::note
Because of the switch to GERS UUIDs this month, we are not release a changelog. See below for paths to the May changelog, with relies on the "old" GERS IDs. For the June release only, we are offering Parquet files, partioned by `theme` and `type` that map the old May IDs to the new June UUIDs. You can find that file here: `s3://overturemaps-extras-us-west-2/june_to_may_id_mapping/`.

:::

The [data changelog](https://docs.overturemaps.org/gers/changelog/) captures any changes in Overture features between this release and the previous release. The changelog is available as Parquet files &mdash; partitioned by theme, type, and change type &mdash; at the following locations on Azure and AWS:

```
az://overturemapswestus2.blob.core.windows.net/changelog/2025-06-25.0/

```

s3://overturemaps-us-west-2/changelog/2025-06-25.0/

```

You can find more information about [the data changelog in our documentation](https://docs.overturemaps.org/gers/changelog/).

## Schema changelog

The changelog for Overture schema `v1.10.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.10.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).
```

---

## 2025-07-23 release notes

## Overview

**The `2025-07-23.0` release of Overture data and `v1.11.0` of the Overture schema are now available.** The datasets and release artifacts are available as GeoParquet files stored on both AWS and Azure. The paths are:

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2025-07-23.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2025-07-23.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2025-07-23.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2025-07-23.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2025-07-23.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2025-07-23.0/
```

### GERS Registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

{/* truncate */}

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- no updates

### Base

- added OSM tags for `quay`, `railway`, `artwork`

### Buildings

- no updates

### Divisions

- added a new data source to populate favelas in Brazil: DadosAbertos
- added `is_land` geometries to the `division_area` type `country` subtype
- added new land polygons `is_land=TRUE` for regions that have access to oceans

### Places

- no updates

### Transportation

- fixed a small bug in the route `source_id` formatting
- added new data from TomTom in Turkey

## Schema changelog

The changelog for Overture schema `v1.11.0` is [here](https://github.com/OvertureMaps/schema/tree/v1.11.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-08-20 release notes

:::info

August 26th, 2025

Today, Overture released a patch for the August data. The new release paths are:

#### Amazon S3 
```
s3://overturemaps-us-west-2/release/2025-08-20.1
```

#### Microsoft Azure 
```
wasbs://release@overturemapswestus2.blob.core.windows.net/2025-08-20.1
```

During our final QA processes, we detected the following issue in the data: all Microsoft ML buildings were incorrectly assigned `"is_underground": true`. We decided to make the `2025-08-20.0
` release public with the bug and follow up with a patch to the data. 

![Schema docs describing is_underground](/img/is_underground.png)

:::

## Overview

**The `2025-08-20.0` release of Overture data and `v1.11.0` of the Overture schema are now available.** The datasets and release artifacts are available as GeoParquet files stored on both AWS and Azure. The paths are:

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2025-08-20.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2025-08-20.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2025-08-20.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2025-08-20.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2025-08-20.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2025-08-20.0/
```

### GERS Registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

{/* truncate */}

You can access the datasets by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at data@overturemaps.org. We’d love to hear from you.

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- no updates

### Base

- added data for `quay`, `railway`, `artwork` classes

### Buildings

- added new data from Esri and Vancouver
- flagged a bug in the data: all Microsoft ML buildings described as underground

### Divisions

- no updates

### Places

- no updates

### Transportation

- no updates

## Schema changelog

The changelog for Overture schema `v1.11.0` is [here](https://github.com/OvertureMaps/schema/tree/v1.11.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-09-24 release notes

:::warning
With the September release, Overture is implementing a data retention policy for publicly-available data releases.

#### What's changing:

- Data releases will be publicly available for a maximum of 60 days (approximately two monthly releases)
- Data files will be automatically removed from public distribution after this period using cloud storage lifecycle policies

#### What remains available:

- The most recent two monthly data releases (last 60 days)
- Versioned changelogs and bridgefiles for all releases
- GERS registry
- Release notes from all past releases

#### Why we're implementing this:

This policy ensures compliance with data protection regulations, including GDPR "right to be forgotten" requirements.

You can find complete details about our release schedule and policies on the [releases](https://docs.overturemaps.org/release-calendar/) page in the Overture documentation. Questions? Comments? Please contribute to [this thread on our GitHub Discussions forum](https://github.com/orgs/OvertureMaps/discussions/422) or reach out to us at info@overturemaps.org.

:::

## Overview

**The `2025-09-24.0` release of Overture data and `v1.12.0` of the Overture schema are now available.** The datasets and release artifacts are available as GeoParquet files stored on both AWS and Azure. There are several data updates and (minor) breaking schema changes in this release.

## What's new?

### New POIs from Foursquare Open Source Places

This release adds approximately 6 million new POIs from Foursquare Open Source Places (FSQ OS Places) to grow the coverage of our data. We selected these records as POIs not previously included in Overture. We plan to add more Foursquare data as our validation models mature.
You can find the original source for FSQ OS Places [here](https://opensource.foursquare.com/os-places/).

#### Overture places is now a multi-license dataset

Previously all places data was under a CDLA license, but in this release each place has a license based on its source property:

- Foursquare-sourced data is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
- Data from other sources remains licensed under [CDLA 2.0](https://cdla.dev/permissive-2-0/).
  Note that all Foursquare-sourced data is single sourced, meaning we do not blend its attributes with any other sources.

#### License requirements

If you use, modify, or redistribute the Foursquare data, you must:

- Provide a copy of the Apache 2.0 license.
- State that you changed the files and include the date of any changes.
- Preserve attribution notices from the source NOTICE file, including at minimum: `Copyright 2024 Foursquare Labs, Inc. All rights reserved.`

More information on license requirements and data usage is available on Foursquare’s [website](https://docs.foursquare.com/data-products/docs/access-fsq-os-places). General information on Overture licensing is available in the [licensing and attribution section](https://docs.overturemaps.org/attribution/) of Overture's documentation.

#### How to filter for CDLA-only data

To create a purely CDLA-licensed dataset, filter out all records where the source property is “Foursquare”.

### New schema properties

This month we added a new `license` sub-property within the `sources` property to more clearly link entities to the licensing information for their source data. This change affects all Overture themes, as `sources` is [a top-level property](https://docs.overturemaps.org/schema/) in the Overture schema.

In the places theme, we added a new `operating_status` property, with all values set to "open". In future releases, we plan to update this property with data that indicates whether a place is "open", "permanently_closed", or "temporarily_closed".

### Signal "patches"

About a million POIs in our places theme now have a signal "patch" that determines the calculation of the score in the `confidence` property. POIs enhanced by these patches have "SparkGeo-confidence-conflation" in the `sources` property.

## Getting the data

You can access this month's data and release artifacts by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at info@overturemaps.org. We’d love to hear from you.

The paths are:

### Release data

**Microsoft Azure:**

```
az://overturemapswestus2.blob.core.windows.net/release/2025-09-24.0/
```

**Amazon S3:**

```
s3://overturemaps-us-west-2/release/2025-09-24.0/
```

### Data changelog

**Microsoft Azure:**

```
az://overturemapswestus2.blob.core.windows.net/changelog/2025-09-24.0/
```

**Amazon S3:**

```
s3://overturemaps-us-west-2/changelog/2025-09-24.0/
```

### Bridge files

**Microsoft Azure:**

```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2025-09-24.0/
```

**Amazon S3:**

```
s3://overturemaps-us-west-2/bridgefiles/2025-09-24.0/
```

### GERS Registry

**Microsoft Azure:**

```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**

```
s3://overturemaps-us-west-2/registry/
```

{/* truncate */}

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha.
:::

### Addresses

- added a new `license` property within `sources`

### Base

- added a new `license` property within `sources` and populated with applicable license information

### Buildings

- added a new `license` property within `sources` and populated with applicable license information for Microsoft and OSM features.

### Divisions

- added a new `license` property within `sources` and populated with applicable license information

- added geoBoundaries-sourced counties in New Zealand

- added LINZ-sourced localities and neighborhoods in New Zealand

- mapped OSM features with an admin_level=7 tag in Argentina to `localadmin`

- fixed `local_type` for geoBoundaries-sourced counties

- refreshed OSM with updates to 2025-08-29

### Places

- added a new `license` property within `sources` and populated with applicable license information

- added a new `operating_status` property, indicating the operating status of a place ("open", "permanently_closed", "temporarily_closed"); set all values to "open" for the September release.

- added six million POIs from Foursquare

- implemented signal “patches” to dynamically update `confidence` property based on signals

### Transportation

- added a new `license` property within `sources` and populated with applicable license information

- added new TomTom-sourced segments

- made significant additions to the data in Italy, Portugal, Mexico, Egypt, Sweden, Indonesia

## Schema changelog

The changelog for Overture schema `v1.12.0` is [here](https://github.com/OvertureMaps/schema/releases).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-10-22 release notes

:::warning

_October 23, 2025_: We detected an issue with the GERS registry generation and have temporarily removed the registry files from our public buckets while we fix it. 

:::

## Overview

**The `2025-10-22.0` release of Overture data and `v1.13.0` of the Overture schema are now available.** The datasets and release artifacts are available as GeoParquet files stored on both AWS and Azure. There are several data updates and (minor) breaking schema changes in this release. 

## What's new?

### New `basic_category` property in the places schema

In the places schema this month, we introduced a simple `basic_category` property that maps to our original `categories.primary` property. This change is part of a new initiative to reimagine Overture's category taxonomy. The new property is based on a commonly-used cognitive science concept called "basic-level categories," where category names balance being specific enough to be useful while general enough to be broadly applicable.

### Major data updates and GERS stability in addresses

The addresses theme has hit a new high of 455 million records, an increase of nine million records from our September release. More than 325 million of those records retained their GERS ID from the previous release, a major milestone for GERS stability as addresses moves toward General Availability next quarter.

## Getting the data and release artifacts

You can access this month's data and release artifacts by following the process outlined [here](/getting-data). We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at info@overturemaps.org. We’d love to hear from you.

The paths are:

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2025-10-22.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2025-10-22.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2025-10-22.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2025-10-22.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2025-10-22.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2025-10-22.0/
```

### GERS registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

{/* truncate */}

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- added additional `postal_city` values to NAD-sourced US addresses
- added new data in the following locations:
    - Faroe Islands
    - Serbia
    - USA
        - Mississippi
        - Idaho: Ada County
        - Oregon: Jackson County 
        - Florida: Orange County, Palm Beach County
        - Michigan: Musgekon County, Kent County, Allegan County 
        - many others from NAD
- refreshed data in the following locations:
    - Austria
    - Australia
    - Canada
    - Japan
    - Finland
    - Germany (Berlin, Hamburg, Hesse, Saxony)
    - Hong Kong
    - Latvia
    - Lithuania
    - Luxembourg
    - Poland
    - Slovakia
    - Spain
    - Taiwan (CHA, KEE, KHH, KIN, MIA, NWT, TAO, TNN, TPE, TXG, YUN)
    - USA
- fixed the following bugs:
    - removed unincorporated placeholder value in `address_level` from NAD
    - added Estonia units
    - fixed missing numbers in Lithuania
    - removed various duplicate address records
    - fixed issue sometimes causing invalid address_level values in Slovenia
- identified the following "known" issues:
    - partial loss of data in: Placer County, CA, USA; Desoto County, FL, USA; Schleswig-Holstein, DE
    - full loss of data in Kern County, CA, USA

### Base

- made minor, incremental updates to the data
- refreshed OpenStreetMap data as of 2025-10-11

### Buildings

- fixed a de-duplication bug, allowing ~5 million more Google-sourced buildings in SE Asia
- populated the license property in sources for building height data
- refreshed OpenStreetMap data as of 2025-10-11

### Divisions

- refreshed OSM data on 2025-10-02
- made minor, incremental updates to the data

### Places

- added a new basic level category property the places schema
- populated the basic level category property with data : https://github.com/OvertureMaps/schema/pull/399

### Transportation

- added new TomTom-sourced `segment` data 
- refreshed OpenStreetMap data as of 2025-09-29

## Schema changelog

The changelog for Overture schema `v1.13.0` is [here](https://github.com/OvertureMaps/schema/releases).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-11-19 release notes

## Overview

**The `2025-11-19.0` release of Overture data and `v1.14.0` of the Overture schema are now available.** The datasets and release artifacts are available as GeoParquet files stored on both AWS and Azure. This is a [minor breaking change](/release-calendar) release. 

## What's new?

We added a `roller_coaster` class to our schema this month. Buckle up because next month we're adding rollercoaster data!

![Rollercoasters!](./assets/roller-coasters.gif) 

## Getting the data and release artifacts

You can access this month's data and release artifacts by following the process outlined [here](/getting-data). The paths to the data and release artifacts are listed below. We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at info@overturemaps.org. We’d love to hear from you.

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2025-11-19.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2025-11-19.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2025-11-19.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2025-11-19.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2025-11-19.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2025-11-19.0/
```

### GERS registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

{/* truncate */}

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- repromoted the October data release

### Base

- added a new `roller_coaster` class to the schema (data coming next month!)
- refreshed OSM data
- made minor, incremental updates to the data

### Buildings

- refreshed OSM data
- made minor, incremental updates to the data

### Divisions

- refreshed OSM data on 6 November 2025
- made minor, incremental updates to the data

### Places

- added ~5,000 new POIs from RenderSEO
- added ~1,500,000 new POIs from AllThePlaces
- known issue: GERS ID churn on 12 million place records

### Transportation

- added new TomTom-sourced `segment` data to bring the total length of road segments from TomTom to more than 1 million kilometers across 115 countries
- refreshed OSM data on 2 November 2025

## Schema changelog

The changelog for Overture schema `v1.14.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.14.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2025-12-17 release notes

## Overview

**The `2025-12-17.0` release of Overture data and `v1.15.0` of the Overture schema are now available.** The datasets and release artifacts are available as GeoParquet files stored on both AWS and Azure. 

## What's new?

We added a new `taxonomy` property to our places schema this month, as part of our ongoing initiative to redesign the places category system. The new property offers a streamlined and logical structure with consolidated primary and alternate names and a hierarchy that makes clear the parent/child relationship between categories. 

In October, we introduced the `basic_category` property. That property corresponds 1:1 to the primary place name in the new `taxonomy` property. (It also maps to the primary name in the original `categories` property.) The hierarchical paths in `taxonomy` support deeper and more logical structures. For example, in the restaurant branch, you can see a clear progression from very broad to very specific category names: `restaurant > asian_restaurant > east_asian_restaurant > chinese_restaurant > cantonese_restaurant`. This kind of structure makes it easier to aggregate and display POIs in meaningful ways.

The original `categories` property, with more than 2100 category names, will remain in the schema for the next several months so that users can compare the old system to the new taxonomy. 

Examples:

1. Original categories system 
```
properties:
   categories:
      primary: greasy_diner
```

2. `basic_category` mapped to primary category in original categories system 
```
properties:
   basic_category: casual_eatery
   categories:
      primary: gas_station_sushi
      alternate:
         - bait_and_tackle
```

3. New taxonomy
```
properties:
   basic_category: casual_eatery
   taxonomy: 
      hierarchy: [food_and_drink, restaurant, casual_eatery, gas_station_sushi]
      primary: gas_station_sushi
      alternate:
         - gas_station
         - sushi_restaurant
```

## Getting the data and release artifacts

You can access this month's data and release artifacts by following the process outlined [here](/getting-data). The paths to the data and release artifacts are listed below. We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at info@overturemaps.org. We’d love to hear from you.

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2025-12-17.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2025-12-17.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2025-12-17.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2025-12-17.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2025-12-17.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2025-12-17.0/
```

### GERS registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

{/* truncate */}

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- added new province-level dataset for Quebec from [Le ministère des Ressources naturelles et des Forêts](https://www.quebec.ca/gouvernement/ministeres-organismes/ressources-naturelles-forets)
- removed certain placeholder values like “N/A” and “unincorporated”

### Base
- refreshed OSM data 2025-11-30
- made minor, incremental updates to the data
- added 9,690 rollercoasters to infrastructure!

![Rollercoasters!](./assets/roller-coasters.gif)

### Buildings

- refreshed OSM data 2025-11-30
- made minor, incremental updates to the data

### Divisions

- refreshed OSM data 
- made minor, incremental updates to the data

### Places

- added new `taxonomy` property

### Transportation

- added more than 725k new TomTom-sourced transportation segments in the US, Puerto Rico, Canada, Algeria, Colombia, Belarus, and Bosnia and Herzegovina

- refreshed OSM data 2025-11-30

## Schema changelog

The changelog for Overture schema `v1.15.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.15.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2026-01-21 release notes

## Overview

**The `2026-01-21.0` release of Overture data and `v1.15.0` of the Overture schema are now available.** The datasets and release artifacts are available as GeoParquet files stored on both AWS and Azure. 

## Getting the data and release artifacts

You can access this month's data and release artifacts by following the process outlined [here](/getting-data). The paths to the data and release artifacts are listed below. We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at info@overturemaps.org. We’d love to hear from you.

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2026-01-21.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2026-01-21.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2026-01-21.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2026-01-21.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2026-01-21.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2026-01-21.0/
```

### GERS registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

{/* truncate */}

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- re-promoted December data, which included new province-level dataset for Quebec from [Le ministère des Ressources naturelles et des Forêts](https://www.quebec.ca/gouvernement/ministeres-organismes/ressources-naturelles-forets)

### Base
- made minor, incremental updates to the data

### Buildings
- made minor, incremental updates to the data

### Divisions
- made minor, incremental updates to the data

### Places
- added ~150,000 place records from [DAC Group](https://www.dacgroup.com/)

### Transportation

- added new road segments covering 85,000 km, expanding coverage across ~150 countries

## Schema changelog

The changelog for Overture schema `v1.15.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.15.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## Overture Has Fully Embraced STAC

Over the past few releases, the Overture engineering team has gone from generating a [STAC catalog](https://stacspec.org/en) as an ad hoc release artifact to making STAC the backbone of our tooling. Now our [Python client](https://github.com/OvertureMaps/overturemaps-py), [Explorer](https://explore.overturemaps.org/), internal QA tools, and data pipelines all use [Overture STAC](https://stac.overturemaps.org/) to stay in sync with the latest release. We did this to improve our own workflows, but we think it'll make things easier for everyone.

Here's our STAC, from the top. https://stac.overturemaps.org/.

```json
{
  "type": "Catalog",
  "id": "Overture Releases",
  "stac_version": "1.1.0",
  "description": "All Overture Releases",
  "links": [
    {
      "rel": "root",
      "href": "./catalog.json",
      "type": "application/json"
    },
    {
      "rel": "child",
      "href": "./2026-01-21.0/catalog.json",
      "type": "application/json",
      "title": "Latest Overture Release",
      "latest": true
    },
    {
      "rel": "child",
      "href": "./2025-12-17.0/catalog.json",
      "type": "application/json",
      "title": "2025-12-17.0 Overture Release"
    }
  ],
  "latest": "2026-01-21.0",
```

:::danger[Shoutout!]

Huge thanks to Ben Clark for getting Overture started on our STAC journey back in 2024. Watch [his talk on STACing GeoParquet](https://youtu.be/FWQz7H99qEs?si=membEVd0JarkKmbn) at the 2025 Cloud Native Geospatial Forum. And thanks to Jennings Anderson for fully realizing Overture's STAC vision and getting us where we are today.

:::

{/* truncate */}

## Why We Needed This

Many of the [examples in our docs](https://docs.overturemaps.org/getting-data/) instruct users to sip or gulp Overture data directly from our public cloud buckets, at very long endpoints like `s3://overturemaps-us-west-2/release/2026-01-21.0/theme=buildings/type=building/*.parquet`.

(\*Not so long ago Paul Ramsey [wrote](https://www.crunchydata.com/blog/vehicle-routing-with-postgis-and-overture-data) that the trickiest part of accessing Overture data was figuring out how to construct the endpoint. **Noted.\***)

Using well-structured files on cloud storage as a de facto API for data distribution isn't new. It's actually one of the most important ideas in cloud-native geospatial. Back in 2014, when the AWS open data team [put Landsat imagery on S3](https://radiant.earth/blog/2023/03/the-naive-origins-of-the-cloud-optimized-geotiff/), they didn't build any custom tooling. No servers. They made well-structured data available on public cloud storage and let people have at it over HTTP. This principle is what makes [Cloud Optimized GeoTIFFs](https://cogeo.org/) work for raster imagery, [PMTiles](https://protomaps.com/) for map tiles, and [GeoParquet](https://geoparquet.org/) for vector map data. The storage endpoint is the API.

For Overture, this means tools like [DuckDB](https://til.simonwillison.net/overture-maps/overture-maps-parquet) can query gigabytes of data because Parquet's Hive-style partitioning (`theme=buildings/type=building/*.parquet`) and built-in row group statistics let query engines skip irrelevant files and irrelevant chunks within files. Users can quickly download megabytes. They don't have to drink the ocean to get the data they want.

The pattern works best with stable endpoints. Things break when endpoints change unpredictably. Overture releases monthly, partitions data by theme and type, and divides its global datasets across multiple Parquet files. All of these factors go into the construction of the S3 and Azure paths. Hardcode a path today, and it's stale in few weeks. We knew this was a pain point for users, but we expected people to build their own solutions around it. Like the AWS team back in 2014, our philosophy was: _give people the data and get out of the way._

Not everyone was happy about this. Many users have asked Overture to provide APIs (and SDKs, mostly to handle the complexity of our schema). We did build overturemaps-py, our Python client, to abstract from those long endpoints, but even early versions of that tool had a hardcoded path to the data and required a manual update after each release.

Internally, the pressure to build better tooling came from a different direction. As we [migrated more data pipelines](https://overturemaps.org/blog/2025/overture-maps-building-platform-agnostic-infrastructure-a-collaboration-story/) from member company infrastructure onto Overture infrastructure, we needed better solutions for keeping things in sync across themes and releases. STAC has helped tremendously. It also lets us access metadata to speed up queries and requests. And because it's the same catalog we publish externally, it solves a lot of user pain points too.

## This Makes Your Life Easier Too (We Hope!)

If you've ever hardcoded an S3 path to Overture data and had it break when we released a new version, we're sorry. Try using Overture STAC. The catalog rebuilds daily directly from our production environment. Instead of checking our [release notes](https://docs.overturemaps.org/blog/tags/releases/) or guessing at paths, query the catalog directly to get the latest release:

```bash
curl https://stac.overturemaps.org | jq -r '.latest'
```

Or if you're in DuckDB:

```sql
SELECT latest FROM 'https://stac.overturemaps.org/catalog.json';
```

Even better, create a variable to use the latest release endpoint in all your queries.

```sql
SET VARIABLE latest = (SELECT latest FROM 'https://stac.overturemaps.org/catalog.json');

SELECT * FROM read_parquet(
    's3://overturemaps-us-west-2/release/'
    || getvariable('latest')
    || '/theme=addresses/type=address/*'
) LIMIT 10;
```

Your scripts stay stable even as the underlying data and cloud storage endpoints update.

## Explore the Metadata

You can quickly poke around the catalog using the [STAC browser](https://radiantearth.github.io/stac-browser/#/external/stac.overturemaps.org/catalog.json). Click into any release and theme, and you'll find links to GeoParquet files on AWS and Azure. You'll also see PMTiles listed under additional resources. Hover over those for a link to load the tiles directly in [PMTiles Viewer](https://pmtiles.io/). This is the data that powers our [Explorer](https://explore.overturemaps.org/) site.

If you want to go deeper, you can drill into a [specific release](https://stac.overturemaps.org/2026-01-21.0/catalog.json) to see which themes it contains and which schema version it uses, then into a [theme](https://stac.overturemaps.org/2026-01-21.0/divisions/catalog.json) to find PMTiles links and the available types. Each type is a [STAC collection](https://stac.overturemaps.org/2026-01-21.0/divisions/division/collection.json) with feature counts, spatial extent, license, and column names, enough to know what you're getting before you download anything. The catalog also includes a peek into our GERS registry by providing a full manifest of the registry files.

If you're using Python, you can install [pystac](https://pystac.readthedocs.io/) to explore the catalog programmatically. Here's a script that grabs feature counts in the latest Overture release.

```python

catalog = pystac.Catalog.from_file("https://stac.overturemaps.org/catalog.json")
latest = next(c for c in catalog.get_children() if c.extra_fields.get("latest"))

print(f"Release: {latest.id}")
print(f"Schema:  {latest.extra_fields['schema:version']}\n")

for theme in latest.get_children():
    print(f"{theme.id}:")
    for collection in theme.get_children():
        count = collection.extra_fields.get("features", "?")
        if isinstance(count, int):
            count = f"{count:,}"
        print(f"  {collection.id}: {count} features")
```

```
Release: 2026-01-21.0
Schema:  1.15.0

divisions:
  division: 4,575,616 features
  division_area: 1,068,997 features
  division_boundary: 87,814 features
places:
  place: 72,444,739 features
addresses:
  address: 460,734,720 features
transportation:
  connector: 401,294,301 features
  segment: 338,773,725 features
buildings:
  building: 2,540,587,907 features
  building_part: 3,577,657 features
base:
  bathymetry: 59,963 features
  infrastructure: 144,896,847 features
  land: 71,029,712 features
  land_cover: 123,302,114 features
  land_use: 53,037,060 features
  water: 63,442,033 features
```

Now let's dig into the metadata for the `building` type:

```python

collection = pystac.Collection.from_file(
    "https://stac.overturemaps.org/2026-01-21.0/buildings/building/collection.json"
)

num_files = sum(1 for link in collection.links if link.rel == "item")

print(f"Type:          {collection.id}")
print(f"Features:      {collection.extra_fields['features']:,}")
print(f"License:       {collection.license}")
print(f"Parquet files: {num_files}")
print(f"Columns:       {collection.summaries.lists.get('columns', [])}")
```

```
Type:          building
Features:      2,540,587,907
License:       ODbL-1.0
Parquet files: 236
Columns:       ['id', 'geometry', 'bbox', 'version', 'sources', 'level', 'subtype', 'class', 'height', 'names', 'has_parts', 'is_underground', 'num_floors', 'num_floors_underground', 'min_height', 'min_floor', 'facade_color', 'facade_material', 'roof_material', 'roof_shape', 'roof_direction', 'roof_orientation', 'roof_color', 'roof_height']
```

You can even fetch the bounding boxes and AWS and Azure paths to individual Parquet files. Exciting!

```bash
  00000
  bbox: [-179.9685336, -84.2945957, -2.8229824, -22.499915]
  aws: https://overturemaps-us-west-2.s3.us-west-2.amazonaws.com/release/2026-01-21.0/theme=buildings/type=building/part-00000-47160ab1-2f19-4475-89f8-cc1348df69a6-c000.zstd.parquet
  azure: https://overturemapswestus2.blob.core.windows.net/release/2026-01-21.0/theme=buildings/type=building/part-00000-47160ab1-2f19-4475-89f8-cc1348df69a6-c000.zstd.parquet

  00001
  bbox: [-71.7188172, -33.7503154, -56.249949, -28.1249106]
  aws: https://overturemaps-us-west-2.s3.us-west-2.amazonaws.com/release/2026-01-21.0/theme=buildings/type=building/part-00001-47160ab1-2f19-4475-89f8-cc1348df69a6-c000.zstd.parquet
  azure: https://overturemapswestus2.blob.core.windows.net/release/2026-01-21.0/theme=buildings/type=building/part-00001-47160ab1-2f19-4475-89f8-cc1348df69a6-c000.zstd.parquet

  00002
  bbox: [-67.5002494, -30.937648, -50.6249127, -22.4999315]
  aws: https://overturemaps-us-west-2.s3.us-west-2.amazonaws.com/release/2026-01-21.0/theme=buildings/type=building/part-00002-47160ab1-2f19-4475-89f8-cc1348df69a6-c000.zstd.parquet
  azure: https://overturemapswestus2.blob.core.windows.net/release/2026-01-21.0/theme=buildings/type=building/part-00002-47160ab1-2f19-4475-89f8-cc1348df69a6-c000.zstd.parquet
```

## GERS Registry Manifest

The catalog also includes the [GERS registry](https://docs.overturemaps.org/gers/registry/) manifest. The registry is split into dozens of Parquet files, sorted by ID, and the manifest lists the maximum ID in each file:

```json
"manifest": [
  ["part-00000-...zstd.parquet", "0492a38d-6c33-417c-abd4-de67d7a1b2d8"],
  ["part-00001-...zstd.parquet", "09ff1f68-d9e0-4739-b3b3-ef375d8bf7fe"],
  ["part-00002-...zstd.parquet", "0edc25ba-2d73-4eb7-9c6e-2648644dc125"],
  ...
]
```

Since GERS IDs sort lexicographically, hex character by hex character, the [Python CLI](https://github.com/OvertureMaps/overturemaps-py?tab=readme-ov-file#gers-uuid) can check this manifest to find exactly which file contains a GERS ID of interest. It's one small JSON fetch instead of checking every file.

## What's Next

Many of the tools I mention in this post are in active development in public GitHub repositories. We welcome your comments, questions, and contributions:

- https://github.com/OvertureMaps/stac — STAC
- https://github.com/OvertureMaps/overturemaps-py — Python CLI
- https://github.com/OvertureMaps/explore-site — Explorer

You can also build your own thing with Overture STAC. Here's a [tiny website I made](https://danabauer.github.io/overture-latest/) to share at meetups and conferences. It answers a question I consistently get from users: what's the latest Overture release? You can grab the source code [here](https://github.com/danabauer/overture-latest).

:::tip[Talk to us]

We want to hear about your experience using Overture Maps. Share your ideas and questions on our [GitHub Discussion Forum](https://github.com/orgs/OvertureMaps/discussions) or reach out to us at community@overturemaps.org.

:::

---

## 2026-02-18 release notes

## Overview

**The `2026-02-18.0` release of Overture data and `v1.16.0` of the Overture schema are now available.** You can access the datasets, changelog, GERS registry, bridge files, and PMTiles on AWS and Azure at the paths listed below. 

## What's new?
In this release, we added a new `admin_level` property to the divisions schema to represent a division’s position in its country’s hierarchy, e.g. 0, 1, 2. We also updated our [places guide](/guides/places/taxonomy) with more information about our recent taxonomy work, including mappings across the `basic_category`, `taxonomy`, and `categories` properties. Last but not least, we updated our address data for Norway and made small improvements to our address schema thanks to [user feedback](https://github.com/orgs/OvertureMaps/discussions/451) from Johannes-Andersen. Keep the [comments](https://github.com/OvertureMaps/data/issues) and [discussions](https://github.com/orgs/OvertureMaps/discussions) coming!

## Deprecations
The `categories` property in the places schema is now deprecated and will be removed in the June 2026 release, replaced by the new `basic_category` and `taxonomy` properties. All three properties will be available until then to ease the transition for our users. 

## Getting the data and release artifacts

You can access this month's data and release artifacts by following the process outlined [here](/getting-data). The paths to the data and release artifacts are listed below. We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at community@overturemaps.org. We’d love to hear from you.

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2026-02-18.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2026-02-18.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2026-02-18.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2026-02-18.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2026-02-18.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2026-02-18.0/
```

### GERS registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

### PMTiles

**Amazon S3:**
```
s3://overturemaps-extras-us-west-2/tiles/2026-02-18.0/
```

{/* truncate */}

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- refreshed data in the following countries: Canada, Poland, Spain, Austria, US, Latvia, and Finland
- updated Norway and improved our schema thanks to [user feedback](https://github.com/orgs/OvertureMaps/discussions/451) from Johannes-Andersen.

### Base
- made minor, incremental updates to the data

### Buildings
- made minor, incremental updates to the data

### Divisions
- added new `admin_level` property to better represent a division's position in its country's administrative hierarchy, i.e. lower numbers correspond to higher level administrative units (0, 1, and 2).
- adjusted top-level subtypes in Antigua and Barbuda.

### Places
- refreshed Foursquare data
- updated matching priorities, causing a slight drop in the number of PinMeTo-sourced place records

### Transportation

- OSM cut-off date: 2026-02-08
- added TomTom-sourced road segments in 65+ new countries including Azerbaijan, Sri Lanka, Nigeria, and El Salvador
- ingested over 1.6M new TomTom-sourced road segments with a combined length of over 280k km
- increased the total number of connectors to 405.9M and the total number of segments to 341.7M

## Schema changelog

The changelog for Overture schema `v1.16.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## The Day Explorer Turned Pretty

When we launched [Explorer](https://explore.overturemaps.org) back in the summer of 2024, we described it as an "x-ray data inspector" and made a deliberate choice to show everything at once — all themes, all feature types, all properties — with minimal cartographic polish. The goal was transparency, not beauty. We wanted you to see the data as it really is.

That was the right call for a launch. But as Explorer has matured and more people have come to rely on it, we've learned that "useful data tool" and "thing you actually enjoy looking at" don't have to be mutually exclusive. The person most responsible for closing that gap is Jonah Adkins, Cartography Lead at Meta. "I didn't have the intention of just redoing the whole thing," Jonah says, "but I was curious what I could get Claude to do." He came up with a plan, and it was, in his words, probably 5 to 6 hours of work total over a few days. By end of day one, Explorer looked like a different site. Dana let him keep going.

("I would have felt better with a heads up," Dana says. "But it's so pretty now.")

<figure className="screenshot-frame">
  <iframe
    src="https://explore.overturemaps.org"
    width="100%"
    height="500"
    style={{ border: 'none', borderRadius: '8px' }}
    loading="lazy"
    allow="fullscreen"
  />
  <figcaption>
    Open in full screen ↗
  </figcaption>
</figure>

{/* truncate */}

:::danger[Shoutout!]
 
Explorer has had many hands on it over the years. Huge thanks to Ben Clark, who first brought it to life, and to Brandon Liu, Charlie McGrady, Ethan Iannicelli, Jennings Anderson, Kyle Barron, and everyone else who has contributed to making it what it is today.
 
:::

## Two modes: Explore and Inspect

The biggest change to Explorer is the introduction of two distinct modes, accessible from the navigation bar at the top of the page.

**Explore mode** is the new default. The data is styled, readable, and cartographically opinionated. Places have icons. Highways look different from residential streets. Buildings have fill colors. If you want to quickly orient yourself in an area, understand what Overture covers, or demo the data to someone who's never seen it, Explore mode is where you want to be. The layers panel on the left toggles Overture's six themes on and off. Click any feature to see its properties.

**Inspect mode** is the spiritual successor to the original Explorer experience: show as much of the data as possible, as directly as possible. The layers panel reorganizes to mirror the Overture schema itself — base breaks down into land, water, bathymetry, land cover, and land use; transportation shows segments and connectors; divisions shows areas, boundaries, and labels. Every feature type is symbolized uniformly as simple points, lines, and polygons. Little to no filtering, very few cartographic opinions.

Think of it this way: Explore mode asks _what does this place look like?_ Inspect mode asks _what's actually in the data?_ Both questions are worth asking.

## Globe

When you open Explorer, you're now looking at a globe. "The globe thing is kind of stupid," Jonah admits, "but it's too easy not to do." Dana disagrees on the stupid part. The previous default dropped you in Washington, DC. The globe communicates something truer: Overture is a global dataset. Go find your place in it.

## Search

Explorer now has a search bar, a feature people have been asking for in every uesr testing session since 2024. Use the **Search Type** dropdown to switch between three modes:

**Locality** and **Country** searches are powered by a [geocoding service](https://github.com/brad-richardson/overture-geocoder) built entirely from Overture's own divisions data. It covers 450,000+ cities, neighborhoods, and administrative areas worldwide, with full-text search and autocomplete. It's a nice demonstration of what you can build on Overture data.

**GERS search** is the one that excites us most. Paste any GERS ID into the search bar and Explorer will fly directly to that feature on the map. This is powered by the GERS manifest in the [Overture STAC catalog](/getting-data/cloud-sources/), which maps every GERS ID to a bounding box. If you've been writing queries and want to visually verify a feature — or if someone hands you a GERS ID and you want to know what it is — this is now a one-step operation. 

## Multilingual names

Toggle between languages using the language selector to see place names rendered in dozens of languages. This comes directly from the `names` field in Overture data, which carries common names, alternate names, and translations from our source datasets. The richness packed into that property is easy to miss when you're writing queries; Explorer makes it visible.

## Under the hood

The styling refresh is powered by a token-based design system Jonah built for Explorer: primitives (color palette, fonts), semantics (feature-level color assignments), and components (stylesheet properties referencing the semantic values). The practical upshot is that adding a new map style — dark mode, for example — means changing one file. Explorer is also built on Next.js, which sets up a better foundation for adding features and making it easier for contributors to build on top of.

Explorer is pinned to a specific Overture release. Updates go through a validation process — a script called, yes, `dont-dream-its-overture` — that audits stylesheets against the current schema and tile metadata before changes reach the live site. This means Explorer doesn't silently drift out of sync with the data. When you see a property in the inspector panel, it's a property that's actually in the schema.

We also want to be clear: Explorer is still fundamentally a data and schema inspector, not a finished cartographic product. But it's also proof of what's possible with Overture data. The components are open source and the design system is built to be extended. We hope people take it and run with it.

Source code is in the [explore-site](https://github.com/OvertureMaps/explore-site) repository. Issues and PRs welcome.

## What's next

Explorer is a tool for getting oriented with Overture data. Once you know what you're looking for, the [Python CLI](/getting-data/overturemaps-py/) and [DuckDB](/getting-data/duckdb/) are your next steps for downloading and querying at scale. The [schema reference](/schema/) is the place to go when you want to understand what those properties in the inspector panel actually mean.

:::tip[Talk to us]

We want to hear about your experience using Overture Maps. Share your ideas and questions on our [GitHub Discussion Forum](https://github.com/orgs/OvertureMaps/discussions) or reach out to us at community@overturemaps.org.

:::

---

## 2026-03-18 release notes

:::note

The `bbox` column fields (`bbox.xmin`, `bbox.ymin`, `bbox.xmax`, `bbox.ymax`) have changed to the [Parquet physical type `DOUBLE` (64-bit floating point)](https://parquet.apache.org/docs/file-format/types/) instead of 32-bit `FLOAT`. This change works around an outstanding Athena bug affecting queries on nested float fields.

:::

## Overview

**The `2026-03-18.0` release of Overture data and `v1.16.0` of the Overture schema are now available.** You can access the datasets, changelog, GERS registry, bridge files, and PMTiles on AWS and Azure at the paths listed below. 

## What's new?
The [data changelog](https://docs.overturemaps.org/gers/changelog/) now includes `columns_changed`, capturing which properties changed, per feature. Also in this release, we've made several improvements to the pipeline architecture of the transportation theme, including adding several data quality improvements and fresher source data. This architectural change also lays the groundwork for integrating additional road network sources into Overture in the near future.

## Deprecations
The `categories` property in the places schema is now deprecated and will be removed in the June 2026 release, replaced by the new `basic_category` and `taxonomy` properties. All three properties will be available until then to ease the transition for our users. The taxonomy documentation is [here](https://docs.overturemaps.org/guides/places/taxonomy/).

## Getting the data and release artifacts

You can access this month's data and release artifacts by following the process outlined [here](/getting-data). The paths to the data and release artifacts are listed below. We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at community@overturemaps.org. We’d love to hear from you.

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2026-03-18.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2026-03-18.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2026-03-18.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2026-03-18.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2026-03-18.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2026-03-18.0/
```

### GERS registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

### PMTiles

**Amazon S3:**
```
s3://overturemaps-extras-us-west-2/tiles/2026-03-18.0/
```

{/* truncate */}

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- improved city, street, or number column in Slovakia, Belgium, Austria, and in Quebec, CA
- added units to Portugal, Iceland, and Baden-Württemberg DE
- added data in Lower Saxony and Mecklenburg-Vorpommern, DE

### Base
- made minor, incremental updates to the data

### Buildings
- made minor, incremental updates to the data

### Divisions
- made minor, incremental changes to the data

### Places
- made improvements to the `taxonomy` and `basic_category` fields
- adjusted methods of calculating feature-level confidence scores

### Transportation

- fixed source linear references: the `sources` array for segment features previously dropped positional information (`between`) on the last source entry; now the `sources` array has correct linear references, and adjacent ranges with identical values are merged into cleaner, more compact output

- cleaned up routes: `routes` with no identifying properties and duplicate entries covering adjacent sub-ranges have been removed

- added more accurate timestamps: `update_time` in the `sources` array now reflects the most recent timestamp across both the feature and its components, a change that accounts for ~90M source-level differences (~28% of segments) but does not affect source identity or count.

## Schema changelog

The changelog for Overture schema `v1.16.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).

---

## 2026-04-15 release notes

## Overview

**The `2026-04-15.0` release of Overture data and `v1.16.0` of the Overture schema are now available.** You can access the datasets, changelog, GERS registry, bridge files, and PMTiles on AWS and Azure at the paths listed below. 

## Deprecations
The `categories` property in the places schema is now deprecated and will be removed in the June 2026 release, replaced by the new `basic_category` and `taxonomy` properties. All three properties will be available until then to ease the transition for our users. The taxonomy documentation is [here](https://docs.overturemaps.org/guides/places/taxonomy/).

## Getting the data and release artifacts

You can access this month's data and release artifacts by following the process outlined [here](/getting-data). The paths to the data and release artifacts are listed below. We encourage you to ask questions and provide feedback on the Overture Maps [Discussion forum on GitHub](https://github.com/orgs/OvertureMaps/discussions). You can also file issues and report bugs in our [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repositories. If you have a suggestion for a new dataset or if you have data you'd like to contribute to Overture, you can email us at community@overturemaps.org. We’d love to hear from you.

### Release data

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/release/2026-04-15.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/release/2026-04-15.0/
```
### Data changelog

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/changelog/2026-04-15.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/changelog/2026-04-15.0/
```

### Bridge files

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/bridgefiles/2026-04-15.0/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/bridgefiles/2026-04-15.0/
```

### GERS registry

**Microsoft Azure:**
```
az://overturemapswestus2.blob.core.windows.net/registry/
```

**Amazon S3:**
```
s3://overturemaps-us-west-2/registry/
```

### PMTiles

**Amazon S3:**
```
s3://overturemaps-extras-us-west-2/tiles/2026-04-15.0/
```

{/* truncate */}

## Theme-specific updates

:::info
The base, buildings, divisions, places, and transportation themes are in GA. The addresses theme is in alpha. 
:::

### Addresses

- refreshed the NAD data source: now using v22
- de-duplicated data from the Državna geodetska uprava source, used for Croatian addresses

### Base
- made minor, incremental updates to the data

### Buildings
- removed ~98M Google and Zenodo sourced building features with small areas

### Divisions
- no changes

### Places
- confidence score updates: The March release contained unexpected changes to our confidence score normalization in Meta-sourced place data. This April release rolls back those changes. We have also increased the number of signals to our places data; ~10M places now receive updated confidence scores based on third-party signal data.

### Transportation

- OSM Cut-Off Date: `2026-04-04`

| Dataset | Feature Count | Length (km) |
|---|---|---|
| OpenStreetMap | 745,146,752 | 93,767,467 |
| TomTom | 8,758,473 | 1,528,165 |

| Subtype | Length (km) |
|---|---|
| road | 91,854,341 |
| rail | 2,859,987 |
| water | 581,304 |

#### Change Summary

##### Count Changes

| Dataset | Type | Diff | Diff (%) |
|---|---|---|---|
| TomTom | segment | 53,123 | 0.61% |
| OpenStreetMap | connector | 1,812,753 | 0.44% |
| OpenStreetMap | segment | 1,097,100 | 0.33% |

##### Length Changes

| Subtype | Diff (km) | Diff (%) |
|---|---|---|
| road | 258,124.28 | 0.28% |
| rail | 3,893.76 | 0.14% |
| water | 329.78 | 0.06% |

## Schema changelog

The changelog for Overture schema `v1.16.0` is [here](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0).

## Attribution

You'll find information about attribution and licensing [here](/attribution).