diff --git a/docs/getting-data/assets/aws-glue-data-catalog-values.png b/docs/examples/assets/aws-glue-data-catalog-values.png similarity index 100% rename from docs/getting-data/assets/aws-glue-data-catalog-values.png rename to docs/examples/assets/aws-glue-data-catalog-values.png diff --git a/docs/getting-data/assets/overture-release-tables.png b/docs/examples/assets/overture-release-tables.png similarity index 100% rename from docs/getting-data/assets/overture-release-tables.png rename to docs/examples/assets/overture-release-tables.png diff --git a/docs/getting-data/assets/review-and-create.png b/docs/examples/assets/review-and-create.png similarity index 100% rename from docs/getting-data/assets/review-and-create.png rename to docs/examples/assets/review-and-create.png diff --git a/docs/getting-data/athena-aws.mdx b/docs/examples/athena-aws.mdx similarity index 100% rename from docs/getting-data/athena-aws.mdx rename to docs/examples/athena-aws.mdx diff --git a/docs/getting-data/sedona.mdx b/docs/examples/sedona.mdx similarity index 100% rename from docs/getting-data/sedona.mdx rename to docs/examples/sedona.mdx diff --git a/docs/getting-data/synapse-azure.mdx b/docs/examples/synapse-azure.mdx similarity index 100% rename from docs/getting-data/synapse-azure.mdx rename to docs/examples/synapse-azure.mdx diff --git a/docs/gers/gers-tutorial.mdx b/docs/gers/gers-tutorial.mdx index 046006c08..3d5546aea 100644 --- a/docs/gers/gers-tutorial.mdx +++ b/docs/gers/gers-tutorial.mdx @@ -18,7 +18,7 @@ To associate your data with GERS identifiers, we need to: 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](https://docs.overturemaps.org/guides/places/) as our foundational dataset, but we want to bring in additional datasets to add details to our restaurant listings.* +*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. @@ -130,7 +130,7 @@ Using these common properties, and a bit of SQL, we can spin up a quick matcher ### 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. +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 diff --git a/docs/gers/index.mdx b/docs/gers/index.mdx index 41813f10f..79af9de18 100644 --- a/docs/gers/index.mdx +++ b/docs/gers/index.mdx @@ -18,10 +18,10 @@ The "S" in GERS stands for a *system*, with the following components: | Component | Description | | ---------- | ---------- | -| [Overture reference map](/#overture-data) | 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 | +| [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? diff --git a/docs/getting-data/cloud-sources.mdx b/docs/getting-data/cloud-sources.mdx new file mode 100644 index 000000000..7a1a2e485 --- /dev/null +++ b/docs/getting-data/cloud-sources.mdx @@ -0,0 +1,108 @@ +--- +title: Accessing the Overture Catalog +description: All of Overture's data offerings +pagination_label: Full Data Catalog +--- + + +Overture publishes 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 with no account or credentials required. Databases, other cloud providers, overture tools, community tools, plugins for ArcGIS and QGIS + +## Published datasets + +Overture distributes its core datasets 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. To learn more about GeoParquet, consult [this guide](https://guide.cloudnativegeo.org/geoparquet/) from the Cloud Native Geospatial Forum. + +| Provider | Path | +|---|---| +| Amazon S3 | `s3://overturemaps-us-west-2/release/` | +| Microsoft Azure | `https://overturemapswestus2.blob.core.windows.net/release/` | + +You can find the latest `` value in the [STAC catalog](https://stac.overturemaps.org/catalog.json) or the [STAC viewer](https://stac.overturemaps.org/). See the [quick start](/getting-data/) for how to query the catalog programmatically. + +### Path structure + +The base paths above point to all of the data in a particular release — about 500 GB. Overture partitions the data by `theme` and `type`; specifying those directories in your path will significantly narrow the data you access. + +Here's an example S3 path to the `infrastructure` feature type in the `base` theme: + +``` +s3://overturemaps-us-west-2/release/2026-02-18.0/theme=base/type=infrastructure/*.parquet +``` + +The components in that path: + +- **``**: Overture releases data monthly following a date-based versioning scheme in the format `yyyy-mm-dd.x`. An archive of releases is maintained on both Amazon S3 and Azure Blob Storage. +- **``**: one of Overture's six data themes — addresses, base, buildings, divisions, places, and transportation — and the first level of partitioning of the data. +- **``**: a feature type within a theme, e.g. `infrastructure` within `base`, and the second level of partitioning of the data. +- **`*.parquet`**: the file type Overture uses to store and deliver the data. The `*` indicates you want all of the Parquet files in a particular 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 | + +### Downloading with the AWS CLI + +You can install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to download Parquet files from S3 at the command line. In this example, you download all nine Parquet files (about one GB) in the `infrastructure` feature type: + +```bash +aws s3 cp --no-sign-request --recursive \ + s3://overturemaps-us-west-2/release/2026-02-18.0/theme=base/type=infrastructure/ . +``` + +### Downloading with AzCopy + +You can download files from Azure Blob Storage using [AzCopy](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-v10). Here's how to grab all of the `place` data: + +```bash +azcopy copy \ + "https://overturemapswestus2.dfs.core.windows.net/release/2026-02-18.0/theme=places/type=place/" \ + "" --recursive +``` + +## PMTiles + +Overture generates [PMTiles](https://docs.protomaps.com/pmtiles/) vector tile archives with each release. Each theme is stored as a separate archive containing geometry and tags in MVT format. These tiles power the [Explore site](https://explore.overturemaps.org) and are designed for data inspection rather than production cartography. + +| Provider | Path | +|---|---| +| Amazon S3 | `s3://overturemaps-tiles-us-west-2-beta//.pmtiles` | +| HTTP | `https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com//.pmtiles` | + +:::note +The `` in the tiles path uses the date only without the minor version, e.g. `2026-02-18` instead of `2026-02-18.0`. +::: + +You can 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 publishes a [STAC catalog](https://stac.overturemaps.org/catalog.json) that serves as the machine-readable index for all releases. It always points to the latest release and includes metadata for every theme and feature 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/). + +See the [quick start](/getting-data/) for examples of querying the STAC catalog in Python and DuckDB. + +## GERS registry, bridge files, and changelog + +Each release includes artifacts from the [Global Entity Reference System (GERS)](/gers/): + +- **[GERS Registry](/gers/registry/)**: a lookup service for GERS IDs that maps stable identifiers to their current feature data across releases. +- **[Bridge files](/gers/bridge-files/)**: files that track how GERS IDs change between releases — additions, removals, and geometry updates. +- **[Changelog](/gers/changelog/)**: a record of schema and data changes across releases. + +## Data mirrors + +In addition to the official sources, several partners maintain mirrors of the data 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, additional tooling, or other platform-specific benefits. \ No newline at end of file diff --git a/docs/getting-data/data-mirrors/fused.mdx b/docs/getting-data/data-mirrors/fused.mdx index 44b42593e..51b2ccadf 100644 --- a/docs/getting-data/data-mirrors/fused.mdx +++ b/docs/getting-data/data-mirrors/fused.mdx @@ -1,5 +1,6 @@ --- title: Fused +pagination_label: Fused --- import Tabs from '@theme/Tabs'; diff --git a/docs/getting-data/data-mirrors/snowflake.mdx b/docs/getting-data/data-mirrors/snowflake.mdx index 47640b24b..0ae61083e 100644 --- a/docs/getting-data/data-mirrors/snowflake.mdx +++ b/docs/getting-data/data-mirrors/snowflake.mdx @@ -1,5 +1,6 @@ --- title: Snowflake +pagination_label: 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: diff --git a/docs/getting-data/duckdb.mdx b/docs/getting-data/duckdb.mdx index 12940eec8..9fc7d6c29 100644 --- a/docs/getting-data/duckdb.mdx +++ b/docs/getting-data/duckdb.mdx @@ -1,5 +1,7 @@ --- title: DuckDB +description: Querying the Overture datalog +pagination_label: DuckDB --- import Tabs from '@theme/Tabs'; diff --git a/docs/getting-data/explore.mdx b/docs/getting-data/explore.mdx new file mode 100644 index 000000000..1f8abe6c7 --- /dev/null +++ b/docs/getting-data/explore.mdx @@ -0,0 +1,47 @@ +--- +title: Explorer +description: No-code tool for exploring and downloading data +pagination_label: Explorer +--- + +--- + +import { ExplorerEmbed } from '@site/src/components/home'; + + +[Overture Maps Explorer](https://explore.overturemaps.org) is a browser-based tool for browsing and inspecting Overture data. No installation, no account, no SQL — just open the link and start exploring. + + + +## Explore and Inspect modes + +The Explorer has two distinct modes. + +**Explore mode** presents the data as a styled, readable map. You can browse places, roads, buildings, land use, and water features with cartographic styling that makes the data easy to understand at a glance. A layers panel lets you toggle feature types on and off, and you can click individual features to see their properties. + +**Inspect mode** is closer to the raw data. 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 show areas, boundaries, and labels. Every feature type is symbolized uniformly as simple points, lines, and polygons. This is the mode for developers and data users who want to see exactly what's in the tiles. + +## Multilingual names + +The Explorer surfaces the richness of Overture's `names` property. Toggle between languages to see place names rendered in dozens of scripts and languages. This comes directly from the names field in Overture data, which carries common names, alternate names, and translations contributed by sources around the world. + +## How it works + +The 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. The tiles are hosted on S3 and loaded directly in the browser — no tile server required. + +The site's styling is built on a token-based design system: primitives (color palette, fonts), semantics (feature-level color assignments), and components (stylesheet properties referencing the semantic values). This architecture makes it straightforward to create new map styles — a dark mode, for example, requires changing just one file. + +The Explorer is pinned to a specific Overture release, and updates go through a validation process that audits stylesheets against the current schema and tile metadata before they reach the live site. + +The source code is available in the [explore-site](https://github.com/OvertureMaps/explore-site) repository. + +## When to use it + +The Explorer is the fastest way to answer questions like: + +- What does Overture data look like in a specific area? +- What properties are available 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? + +It's a good starting point before writing queries with the [Python CLI](/getting-data/overturemaps-py/) or [DuckDB](/getting-data/duckdb/). \ No newline at end of file diff --git a/docs/getting-data/index.mdx b/docs/getting-data/index.mdx deleted file mode 100644 index 0ee85a6f2..000000000 --- a/docs/getting-data/index.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Accessing the Data -sidebar_label: Overview ---- - -import QueryBuilder from '@site/src/components/queryBuilder'; -import MadridBuildings from '!!raw-loader!@site/src/queries/duckdb/buildings_madrid.sql'; - -## Official Overture sources - -The Overture Maps Foundation provides free access to its data on Amazon S3 and Microsoft Azure Blob Storage, with no account registration or credentials required. - -| Provider | Location | -| ---------------------------- | --------------------------------------------------------------------- | -| Amazon S3 | `s3://overturemaps-us-west-2/release/` | -| Microsoft Azure Blob Storage | `https://overturemapswestus2.blob.core.windows.net/release/` | - -The latest Overture data `` is: - - - -### Getting only the data you want - -The base paths above point to all of the data in a particular Overture release, about 500 GigaBytes (GB) worth. Overture partitions the data by `theme` and `type`; specifying those directories in your path will significantly narrow the universe of data you are trying to access. For example, here's the S3 path to the `infrastructure` feature type in the `base` theme: - - - -Let's break down the components in that path: - -- ``: Overture releases data monthly — following a date-based versioning scheme in the format `yyyy-mm-dd.x` —and maintains an archive of releases on Amazon S3 and Azure Blob Storage -- ``: one of Overture's six data themes — addresses, base, buildings, divisions, places, and transportation — and the first level of partitioning of the data -- ``: a feature type within a theme, e.g. infrastructure within base, and the second level of partitioning of the data | -- `*.parquet`: the file type Overture uses to store and deliver the data, the `*` indicates you want all of the Parquet files in a particular directory - -### Parquet files - -Overture distributes its data as [GeoParquet](https://geoparquet.org/) files, 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 efficiently fetch chunks of the data from cloud storage. Instead of extracting one huge data file containing a planet's worth of data, you can scan across the many GeoParquet files in each `type` directory and pull only the data you need. To learn more about GeoParquet, you can consult [this guide](https://guide.cloudnativegeo.org/geoparquet/) from the Cloud Native Geospatial Forum. - -## Quickstart - -Let's go back to the example above with the infrastructure map data. Now that you know the correct path, how do you actually query and download the data? Below are a few examples to get you started quickly. - -### AWS CLI - -You can install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to download the Parquet files from S3 at the command line. Set `` to a local directory path to download the files, or to an `s3://` path you control to copy them into your S3 bucket. - -In this example, you can use the AWS CLI to download all nine Parquet files, about one GB of data, in the `infrastructure` feature type to the current working directory on your local drive. - - - -Here's another example with the AWS CLI, this time extracting all of the data for the `building` feature type: - - - -This will download 200 GeoParquet files containing all of the `building` feature type data around the world — that's more than 230 GB of data! - -:::tip -If you'd like to query the data directly on the AWS platform, please read our documentation about setting up an Overture data catalog on [Athena](athena-aws). You'll need an AWS account secured with a credit card. -::: - -### AzCopy - -You can download the files from Azure Blob Storage directly using [Azure Storage Explorer](https://azure.microsoft.com/en-us/products/storage/storage-explorer/) or by installing Microsoft's [AzCopy](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-v10?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json#download-azcopy) command-line tool. Here's how you would use the`azcopy` command to grab all of the `place` data: - - - -:::tip -You can read more about querying with the data directly in [Azure using Synapse](synapse-azure). You'll need an account backed by a credit card to do this. -::: - -### DuckDB - -[DuckDB](https://duckdb.org/) is one of our favorite tools for querying the data and downloading only what you need. We have a full page of example queries [here](/getting-data/duckdb/); we'll give you one quick example below. - -Let's say you don't want the entire buildings dataset for the planet. With DuckDB, you can scan Parquet files directly in S3 and extract only the data that matches specific parameters: - - - -Alternatively, you can put your query in a SQL file and run `duckdb -f query.sql` at the command line. - -### Python CLI - -Overture also offers its own [Python CLI](overturemaps-py) for downloading data at the command line. - -``` -$ overturemaps download --bbox=-75,40,-73,41 -f geojson --type=building -o nyc_buildings.geojson -``` - -## Data mirrors - -In addition to the official sources maintained by the Overture Maps Foundation, several _friends of Overture_ are maintaining mirrors of the data on these platforms: - -- [Bigquery](data-mirrors/bigquery) -- [Databricks](data-mirrors/databricks) -- [Fused](data-mirrors/fused) -- [Source Cooperative](https://source.coop/) -- [Snowflake](data-mirrors/snowflake) -- [Wherobots](data-mirrors/wherobots) - -These are community-maintained resources. These mirrors may offer different access patterns, additional tooling, or other platform-specific benefits. Please consult the documentation for details. diff --git a/docs/getting-data/overturemaps-py.mdx b/docs/getting-data/overturemaps-py.mdx index 646cd7bfc..538ecfb56 100644 --- a/docs/getting-data/overturemaps-py.mdx +++ b/docs/getting-data/overturemaps-py.mdx @@ -1,21 +1,33 @@ --- -title: Python CLI +title: Python Client +description: Overture's official Python CLI and library +pagination_label: Python Client --- -Overture's [Python command-line tool](https://github.com/OvertureMaps/overturemaps-py) helps you download data within a region of interest and converts it to several common geospatial file formats. [This example](/blog/2024/05/16/land-cover/) shows how to use the tool to download Overture's land cover data in a Jupyter notebook. +# Python CLI + +Overture's [Python command-line tool](https://github.com/OvertureMaps/overturemaps-py) downloads data within a region of interest and converts it to several common geospatial file formats. It reads directly from Overture's S3 bucket using the [STAC catalog](https://stac.overturemaps.org/catalog.json) to always target the latest release. :::note - This project is experimental and likely to change. See the [overturemaps-py repository](https://github.com/OvertureMaps/overturemaps-py) for timely updates. - ::: +This project is experimental and likely to change. See the [overturemaps-py repository](https://github.com/OvertureMaps/overturemaps-py) for timely updates. +::: ## Installation -`pip install overturemaps` - -## Quick Start -Download the building footprints for the specific bounding box as GeoJSON and save to a file named "boston.geojson" +```bash +pip install overturemaps ``` -$ overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=building -o boston.geojson + +## Quick example + +Download building footprints for a specific bounding box as GeoJSON: + +```bash +overturemaps download \ + --bbox=-71.068,42.353,-71.058,42.363 \ + -f geojson \ + --type=building \ + -o boston_buildings.geojson ``` 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: @@ -25,26 +37,29 @@ uvx overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type ``` ## Usage -**download** -Right now there is only one option to the overturemaps utility: download. It will download Overture Maps data with an optional bounding box into the specified file format. When specifying a bounding box, only the minimum data is transferred. The result is streamed out and can handle arbitrarily large bounding boxes. +The `overturemaps download` command downloads Overture data with an optional bounding box into the specified file format. When specifying a bounding box, only the minimum data is transferred. The result is streamed and can handle arbitrarily large bounding boxes. -Command-line options: +**Options:** -- `--bbox` (optional): west, south, east, north longitude and latitude coordinates. When omitted the entire dataset for the specified type will be downloaded -- `-f` (required: one of "geojson", "geojsonseq", "geoparquet"): output format -- `--output/-o` (optional): Location of output file. When omitted output will be written to stdout. -- `--type/-t` (required): The Overture map data type to be downloaded. Examples of types are building for building footprints, place for POI places data, etc. Run overturemaps download --help for the complete list of allowed types +| 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` | By default, the reader uses Overture's STAC catalog to speed up queries. Use `--no-stac` to read data without it. | -This downloads data directly from Overture's S3 bucket without interacting with any other servers. By including bounding box extents on each row in the Overture distribution, the underlying Parquet readers use the Parquet summary statistics to download the minimum amount of data necessary to extract data from the desired region. +This downloads data directly from Overture's S3 bucket without interacting with any other servers. By including bounding box extents on each row in the Overture distribution, the underlying Parquet readers use the summary statistics to download the minimum amount of data necessary to extract data from the desired region. -To help find bounding boxes of interest, we like this [bounding box](https://boundingbox.klokantech.com/) tool from [Klokantech](https://www.klokantech.com/). Choose the CSV format and copy the value directly into the `--bbox` field. +:::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. +::: ## Next steps -- Contribute to [overturemaps-py](//github.com/overturemaps/overturemaps-py). -- Visualize the data in [QGIS](/examples/QGIS) or [kepler.gl](/examples/kepler-gl). -- [Make an interactive map](/examples/build-a-map). -- Check out our Made by the Overture [Community page](/community). -- Dig into the [Overture schema](//docs.overturemaps.org/schema/). -- [Talk to us on GitHub](https://github.com/orgs/OvertureMaps/discussions)! +- Contribute to [overturemaps-py](https://github.com/OvertureMaps/overturemaps-py) +- Visualize the data in [QGIS](/examples/QGIS/) or [kepler.gl](/examples/kepler-gl/) +- [Make an interactive map](/examples/build-a-map/) +- Check out our [community projects](/community/) +- Dig into the [Overture schema](/schema/) diff --git a/docs/getting-data/quick-start.mdx b/docs/getting-data/quick-start.mdx new file mode 100644 index 000000000..b1a38b212 --- /dev/null +++ b/docs/getting-data/quick-start.mdx @@ -0,0 +1,80 @@ +--- +title: Quickstart +description: Concise guide to get started with Overture data in a few minutes +slug: /getting-data/ +pagination_label: Quickstart +--- + + +## Explore in the browser + +The fastest way to dig into the data and schema is the [Explorer site](./explore). No installation, no account. Start browsing buildings, roads, places, addresses, and more. Click any feature to inspect its properties and schema. Download visible data as GeoJSON files. + +## Download by area of interest with Python client + +Install Overture's [Python client](https://github.com/OvertureMaps/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 S3 bucket and transfers only the data inside your bounding box. See the [Python Client page](./overturemaps-py) for the full list of options and feature types. + +## Query with DuckDB + +[DuckDB](https://duckdb.org/) lets you query Overture's cloud-hosted GeoParquet files directly. [Install DuckDB](https://duckdb.org/docs/installation/), then run: + +```sql +INSTALL spatial; +INSTALL httpfs; + +LOAD spatial; + +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-02-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'); +``` + +This extracts all Wawa convenience stores in the Philadelphia area and saves them as GeoJSON. See the [DuckDB page](./duckdb) for more examples across all six themes. + +## Get the latest release + +Overture publishes a [STAC catalog](https://stac.overturemaps.org/catalog.json) that always points to the latest release. Instead of hardcoding release paths, you can query the catalog. See an example with DuckDB: + +```sql +SET VARIABLE latest = ( + SELECT latest FROM 'https://stac.overturemaps.org/catalog.json' +); +``` + +Browse all release artifacts in the [STAC browser](https://radiantearth.github.io/stac-browser/#/external/stac.overturemaps.org/catalog.json), hosted by Radiant Earth. The Python Client uses the STAC catalog automatically. + +## Next steps + +- [Explore the data](./explore) in the browser +- [Download data with the Python CLI](./overturemaps-py) +- [Query with DuckDB](./duckdb) +- [Access the full Overture catalog](./cloud-sources) — storage paths, PMTiles, STAC, GERS artifacts, and data mirrors +- [Guides](../guides/) — understand how Overture organizes its six themes +- [Schema reference](../schema/) — column definitions and data types +- [Examples](../examples/) — QGIS, kepler.gl, Pandas, Spark, and more diff --git a/docs/guides/addresses/overview.mdx b/docs/guides/addresses/index.mdx similarity index 73% rename from docs/guides/addresses/overview.mdx rename to docs/guides/addresses/index.mdx index 94e836c97..ee3f6e872 100644 --- a/docs/guides/addresses/overview.mdx +++ b/docs/guides/addresses/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: A collection of global address points -slug: /guides/addresses/ pagination_label: Addresses Overview --- @@ -21,7 +20,7 @@ This theme is currently in Alpha. We invite the Overture community to test the a 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](https://docs.overturemaps.org/attribution/). +For licensing information, please see the [Attribution and Licensing page](../../attribution). Address data can be used for a variety of purposes, which can include: @@ -40,7 +39,7 @@ Address data can be used for a variety of purposes, which can include: ### 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). +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/).
Address counts, per country @@ -91,10 +90,10 @@ An `address` is a feature type that represents a physical place through a series
-## Understanding the parquet files +### Data Dictionary
- Schema for the GeoParquet files in the addresses theme + Column definitions for addresses
| column | type | description | @@ -129,7 +128,7 @@ Overture's addresses theme data is freely available on both Amazon S3 and Micros 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](https://docs.overturemaps.org/getting-data/) offers instructions for using several tools to access Overture data, including DuckDB and Overture's Python command-line tool. See examples below for addresses. +[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. @@ -145,8 +144,8 @@ This example returns address data for Calgary, CA and the surrounding area: - -You can find Overture's official Python command-line tool [here](https://github.com/OvertureMaps/overturemaps-py). + +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: @@ -158,17 +157,6 @@ This command results in the following address points, displayed in QGIS: ![Boston address coverage via bbox](/img/addresses/boston-export.png) -Right now there is only one option to the overturemaps utility: download. It will download Overture Maps data with an optional bounding box into the specified file format. When specifying a bounding box, only the minimum data is transferred. The result is streamed out and can handle arbitrarily large bounding boxes. - -Command-line options: - -- **--bbox** (optional): west, south, east, north longitude and latitude coordinates. When omitted the entire dataset for the specified type will be downloaded -- **-f** (required: one of "geojson", "geojsonseq", "geoparquet"): output format -- **--output/-o** (optional): Location of output file. When omitted output will be written to stdout. -- **--type/-t** (required): The Overture map data type to be downloaded. Examples of types are building for building footprints, place for POI places data, etc. Run overturemaps download --help for the complete list of allowed types - -This downloads data directly from Overture's S3 bucket without interacting with any other servers. By including bounding box extents on each row in the Overture distribution, the underlying Parquet readers use the Parquet summary statistics to download the minimum amount of data necessary to extract data from the desired region. - @@ -197,37 +185,13 @@ This query will create a CSV file of address within the State of Utah, using the
-## Revision history -### Version info - -You can find the most recent release notes [here](https://docs.overturemaps.org/release/latest/). - -## Support - -### Feedback - -You can find a list of Overture repositories [here](https://github.com/orgs/OvertureMaps/repositories). - -Discussions are generally reserved for broader conversations around the addresses project as a whole (supporting a new workflow, adding a dataset, null attributes). - -Issues are generally reserved for more specific concerns with specific entities in the dataset (geometry validation, missing entities, duplicate entities) or country-specific concerns. - -### Discussions - -You can start and add to discussions in each of the public Overture repositories. Some examples: - -- **General Overture Discussions**: https://github.com/orgs/OvertureMaps/discussions -- **Data Discussions**: https://github.com/OvertureMaps/data/discussions -- **Schema Discussions**: https://github.com/OvertureMaps/schema/discussions -Discussions around Overture's address data should be filed in the Data repository. +## Get support -### Issues +Overture is an open project and we welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps). -You can start and add to issues in each of the public Overture repositories, too. Some examples: +**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. -- **Data Issues**: https://github.com/OvertureMaps/data/issues -- **Schema Issues**: https://github.com/OvertureMaps/schema/issues -- **Tiles issues**: https://github.com/OvertureMaps/overture-tiles/issues +**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. -Issues around Overture's address data should be filed in the data repository. +**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. diff --git a/docs/guides/base/overview.mdx b/docs/guides/base/index.mdx similarity index 90% rename from docs/guides/base/overview.mdx rename to docs/guides/base/index.mdx index 323dd4680..546f090cb 100644 --- a/docs/guides/base/overview.mdx +++ b/docs/guides/base/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: Bathymetry, Infrastructure, Land, Landuse, Landcover, and Water features. -slug: /guides/base/ pagination_label: Base Overview --- @@ -21,10 +20,10 @@ The Overture Maps base theme provides the land, water, infrastructure, and bathy - **`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. -## Understanding the parquet files +## Data dictionary
- Schema for the GeoParquet files in the base theme + Column definitions in the base theme
@@ -196,7 +195,7 @@ Overture's base theme data is freely available on both Amazon S3 and Microsoft A 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](https://docs.overturemaps.org/getting-data/) offers instructions for using several tools to access Overture data, including DuckDB and Overture's Python command-line tool. See examples below for addresses. +[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. @@ -210,9 +209,19 @@ If you have a particular geographic area of interest, there are several options ## 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). +- [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. diff --git a/docs/guides/buildings/overview.mdx b/docs/guides/buildings/index.mdx similarity index 91% rename from docs/guides/buildings/overview.mdx rename to docs/guides/buildings/index.mdx index 2264ddf01..fb1952884 100644 --- a/docs/guides/buildings/overview.mdx +++ b/docs/guides/buildings/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: 2.6 billion buildings and counting -slug: /guides/buildings/ pagination_label: Buildings Overview --- @@ -18,7 +17,7 @@ The Overture Maps buildings theme describes human-made structures with roofs or ### 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](https://docs.overturemaps.org/getting-data/) to accessing Overture data in our documentation. +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. @@ -45,9 +44,9 @@ Our buildings data is intended to support multiple use cases, as defined and pri - **Spatial Analysis**: Enable end users to perform analysis to create derivative datasets or train AI models. -## Dataset schema +## 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](https://docs.overturemaps.org/schema/). +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/).
Column definitions for the `building` and `building_part` datasets @@ -169,7 +168,17 @@ The visualization below shows Overture buildings data looking across the US-Mexi ## 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](https://docs.overturemaps.org/attribution/) section of our documentation. +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. diff --git a/docs/guides/divisions/overview.mdx b/docs/guides/divisions/index.mdx similarity index 86% rename from docs/guides/divisions/overview.mdx rename to docs/guides/divisions/index.mdx index 27d1f2983..06a38748f 100644 --- a/docs/guides/divisions/overview.mdx +++ b/docs/guides/divisions/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: Global administrative data, from microhoods to countries -slug: /guides/divisions/ pagination_label: Divisions Overview --- @@ -26,7 +25,7 @@ import PhillyPlaces from '!!raw-loader!@site/src/queries/duckdb/divisions_philly 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](https://docs.overturemaps.org/attribution/) for more information.) +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 @@ -44,11 +43,11 @@ Divisions data can be used for many purposes, which can include, but are not lim ### 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. — 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` is a feature type that represents an official or non-official organization of people: country, region, province, city, neighborhood, etc. — 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_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). +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 @@ -74,10 +73,10 @@ Subtypes can represent each feature's administrative level, from `country` down
-## Understanding the parquet files +## Data dictionary
- Schema for the GeoParquet files in the divisions theme + Column definitions in the divisions theme
@@ -184,11 +183,11 @@ Overture's divisions theme data is freely available on both Amazon S3 and Micros 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](https://docs.overturemaps.org/getting-data/) offers instructions for using several tools to access Overture data, including DuckDB and Overture's Python command-line tool. See examples below for divisions. +[The Getting Data section of this documentation](/getting-data/cloud-sources/) offers instructions accessing the full Overture catalog. See examples below for divisions. - + 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: @@ -197,20 +196,10 @@ This tool helps to download Overture data within a region of interest and conver overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=division -o boston.geojson ``` -Right now there is only one option to the overturemaps utility: download. It will download Overture Maps data with an optional bounding box into the specified file format. When specifying a bounding box, only the minimum data is transferred. The result is streamed out and can handle arbitrarily large bounding boxes. - -Command-line options: - -- **--bbox** (optional): west, south, east, north longitude and latitude coordinates. When omitted the entire dataset for the specified type will be downloaded -- **-f** (required: one of "geojson", "geojsonseq", "geoparquet"): output format -- **--output/-o** (optional): Location of output file. When omitted output will be written to stdout. -- **--type/-t** (required): The Overture map data type to be downloaded. Examples of types are building for building footprints, place for POI places data, etc. Run overturemaps download --help for the complete list of allowed types - -This downloads data directly from Overture's S3 bucket without interacting with any other servers. By including bounding box extents on each row in the Overture distribution, the underlying Parquet readers use the Parquet summary statistics to download the minimum amount of data necessary to extract data from the desired region. -First, follow the [setup guide for DuckDB](/getting-data/duckdb/). +First, follow the [setup guide for DuckDB](../../getting-data/duckdb). Note: Running this query will result in a ~6.4GB file. @@ -241,8 +230,8 @@ This will download the area visible on your screen. - -First, follow the [setup guide for the Python Command-line Tool](/getting-data/overturemaps-py/). + +First, follow the [setup guide for the Python Client](../../getting-data/overturemaps-py). You can alter the `bbox` value to download a particular area. @@ -252,7 +241,7 @@ overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=div -First, follow the [setup guide for DuckDB](/getting-data/duckdb/). +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. @@ -316,37 +305,13 @@ This query will return Places theme data for any place within the locality of Ph
-## Revision history -### Version info - -You can find the most recent release notes [here](https://docs.overturemaps.org/release/latest/). - -## Support - -### Feedback - -You can find a list of Overture repositories [here](https://github.com/orgs/OvertureMaps/repositories). - -Discussions are generally reserved for broader conversations around the divisions project as a whole (supporting a new workflow, adding a dataset, null attributes). - -Issues are generally reserved for more specific concerns with specific entities in the dataset (geometry validation, missing entities, duplicate entities) or country-specific concerns. - -### Discussions - -You can start and add to discussions in each of the public Overture repositories. Some examples: - -- **General Overture Discussions**: https://github.com/orgs/OvertureMaps/discussions -- **Data Discussions**: https://github.com/OvertureMaps/data/discussions -- **Schema Discussions**: https://github.com/OvertureMaps/schema/discussions -Discussions around Overture's divisions data should be filed in the Data repository. +## Get support -### Issues +Overture is an open project and we welcome feedback, questions, and bug reports through our [public GitHub repositories](https://github.com/OvertureMaps). -You can start and add to issues in each of the public Overture repositories, too. Some examples: +**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. -- **Data Issues**: https://github.com/OvertureMaps/data/issues -- **Schema Issues**: https://github.com/OvertureMaps/schema/issues -- **Tiles issues**: https://github.com/OvertureMaps/overture-tiles/issues +**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. -Issues around Overture's divisions data should be filed in the data repository. +**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. diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx index 29408ede5..eadbcf949 100644 --- a/docs/guides/index.mdx +++ b/docs/guides/index.mdx @@ -13,9 +13,9 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; **View Theme Definitions Table →** -- **[Addresses](/guides/addresses)** -- **[Base](/guides/base)** -- **[Buildings](/guides/buildings)** -- **[Divisions](/guides/divisions)** -- **[Places](/guides/places)** -- **[Transportation](/guides/transportation)** \ No newline at end of file +- **[Addresses](./addresses)** +- **[Base](./base)** +- **[Buildings](./buildings)** +- **[Divisions](./divisions)** +- **[Places](./places)** +- **[Transportation](./transportation)** \ No newline at end of file diff --git a/docs/guides/places/overview.mdx b/docs/guides/places/index.mdx similarity index 84% rename from docs/guides/places/overview.mdx rename to docs/guides/places/index.mdx index 79455e69c..b00fdd318 100644 --- a/docs/guides/places/overview.mdx +++ b/docs/guides/places/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: Points of interest around the world -slug: /guides/places/ pagination_label: Places Overview --- @@ -36,12 +35,12 @@ The Overture places theme has one feature type, called `place`, and contains mor | RenderSEO, Overture | CDLA-Permissive-2.0 | 4,844 | | meta, Overture | CDLA-Permissive-2.0 | 58,958,274 | -## Dataset description +## 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. Of particular interest to users is the categories property; we offer a complete list of available categories [here](https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/overture_categories.csv). +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.
- Schema for GeoParquet files in the places theme + Column definitions for the Places theme
| column | type | description | @@ -78,12 +77,12 @@ Overture's places theme data is freely available on both Amazon S3 and Microsoft | Amazon S3 | | | Azure Blob Storage | | -More information can be found in the [Getting Overture Data](https://docs.overturemaps.org/getting-data/) 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. +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: - -First, follow the [setup guide for the Python Command-line Tool](/getting-data/overturemaps-py/). + +First, follow the [setup guide for the Python Client](/getting-data/overturemaps-py/). ``` overturemaps download -f geoparquet --type=place -o places.geoparquet @@ -108,8 +107,8 @@ To download data: Pan to the area you are interested in, turn off the other laye This will download the area visible on your screen. - -First, follow the [setup guide for the Python Command-line Tool](/getting-data/overturemaps-py/). + +First, follow the [setup guide for the Python Client](/getting-data/overturemaps-py/). Simply alter the `bbox` value to download a particular area. ``` @@ -187,3 +186,14 @@ The places theme has wide coverage and many of the place point features have add 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. \ No newline at end of file diff --git a/docs/guides/transportation/overview.mdx b/docs/guides/transportation/index.mdx similarity index 92% rename from docs/guides/transportation/overview.mdx rename to docs/guides/transportation/index.mdx index 512eec14b..d71918d2b 100644 --- a/docs/guides/transportation/overview.mdx +++ b/docs/guides/transportation/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: Global road, rail, and water transportation data -slug: /guides/transportation/ pagination_label: Transportation Overview --- @@ -101,7 +100,7 @@ Transportation segments are divided into three subtypes: **rail**, **water**, an 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.
- Data dictionary for the GeoParquet files in the transportation theme + Column definitions in the transportation theme
@@ -174,8 +173,8 @@ Overture's transportation theme data is freely available on both Amazon S3 and M 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. - -First, follow the [setup guide for the Python Command-line Tool](/getting-data/overturemaps-py/). + +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. ``` @@ -183,7 +182,7 @@ overturemaps download --bbox=12.46,41.89,12.48,41.91 -f geojson --type=segment - ``` -First, follow the [setup guide for DuckDB](/getting-data/duckdb/). +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. @@ -266,3 +265,14 @@ To help visualize this process better, here is a real-world example of a residen 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. + diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 000000000..b55c97272 --- /dev/null +++ b/docs/index.mdx @@ -0,0 +1,36 @@ +--- +slug: / +title: ' ' +sidebar_class_name: hidden +hide_table_of_contents: true +className: landing-page +--- + +import { + Hero, + HeroHeadline, + HeroSubtext, + HeroCTAs, + PrimaryButton, + SecondaryButton, + ExplorerEmbed, +} from '@site/src/components/home'; + + + + + + 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. + + + + Quickstart + + Explore the data and schema → + + + + + diff --git a/docs/introduction.mdx b/docs/introduction.mdx deleted file mode 100644 index cd8568da1..000000000 --- a/docs/introduction.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -description: Overture Documentation -slug: / -title: Introduction ---- - -Welcome! Overture provides free and open map data normalized to [one schema](/schema). Our [six data "themes"](guides) — [addresses](guides/addresses), [buildings](guides/buildings), [base](guides/base), [divisions](guides/divisions), [places](guides/places), and [transportation](guides/transportation) — contain nearly 4.2 billion features and will continue to expand in size and scale. The data we use to build our datasets comes from many sources, including OpenStreetMap, Meta, Microsoft, Esri, OpenAddresses, and [more](attribution). - -In this documentation, you'll find [instructions](getting-data) for accessing and handling Overture's large datasets, [reference material](/schema) to help you understand the Overture schema, comprehensive [guides](guides) to working with the many themes and types of Overture data, and [hands-on examples](examples) using data wrangling, analysis, and visualization tools you know and love. Want to see what our community has been building? Check out the [community projects](community) section of our documentation for inspiration. - -## Overture data - -We release our data monthly as [cloud-native GeoParquet](https://guide.cloudnativegeo.org/geoparquet/) files, partitioned by theme and type. Each data theme contains one or more feature types: - -| 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 | - -
-Theme-type mapping as JSON - -```json -type_theme_map = { - "address": "addresses", - "building": "buildings", - "building_part": "buildings", - "division": "divisions", - "division_area": "divisions", - "division_boundary": "divisions", - "place": "places", - "segment": "transportation", - "connector": "transportation", - "bathymetry": "base", - "infrastructure": "base", - "land": "base", - "land_cover": "base", - "land_use": "base", - "water": "base" -} -``` - -
- -You'll find the GeoParquet column definitions for each feature type in our data [guides](guides). - -## Overture schema - -In our [schema reference docs](/schema), we describe key schema concepts for each theme and definitions and examples for each feature type. - -## Vision - -The [member companies of the Overture Maps Foundation](https://overturemaps.org/about/members/) are working collaboratively to build the datasets and schema. They share a common vision: - -### Address the core, enable the periphery - -The Overture schema doesn't solve every problem. It offers complete, out-of-the-box solutions for the most fundamental "core" use cases. At the same time, the schema's extensible structure enables a wide range of other use cases ("the periphery"). - -### Invent across the gap - -The mapping community already has access to many excellent tools, standards and practices. The Overture schema reuses these existing solutions to maximize compatibility and focus on solving unaddressed pain points. - -### Backward-compatible is forward-compatible - -No design is future-proof, but good designs stay relevant by adding features without breaking what already works. The Overture schema can be enhanced in a backward-compatible way. - -### Always open - -The Overture schema and data formats aim for compatibility with free and open-source tools, avoiding dependency on proprietary technologies. - -## Contact us - -We want to hear from you. Ask questions, report bugs, provide feedback, and submit contributions via our public Overture GitHub repositories: - -- [Schema](https://github.com/OvertureMaps/schema) -- [Data](https://github.com/OvertureMaps/data) -- [Docs](https://github.com/OvertureMaps/docs) diff --git a/docs/schema/index.md b/docs/schema/index.md index a7270de53..148d39def 100644 --- a/docs/schema/index.md +++ b/docs/schema/index.md @@ -4,7 +4,7 @@ slug: /schema/ title: Schema Reference sidebar_label: Overview description: Pydantic schemas for Overture Maps data -pagination_label: Schema Reference +pagination_label: Schema Reference Overview --- # Overture Maps Schema {#top-level-properties} diff --git a/docusaurus.config.js b/docusaurus.config.js index 8d8751689..0b5014b80 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -142,8 +142,7 @@ const config = { }, items: [ { - type: 'docSidebar', - sidebarId: 'docs', + to: '/', position: 'left', label: 'Docs', }, @@ -193,4 +192,4 @@ const config = { }), }; -module.exports = config; +module.exports = config; \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index dff2578f5..ca77b1bc1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1,17 +1,16 @@ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { docs: [ - 'introduction', { type: 'category', label: 'Getting Started', collapsed: true, items: [ - 'getting-data/index', - 'getting-data/duckdb', + 'getting-data/quick-start', + 'getting-data/cloud-sources', + 'getting-data/explore', 'getting-data/overturemaps-py', - 'getting-data/athena-aws', - 'getting-data/synapse-azure', + 'getting-data/duckdb', { type: 'category', label: 'Data Mirrors', @@ -43,7 +42,10 @@ const sidebars = { 'examples/QGIS', 'examples/rapid', 'examples/spark', + 'examples/sedona', 'examples/wherobots', + 'examples/athena-aws', + 'examples/synapse-azure', ], }, { @@ -57,7 +59,7 @@ const sidebars = { label: 'Addresses', collapsed: true, items: [ - 'guides/addresses/overview', + 'guides/addresses/index', ], }, { @@ -65,7 +67,7 @@ const sidebars = { label: 'Base', collapsed: true, items: [ - 'guides/base/overview', + 'guides/base/index', ], }, { @@ -73,7 +75,7 @@ const sidebars = { label: 'Buildings', collapsed: true, items: [ - 'guides/buildings/overview', + 'guides/buildings/index', ], }, { @@ -81,7 +83,7 @@ const sidebars = { label: 'Divisions', collapsed: true, items: [ - 'guides/divisions/overview', + 'guides/divisions/index', ], }, { @@ -89,7 +91,7 @@ const sidebars = { label: 'Places', collapsed: true, items: [ - 'guides/places/overview', + 'guides/places/index', 'guides/places/taxonomy', ], }, @@ -98,7 +100,7 @@ const sidebars = { label: 'Transportation', collapsed: true, items: [ - 'guides/transportation/overview', + 'guides/transportation/index', 'guides/transportation/segments-and-connectors', 'guides/transportation/scoping-and-travel-modes', 'guides/transportation/linear-referencing', diff --git a/src/components/RotatingWord.jsx b/src/components/RotatingWord.jsx new file mode 100644 index 000000000..75f1b543d --- /dev/null +++ b/src/components/RotatingWord.jsx @@ -0,0 +1,81 @@ +import React, { useEffect, useRef, useState } from 'react'; +import styles from './RotatingWord.module.css'; + +const WORDS = [ + 'free and open map data.', + 'modular, extensible schemas.', + 'stable UUIDs for the world.', + 'shared infrastructure.', + 'global, cross-sector collaboration.', + 'an invitation to build together.', +]; + +const EASTER_EGG = 'Jennings Anderson.'; +const LOOPS_BEFORE_EGG = 10; + +export default function RotatingWord() { + const [index, setIndex] = useState(0); + const [showEgg, setShowEgg] = useState(false); + const pausedRef = useRef(false); + const loopCountRef = useRef(0); + + useEffect(() => { + const interval = setInterval(() => { + if (!pausedRef.current) { + setIndex(prev => { + const next = (prev + 1) % WORDS.length; + if (next === 0) { + loopCountRef.current += 1; + if (loopCountRef.current === LOOPS_BEFORE_EGG) { + setShowEgg(true); + return prev; + } + } + return next; + }); + } + }, 3200); + return () => clearInterval(interval); + }, []); + + // After showing the easter egg, resume normal rotation + useEffect(() => { + if (!showEgg) return; + const timeout = setTimeout(() => { + setShowEgg(false); + setIndex(0); + }, 3200); + return () => clearTimeout(timeout); + }, [showEgg]); + + const displayWords = showEgg ? [EASTER_EGG] : WORDS; + const activeIndex = showEgg ? 0 : index; + + return ( + <> +
{ pausedRef.current = true; }} + onMouseLeave={() => { pausedRef.current = false; }} + > + {displayWords.map((word, i) => ( + + {word} + + ))} +
+
+ {WORDS.map((_, i) => ( +
{ setShowEgg(false); setIndex(i); }} + /> + ))} +
+ + ); +} \ No newline at end of file diff --git a/src/components/RotatingWord.module.css b/src/components/RotatingWord.module.css new file mode 100644 index 000000000..5da5875ac --- /dev/null +++ b/src/components/RotatingWord.module.css @@ -0,0 +1,49 @@ +.rotatingWrap { + position: relative; + overflow: hidden; + height: clamp(5.5rem, 11vw, 9rem); + width: 100%; + margin-top: 0.15rem; +} + +.rotatingWord { + font-family: Montserrat, var(--ifm-font-family-base); + font-size: clamp(2.2rem, 5vw, 3.75rem); + font-weight: 600; + line-height: 1.15; + letter-spacing: -0.02em; + position: absolute; + white-space: normal; + width: 100%; + opacity: 0; + transform: translateY(110%); + transition: opacity 0.4s ease, transform 0.4s ease; + color: var(--ifm-font-color-base); +} + +.rotatingWord.active { + opacity: 1; + transform: translateY(0); +} + +.rotateDots { + display: flex; + gap: 6px; + margin-top: 1.25rem; +} + +.rotateDot { + width: 6px; + height: 6px; + border-radius: 50%; + background: var(--ifm-color-emphasis-300); + cursor: pointer; + transition: background 0.2s, transform 0.2s; + border: 1px solid var(--ifm-color-emphasis-300); +} + +.rotateDot.activeDot { + background: #4edad8; + border-color: #4edad8; + transform: scale(1.35); +} diff --git a/src/components/home.jsx b/src/components/home.jsx new file mode 100644 index 000000000..da6870138 --- /dev/null +++ b/src/components/home.jsx @@ -0,0 +1,72 @@ +import React from 'react'; +import Link from '@docusaurus/Link'; +import RotatingWord from './RotatingWord'; +import styles from './home.module.css'; + +export function Hero({ children }) { + return
{children}
; +} + +export function HeroHeadline() { + return ( +
+
+ Overture + is +
+ +
+ ); +} + +export function HeroSubtext({ children }) { + return

{children}

; +} + +export function HeroCTAs({ children }) { + return
{children}
; +} + +export function PrimaryButton({ to, children }) { + return ( + + {children} + + ); +} + +export function SecondaryButton({ href, children }) { + return ( + + {children} + + ); +} + +export function ExplorerEmbed({ src = 'https://explore.overturemaps.org' }) { + return ( +
+
+