Skip to main content

Cloud Services

You can access and query Overture Maps parquet files directly in the cloud using one of the SQL query options documented below. You'll need an AWS account or a Microsoft Azure account.

tip

Overture's S3 bucket is located in the us-west-2 AWS region, so use us-west-2 for best performance.

Amazon Athena (AWS)

1. Add Overture as a data source

Add Overture as a cross-account data source using these instructions. The Catalog ID is 913550007193.

AWS Glue Data Catalog

AWS Glue Catalog

Depending on the permissions attached to your AWS user account/role, you may need to explicitly enable access to the Overture catalog. You can do that by adding a new IAM policy-- we suggest calling it OvertureGlueCatalogAccess -- with the following permissions:

IAM policy for Overture Glue Data Catalog access
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:GetTable*",
"glue:GetDatabase*",
"glue:GetPartition*"
],
"Resource": [
"arn:aws:glue:us-west-2:913550007193:catalog",
"arn:aws:glue:us-west-2:913550007193:database/release",
"arn:aws:glue:us-west-2:913550007193:table/*"
]
}
]
}

2. Inspect release tables

Now each release is available as a table under the release database in the overture data source (note the v at the beginning of the table name). The overture data catalog will be updated with a new table for each new release.

Overture Maps release tables

Release Tables

3. Access data from a release table

You can access Overture Maps data in a particular release like this:

SELECT *
FROM overture.release.v2024_05_16_beta_0
LIMIT 10

Here's how you might write an Athena SQL query to get Overture Maps places in Seattle:

SELECT id,
class,
sources[1].dataset AS primary_source,
names.primary AS primary_names,
ST_GeomFromBinary(geometry) AS geometry
FROM
overture.release.v2024_05_16_beta_0
WHERE theme='places'
AND type='place'
AND bbox.xmin > -122.44
AND bbox.xmax < -122.25
AND bbox.ymin > 47.56
AND bbox.ymax < 47.71

More information on using Athena is available in the Amazon Athena User Guide.

Optional

Add the table directly using the DDL

If you prefer to create the table in your own data catalog, you can run the complete DDL query in the Athena Query Console. This will create tables in your AWS account's data catalog pointing directly to data hosted on Overture's S3 bucket.

DDL query statement
CREATE EXTERNAL TABLE `v2024_05_16_beta_0` (
`id` string,
`geometry` binary,
`bbox` struct<xmin:float,xmax:float,ymin:float,ymax:float>,
`admin_level` int,
`is_maritime` boolean,
`geopol_display` string,
`version` int,
`update_time` string,
`sources` array<struct<property:string,dataset:string,record_id:string,confidence:double>>,
`subtype` string,
`locality_type` string,
`wikidata` string,
`context_id` string,
`population` int,
`iso_country_code_alpha_2` string,
`iso_sub_country_code` string,
`default_language` string,
`driving_side` string,
`names` struct<primary:string,common:map<string,string>,rules:array<struct<variant:string,language:string,value:string,at:array<double>,side:string>>>,
`locality_id` string,
`class` string,
`elevation` int,
`source_tags` map<string,string>,
`surface` string,
`is_salt` boolean,
`is_intermittent` boolean,
`level` int,
`has_parts` boolean,
`height` double,
`num_floors` int,
`facade_color` string,
`facade_material` string,
`roof_material` string,
`roof_shape` string,
`roof_direction` double,
`roof_orientation` string,
`roof_color` string,
`eave_height` double,
`min_height` double,
`building_id` string,
`categories` struct<main:string,alternate:array<string>>,
`confidence` double,
`websites` array<string>,
`socials` array<string>,
`emails` array<string>,
`phones` array<string>,
`brand` struct<wikidata:string,names:struct<primary:string,common:map<string,string>,rules:array<struct<variant:string,language:string,value:string,at:array<double>,side:string>>>>,
`addresses` array<struct<freeform:string,locality:string,postcode:string,region:string,country:string>>,
`connector_ids` array<string>,
`road` string)
PARTITIONED BY (
`theme` string,
`type` string)
STORED AS PARQUET
LOCATION
's3://overturemaps-us-west-2/release/2024-05-16-beta.0'

After you run the set-up query, you can load the partitions by running MSCK REPAIR TABLE overture or choosing "Load Partitions" from the table options menu.

Add a policy in your data catalog settings

If you want to share this catalog with other users and accounts, you'll need to add a policy enabling cross-account Glue catalog access. To do so, navigate to the data catalog settings and add a catalog policy that looks this:

Policy for sharing Overture Maps catalog
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": [
"glue:GetTable*",
"glue:GetDatabase*",
"glue:GetPartition*"
],
"Resource": [
"arn:aws:glue:<region>:<account id>:catalog",
"arn:aws:glue:<region>:<account id>:database/release",
"arn:aws:glue:<region>:<account id>:table/*"
]
}
]
}

release is the name of the database containing Overture tables.

Microsoft Synapse (Azure)

In your Azure account, create a Synapse workspace. You can then run this SQL query to read places in Seattle:

SELECT TOP 10 *
FROM
OPENROWSET(
BULK 'https://overturemapswestus2.blob.core.windows.net/release/2024-05-16-beta.0/theme=places/type=place/',
FORMAT = 'PARQUET'
)
WITH
(
names VARCHAR(MAX),
categories VARCHAR(MAX),
websites VARCHAR(MAX),
phones VARCHAR(MAX),
bbox VARCHAR(200),
geometry VARBINARY(MAX)
)
AS
[result]
WHERE
TRY_CONVERT(FLOAT, JSON_VALUE(bbox, '$.xmin')) > -122.4447744
AND TRY_CONVERT(FLOAT, JSON_VALUE(bbox, '$.xmax')) < -122.2477071
AND TRY_CONVERT(FLOAT, JSON_VALUE(bbox, '$.ymin')) > 47.5621587
AND TRY_CONVERT(FLOAT, JSON_VALUE(bbox, '$.ymax')) < 47.7120663

More information is available at "Query files using a serverless SQL pool" on Microsoft Learn.