add taxonomy info to places guide

docs/guides/addresses.mdx → 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';

docs/guides/base.mdx → 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';

docs/guides/buildings.mdx → 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';

docs/guides/divisions.mdx → 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';

docs/guides/places.mdx → 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.
 

docs/guides/places/taxonomy.mdx

@@ -0,0 +1,87 @@
+---
+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. 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 | 
+
+

docs/guides/transportation.mdx → 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';

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/<version>)
+      dirName: 'schema',
     }
   ]
 };
-
-module.exports = sidebars;
+module.exports = sidebars;