### Installation

Source: https://docs.overturemaps.org/getting-data/overturemaps-py

Instructions for installing the Overture Maps Python client using pip or conda, and how to run it without installation using uvx.

```APIDOC
## Installation

Install the package using pip:
```
pip install overturemaps
```

Or using conda:
```
conda install -c conda-forge overturemaps
```

To run without installation using uvx:
```
uvx overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=building -o boston.geojson
```
```

--------------------------------

### Install Fused Library

Source: https://docs.overturemaps.org/getting-data/data-mirrors/fused

Installs the Fused Python library with all optional dependencies using pip. This is the first step to using Fused functionalities.

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

--------------------------------

### Install Overture Maps Client

Source: https://docs.overturemaps.org/getting-data/overturemaps-py

Instructions for installing the Overture Maps Python package using standard package managers. It is available via pip and conda-forge.

```bash
pip install overturemaps
```

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

--------------------------------

### Querying Changelog with DuckDB (Example 1)

Source: https://docs.overturemaps.org/gers/changelog

This example demonstrates how to query the changelog using DuckDB to retrieve the ID, type, and change type for buildings within a specific geographic bounding box in Ethiopia.

```APIDOC
## Querying Changelog with DuckDB (Example 1)

### Description
This query uses DuckDB to fetch `id`, `type`, and `change_type` for building entities within a specified bounding box in the Amhara Region, Ethiopia, from a particular release of the changelog.

### Method
SQL (using DuckDB)

### Endpoint
N/A (Local query against cloud storage)

### Parameters

#### Query Parameters
- **release**: The specific release version of the changelog (e.g., `2024-06-13-beta.0`).
- **theme**: The data theme to query (e.g., `buildings`).
- **type**: Wildcard for entity types.
- **change_type**: Wildcard for change types.
- **bbox.xmin**, **bbox.xmax**, **bbox.ymin**, **bbox.ymax**: Bounding box coordinates for spatial filtering.

### Request Example
```sql
LOAD spatial;
LOAD httpfs;
SET s3_region='us-west-2';

SELECT id, type, change_type
FROM read_parquet('s3://overturemaps-us-west-2/changelog/2024-06-13-beta.0/theme=buildings/type=*/change_type=*/*', filename=true, hive_partitioning=1)
WHERE
        bbox.xmin > 37.165914
        AND bbox.xmax < 37.902271
        AND bbox.ymin > 10.221917
        AND bbox.ymax < 10.751245;
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the entity.
- **type** (string) - The type of the entity (e.g., 'building').
- **change_type** (string) - The type of change recorded for the entity ('added', 'removed', 'data_changed', 'unchanged').

#### Response Example
```json
{
  "id": "some_building_id",
  "type": "building",
  "change_type": "added"
}
```
```

--------------------------------

### Address Schema Example

Source: https://docs.overturemaps.org/schema/reference/addresses/address

An example demonstrating the structure and values for an address feature.

```APIDOC
## Address Schema Example

### Description
This example illustrates a complete address object, showcasing the populated fields and their corresponding values.

### Request Body Example
```json
{
  "id": "416ab01c-d836-4c4f-aedc-2f30941ce94d",
  "bbox": {
    "xmin": -176.56381225585938,
    "xmax": -176.56378173828125,
    "ymin": -43.94719696044922,
    "ymax": -43.94718933105469
  },
  "geometry": {
    "type": "Point",
    "coordinates": [-176.5637854, -43.9471955]
  },
  "theme": "addresses",
  "type": "address",
  "version": "1",
  "sources": [
    {
      "property": null,
      "dataset": "OpenAddresses/LINZ",
      "record_id": null,
      "update_time": null,
      "confidence": null,
      "between": null
    }
  ],
  "address_levels": [
    {
      "value": "Chatham Islands"
    },
    {
      "value": "Chatham Island"
    }
  ],
  "country": "NZ",
  "number": "54",
  "postal_city": null,
  "postcode": null,
  "street": "Tikitiki Hill Road",
  "unit": null
}
```
```

--------------------------------

### Docker Setup for Sedona

Source: https://docs.overturemaps.org/examples/sedona

Commands to pull and run a single-node Apache Sedona Docker image. This provides a local environment for testing and development.

```bash
docker pull apache/sedona
docker run -p 8888:8888 apache/sedona:latest
```

--------------------------------

### Initialize DuckDB and Load Spatial Extensions

Source: https://docs.overturemaps.org/gers/gers-tutorial

Starts the DuckDB CLI and installs/loads the necessary spatial and httpfs extensions required for processing geospatial data and reading from S3.

```sql
duckdb inspection_match.ddb
INSTALL spatial;
LOAD spatial;
INSTALL httpfs;
LOAD httpfs;
```

--------------------------------

### Water Feature Example

Source: https://docs.overturemaps.org/schema/reference/base/water

An example of a water feature with its associated fields and values.

```APIDOC
## Water Feature Example

