API URL Format

The format of the new API URLs includes https://api.nearmap.com, then the API namespace and version, then the API parameters, then the query parameters.

API Parameters

API parameters are part of the URL path, and the order in which they are used is significant.

Query Parameters

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.

Case Sensitivity

All parameter names (in query parameters) and all parameter values are case sensitive.

Example

Format: https://api.nearmap.com/tiles/v3/{tileResourceType}/{z}/{x}/{y}.{format}?apikey={YOUR_API_KEY}&since={xxM}&until={YYYY-MM-DD} Request: https://api.nearmap.com/tiles/v3/Vert/21/1855981/1265938.jpg?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz&since=12M&until=2018-08-01\

In the above example, tileResourceType, z, x, y, and format are API parameters, and apikey, since, and until are query parameters.

Rate Limiting

Nearmap's 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 whether 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