From b36c0fd971792b4a7dfc401873009c5897c425bd Mon Sep 17 00:00:00 2001 From: Dana Bauer Date: Fri, 13 Feb 2026 16:06:06 -0500 Subject: [PATCH 1/3] add taxomony to places guide --- docs/gers/registry.mdx | 62 ------------- .../{addresses.mdx => addresses/overview.mdx} | 3 +- docs/guides/{base.mdx => base/overview.mdx} | 3 +- .../{buildings.mdx => buildings/overview.mdx} | 3 +- .../{divisions.mdx => divisions/overview.mdx} | 3 +- .../{places.mdx => places/overview.mdx} | 12 +-- docs/guides/places/taxonomy.mdx | 86 +++++++++++++++++++ .../overview.mdx} | 3 +- sidebars.js | 70 ++++++++++++--- 9 files changed, 156 insertions(+), 89 deletions(-) delete mode 100644 docs/gers/registry.mdx rename docs/guides/{addresses.mdx => addresses/overview.mdx} (99%) rename docs/guides/{base.mdx => base/overview.mdx} (99%) rename docs/guides/{buildings.mdx => buildings/overview.mdx} (99%) rename docs/guides/{divisions.mdx => divisions/overview.mdx} (99%) rename docs/guides/{places.mdx => places/overview.mdx} (96%) create mode 100644 docs/guides/places/taxonomy.mdx rename docs/guides/{transportation.mdx => transportation/overview.mdx} (99%) diff --git a/docs/gers/registry.mdx b/docs/gers/registry.mdx deleted file mode 100644 index 1a6d28772..000000000 --- a/docs/gers/registry.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Registry ---- - -import QueryBuilder from '@site/src/components/queryBuilder'; - -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. - - diff --git a/docs/guides/addresses.mdx b/docs/guides/addresses/overview.mdx similarity index 99% rename from docs/guides/addresses.mdx rename to docs/guides/addresses/overview.mdx index dec114ca7..46804a0d9 100644 --- a/docs/guides/addresses.mdx +++ b/docs/guides/addresses/overview.mdx @@ -1,6 +1,7 @@ --- -title: Addresses +title: Overview description: A collection of global address points +slug: /guides/addresses/ --- import Tabs from '@theme/Tabs'; diff --git a/docs/guides/base.mdx b/docs/guides/base/overview.mdx similarity index 99% rename from docs/guides/base.mdx rename to docs/guides/base/overview.mdx index 445ef5289..cc6f87e58 100644 --- a/docs/guides/base.mdx +++ b/docs/guides/base/overview.mdx @@ -1,6 +1,7 @@ --- -title: Base +title: Overview description: Bathymetry, Infrastructure, Land, Landuse, Landcover, and Water features. +slug: /guides/base/ --- import Tabs from '@theme/Tabs'; diff --git a/docs/guides/buildings.mdx b/docs/guides/buildings/overview.mdx similarity index 99% rename from docs/guides/buildings.mdx rename to docs/guides/buildings/overview.mdx index 216625421..d8412ac71 100644 --- a/docs/guides/buildings.mdx +++ b/docs/guides/buildings/overview.mdx @@ -1,6 +1,7 @@ --- -title: Buildings +title: Overview description: 2.6 billion buildings and counting +slug: /guides/buildings/ --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import QueryBuilder from '@site/src/components/queryBuilder'; import ThemedImage from '@theme/ThemedImage'; import useBaseUrl from '@docusaurus/useBaseUrl'; diff --git a/docs/guides/divisions.mdx b/docs/guides/divisions/overview.mdx similarity index 99% rename from docs/guides/divisions.mdx rename to docs/guides/divisions/overview.mdx index 55527f817..997181614 100644 --- a/docs/guides/divisions.mdx +++ b/docs/guides/divisions/overview.mdx @@ -1,6 +1,7 @@ --- -title: Divisions +title: Overview description: Global administrative data, from microhoods to countries +slug: /guides/divisions/ --- import Tabs from '@theme/Tabs'; diff --git a/docs/guides/places.mdx b/docs/guides/places/overview.mdx similarity index 96% rename from docs/guides/places.mdx rename to docs/guides/places/overview.mdx index 72d0c4af5..17e54d387 100644 --- a/docs/guides/places.mdx +++ b/docs/guides/places/overview.mdx @@ -1,6 +1,7 @@ --- -title: Places -description: 64M+ places and points of interest around the world +title: Overview +description: Points of interest around the world +slug: /guides/places/ --- import Tabs from '@theme/Tabs'; @@ -14,13 +15,6 @@ import ConfidenceQuery from '!!raw-loader!@site/src/queries/duckdb/places_confid import ConflateOSMQuery from '!!raw-loader!@site/src/queries/duckdb/places_conflating_OSM.sql'; import PlacesInBuildingsQuery from '!!raw-loader!@site/src/queries/duckdb/places_in_buildings.sql'; -:::note - -This guide is focused on the Overture places **data**—its content, scope, properties, and use cases. Please see the [schema reference documentation](/schema/reference/places/place) for more information on the Overture places **schema**. - -::: - -## Overview 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. diff --git a/docs/guides/places/taxonomy.mdx b/docs/guides/places/taxonomy.mdx new file mode 100644 index 000000000..bcc3cea22 --- /dev/null +++ b/docs/guides/places/taxonomy.mdx @@ -0,0 +1,86 @@ +--- +title: Taxonomy +description: How we organize categories of places +--- + +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. We encourage users to provide [feedback](https://github.com/orgs/OvertureMaps/discussions) on the new structure and make 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 | + + diff --git a/docs/guides/transportation.mdx b/docs/guides/transportation/overview.mdx similarity index 99% rename from docs/guides/transportation.mdx rename to docs/guides/transportation/overview.mdx index a2a7cadbe..de182e759 100644 --- a/docs/guides/transportation.mdx +++ b/docs/guides/transportation/overview.mdx @@ -1,6 +1,7 @@ --- -title: Transportation +title: Overview description: Global road, rail, and water transportation data +slug: /guides/transportation/ --- import Tabs from '@theme/Tabs'; diff --git a/sidebars.js b/sidebars.js index d6dae5cac..523dcf557 100644 --- a/sidebars.js +++ b/sidebars.js @@ -5,9 +5,12 @@ const sidebars = { { type: 'category', label: 'Getting Started', + link: { + type: 'doc', + id: 'getting-data/index' + }, collapsed: true, items: [ - 'getting-data/index', 'getting-data/duckdb', 'getting-data/overturemaps-py', 'getting-data/athena-aws', @@ -48,7 +51,7 @@ const sidebars = { 'examples/wherobots', ] }, - { + { type: 'category', label: 'Data Guides', link: { @@ -57,12 +60,55 @@ const sidebars = { }, collapsed: true, items: [ - 'guides/addresses', - 'guides/base', - 'guides/buildings', - 'guides/divisions', - 'guides/places', - 'guides/transportation', + { + type: 'category', + label: 'Addresses', + collapsed: true, + items: [ + 'guides/addresses/overview', + ], + }, + { + type: 'category', + label: 'Base', + collapsed: true, + items: [ + 'guides/base/overview', + ], + }, + { + type: 'category', + label: 'Buildings', + collapsed: true, + items: [ + 'guides/buildings/overview', + ], + }, + { + type: 'category', + label: 'Divisions', + collapsed: true, + items: [ + 'guides/divisions/overview', + ], + }, + { + type: 'category', + label: 'Places', + collapsed: true, + items: [ + 'guides/places/overview', + 'guides/places/taxonomy', + ], + }, + { + type: 'category', + label: 'Transportation', + collapsed: true, + items: [ + 'guides/transportation/overview', + ], + }, ], }, { @@ -77,18 +123,16 @@ const sidebars = { 'gers/registry', 'gers/gers-tutorial', 'gers/gers-demonstrations', - ] }, 'attribution', 'release-calendar' ], - schema:[ + schema: [ { type: 'autogenerated', - dirName: 'schema', // generate sidebar slice from the docs folder (or versioned_docs/) + dirName: 'schema', } ] }; - -module.exports = sidebars; +module.exports = sidebars; \ No newline at end of file From 70e1312f98c67c5d96d30d7df49488e744ce11d5 Mon Sep 17 00:00:00 2001 From: Dana Bauer Date: Fri, 13 Feb 2026 16:12:02 -0500 Subject: [PATCH 2/3] restore registry page --- docs/gers/registry.mdx | 62 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/gers/registry.mdx diff --git a/docs/gers/registry.mdx b/docs/gers/registry.mdx new file mode 100644 index 000000000..1a6d28772 --- /dev/null +++ b/docs/gers/registry.mdx @@ -0,0 +1,62 @@ +--- +title: Registry +--- + +import QueryBuilder from '@site/src/components/queryBuilder'; + +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. + + From 9ad6438d2ce6650e30ac39571b0ac1d4d090645d Mon Sep 17 00:00:00 2001 From: Dana Bauer Date: Fri, 13 Feb 2026 18:34:28 -0500 Subject: [PATCH 3/3] add link to category mappings --- docs/guides/places/taxonomy.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/places/taxonomy.mdx b/docs/guides/places/taxonomy.mdx index bcc3cea22..f0c1432ac 100644 --- a/docs/guides/places/taxonomy.mdx +++ b/docs/guides/places/taxonomy.mdx @@ -7,7 +7,7 @@ Recently, Overture introduced new `basic_category` and `taxonomy` properties for :::tip -The original `categories` property will be available alongside the new `basic_category` and `taxonomy` properties for several months. We encourage users to provide [feedback](https://github.com/orgs/OvertureMaps/discussions) on the new structure and make suggestions for further improvement. +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. ::: @@ -28,6 +28,7 @@ Users should be aware of the following key updates when evaluating and integrati ## 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.