This example demonstrates the structure and typical values for a water feature.

### Request Example

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

### Response Example

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

--------------------------------

### Install DuckDB Spatial Extension

Source: https://docs.overturemaps.org/getting-data/duckdb

Installs the SPATIAL extension for DuckDB, enabling support for spatial data types and operations. This is a prerequisite for working with spatial data in DuckDB.

```sql
INSTALL SPATIAL;
```

--------------------------------

### Overture Schema Example

Source: https://docs.overturemaps.org/guides/transportation/segments-and-connectors

Illustrates how classes, subclasses, and flags are modeled within the Overture schema for transportation features.

```APIDOC
## Overture Schema Modeling Example

### Description
This example demonstrates the structure for defining classes, subclasses, and flags for transportation segments in the Overture schema. It shows how properties like `road_flags` and `subclass_rules` can be applied with specific values and geometric ranges.

### Code Example
```
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
```
```

--------------------------------

### Query Overture GeoParquet with DuckDB

Source: https://docs.overturemaps.org/getting-data

Demonstrates how to use DuckDB to query cloud-hosted GeoParquet files. This example filters for specific locations and exports the result to a GeoJSON file.

```sql
LOAD spatial; --noqa
LOAD httpfs; --noqa

SET s3_region = 'us-west-2';

COPY(
  SELECT
    id,
    names.primary as name,
    categories.primary as category,
    addresses[1].freeform as address,
    geometry
  FROM read_parquet(
    's3://overturemaps-us-west-2/release/2026-03-18.0/theme=places/type=place/*',
    filename=true, hive_partitioning=1)
  WHERE
    names.primary ILIKE '%wawa%'
    AND bbox.xmin BETWEEN -76.5 AND -74.5
    AND bbox.ymin BETWEEN 39.5 AND 40.5
) TO 'wawa_stores.geojson' WITH (FORMAT GDAL, DRIVER 'GeoJSON');
```

--------------------------------

### Downloading Data with Overture CLI

Source: https://docs.overturemaps.org/guides/divisions

Example of how to download Overture divisions data for a specific bounding box using the Overture Maps command-line interface.

```APIDOC
## Downloading Data with Overture CLI

### Description
This example demonstrates how to use the Overture Maps CLI tool to download divisions data for a specified bounding box and save it as a GeoJSON file.

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

### Parameters
- **--bbox** (string) - Required - Bounding box coordinates (min_lon,min_lat,max_lon,max_lat) to define the area of interest.
- **-f** or **--format** (string) - Required - Output file format (e.g., geojson).
- **--type** (string) - Required - The type of Overture data to download (e.g., division).
- **-o** or **--output** (string) - Required - The name of the output file.
```

--------------------------------

### Define Overture Places Schema Properties

Source: https://docs.overturemaps.org/blog/2025/12/17/release-notes

Examples demonstrating the evolution of the Overture Places schema from the original categories system to the new hierarchical taxonomy structure.

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

```yaml
properties:
   basic_category: casual_eatery
   categories:
      primary: gas_station_sushi
      alternate:
         - bait_and_tackle
```

```yaml
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
```

--------------------------------

### Querying Changelog with Athena

