Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Current »

Introduction

Nearmap's Tile API and Coverage API are the first widely available APIs that follows a new standard for Nearmap APIs. 

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 include 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}

URL Request:
https://api.nearmap.com/tiles/v3/Vert/21/1855981/1265938.jpg?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz&since=12M&until=2018-08-01

In the above example tileResourceTypezxy, and format are API parameters, and apikeysince, and until are query parameters.

Rate Limiting

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


  • No labels