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 72 Next »

About this API

Tile API v3 is the first widely available API 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 is:

  • Available on HTTPS only
  • Global endpoint, intelligently routing requests to the closest Nearmap server
  • Namespaced and versioned
  • Available on api.nearmap.com only


Should I be using this API?

If you have not used our APIs before then yes, this is the right Tile API for you to use. If you are already using the Nearmap Tile API (TMS), you should consider switching to this version of the API. This version is more feature rich and will allow you to do more with Nearmap content, such as:

  • Control over tile upscaling
  • Ability to hide low resolution satellite background imagery
  • Ability to request JPG or PNG tiles
  • Ability to request relative dates (e.g. show imagery that is at least one year old)
  • Richer metadata
  • Explicit survey tile requests

Introduction

Nearmap provides access to its vertical imagery via a Tile API using Google Maps Tile Coordinates, also known as Slippy Tilenames . The map into a pyramid of 256x256-pixel map tiles at multiple zoom levels. An application typically downloads a collection of adjacent tiles to cover a given region.

Only the Web Mercator projection is supported, as per the de-facto web mapping standard (EPSG:3857; also known as EPSG:3785 and EPSG:900913). Nearmap’s Web Map Service (WMS) is recommended for other projections.

There are two ways you can use this API to retrieve tiles:

You can use the Coverage API in conjunction with the Tile API:

Authentication

Access to Nearmap imagery is only available to authenticated subscribers. Tiles may be requested from Nearmap servers with an API Key. Please refer to the API Key Authentication guide for details on how to obtain and use an API Key.

Note: If you have been using the previous version of our Nearmap Tile API (TMS), you may need to delete your API key and create a new one. You can still use the same application, you do not have to create a new one.

URL Requests

Nearmap's Tile API is designed to be accessed by an application in an automated fashion via URL requests. We recommend that you use a mapping framework designed to consume tiled maps, such as  Google Maps JavaScript API,  OpenLayers,  Leaflet, etc.

Retrieve Tiles

This API retrieves vertical or panorama tiles for a specified location. Use this API to add a Nearmap basemap to your application, with optional date control.

Format

https://api.nearmap.com/tiles/v3/{TILERESOURCETYPE}/{X}/{Y}/{Z} .jpg

Parameters

RequiredNameTypeDescription

tileResourceTypestring

The resource type for the requested tiles. The available values are:

  • Vert - for vertical imagery
  • North - for North panorama imagery
  • South - for South panorama imagery
  • East - for East panorama imagery
  • West - for West panorama imagery

Note: the tileResourceType values are case sensitive.

zinteger

The zoom level. Uses the Google Maps Tile Coordinates.

Note: maximum zoom level is available from the Coverage API.

xintegerThe X tile coordinate (column). Uses the Google Maps Tile Coordinates.

yintegerThe Y tile coordinate (row). Uses the Google Maps Tile Coordinates.

formatstring

The format of the tile output. The available values are:

  • JPG - always JPEG
  • PNG - always PNG
  • IMG - JPEG by default, PNG when the tile is partial

Note that imagery is stored on Nearmap's servers as JPEG, so switching to PNG does not result in improvement in quality, whilst increasing the size of the response .

tertiarystring

The tertiary map to return when Nearmap tile is not found. The available values are: none, Default.

The default value is none.

Note: returned tiles will always be blended with tiles from another survey. Tertiary tiles will only be blended when tertiary parameter is not 'none'.

sincestring

The first day from which to retrieve the tiles (inclusive).

There two possible formats are:

  • For a specific date: YYYY-MM-DD, e.g. 2015-10-31 to retrieve imagery since this date.
  • For a relative date: xxY, xxM, or xxD, e.g. 5M to retrieve imagery since 5 months ago.

Notes:

  • If specified, and imagery at that location at that date exists, the request returns the imagery.
  • If specified, and imagery at that location at that date does not exist, the request returns imagery of the next available date after the specified date.
  • If neither since nor until are specified, the request returns the latest imagery.

untilstring

The last day from which to retrieve the tiles (inclusive).

There two possible formats are:

  • For a specific date: YYYY-MM-DD, e.g. 2015-10-31 to retrieve imagery until this date.
  • For a relative date: xxY, xxM, or xxD, e.g. 5M to retrieve imagery until 5 months ago.

Notes:

  • If specified, and imagery at that location at that date exists, the request returns the imagery.
  • If specified, and imagery at that location at that date does not exist, the request returns imagery of the next available date before the specified date.
  • If neither since nor until are specified, the request returns the latest imagery.

apikeystringYour API key. See API Key Authentication for more information.

Example

The following example shows a typical URL request :

https://api.nearmap.com/tiles/v3/Vert/14/15070/9842.jpg?apikey=YOUR_API_KEY

Responses

The possible responses to the URL request are:

CodeDescription
200OK. Tile image in JPEG or PNG format.
400

Bad Request. Return when request is invalid .

401

Unauthorized. Return when API key is invalid.

403Forbidden. Return when try to access not allowed area.
404Not Found. Return when cannot find any tiles for the requested condition.
429Too Many Requests. Return when rate limit is reached.
5XXServer Error. Return when something wrong in the server side.

Retrieve Tiles of a Specified Survey

This API retrieves vertical or panorama tiles of a specified survey for a specified location. Use this API to retrieve imagery for a single survey.

Format

https://api.nearmap.com/tiles/v3/surveys/{surveyid}/{contentType}/{z}/{x}/{y}.{format}

Parameters

RequiredNameTypeDescription

surveyidstring

The survey ID in the format of UUID. Only tiles of the specified survey will be returned. You can use the ID from the survey object returned by the Coverage API.

contentTypestring

The content type for the requested tiles. The available values are:

  • Vert - for vertical imagery
  • North - for North panorama imagery
  • South - for South panorama imagery
  • East - for East panorama imagery
  • West - for West panorama imagery

zintegerThe zoom level. The highest resolution is typically 21. Uses the Google Maps Tile Coordinates.

xintegerThe X tile coordinate (column). Uses the Google Maps Tile Coordinates.

yintegerThe Y tile coordinate (row). Uses the Google Maps Tile Coordinates.

formatstring

The format of the tile output. The available values are:

  • JPG - always JPEG
  • PNG - always PNG
  • IMG - JPEG by default, PNG when the tile is partial

Note that imagery is stored on Nearmap's servers as JPEG, so switching to PNG does not result in improvement in quality, whilst increasing the size of the response

apikeystringYour API key. See API Key Authentication for more information.

Example

The following example shows a typical URL request:

https://api.nearmap.com/tiles/v3/surveys/100-a46aede4-a697-11e8-89dc-236477e9a379/Vert/14/15070/9842.jpg?apikey=YOUR_API_KEY

Responses

The possible responses to the URL request are :

CodeDescription
200OK. Tile image in JPEG or PNG format.
400

Bad Request. Return when request is invalid.

401

Unauthorized. Return when API key is invalid.

403Forbidden. Return when try to access not allowed area.
404Not Found. Return when cannot find any tiles for the requested condition.
429Too Many Requests. Return when rate limit is reached.
5XXServer Error. Return when something wrong in the server side.
  • No labels