Source: https://docs.overturemaps.org/gers/changelog

This example shows how to use Amazon Athena to join the changelog data with the main data release, allowing for the retrieval of entity properties alongside change type information.

```APIDOC
## Querying Changelog with Athena

### Description
This query uses Amazon Athena to join the changelog data with the main data release. It allows retrieval of entity properties, geometry, and the `change_type` for entities within a specified bounding box and theme.

### Method
SQL (using Amazon Athena)

### Endpoint
N/A (Querying tables in Athena)

### Parameters

#### Path Parameters
- **vYYYY_MM_DD_HH_MM_SS**: Represents the version of the main data release table (e.g., `v2026_03_18_0`).
- **changelog_vYYYY_MM_DD_HH_MM_SS**: Represents the version of the changelog table (e.g., `changelog_v2024_07_22_0`).

#### Query Parameters
- **release.theme**: The data theme to filter by (e.g., 'buildings').
- **release.bbox.xmin**, **release.bbox.xmax**, **release.bbox.ymin**, **release.bbox.ymax**: Bounding box coordinates for spatial filtering.

### Request Example
```sql
SELECT
    release.id,
    release.names."primary" AS primary_name,
    release.sources [ 1 ].dataset AS primary_source,
    changelog.change_type,
    ST_GEOMFROMBINARY(geometry) AS geometry
FROM v2026_03_18_0 AS release
    INNER JOIN changelog_v2024_07_22_0 AS changelog ON release.id = changelog.id
WHERE release.theme = 'buildings'
    AND release.bbox.xmin > 37.165914
    AND release.bbox.xmax < 37.902271
    AND release.bbox.ymin > 10.221917
    AND release.bbox.ymax < 10.751245;
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the entity.
- **primary_name** (string) - The primary name of the entity.
- **primary_source** (string) - The dataset that is the primary source for this entity.
- **change_type** (string) - The type of change recorded for the entity ('added', 'removed', 'data_changed', 'unchanged').
- **geometry** (geometry) - The spatial geometry of the entity.

#### Response Example
```json
{
  "id": "building_xyz",
  "primary_name": "Example Building",
  "primary_source": "Microsoft Buildings",
  "change_type": "data_changed",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [37.165914, 10.221917],
        [37.902271, 10.221917],
        [37.902271, 10.751245],
        [37.165914, 10.751245],
        [37.165914, 10.221917]
      ]
    ]
  }
}
```
```

--------------------------------

### Define segment geometry orientation

Source: https://docs.overturemaps.org/guides/transportation/segments-and-connectors

Examples of defining LineString geometry to represent segments oriented in specific cardinal directions based on start and end coordinates.

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

---

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

--------------------------------

### Initialize Spark Session and Configuration

Source: https://docs.overturemaps.org/examples/spark

Sets up a SparkSession and defines constants for the Overture release version and S3 data source path.

```python
import pyspark.sql.functions as F
from pyspark.sql import SparkSession

spark = SparkSession.builder.getOrCreate()

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"
```

--------------------------------

### Initialize Environment and DuckDB Extensions

Source: https://docs.overturemaps.org/examples/pandas

Imports necessary libraries and configures the Jupyter environment with DuckDB extensions for spatial data and S3 connectivity.

```python
import pandas as pd
import geopandas as gpd
import duckdb
from shapely import wkt
%reload_ext sql
%sql duckdb://
%sql INSTALL spatial;
%sql INSTALL httpfs;
%sql LOAD spatial;
%sql LOAD httpfs;
%sql SET s3_region='us-west-2'
```

--------------------------------

### Via Turn Restriction Example

Source: https://docs.overturemaps.org/guides/transportation/roads

This example illustrates a via turn restriction, which is used for more complex scenarios where the sequence of maneuvers is important. This is a conceptual example as the provided text focuses on simple restrictions.

```APIDOC
## POST /websites/overturemaps/via-turn-restrictions

### Description
This endpoint is used to define 'via' turn restrictions, which are applicable in complex scenarios requiring a sequence of maneuvers. This is a conceptual endpoint as the provided text focuses on simple restrictions.

