Skip to main content

Divisions

Overview​

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

There are more than 5.3 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 data and geoBoundaries data and is available under an ODbL license. (See the attribution page for more information.)

Divisions data can be used for many purposes, which can include, but are not limited to:

  • reverse-geocoding
  • cartographic styling and map rendering
  • place labels
  • choropleth rendering
  • containment checks (e.g. point-in-polygon analysis)
  • choosing a geometry based on your use case
Overture divisions coverage - country and region boundaries
Overture divisions data, styled by subtype: countries in purple, region boundaries as green lines.

Dataset description​

Feature type descriptions​

A division is a feature type that represents an official or non-official organization of people: country, region, province, city, neighborhood, etc. — 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.

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.

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.

warning

The division_boundary feature type was introduced in the July 2024 release. It replaced the boundary feature type.

Subtype descriptions​

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

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

Data columns​

The addresses GeoParquet file contains the following properties:

Schema for the GeoParquet files in the divisions theme
Property NameTypeDescription
idstringA feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS.
geometryblobA WKB representation of the entity's geometry - a Point, Polygon, MultiPolygon, or LineString.
bboxarrayThe bounding box of an entity's geometry, represented with float values, in a xmin, xmax, ymin, ymax format.
versionintegerVersion number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed.
sourcesarrayThe array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified.
subtypestringCategory of the division from a finite, hierarchical, ordered list of categories (e.g. country, region, locality, etc.) similar to a Who's on First placetype.
wikidatastringA wikidata ID if available, as found on https://www.wikidata.org/.
populationintegerPopulation of the division.
namesarrayA primary name of the entity, and a set of optional name translations. Name translations are represented in key, value pairs, where the key is an ISO language code and the value is the translated name.
classstringA value to represent whether an entity represents a maritime or land feature.
division_idslistA list of the two division IDs that share this division boundary.
is_disputedbooleanIndicator if there are entities disputing this division boundary. Information about entities disputing this boundary should be included in perspectives property. This property should also be true if boundary between two entities is unclear and this is "best guess". So having it true and no perspectives gives map creators reason not to fully trust the boundary, but use it if they have no other.
perspectivesarrayPolitical perspectives from which this division boundary is considered to be an accurate representation. If this property is absent, then this boundary is not known to be disputed from any political perspective. Consequently, there is only one boundary feature representing the entire real world entity. If this property is present, it means the boundary represents one of several alternative perspectives on the same real-world entity.
local_typestringLocal name for the subtype property, optionally localized. This property is localized using a standard Overture names structure.
countrystringISO 3166-1 alpha-2 country code of the country or country-like entity, that this division represents or belongs to. If the entity this division represents has a country code, the country property contains it. If it does not, the country property contains the country code of the first division encountered by traversing the parent_division_id chain to the root.
regionstringISO 3166-2 principal subdivision code of the subdivision-like entity this division represents or belongs to. If the entity this division represents has a principal subdivision code, the region property contains it. If it does not, the region property contains the principal subdivision code of the first division encountered by traversing the parent_division_id chain to the root.
hierarchiesArrayHierarchies in which this division participates.
parent_division_idstringDivision ID of this division's parent division. Not allowed for top-level divisions (countries) and required for all other divisions. The default parent division is the parent division as seen from the default political perspective, if there is one, and is otherwise chosen somewhat arbitrarily. The hierarchies property can be used to inspect the exhaustive list of parent divisions.
normslistCollects information about local norms and rules within the division that are generally useful for mapping and map-related use cases. If the norms property or a desired sub-property of the norms property is missing on a division, but at least one of its ancestor divisions has the norms property and the desired sub-property, then the value from the nearest ancestor division may be assumed.
capital_division_idsarrayDivision IDs of this division's capital divisions. If present, this property will refer to the division IDs of the capital cities, county seats, etc. of a division.
capital_of_divisionslistDivision ID of the division that this feature is the capital of. If present, this property will refer to the division IDs of a parent county, region, country, etc.
division_idstringDivision ID of the division this area belongs to.
filenamestringName of the S3 file being queried.
themestringName of the Overture theme being queried.
typestringName of the Overture feature type being queried.

Data access and retrieval​

Overture's six data themes, including divisions, are freely available on both Amazon S3 and Microsoft Azure Blob Storage at these locations:

