{ "openapi": "3.0.0", "paths": { "/": { "get": { "description": "Returns the service name and version with links to the docs, the OpenAPI spec and llms.txt. Needs no API key.", "operationId": "getServiceInfo", "parameters": [], "responses": { "200": { "description": "Service information and documentation links." } }, "summary": "Service information", "tags": [ "root" ], "security": [] } }, "/buildings": { "get": { "description": "Find buildings within `radius` metres of a `lat`/`lng`, with footprint geometry and attributes such as height and number of floors where known. A location is required. Use `format=geojson` to draw them on a map.", "operationId": "searchBuildings", "parameters": [ { "name": "lat", "required": false, "in": "query", "description": "Latitude coordinate. Required if country code is not provided.", "schema": { "example": 40.7128, "type": "number" } }, { "name": "lng", "required": false, "in": "query", "description": "Longitude coordinate. Required if country code is not provided.", "schema": { "example": -74.006, "type": "number" } }, { "name": "radius", "required": false, "in": "query", "description": "Search radius in meters, defaulting to 1000 meters if not provided.", "schema": { "minimum": 1, "default": 1000, "example": 1000, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "schema": { "default": "json", "example": "json", "enum": [ "json", "csv", "geojson" ], "type": "string" } }, { "name": "includes", "required": false, "in": "query", "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "schema": { "example": [ "id", "geometry", "properties" ], "type": "array", "items": { "type": "string" } } }, { "name": "country", "required": false, "in": "query", "description": "ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided.", "schema": { "example": "US", "type": "string" } } ], "responses": { "200": { "description": "Buildings near the point.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BuildingDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "Search building footprints", "tags": [ "Buildings" ] } }, "/places": { "get": { "description": "Find points of interest near a point, or across a country on paid plans. Best query: `lat` + `lng` + `radius` (metres) with optional `categories`, `taxonomy`, `brand_name` or `name_prefix`. Country-level searches (`country` with no lat/lng) need a paid plan and a narrowing filter. Get valid category values from `GET /places/categories`. Page with `limit` and `page` and read the total from the `Pagination-Count` header. `enrichment_fields=brand` adds Wikidata brand details. The demo key is limited to small lat/lng searches.", "operationId": "searchPlaces", "parameters": [ { "description": "Latitude coordinate. Required if country code is not provided.", "name": "lat", "in": "query", "required": false, "schema": { "example": 40.7128, "type": "number" } }, { "description": "Longitude coordinate. Required if country code is not provided.", "name": "lng", "in": "query", "required": false, "schema": { "example": -74.006, "type": "number" } }, { "description": "Search radius in meters, defaulting to 1000 meters if not provided.", "required": false, "name": "radius", "in": "query", "schema": { "minimum": 1, "default": 1000, "example": 1000, "type": "integer" } }, { "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "required": false, "name": "limit", "in": "query", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "integer" } }, { "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "required": false, "name": "page", "in": "query", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "integer" } }, { "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "required": false, "name": "format", "in": "query", "schema": { "default": "json", "example": "json", "type": "string", "enum": [ "json", "csv", "geojson" ] } }, { "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "required": false, "name": "includes", "in": "query", "schema": { "example": [ "id", "geometry", "properties" ], "type": "string" } }, { "description": "ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided.", "required": false, "name": "country", "in": "query", "schema": { "example": "US", "type": "string" } }, { "description": "Filter places to only those with a source dataset matching this value.", "required": false, "name": "source", "in": "query", "schema": { "example": "meta", "type": "string" } }, { "description": "Wikidata brand ID associated with the place.", "required": false, "name": "brand_wikidata", "in": "query", "schema": { "example": "Q12345", "type": "string" } }, { "description": "Brand name associated with the place.", "required": false, "name": "brand_name", "in": "query", "schema": { "example": "Starbucks", "type": "string" } }, { "description": "Filter by the place's own name — an additional filter on top of lat/lng/radius (or country) search, not a standalone text search. Case-insensitive exact match against names.primary or any localized value in names.common.", "required": false, "name": "name", "in": "query", "schema": { "example": "Central Park", "type": "string" } }, { "description": "Partial-name search for type-ahead: matches places whose primary name starts with this text, or has a word that does (so \"blue bo\" and \"bottle\" both match \"Blue Bottle Coffee\"). Case-insensitive, at least 2 characters. Combine with lat/lng/radius and a small limit: results come nearest first.", "required": false, "name": "name_prefix", "in": "query", "schema": { "example": "blue bo", "type": "string" } }, { "description": "Minimum confidence score for the places to be returned, defaulting to 0.5 if not provided.", "required": false, "name": "min_confidence", "in": "query", "schema": { "default": 0.5, "example": 0.5, "type": "number" } }, { "description": "Array of category names, provided as a comma-separated string. Matches the legacy Overture categories vocabulary and the newer taxonomy/basic_category vocabulary.", "required": false, "name": "categories", "in": "query", "schema": { "example": "food,retail", "type": "string" } }, { "description": "Array of Overture taxonomy categories, provided as a comma-separated string. Matches the primary category or any ancestor in the taxonomy hierarchy, so e.g. \"food_and_drink\" matches every descendant category.", "required": false, "name": "taxonomy", "in": "query", "schema": { "example": "food_and_drink", "type": "string" } }, { "description": "Filter by operating status, e.g. \"open\" or \"permanently_closed\". Places without signals have a null operating status and are excluded when this filter is used.", "required": false, "name": "operating_status", "in": "query", "schema": { "example": "open", "type": "string" } }, { "description": "Comma-separated list of enrichment fields to include. Use \"brand\" for Wikidata-sourced brand details (logo, website, industry, parent) on branded places.", "required": false, "name": "enrichment_fields", "in": "query", "schema": { "example": "brand", "type": "string" } }, { "description": "Return only places that already have at least one of the listed contact fields. Comma-separated, matched with OR: e.g. \"website\" returns places with a website; \"website,social\" returns places with a website OR a social link. Useful for filtering to businesses you can verify. Allowed values: website, phone, email, social.", "required": false, "name": "has_contact", "in": "query", "schema": { "example": "website,social", "type": "string" } } ], "responses": { "200": { "description": "Return Places.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlaceResponseDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "Search places (POIs)", "tags": [ "Places" ] } }, "/places/buildings": { "get": { "description": "Same filters as `GET /places`, and each place also carries the footprint of the building it sits in. Use it when you need the shape or size of the premises, for example for site analysis or rooftop mapping. Slower than `/places`, so keep the radius small.", "operationId": "searchPlacesWithBuildings", "parameters": [ { "description": "Latitude coordinate. Required if country code is not provided.", "name": "lat", "in": "query", "required": false, "schema": { "example": 40.7128, "type": "number" } }, { "description": "Longitude coordinate. Required if country code is not provided.", "name": "lng", "in": "query", "required": false, "schema": { "example": -74.006, "type": "number" } }, { "description": "Search radius in meters, defaulting to 1000 meters if not provided. Capped lower than /places because building lookups are more expensive per meter of radius.", "required": false, "name": "radius", "in": "query", "schema": { "minimum": 1, "maximum": 2000, "default": 1000, "example": 1000, "type": "integer" } }, { "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "required": false, "name": "limit", "in": "query", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "integer" } }, { "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "required": false, "name": "page", "in": "query", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "integer" } }, { "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "required": false, "name": "format", "in": "query", "schema": { "default": "json", "example": "json", "type": "string", "enum": [ "json", "csv", "geojson" ] } }, { "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "required": false, "name": "includes", "in": "query", "schema": { "example": [ "id", "geometry", "properties" ], "type": "string" } }, { "description": "ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided.", "required": false, "name": "country", "in": "query", "schema": { "example": "US", "type": "string" } }, { "description": "Filter places to only those with a source dataset matching this value.", "required": false, "name": "source", "in": "query", "schema": { "example": "meta", "type": "string" } }, { "description": "Wikidata brand ID associated with the place.", "required": false, "name": "brand_wikidata", "in": "query", "schema": { "example": "Q12345", "type": "string" } }, { "description": "Brand name associated with the place.", "required": false, "name": "brand_name", "in": "query", "schema": { "example": "Starbucks", "type": "string" } }, { "description": "Filter by the place's own name — an additional filter on top of lat/lng/radius (or country) search, not a standalone text search. Case-insensitive exact match against names.primary or any localized value in names.common.", "required": false, "name": "name", "in": "query", "schema": { "example": "Central Park", "type": "string" } }, { "description": "Partial-name search for type-ahead: matches places whose primary name starts with this text, or has a word that does (so \"blue bo\" and \"bottle\" both match \"Blue Bottle Coffee\"). Case-insensitive, at least 2 characters. Combine with lat/lng/radius and a small limit: results come nearest first.", "required": false, "name": "name_prefix", "in": "query", "schema": { "example": "blue bo", "type": "string" } }, { "description": "Minimum confidence score for the places to be returned, defaulting to 0.5 if not provided.", "required": false, "name": "min_confidence", "in": "query", "schema": { "default": 0.5, "example": 0.5, "type": "number" } }, { "description": "Array of category names, provided as a comma-separated string. Matches the legacy Overture categories vocabulary and the newer taxonomy/basic_category vocabulary.", "required": false, "name": "categories", "in": "query", "schema": { "example": "food,retail", "type": "string" } }, { "description": "Array of Overture taxonomy categories, provided as a comma-separated string. Matches the primary category or any ancestor in the taxonomy hierarchy, so e.g. \"food_and_drink\" matches every descendant category.", "required": false, "name": "taxonomy", "in": "query", "schema": { "example": "food_and_drink", "type": "string" } }, { "description": "Filter by operating status, e.g. \"open\" or \"permanently_closed\". Places without signals have a null operating status and are excluded when this filter is used.", "required": false, "name": "operating_status", "in": "query", "schema": { "example": "open", "type": "string" } }, { "description": "Comma-separated list of enrichment fields to include. Use \"brand\" for Wikidata-sourced brand details (logo, website, industry, parent) on branded places.", "required": false, "name": "enrichment_fields", "in": "query", "schema": { "example": "brand", "type": "string" } }, { "description": "Return only places that already have at least one of the listed contact fields. Comma-separated, matched with OR: e.g. \"website\" returns places with a website; \"website,social\" returns places with a website OR a social link. Useful for filtering to businesses you can verify. Allowed values: website, phone, email, social.", "required": false, "name": "has_contact", "in": "query", "schema": { "example": "website,social", "type": "string" } } ], "responses": { "200": { "description": "Return Places with Buildings.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlaceResponseDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "Search places with their building footprints", "tags": [ "Places" ] } }, "/places/brands": { "get": { "description": "List brands (chains) with how many places each has, for a country or a lat/lng area. Use it to find the exact `brand_name` or `brand_wikidata` value to pass to `GET /places`, for example to map every location of a retail chain.", "operationId": "listPlaceBrands", "parameters": [ { "description": "Latitude coordinate. Required if country code is not provided.", "name": "lat", "in": "query", "required": false, "schema": { "example": 40.7128, "type": "number" } }, { "description": "Longitude coordinate. Required if country code is not provided.", "name": "lng", "in": "query", "required": false, "schema": { "example": -74.006, "type": "number" } }, { "description": "Search radius in meters, defaulting to 1000 meters if not provided.", "required": false, "name": "radius", "in": "query", "schema": { "minimum": 1, "default": 1000, "example": 1000, "type": "integer" } }, { "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "required": false, "name": "limit", "in": "query", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "integer" } }, { "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "required": false, "name": "page", "in": "query", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "integer" } }, { "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "required": false, "name": "format", "in": "query", "schema": { "default": "json", "example": "json", "type": "string", "enum": [ "json", "csv", "geojson" ] } }, { "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "required": false, "name": "includes", "in": "query", "schema": { "example": [ "id", "geometry", "properties" ], "type": "string" } }, { "description": "ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided.", "required": false, "name": "country", "in": "query", "schema": { "example": "US", "type": "string" } }, { "description": "Array of category names, provided as a comma-separated string.", "required": false, "name": "categories", "in": "query", "schema": { "example": [ "food", "retail" ], "type": "string" } } ], "responses": { "200": { "description": "Return all Brands, along with a count of all Places for each.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "List brands", "tags": [ "Places" ] } }, "/places/countries": { "get": { "description": "List the countries that have places, with place and brand counts for each. Use it to check coverage before a country-level search.", "operationId": "listPlaceCountries", "parameters": [], "responses": { "200": { "description": "Return all Countries, as well as a count of all the Places and Brands in each.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CountryResponseDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "List countries with places", "tags": [ "Places" ] } }, "/places/categories": { "get": { "description": "List the place categories present in a country or a lat/lng area, with place and brand counts. Use it to find valid values for the `categories` filter on `GET /places` (for example `cafe`, `pharmacy`, `restaurant`).", "operationId": "listPlaceCategories", "parameters": [ { "description": "Latitude coordinate. Required if country code is not provided.", "name": "lat", "in": "query", "required": false, "schema": { "example": 40.7128, "type": "number" } }, { "description": "Longitude coordinate. Required if country code is not provided.", "name": "lng", "in": "query", "required": false, "schema": { "example": -74.006, "type": "number" } }, { "description": "Search radius in meters, defaulting to 1000 meters if not provided.", "required": false, "name": "radius", "in": "query", "schema": { "minimum": 1, "default": 1000, "example": 1000, "type": "integer" } }, { "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "required": false, "name": "limit", "in": "query", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "integer" } }, { "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "required": false, "name": "page", "in": "query", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "integer" } }, { "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "required": false, "name": "format", "in": "query", "schema": { "default": "json", "example": "json", "type": "string", "enum": [ "json", "csv", "geojson" ] } }, { "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "required": false, "name": "includes", "in": "query", "schema": { "example": [ "id", "geometry", "properties" ], "type": "string" } }, { "description": "ISO 3166 country code consisting of 2 characters.", "required": false, "name": "country", "in": "query", "schema": { "minLength": 2, "maxLength": 2, "example": "US", "type": "string" } } ], "responses": { "200": { "description": "Return all Categories, along with a count of all Brands and Places for each", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryResponseDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "List place categories", "tags": [ "Places" ] } }, "/addresses": { "get": { "description": "Find address points within `radius` metres of a `lat`/`lng`. A location is required. Use it for address lookup, validation or reverse geocoding.", "operationId": "searchAddresses", "parameters": [ { "name": "lat", "required": false, "in": "query", "description": "Latitude coordinate. Required if country code is not provided.", "schema": { "example": 40.7128, "type": "number" } }, { "name": "lng", "required": false, "in": "query", "description": "Longitude coordinate. Required if country code is not provided.", "schema": { "example": -74.006, "type": "number" } }, { "name": "radius", "required": false, "in": "query", "description": "Search radius in meters, defaulting to 1000 meters if not provided.", "schema": { "minimum": 1, "default": 1000, "example": 1000, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "schema": { "default": "json", "example": "json", "enum": [ "json", "csv", "geojson" ], "type": "string" } }, { "name": "includes", "required": false, "in": "query", "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "schema": { "example": [ "id", "geometry", "properties" ], "type": "array", "items": { "type": "string" } } }, { "name": "country", "required": false, "in": "query", "description": "ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided.", "schema": { "example": "US", "type": "string" } } ], "responses": { "200": { "description": "Return Addresses.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AddressDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "Search addresses", "tags": [ "Addresses" ] } }, "/base": { "get": { "description": "Find base map features (land use, land cover, water and similar) within `radius` metres of a `lat`/`lng`. A location is required.", "operationId": "searchBaseFeatures", "parameters": [ { "name": "lat", "required": false, "in": "query", "description": "Latitude coordinate. Required if country code is not provided.", "schema": { "example": 40.7128, "type": "number" } }, { "name": "lng", "required": false, "in": "query", "description": "Longitude coordinate. Required if country code is not provided.", "schema": { "example": -74.006, "type": "number" } }, { "name": "radius", "required": false, "in": "query", "description": "Search radius in meters, defaulting to 1000 meters if not provided.", "schema": { "minimum": 1, "default": 1000, "example": 1000, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "schema": { "default": "json", "example": "json", "enum": [ "json", "csv", "geojson" ], "type": "string" } }, { "name": "includes", "required": false, "in": "query", "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "schema": { "example": [ "id", "geometry", "properties" ], "type": "array", "items": { "type": "string" } } }, { "name": "country", "required": false, "in": "query", "description": "ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided.", "schema": { "example": "US", "type": "string" } } ], "responses": { "200": { "description": "Return Base features.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "Search base map features", "tags": [ "Base" ] } }, "/transportation": { "get": { "description": "Find road, rail and path segments within `radius` metres of a `lat`/`lng`. A location is required.", "operationId": "searchTransportationSegments", "parameters": [ { "name": "lat", "required": false, "in": "query", "description": "Latitude coordinate. Required if country code is not provided.", "schema": { "example": 40.7128, "type": "number" } }, { "name": "lng", "required": false, "in": "query", "description": "Longitude coordinate. Required if country code is not provided.", "schema": { "example": -74.006, "type": "number" } }, { "name": "radius", "required": false, "in": "query", "description": "Search radius in meters, defaulting to 1000 meters if not provided.", "schema": { "minimum": 1, "default": 1000, "example": 1000, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "schema": { "default": "json", "example": "json", "enum": [ "json", "csv", "geojson" ], "type": "string" } }, { "name": "includes", "required": false, "in": "query", "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "schema": { "example": [ "id", "geometry", "properties" ], "type": "array", "items": { "type": "string" } } }, { "name": "country", "required": false, "in": "query", "description": "ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided.", "schema": { "example": "US", "type": "string" } } ], "responses": { "200": { "description": "Return Transportation segments.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransportationDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "Search transportation segments", "tags": [ "Transportation" ] } }, "/divisions": { "get": { "description": "Find countries, regions, localities and neighbourhoods by `name`, `country`, `subtype` or `admin_level`, or those containing or near a `lat`/`lng`. Use it to geocode a place name to a point or boundary before searching `/places`. Name searches omit boundary geometry by default (set `include_geometry=true`, or fetch one area with `GET /divisions/{id}`), because polygons can be megabytes each.", "operationId": "searchDivisions", "parameters": [ { "name": "lat", "required": false, "in": "query", "description": "Latitude coordinate. Required if no country, name or bbox filter is provided.", "schema": { "example": 40.7128, "type": "number" } }, { "name": "lng", "required": false, "in": "query", "description": "Longitude coordinate. Required if no country, name or bbox filter is provided.", "schema": { "example": -74.006, "type": "number" } }, { "name": "radius", "required": false, "in": "query", "description": "Search radius in meters, defaulting to 1000 meters if not provided.", "schema": { "minimum": 1, "default": 1000, "example": 1000, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more.", "schema": { "minimum": 1, "default": 100, "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0.", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Response format, defaulting to JSON. Options are \"json\", \"csv\", or \"geojson\".", "schema": { "default": "json", "example": "json", "enum": [ "json", "csv", "geojson" ], "type": "string" } }, { "name": "includes", "required": false, "in": "query", "description": "Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster.", "schema": { "example": [ "id", "geometry", "properties" ], "type": "array", "items": { "type": "string" } } }, { "name": "country", "required": false, "in": "query", "description": "ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided.", "schema": { "example": "US", "type": "string" } }, { "name": "name", "required": false, "in": "query", "description": "Case-insensitive substring match against the division primary name and English common name. Also matches an exact division ID.", "schema": { "example": "westminster", "type": "string" } }, { "name": "subtype", "required": false, "in": "query", "description": "Filter by division subtype, provided as a comma-separated list (e.g. \"county,locality\").", "schema": { "example": "county,locality", "type": "array", "items": { "type": "string" } } }, { "name": "admin_level", "required": false, "in": "query", "description": "Filter by admin_level — the division's position in its country's hierarchy (0 = country). Provided as a comma-separated list (e.g. \"1,2\").", "schema": { "example": "2", "type": "string" } }, { "name": "bbox", "required": false, "in": "query", "description": "Bounding box filter as \"xmin,ymin,xmax,ymax\" (lng/lat order). Returns divisions whose bounding box intersects it.", "schema": { "example": "-74.3,40.5,-73.7,40.9", "type": "string" } }, { "name": "include_geometry", "required": false, "in": "query", "description": "Whether to include the full polygon geometry in each result. Defaults to false for name searches (fetch geometry via GET /divisions/{id}) and true otherwise. Division polygons can be megabytes each, so leave this off for search boxes.", "schema": { "example": false, "type": "boolean" } } ], "responses": { "200": { "description": "Return Division areas.", "headers": { "Pagination-Count": { "description": "Total number of results matching the query, across all pages.", "schema": { "type": "integer" } }, "Pagination-Page": { "description": "The page served (0-indexed).", "schema": { "type": "integer" } }, "Pagination-Limit": { "description": "The page size used.", "schema": { "type": "integer" } }, "X-Total-Count": { "description": "Number of results in this response.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DivisionDto" } } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "Search administrative areas", "tags": [ "Divisions" ] } }, "/divisions/{id}": { "get": { "description": "Fetch one division area by its Overture ID, including its full boundary polygon. Use an ID returned by `GET /divisions`.", "operationId": "getDivision", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Overture division area ID", "schema": { "example": "0850b45bffffffff01c3320da9d5f43d", "type": "string" } } ], "responses": { "200": { "description": "Return the Division area.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DivisionDto" } } } }, "400": { "description": "The query is invalid or too broad: a parameter failed validation, a required location is missing, or the demo key was used outside its limits. The message says what to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "No API key, or the key is not valid. Send it in the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "The key is valid but its plan does not allow this query (for example a country-level /places query on the Free plan). Search by `lat`/`lng`/`radius` instead, or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Division area not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "429": { "description": "Rate limited. `error` is `rate_limited` for the per-minute limit or `monthly_quota_exceeded` for the plan's monthly limit. Wait for `Retry-After` seconds before retrying; do not retry immediately.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "API_KEY": [] } ], "summary": "Get an administrative area by ID", "tags": [ "Divisions" ] } } }, "info": { "title": "Overture Maps API", "description": "REST API for [Overture Maps Foundation](https://overturemaps.org) open data: places (POIs), buildings, addresses, administrative divisions, base and transportation features. No BigQuery, Athena or GeoParquet needed.\n\n## Authentication\nSend your key in the `x-api-key` header. Get a free key at https://account.overturemapsapi.com. The public key `DEMO-API-KEY` works for small lat/lng searches near a few demo cities.\n\n## Choosing a query\n- Search by `lat` + `lng` + `radius` (metres, up to 25,000) wherever you can. It is the fastest and cheapest query on every plan.\n- Country-level place searches (`country` with no `lat`/`lng`) need a paid plan and a narrowing filter such as `categories`, `brand_name` or `name`.\n- Use `GET /places/categories` to find valid category values before filtering `/places` by `categories`.\n- Results are paginated with `limit` and `page` (0-indexed). The `Pagination-Count` response header holds the total number of matches.\n- `format=geojson` returns a GeoJSON FeatureCollection; the default `json` returns an array.\n\n## Limits and errors\nEach plan has a monthly request limit (see https://www.overturemapsapi.com/pricing). Responses carry `X-Quota-Limit`, `X-Quota-Used`, `X-Quota-Remaining` and `X-Quota-Reset` headers. Errors return `{ statusCode, message, error? }`; the `message` explains how to fix the request. On `429`, wait for the `Retry-After` header before retrying.\n\n## More\nDocs and guides: https://www.overturemapsapi.com/docs/intro · LLM-friendly index: https://www.overturemapsapi.com/llms.txt · MCP server for Claude, ChatGPT and other AI tools: https://www.npmjs.com/package/@thatapicompany/overture-maps-mcp", "version": "1.0", "contact": { "name": "ThatAPICompany", "url": "https://www.overturemapsapi.com", "email": "aden@thatapicompany.com" } }, "tags": [ { "name": "Places", "description": "Points of interest: businesses, landmarks and amenities, with categories, brands, contact details and confidence scores." }, { "name": "Buildings", "description": "Building footprints and attributes such as height and number of floors." }, { "name": "Addresses", "description": "Address points." }, { "name": "Divisions", "description": "Administrative areas: countries, regions, localities and neighbourhoods, with names and boundaries." }, { "name": "Base", "description": "Base map features such as land use, land cover and water." }, { "name": "Transportation", "description": "Road, rail and path segments." }, { "name": "root", "description": "Service information and documentation links." } ], "servers": [ { "url": "https://api.overturemapsapi.com", "description": "Production" } ], "components": { "securitySchemes": { "API_KEY": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your API key from https://account.overturemapsapi.com. Use DEMO-API-KEY to try small lat/lng searches." } }, "schemas": { "ErrorResponseDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400, "description": "HTTP status code, repeated in the body." }, "message": { "description": "Human-readable explanation, written to be shown to the end user or relayed by an AI assistant. Often says how to fix the request (a narrower filter, a lat/lng search, or a plan that allows it). Validation errors return an array of messages.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Radius must be 25000 meters or less." }, "error": { "type": "string", "description": "Machine-readable reason, e.g. `monthly_quota_exceeded` or `rate_limited` on a 429.", "example": "monthly_quota_exceeded" } }, "required": [ "statusCode", "message" ] }, "GeometryDto": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of geometry", "example": "Point" }, "coordinates": { "description": "Coordinates representing the geometry.", "example": [ 40.7128, -74.006 ], "type": "array", "items": { "type": "number" } } }, "required": [ "type", "coordinates" ] }, "BuildingPropertiesDto": { "type": "object", "properties": { "subtype": { "type": "string", "description": "Subtype of the building" }, "class": { "type": "string", "description": "Class of the building" }, "names": { "type": "string", "description": "Names associated with the building" }, "level": { "type": "string", "description": "Level of the building" }, "has_parts": { "type": "boolean", "description": "Whether the building has parts" }, "height": { "type": "number", "description": "Height of the building" }, "is_underground": { "type": "boolean", "description": "Whether the building is underground" }, "num_floors": { "type": "number", "description": "Number of floors" } } }, "BuildingDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the place.", "example": "12345" }, "type": { "type": "string", "description": "Type of place or feature.", "example": "Point of Interest" }, "geometry": { "description": "Geometric representation of the place.", "allOf": [ { "$ref": "#/components/schemas/GeometryDto" } ] }, "properties": { "description": "Properties and additional details.", "allOf": [ { "$ref": "#/components/schemas/BuildingPropertiesDto" } ] } }, "required": [ "id", "type", "geometry", "properties" ] }, "CategoryDto": { "type": "object", "properties": { "primary": { "type": "string", "description": "Primary category of the place.", "example": "Retail" } }, "required": [ "primary" ] }, "TaxonomyDto": { "type": "object", "properties": { "primary": { "type": "string", "description": "Primary taxonomy category of the place.", "example": "accountant" }, "hierarchy": { "description": "Full taxonomy hierarchy path from the top-level category to the primary category.", "example": [ "services_and_business", "financial_service", "accountant" ], "type": "array", "items": { "type": "string" } }, "alternates": { "description": "Alternate taxonomy categories for the place.", "type": "array", "items": { "type": "string" } } } }, "BrandRulesDto": { "type": "object", "properties": { "variant": { "type": "string", "description": "Variant of the rule.", "example": "Abbreviation" }, "value": { "type": "string", "description": "Value associated with the rule.", "example": "CP" } }, "required": [ "variant", "value" ] }, "BrandNamesDto": { "type": "object", "properties": { "primary": { "type": "string", "description": "Primary name of the place.", "example": "Central Park" }, "common": { "type": "object", "description": "Common names in different languages.", "example": { "en": "Central Park", "es": "Parque Central" }, "properties": {} }, "rules": { "description": "Naming rules or variants associated with the place.", "type": "array", "items": { "$ref": "#/components/schemas/BrandRulesDto" } } }, "required": [ "primary" ] }, "BrandDto": { "type": "object", "properties": { "names": { "description": "Names associated with the brand, usually Primary is the most useful", "allOf": [ { "$ref": "#/components/schemas/BrandNamesDto" } ] }, "wikidata": { "type": "string", "description": "Wikidata QID of the brand.", "example": "Q37158" }, "ext_logo_url": { "type": "string", "description": "Brand logo URL (Wikimedia Commons, resizable with ?width=N). Sourced from Wikidata (CC0).", "example": "http://commons.wikimedia.org/wiki/Special:FilePath/Starbucks%20coffee%20wordmark.png" }, "ext_website": { "type": "string", "description": "Official brand website. Sourced from Wikidata (CC0).", "example": "https://www.starbucks.com/" }, "ext_industry": { "type": "string", "description": "Industry of the brand. Sourced from Wikidata (CC0).", "example": "coffee industry" }, "ext_parent": { "type": "string", "description": "Parent organisation of the brand. Sourced from Wikidata (CC0).", "example": "Starbucks Corporation" }, "ext_wikidata_label": { "type": "string", "description": "English label of the brand on Wikidata (CC0).", "example": "Starbucks" } }, "required": [ "names" ] }, "AddressDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the address.", "example": "12345" }, "type": { "type": "string", "description": "Type of place or feature.", "example": "Address" }, "geometry": { "description": "Geometric representation of the address.", "allOf": [ { "$ref": "#/components/schemas/GeometryDto" } ] }, "properties": { "description": "Properties and additional details.", "allOf": [ { "$ref": "#/components/schemas/AddressPropertiesDto" } ] } }, "required": [ "id", "type", "geometry", "properties" ] }, "SourceDto": { "type": "object", "properties": { "property": { "type": "string", "description": "Source property name.", "example": "OpenStreetMap" }, "dataset": { "type": "string", "description": "Dataset source for the place.", "example": "OSM" }, "record_id": { "type": "string", "description": "Unique identifier for the record in the dataset.", "example": "osm12345" }, "license": { "type": "string", "description": "License of the source data.", "example": "CDLA-Permissive-2.0" } }, "required": [ "property", "dataset", "record_id" ] }, "RulesDto": { "type": "object", "properties": { "variant": { "type": "string", "description": "Variant of the rule.", "example": "Abbreviation" }, "value": { "type": "string", "description": "Value associated with the rule.", "example": "CP" } }, "required": [ "variant", "value" ] }, "PlaceNamesDto": { "type": "object", "properties": { "primary": { "type": "string", "description": "Primary name of the place.", "example": "Central Park" }, "common": { "type": "object", "description": "Common names in different languages.", "example": { "en": "Central Park", "es": "Parque Central" }, "properties": {} }, "rules": { "description": "Naming rules or variants associated with the place.", "type": "array", "items": { "$ref": "#/components/schemas/RulesDto" } } }, "required": [ "primary" ] }, "PlacePropertiesDto": { "type": "object", "properties": { "categories": { "description": "Primary category of the place.", "allOf": [ { "$ref": "#/components/schemas/CategoryDto" } ] }, "basic_category": { "type": "string", "description": "Basic category of the place from the Overture taxonomy (schema v1.15+).", "example": "financial_service" }, "taxonomy": { "description": "Overture places taxonomy classification (schema v1.15+). Replaces `categories` upstream from September 2026; both are provided here.", "allOf": [ { "$ref": "#/components/schemas/TaxonomyDto" } ] }, "operating_status": { "type": "string", "description": "Operating status of the place, e.g. \"open\" or \"permanently_closed\". Null when no signals are present.", "example": "open" }, "confidence": { "type": "number", "description": "Confidence score of the place.", "example": 0.8 }, "websites": { "description": "Websites associated with the place.", "type": "array", "items": { "type": "string" } }, "emails": { "description": "Emails associated with the place.", "type": "array", "items": { "type": "string" } }, "socials": { "description": "Social media links associated with the place.", "type": "array", "items": { "type": "string" } }, "phones": { "description": "Phone numbers associated with the place.", "type": "array", "items": { "type": "string" } }, "brand": { "description": "Brand details if applicable.", "allOf": [ { "$ref": "#/components/schemas/BrandDto" } ] }, "addresses": { "description": "Address information of the place.", "type": "array", "items": { "$ref": "#/components/schemas/AddressDto" } }, "theme": { "type": "string", "description": "Theme associated with the place.", "example": "Restaurant" }, "type": { "type": "string", "description": "Type of feature or place.", "example": "Commercial" }, "version": { "type": "string", "description": "Version number of the place data.", "example": "1" }, "sources": { "description": "Source information for the place data.", "type": "array", "items": { "$ref": "#/components/schemas/SourceDto" } }, "names": { "description": "Name details for the place.", "allOf": [ { "$ref": "#/components/schemas/PlaceNamesDto" } ] }, "ext_name": { "description": "Name of the place.", "allOf": [ { "$ref": "#/components/schemas/PlaceNamesDto" } ] }, "ext_brand": { "type": "object", "description": "Wikidata-sourced brand details (CC0). Present when enrichment_fields includes \"brand\" and the place has a brand with a Wikidata QID." } }, "required": [ "categories", "theme", "type", "version", "sources", "names", "ext_name" ] }, "PlaceEnrichmentDto": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "hosted" ] }, "fields": { "type": "object" } }, "required": [ "source", "fields" ] }, "PlaceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the place.", "example": "12345" }, "type": { "type": "string", "description": "Type of place or feature.", "example": "Point of Interest" }, "geometry": { "description": "Geometric representation of the place.", "allOf": [ { "$ref": "#/components/schemas/GeometryDto" } ] }, "properties": { "description": "Properties and additional details of the place.", "allOf": [ { "$ref": "#/components/schemas/PlacePropertiesDto" } ] }, "enrichment": { "description": "Hosted enrichment data.", "allOf": [ { "$ref": "#/components/schemas/PlaceEnrichmentDto" } ] } }, "required": [ "id", "type", "geometry", "properties" ] }, "CountryCountsDto": { "type": "object", "properties": { "places": { "type": "number", "description": "Number of places in this Country", "example": 100 }, "brands": { "type": "number", "description": "Number of brands that are associated with the Country", "example": 10 } }, "required": [ "places", "brands" ] }, "CountryResponseDto": { "type": "object", "properties": { "country": { "type": "string", "description": "The ISO code of the Country.", "example": "US" }, "ext_counts": { "description": "Counts related to the Country e.g. how many Places and Brands are associated with it", "allOf": [ { "$ref": "#/components/schemas/CountryCountsDto" } ] } }, "required": [ "country", "ext_counts" ] }, "CategoryCountsDto": { "type": "object", "properties": { "places": { "type": "number", "description": "Number of places with this Category", "example": 100 }, "brands": { "type": "number", "description": "Number of brands that are associated with the Categorys", "example": 10 } }, "required": [ "places", "brands" ] }, "CategoryResponseDto": { "type": "object", "properties": { "primary": { "type": "string", "description": "Primary category of the place.", "example": "Retail" }, "ext_counts": { "description": "Counts related to the Category e.g. how many Places and Brands are associated with it", "allOf": [ { "$ref": "#/components/schemas/CategoryCountsDto" } ] } }, "required": [ "primary", "ext_counts" ] }, "AddressPropertiesDto": { "type": "object", "properties": { "country": { "type": "string", "description": "Country" }, "postcode": { "type": "string", "description": "Postcode" }, "street": { "type": "string", "description": "Street name" }, "number": { "type": "string", "description": "Street number" }, "unit": { "type": "string", "description": "Unit number" }, "address_levels": { "description": "Address levels (e.g., state, city)", "type": "array", "items": { "type": "string" } }, "postal_city": { "type": "string", "description": "Postal city" } } }, "BasePropertiesDto": { "type": "object", "properties": { "subtype": { "type": "string", "description": "Subtype of the feature" }, "class": { "type": "string", "description": "Class of the feature" } } }, "BaseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the base feature.", "example": "12345" }, "type": { "type": "string", "description": "Type of feature.", "example": "landUse" }, "geometry": { "description": "Geometric representation of the base feature.", "allOf": [ { "$ref": "#/components/schemas/GeometryDto" } ] }, "properties": { "description": "Properties and additional details.", "allOf": [ { "$ref": "#/components/schemas/BasePropertiesDto" } ] } }, "required": [ "id", "type", "geometry", "properties" ] }, "TransportationPropertiesDto": { "type": "object", "properties": { "subtype": { "type": "string", "description": "Subtype of the segment" }, "class": { "type": "string", "description": "Class of the segment" }, "subclass": { "type": "string", "description": "Subclass of the segment" }, "names": { "type": "object", "description": "Names associated with the segment" }, "connectors": { "description": "List of connectors", "type": "array", "items": { "type": "string" } }, "routes": { "description": "Routes", "type": "array", "items": { "type": "string" } }, "subclass_rules": { "description": "Subclass rules", "type": "array", "items": { "type": "string" } }, "access_restrictions": { "description": "Access restrictions", "type": "array", "items": { "type": "string" } }, "level_rules": { "description": "Level rules", "type": "array", "items": { "type": "string" } }, "destinations": { "description": "Destinations", "type": "array", "items": { "type": "string" } }, "prohibited_transitions": { "description": "Prohibited transitions", "type": "array", "items": { "type": "string" } }, "road_surface": { "description": "Road surface", "type": "array", "items": { "type": "string" } }, "road_flags": { "description": "Road flags", "type": "array", "items": { "type": "string" } }, "speed_limits": { "description": "Speed limits", "type": "array", "items": { "type": "string" } }, "width_rules": { "description": "Width rules", "type": "array", "items": { "type": "string" } }, "rail_flags": { "description": "Rail flags", "type": "array", "items": { "type": "string" } } } }, "TransportationDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the transportation segment.", "example": "12345" }, "type": { "type": "string", "description": "Type of segment.", "example": "Feature" }, "geometry": { "description": "Geometric representation of the segment.", "allOf": [ { "$ref": "#/components/schemas/GeometryDto" } ] }, "properties": { "description": "Properties and additional details.", "allOf": [ { "$ref": "#/components/schemas/TransportationPropertiesDto" } ] } }, "required": [ "id", "type", "geometry", "properties" ] }, "DivisionBboxDto": { "type": "object", "properties": { "xmin": { "type": "number", "description": "Minimum longitude", "example": -74.3 }, "xmax": { "type": "number", "description": "Maximum longitude", "example": -73.7 }, "ymin": { "type": "number", "description": "Minimum latitude", "example": 40.5 }, "ymax": { "type": "number", "description": "Maximum latitude", "example": 40.9 } }, "required": [ "xmin", "xmax", "ymin", "ymax" ] }, "DivisionPropertiesDto": { "type": "object", "properties": { "subtype": { "type": "string", "description": "Subtype of the division" }, "class": { "type": "string", "description": "Class of the division" }, "primary_name": { "type": "string", "description": "Primary name of the division", "example": "City of Westminster" }, "names": { "type": "object", "description": "Names of the division, including common names keyed by language code" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "GB" }, "region": { "type": "string", "description": "ISO 3166-2 region code", "example": "GB-WSM" }, "admin_level": { "type": "number", "description": "Position of the division in its country's hierarchy, e.g. 0 (country), 1, 2.", "example": 2 }, "is_land": { "type": "boolean", "description": "Whether the area represents land (vs maritime).", "example": true }, "is_territorial": { "type": "boolean", "description": "Whether the area includes territorial waters.", "example": false }, "division_id": { "type": "string", "description": "ID of the division feature this area belongs to." }, "ext_geometry_source": { "type": "string", "description": "Set when this record's own geometry is missing upstream and the boundary was served from a sibling area of the same division; the value is the sibling's class, e.g. \"maritime\" (land plus territorial waters).", "example": "maritime" } } }, "DivisionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the division area.", "example": "12345" }, "type": { "type": "string", "description": "Type of division.", "example": "division_area" }, "bbox": { "description": "Bounding box of the division area.", "allOf": [ { "$ref": "#/components/schemas/DivisionBboxDto" } ] }, "geometry": { "description": "Geometric representation of the division area. Omitted when include_geometry resolves to false; fetch it via GET /divisions/{id}.", "allOf": [ { "$ref": "#/components/schemas/GeometryDto" } ] }, "properties": { "description": "Properties and additional details.", "allOf": [ { "$ref": "#/components/schemas/DivisionPropertiesDto" } ] } }, "required": [ "id", "type", "properties" ] } } }, "externalDocs": { "description": "Documentation and guides", "url": "https://www.overturemapsapi.com/docs/intro" }, "security": [ { "API_KEY": [] } ] }