Skip to content

Overview

Authorization

In order to use the API, a key is required. This key is used to authenticate requests associated with your project for usage and billing purposes. All requests that lack an API key will fail.

To authenticate requests, include the API key as a bearer token in the Authorization header.

Authorization: Bearer <API_KEY>

Format

The API expects requests to be in JSON format. The response will also be in JSON format.

For endpoints that return geometry information, the format will be compatible with the GeoJSON specification.

Tip

Coordinates are represented as an array or a set of arrays with the longitude and latitude values.

Rate Limiting and Quotas

Be aware that all requests are subject to rate limiting and quotas. These values are set per API key depending on the plan you are subscribed to and they are enforced to prevent abuse and ensure fair usage.

Rate limits are applied to the number of requests you can make in a given time frame. Quotas are applied to the total number of requests you can make in a month.

Note

Rate limits are usually applied on a per-minute basis, but this may vary depending on your plan.

Warning

If you exceed the monthly quota, the requests won't be rejected, but you might be charged for the extra usage.

Caching and Data Persistence

Caching data is allowed and encouraged to reduce the number of requests and increase the speed of your application. However, there are some considerations to take into account:

  • Data Refresh: You must refresh your cache at least once every 24 hours to ensure freshness. We update our data regularly, so you should not rely on outdated information.
  • Cache Expiry: Cached data cannot be stored for more than 30 days. After this period, it must be refreshed or deleted.
  • Geometry Simplification: While internally we use full-quality geometry for operations, any geometry data returned might be simplified to optimize response size.
  • Persistent Storage: You may persist data in a storage system as a fallback for your cache, but it should not replace the need for periodic updates.
  • Persistent Storage Policy: While caching is permitted, you are not allowed to structure or store our data in a way that creates a permanent database or any other system that functions as a long-term storage repository.