ProviderLocation
Amazon S3s3://overturemaps-us-west-2/release/
Azure Blob Storagehttps://overturemapswestus2.blob.core.windows.net/release/

Overture distributes its datasets as GeoParquet, a column-oriented spatial data format that is a backwards-compatible extension of Apache Parquet. 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.

The Getting Data section of this documentation offers instructions for using several tools to access Overture data, including DuckDB and Overture's Python command-line tool. See examples below for divisions.

You can find Overture's official Python command-line tool here.

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

overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=divisions -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.

Data usage guidelines​

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

To quickly view and download modest amounts of data, you can use the Overture Maps Explorer website.

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

This will download the area visible on your screen.

Exploring divsions data in NYC
Exploring divisions data in NYC using Overture's Explore tool.

Data manipulation and analysis​

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

LOAD spatial; -- noqa
LOAD httpfs;  -- noqa
-- Access the data on AWS in this example
SET s3_region='us-west-2';

SELECT
  count(*)
FROM
  read_parquet('s3://overturemaps-us-west-2/release/2024-11-13.0/theme=divisions/type=*/*', filename=true, hive_partitioning=1);
LOAD spatial; -- noqa
LOAD httpfs;  -- noqa

-- Access the data on AWS in this example
SET s3_region='us-west-2';

SELECT
  *
FROM
  read_parquet('s3://overturemaps-us-west-2/release/2024-11-13.0/theme=divisions/type=division_boundary/*', filename=true, hive_partitioning=1)
WHERE
  id = '085db5bb7fffffff0173c9b945a8c25f';

Exporting locality and neighborhood divisions to a local shapefile​

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

Query
LOAD spatial; -- noqa
LOAD httpfs;  -- noqa
-- Access the data on AWS in this example
SET s3_region='us-west-2';

COPY (
  SELECT
    id,
    names.primary as name,
    subtype,
    geometry -- DuckDB v.1.1.0 will autoload this as a `geometry` type
  FROM
    read_parquet('s3://overturemaps-us-west-2/release/2024-07-22.0/theme=divisions/type=division/*', filename=true, hive_partitioning=1)
  WHERE
    country = 'DK'
    AND subtype IN ('locality','neighborhood')
)
TO
  'overture_denmark_locality_neighborhood.shp'
WITH (
  FORMAT GDAL,
  DRIVER 'ESRI Shapefile',
  SRS 'EPSG:4326'
);

Exporting places data within Philadelphia to a local Parquet file​

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

Query
LOAD spatial; -- noqa
LOAD httpfs;  -- noqa

-- Access the data on AWS in this example
SET s3_region='us-west-2';

COPY (
  -- Create a temp table with the locality of Philadelphia
  WITH philly AS (
    SELECT
      id AS philly_id,
      names.primary AS philly_name,
      geometry AS philly_geom -- DuckDB v.1.1.0 will autoload this as a `geometry` type
    FROM
      read_parquet('s3://overturemaps-us-west-2/release/2024-11-13.0/theme=divisions/type=division_area/*', filename=true, hive_partitioning=1)
    WHERE
      subtype = 'locality'
      AND country = 'US'
      AND region = 'US-PA'
      AND names.primary = 'Philadelphia'
  ),

  -- Use the geometry of Philadelphia to filter out places within the locality boundary
  places AS (
    SELECT
      names.primary AS name,
      categories.primary AS category,
      ROUND(confidence,2) AS confidence,
      geometry -- DuckDB v.1.1.0 will autoload this as a `geometry` type
    FROM
      read_parquet('s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=places/type=*/*', filename=true, hive_partitioning=1)
    INNER JOIN
      philly
    ON ST_WITHIN(geometry, philly.philly_geom)
  )

  -- Export the places selection to a Parquet file
  SELECT
    *
  FROM
    places
)
TO
  'philly_places.parquet';

Revision history​

Version info​

You can find the most recent release notes here.

Support​

Feedback​

You can find a list of Overture repositories here.

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:

Discussions around Overture's divisions data should be filed in the Data repository.

Issues​

You can start and add to issues in each of the public Overture repositories, too. Some examples:

Issues around Overture's divisions data should be filed in the data repository.

Last updated on