Construct Nearmap API requests with the correct URL format, authentication, and rate-limit handling.

The 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

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.
Add the first query parameter after a question mark (?). Separate subsequent query parameters with an ampersand (&).

Case Sensitivity

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

Example

1. Create an API key in MyAccount and select the API application for your integration. If the application is unavailable, ask your Nearmap administrator to create it. See Authentication for API application and key management details.
2. Construct the URL using the format below. Replace each placeholder, including its braces, with the corresponding value. Replace {YOUR_API_KEY} with your API key, not your Nearmap username or password. Keep the key private; do not commit a URL containing it to source control or include it in shared logs.
3. Send an HTTPS GET request. The example requests a JPEG tile; on success, expect image content rather than a JSON response. If the request fails, check the HTTP status before interpreting the response body.

URL format

https://api.nearmap.com/tiles/v3/{tileResourceType}/{z}/{x}/{y}.{format}?apikey={YOUR_API_KEY}&since={xxM}&until={YYYY-MM-DD}

Example request URL — replace {YOUR_API_KEY} before sending:

https://api.nearmap.com/tiles/v3/Vert/21/1855981/1265938.jpg?apikey={YOUR_API_KEY}&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 APIs have a rate limit, meaning that there is a restriction on the number of requests and bulk requests that can be made against an endpoint over a period of time.

Number of requests

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. 

Responses from rate-limited APIs include these HTTP headers, whether or not the request exceeds the limit:

• 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

Inspect these headers to validate your client's request pacing. When X-Ratelimit-Remaining reaches 0, pause requests until X-Ratelimit-Reset rather than continuing to send requests.

A rate-limit error returns status 429 with this plain-text message:

Rate limit exceeded

To recover:

1. Read X-Ratelimit-Reset as a Unix timestamp in seconds, not milliseconds.
2. Wait until that time before retrying the request. If the response includes Retry-After, honor that delay as well.
3. Cap retries and pace subsequent requests within the published limit. Retries count toward the limit, so do not retry continuously.

Bulk requests

If you attempt to retrieve a large number of properties or tiles in bulk, causing excessive API requests in a short time and the operation cannot be completed, you will receive an HTTP 502 Bad Gateway error.

Reduce the number of concurrent requests and split the operation into smaller batches before retrying. Pace the batches using the rate-limit headers above instead of immediately resending the entire operation. Check the HTTP status rather than assuming that a 502 response has a JSON body.

API error codes

Check the HTTP status first. Parse an error body as JSON only when its Content-Type is application/json; gateway errors can return plain text.

• 401 Unauthorized: Check that you supplied your API key, that it is still valid in MyAccount, and that the request satisfies its IP address or referrer restrictions. Fix the key or restrictions before retrying.
• 403 Forbidden: Check whether your subscription includes access to the API. Retrying the same request will not grant access.
• 429 Too Many Requests: Wait for the reset time before retrying, as described above.
• 502 Bad Gateway during a bulk operation: Reduce concurrency and batch size before retrying.

For other generic errors and recovery steps, see API Error Codes. API-specific errors are covered in the documentation for each API.