If you have used our APIs before, some of these features may be new to you.
The new Nearmap API standard is:
- Available on HTTPS only
- A global endpoint, intelligently routing requests to the closest Nearmap server
- Namespaced and versioned
- Available on api.nearmap.com only
- Rate limited
New API URL Format
The format of the new API URLs includethen the API namespace and version, then the API parameters, then the query parameters.
API parameters are part of the URL path, and the order in which they are used is significant.
The query parameters are added to the end of the URL in name and value pairs.
There is no significance to the order.
The first query parameter is added to the end of the URL following a question mark (?). The rest of the query parameters are separated from each other by the ampersand sign (&).
Read more about URL syntax.
All parameter names (in query parameters) and all parameter values are case sensitive.
In the above example tileResourceType, z, x, y, and format are API parameters, and apikey, since, and until are query parameters.
Nearmap's New APIs have a rate limit, meaning that there is a restriction on the number of requests that can be made against an endpoint over a period of time. If you go over the limit your request will fail, and you will receive an HTTP response saying that you have exceeded the limit, status code 429.
The intervals start at the first request, and there is a counter that is decremented on each request.
The API returns the following fields on every request, regardless if it's rate limited or not:
- X-Ratelimit-Limit - the total number of requests that the user is allowed to make in a given interval
- X-Ratelimit-Remaining - the remaining number of requests that the user can make before the reset time
- X-Ratelimit-Reset - Unix timestamp (seconds since Jan 1 1970 UTC) when the rate limit counter is reset