### Method
POST

### Endpoint
/websites/overturemaps/via-turn-restrictions

### Parameters
#### Request Body
- **sequence** (array) - Required - An array of objects, each defining a segment and connector in the maneuver sequence.
  - **segment_id** (string) - Required - The ID of the road segment.
  - **connector_id** (string) - Required - The ID of the connector on the segment.
- **final_heading** (string) - Required - The required heading upon completion of the maneuver sequence.
- **when** (object) - Optional - Conditions under which the restriction applies.

### Request Example
```json
{
  "sequence": [
    {
      "segment_id": "overture:transportation:example:via-turn-restriction-source",
      "connector_id": "overture:transportation:example:via-turn-restriction-connector1"
    },
    {
      "segment_id": "overture:transportation:example:via-turn-restriction-intermediate",
      "connector_id": "overture:transportation:example:via-turn-restriction-intermediate-connector"
    }
  ],
  "final_heading": "forward",
  "when": {
    "heading": "forward"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the via turn restriction was added.

#### Response Example
```json
{
  "message": "Via turn restriction successfully added."
}
```
```

--------------------------------

### Install PySpark Dependency

Source: https://docs.overturemaps.org/examples/spark

Installs the necessary PySpark library required for distributed data processing in a Python environment.

```bash
pip install pyspark
```

--------------------------------

### Simple Turn Restriction Example

Source: https://docs.overturemaps.org/guides/transportation/roads

This example demonstrates a simple turn restriction where a right turn from a source segment onto a target segment is prohibited.

```APIDOC
## POST /websites/overturemaps/turn-restrictions

### Description
This endpoint allows for the definition and management of turn restrictions on road segments. Turn restrictions limit allowed transitions between connected road segments.

### Method
POST

### Endpoint
/websites/overturemaps/turn-restrictions

### Parameters
#### Request Body
- **source_segment_id** (string) - Required - The ID of the source road segment.
- **target_segment_id** (string) - Required - The ID of the target road segment.
- **restriction_type** (string) - Required - The type of restriction (e.g., "no_right_turn", "no_u_turn").
- **connector_id** (string) - Optional - The ID of the connector where the restriction applies.
- **when** (object) - Optional - Conditions under which the restriction applies (e.g., time of day, heading).

### Request Example
```json
{
  "source_segment_id": "overture:transportation:example:simple-turn-restriction-source",
  "target_segment_id": "overture:transportation:example:simple-turn-restriction-target",
  "restriction_type": "no_right_turn",
  "connector_id": "overture:transportation:example:simple-turn-restriction-connector2",
  "when": {
    "heading": "forward"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the turn restriction was added.

#### Response Example
```json
{
  "message": "Turn restriction successfully added."
}
```
```

--------------------------------

### Initialize Sedona Context for Wherobots

Source: https://docs.overturemaps.org/examples/wherobots

Sets up the Sedona environment by importing necessary PySpark modules and initializing the SedonaContext. This is required to execute spatial operations in a Wherobots notebook.

```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)
```

--------------------------------

### Deploy Overture Tiles CDK Stack on AWS

Source: https://docs.overturemaps.org/examples/overture-tiles

Deploys the overture-tiles CDK stack to AWS for automated tile generation. This process involves bootstrapping the CDK, deploying the stack, and authenticating Docker for ECR. Prerequisites include AWS CLI, AWS CDK, and Docker Desktop.

```bash
npm run cdk bootstrap
npm run cdk deploy
```

--------------------------------

### Fetch and Visualize Building Data using GeoPandas and Lonboard PolygonLayer

Source: https://docs.overturemaps.org/examples/lonboard

This example shows how to fetch Overture building data, convert it to a GeoPandas GeoDataFrame, and visualize it using Lonboard's PolygonLayer. It involves reading data into a PyArrow table, converting to a Pandas DataFrame, and then to a GeoDataFrame with Shapely geometries. Dependencies include overturemaps-py, pandas, geopandas, shapely, and lonboard.

```python
import overturemaps
import pandas
import geopandas as gpd
from shapely import wkb
from lonboard import Map, PolygonLayer

# specify bounding box
bbox = 9.125034,45.433352,9.245223,45.507116

# need feature type and bounding box as arguments
table = overturemaps.record_batch_reader("building", bbox).read_all()
table = table.combine_chunks()

# convert to dataframe
df = table.to_pandas()

# DataFrame to GeoDataFrame, set crs
gdf = gpd.GeoDataFrame(
    df,
    geometry=df['geometry'].apply(wkb.loads),
    crs="EPSG:4326"
)

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
```

--------------------------------

### Install DuckDB Cloud Storage Extensions

Source: https://docs.overturemaps.org/getting-data/duckdb

Installs extensions for DuckDB to read data from cloud storage services. Choose 'httpfs' for Amazon S3 or 'azure' for Microsoft Azure Blob Storage. These extensions allow DuckDB to access remote files directly.

```sql
INSTALL httpfs;
```

```sql
INSTALL azure;
```

--------------------------------

### Query Overture Changelog with DuckDB

Source: https://docs.overturemaps.org/gers/changelog

Demonstrates how to query building changes within a specific geographic bounding box using DuckDB and S3 Parquet files. Requires the spatial and httpfs extensions to be loaded.

```sql
LOAD spatial; -- noqa
LOAD httpfs; -- noqa
SET s3_region='us-west-2';

SELECT id, type, change_type
FROM read_parquet('s3://overturemaps-us-west-2/changelog/2024-06-13-beta.0/theme=buildings/type=*/change_type=*/*', filename=true, hive_partitioning=1)
WHERE
        bbox.xmin > 37.165914
        AND bbox.xmax < 37.902271
        AND bbox.ymin > 10.221917
        AND bbox.ymax < 10.751245;
```

--------------------------------

### Download Overture Divisions Data with Overture CLI

Source: https://docs.overturemaps.org/guides/divisions

This command-line example demonstrates how to download Overture divisions data for a specific bounding box using the Overture CLI. It specifies the bounding box coordinates, output format (GeoJSON), feature type, and output filename.

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

--------------------------------

### LanguageTag Definition

Source: https://docs.overturemaps.org/schema/reference/system/language_tag

Defines the LanguageTag data type, its purpose, and examples.

```APIDOC
## LanguageTag

### Description
A BCP-47 language tag. As described in `Tags for Identifying Languages, BCP-47`_.

### Examples
  * "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`
  * `NameRule`
  * `Names`
  * `CommonNames`
```

--------------------------------

### Load Overture Data via DataFrame and SQL APIs

Source: https://docs.overturemaps.org/examples/wherobots

Demonstrates two methods to load Overture Maps datasets into a notebook environment. The DataFrame API provides direct table access, while the SQL API allows for custom query execution and temporary view creation.

```python
# DataFrame API
places_df = sedona.table("wherobots_open_data.overture_maps_foundation.places_place")
places_df.show(5)

# SQL API
places_df = sedona.sql("""
    SELECT * FROM wherobots_open_data.overture_maps_foundation.places_place
""")
places_df.createOrReplaceTempView("places")
places_df.show(5)
```

--------------------------------

### GET /divisions/division_area

Source: https://docs.overturemaps.org/schema/reference/divisions/division_area

Retrieves the definition and schema for the DivisionArea feature type.

```APIDOC
## GET /divisions/division_area

### Description
Retrieves the schema definition for a DivisionArea, which represents a polygon area for a specific administrative division.

### Method
GET

### Endpoint
/divisions/division_area

### Parameters
#### Path Parameters
- **id** (Id) - Required - The unique identifier for the division area feature.

### Request Example
GET /divisions/division_area/eb9b112f-ec3c-47f7-b519-6f9f2e6fc2bd

### Response
#### Success Response (200)
- **id** (Id) - The feature ID.
- **geometry** (geometry) - The MultiPolygon or Polygon representing the area.
- **division_id** (Id) - Reference to the parent division.
- **country** (CountryCodeAlpha2) - ISO 3166-1 alpha-2 code.
- **is_land** (boolean) - Indicates if the geometry represents land.
- **is_territorial** (boolean) - Indicates if the geometry represents a maritime boundary.

#### Response Example
{
  "id": "eb9b112f-ec3c-47f7-b519-6f9f2e6fc2bd",
  "theme": "divisions",
  "type": "division_area",
  "subtype": "region",
  "division_id": "21597af0-b564-463c-a356-42c29e712b7d",
  "country": "TO",
  "is_land": true,
  "is_territorial": false
}
```

--------------------------------

### GET /buildings/building_part

Source: https://docs.overturemaps.org/schema/reference/buildings/building_part

Retrieves the schema and field definitions for a BuildingPart feature.

```APIDOC
## GET /buildings/building_part

### Description
Retrieves the structural definition of a BuildingPart, which represents a segment of a larger building feature used for 3D modeling.

### Method
GET

### Endpoint
/buildings/building_part

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
{
  "query": "get_schema",
  "feature_type": "building_part"
}

### Response
#### Success Response (200)
- **id** (Id) - Unique feature identifier
- **building_id** (Id) - Reference to the parent building
- **geometry** (Polygon/MultiPolygon) - Footprint of the part
- **height** (float64) - Total height in meters
- **num_floors** (int32) - Number of above-ground floors

#### Response Example
{
  "id": "12345",
  "building_id": "parent_bldg_001",
  "geometry": {"type": "Polygon", "coordinates": [...]},
  "height": 15.5,
  "num_floors": 4
}
```

--------------------------------

### Download Data by Bounding Box

Source: https://docs.overturemaps.org/getting-data/overturemaps-py

How to use the `overturemaps download` command to retrieve data within a specified bounding box and output it to a chosen format.

```APIDOC
## `overturemaps download`

The `overturemaps download` command downloads Overture data within an optional bounding box into a specified file format. Results are streamed, allowing for arbitrarily large areas.

### Usage Example

```
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` or `-t` | Feature type to download (e.g., `building`, `place`, `segment`, `address`). Run `overturemaps download --help` for a complete list. |
| `--output` or `-o` | Output file path. Omit to write to stdout. |
| `--stac`/`--no-stac` | Use Overture's STAC catalog to speed up queries (default: on). |
```

--------------------------------

### Access Restrictions: Blanket Denial

Source: https://docs.overturemaps.org/guides/transportation/roads

Example of a road segment with a blanket denial of access for all users.

```APIDOC
## Access Restrictions: Blanket Denial

### Description
This example demonstrates a road segment where access is denied to everyone.

### Method
N/A (Data Representation)

### Endpoint
N/A (Data Representation)

### Request Body
```json
{
  "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"
      }
    ]
  }
}
```

### Response
#### Success Response (200)
N/A (Data Representation)

#### Response Example
```json
{
  "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"
      }
    ]
  }
}
```
```

--------------------------------

### Download Overture Data via CLI

Source: https://docs.overturemaps.org/getting-data/overturemaps-py

Demonstrates how to download Overture geospatial data using the command line. Supports bounding box filtering, format selection, and feature type specification.

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

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

--------------------------------

### GET /infrastructure/classes

Source: https://docs.overturemaps.org/schema/reference/base/types/infrastructure_class

Retrieves the list of valid InfrastructureClass values used for categorizing infrastructure assets.

```APIDOC
## GET /infrastructure/classes

### Description
Returns a comprehensive list of all supported infrastructure class identifiers used within the Overture Maps schema.

### Method
GET

### Endpoint
/infrastructure/classes

### Parameters
None

### Response
#### Success Response (200)
- **classes** (array) - A list of strings representing valid infrastructure class types.

#### Response Example
{
  "classes": [
    "aerialway_station",
    "airport",
    "bridge",
    "power_line",
    "water_tower"
  ]
}
```

--------------------------------

### Access Restrictions: Private with Deliveries

Source: https://docs.overturemaps.org/guides/transportation/roads

Example of a road segment that is private but allows deliveries during business hours.

```APIDOC
## Access Restrictions: Private with Deliveries

### Description
This example shows a road segment that is generally denied access, but allows recognized private access and deliveries during specific hours.

### Method
N/A (Data Representation)

### Endpoint
N/A (Data Representation)

### Request Body
```json
{
  "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"
        }
      }
    ]
  }
}
```

### Response
#### Success Response (200)
N/A (Data Representation)

#### Response Example
```json
{
  "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"
        }
      }
    ]
  }
}
```
```

--------------------------------

### GET /divisions/boundary

Source: https://docs.overturemaps.org/schema/reference/divisions/division_boundary

Retrieves division boundary data with specific constraints on administrative levels and territorial properties.

```APIDOC
## GET /divisions/boundary

### Description
Retrieves division boundary records. The response includes geometry, theme, and classification properties. Boundaries must satisfy specific constraints regarding land/territorial status and administrative levels.

### Method
GET

### Endpoint
/divisions/boundary

### Parameters
#### Query Parameters
- **country** (string) - Optional - Filter boundaries by country code.
- **subtype** (string) - Optional - Filter by division subtype (e.g., county, region, country).

### Request Example
{
  "country": "PF"
}

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the boundary.
- **geometry** (string) - LINESTRING geometry representation.
- **subtype** (string) - The administrative subtype (e.g., county).
- **is_land** (boolean) - Indicates if the boundary is on land.
- **is_territorial** (boolean) - Indicates if the boundary is territorial.

#### Response Example
{
  "id": "2bdf68e4-860d-3d8c-a472-ccf439a5302a",
  "subtype": "county",
  "is_land": false,
  "is_territorial": true,
  "country": "PF"
}
```

--------------------------------

### Fetch and Visualize Road Data using PyArrow and Lonboard PathLayer

Source: https://docs.overturemaps.org/examples/lonboard

This snippet demonstrates fetching Overture road data using overturemaps-py's record_batch_reader and visualizing it with Lonboard's PathLayer. It loads data directly into a PyArrow table, suitable for large datasets, and configures an interactive map view. Dependencies include overturemaps-py, lonboard, and pandas.

```python
import overturemaps
from lonboard import Map, PathLayer

# specify bounding box in Milan
bbox = 9.125034,45.433352,9.245223,45.507116

# need feature type and bounding box as arguments
table = overturemaps.record_batch_reader("segment", bbox).read_all()

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
```

--------------------------------

### Query Overture Maps Buildings with DuckDB

Source: https://docs.overturemaps.org/blog/2024/04/22/beta-release

Compares SQL queries for building data using DuckDB, demonstrating performance improvements between the alpha and beta releases by filtering on bounding box coordinates.

```SQL
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;
```

```SQL
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
```

--------------------------------

### GET /divisions/{id}

Source: https://docs.overturemaps.org/schema/reference/divisions/division

Retrieves the details of a specific administrative division, including its hierarchy, population, and political perspectives.

```APIDOC
## GET /divisions/{id}

### Description
Retrieves a specific administrative division record. This includes metadata, hierarchical position, and optional attributes like population and political perspectives.

### Method
GET

### Endpoint
/divisions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the division.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier
- **subtype** (string) - The type of division (e.g., locality, country)
- **population** (int32) - Optional population count
- **perspectives** (object) - Optional political perspectives (accepted_by/disputed_by)
- **hierarchies** (array) - List of parent division IDs and names

#### Response Example
{
  "id": "350e85f6-68ba-4114-9906-c2844815988b",
  "subtype": "locality",
  "population": 534,
  "country": "TO",
  "parent_division_id": "8730f0cc-d436-4f11-a7d3-49085813ef44"
}
```

--------------------------------

### Render Map with Land Cover Data using Lonboard (Python)

Source: https://docs.overturemaps.org/blog/2024/05/16/land-cover

Defines the initial view state (longitude, latitude, zoom, pitch, bearing) and renders the map with the created PolygonLayer using the lonboard Map object.

```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

```