Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This guide includes the following sections:

Table of Contents
maxLevel1

About this API

Tile API and Coverage API are the first widely available APIs that follow a new standard for Nearmap APIs

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 TMS (Tile) API, 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 Vertical and Panorama Imagery via a subset of the Tile Map Service (TMS) protocol. TMS splits a Tile API using Google Maps Tile Coordinates, also known as Slippy Tilenames. They 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 by Nearmap’s TMS , 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.

Available APIs

Nearmap Tiles APIs are used to retrieve tiles. There are two APIs ways you can use for this purposeAPI to retrieve tiles:

In addition, there are three Coverage APIs that are used in You can use the Coverage API in conjunction with the Tile APIsAPI to retrieve coverage (surveys):

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.

Info

Note: If you have been using the previous version of our Nearmap Tile API (TMS), your existing API key might not work with the new API. If this is the case, please create a new API key to utilise this API. Note that your existing applications will be affected if you delete and re-create your existing API Key.

Panorama Imagery

Nearmap Panorama imagery is an orthorectified mosaic of 45 degree imagery from each cardinal direction (North, South, East, West), intended for visualisation use only.

The intended use of the Tile API for Panorama imagery is integration of Panorama imagery in a third-party web application, also for visualisation only.

Because it is created by combining many images, metadata that is normally associated with oblique imagery (such as pose and calibration), is not available. All the metadata available for panorama imagery is described under Coverage API.

Info

Availability

The Panorama imagery is only available to customers with a Nearmap Panorama or Nearmap Oblique product.

Integration of Panorama tiles into a mapping application is complex. You will need to have significant experience with coordinate system geometry and map projections, and experience developing non-trivial mapping applications with a mapping framework such as OpenLayers or Leaflet.

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 OpenLayersLeafletGoogle Maps JavaScript API,  OpenLayers,  Leaflet, etc etc.

Security

...

Rate Limit

Nearmap's Tile API has a rate limit, meaning that there is a restriction on the number of requests that can be made against an endpoint. 

Retrieve Tiles

This API retrieves vertical or panorama tiles for a specified location

Talk
idtalk-82
. Use this API to add a Nearmap basemap to your application, with optional date control.

API URL Format

https://api.nearmap.com/tiles/v3/{

...

tileResourceType}/{

...

z}/{

...

x}/{

...

y}.

...

{format}?apikey={YOUR_API_KEY}

Read more about the API URL format.

Parameters

RequiredNameAPI / queryTypeDescription

Awesome Icon
color#001E60
iconfa-check-square-o

contentType
tileResourceType
Talk
idtalk-83
APIstring

The

content

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.

Awesome Icon
color#001E60
iconfa-check-square-o

zAPIinteger

The zoom level.

The highest resolution is typically 21.

Uses the Google

XYZ scheme.

Maps Tile Coordinates.

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

Awesome Icon
color#001E60
iconfa-check-square-o

xAPIintegerThe X tile coordinate (column). Uses the Google
XYZ scheme
Maps Tile Coordinates.

Awesome Icon
color#001E60
iconfa-check-square-o

yAPIintegerThe Y tile coordinate (row). Uses the Google
XYZ scheme
Maps Tile Coordinates.

Awesome Icon
color#001E60
iconfa-check-square-o

formatAPIstring

The format of the tile output.

The

available

available values are

 

:

  • jpg - always JPEG
  • png
, jpg, img
Talk
idtalk-84
.
  • - 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, however it will increase the size of the response.

Awesome Icon
color#001E60
iconfa-check-square-o

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

Awesome Icon
color#001E60
iconfa-square-o

tertiaryquerystring

The tertiary map to return when a Nearmap tile is not found.

The

available

available values

 are

are:

none, Default, Google, Here
Talk
idtalk-85
.

The default value is none.

  • none (default) - no tertiary imagery in the background
  • satellite - use our current tertiary backdrop

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

Awesome Icon
color#001E60
iconfa-square-o

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

There

The two possible formats are:

  • For a specific date:
YYYYMMDD
  • 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 closest previous date.
  • If not specified
    • the since parameter controls the earliest imagery that is returned. If there are multiple captures after the date specified by the since parameter, the latest imagery is returned.

    • If the mosaic parameter is set to earliest, the imagery on or after the date specified by the since parameter is returned.

    • If neither since nor until are specified, the request returns the latest imagery.

    Awesome Icon
    color#001E60
    iconfa-square-o

    untilquerystring

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

    There

    The two possible formats are:

    • For a specific date:
    YYYYMMDD
    • 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
    closest previous date
    • next available date before the specified date.
    • If
    not specified
    • neither since nor until are specified, the request returns the latest imagery.

    Awesome Icon
    color#001E60
    iconfa-square-o

    apikey
    mosaic
    stringYour API key. See API Key Authentication for more information.

    Example

    querystring

    Specifies the order in which the surveys covering the specified area are prioritised.

    The available values are:

    • latest - the imagery with the later capture date is prioritised

    • earliest - imagery with the earlier capture date is prioritised

    If the mosaic parameter is not specified, the imagery with the later capture date is prioritised.

    To return imagery on or after a specified date, use mosaic=earliest in combination with the since parameter.

    Examples

    These examples use a demo API key. Replace this API key with your own when using the Tile API.

    The following example shows a typical URL request:

    Code Block
    themeEclipse
    https://api.nearmap.com/tiles/v3/Vert/21/1855981/1265938.jpg?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz


    The following example shows a URL request that specifies the dates for which to retrieve the imagery using the until optional parameter:

    Code Block
    themeEclipse
    https://api.nearmap.com/tiles/v3/Vert/1721/1159951855981/791171265938.pngjpg?tertiaryapikey=noneYzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz&apikey=YOUR_API_KEYuntil=2018-08-01

    Responses

    ...

    The possible responses to HTTP response status codes to the URL request are:

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

    Bad Request.

    Return

    Returned when the request is invalid. This means either the format is wrong, or a value is out of range.

    401

    Unauthorized. Return Returned when the API key is invalid.

    403

    Forbidden.

    Return

    Returned when

    try

    not allowed to access

    not allowed area

    the requested location.

    404Not Found. Return Returned when cannot find any tiles for the requested condition.
    429

    Too Many Requests.

    Return

    Returned when the rate limit is reached.

    5XX

    Server Error.

    Return

    Returned when something is 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.

    API URL Format

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

    Read more about the API URL format.

    Parameters

    RequiredNameAPI / queryTypeDescription

    Awesome Icon
    color#001E60
    iconfa-check-square-o

    surveyidAPIstring

    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.

    Awesome Icon
    color#001E60
    iconfa-check-square-o

    contentTypeAPIstring

    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

    Note: the tileResourceType values are case sensitive.

    Awesome Icon
    color#001E60
    iconfa-check-square-o

    zAPIintegerThe zoom level. The highest resolution is typically 21. Uses the Google
    XYZ scheme
    Maps Tile Coordinates.

    Awesome Icon
    color#001E60
    iconfa-check-square-o

    xAPIintegerThe X tile coordinate (column). Uses the Google
    XYZ scheme
    Maps Tile Coordinates.

    Awesome Icon
    color#001E60
    iconfa-check-square-o

    yAPIintegerThe Y tile coordinate (row). Uses the Google
    XYZ scheme
    Maps Tile Coordinates.

    Awesome Icon
    color#001E60
    iconfa-check-square-o

    formatAPIstring

    The format of the tile output. The available values are

     

    :

      • jpg - always JPEG
      • png
    , jpg, img
      • - 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, however it will increase the size of the response.

    Awesome Icon
    color#001E60
    iconfa-check-square-o

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

    Example

    The following example shows a typical URL request:

    Code Block
    themeEclipse
    https://api.nearmap.com/api/tiles/v3/surveys/7b3e120a100-79454c51ffe8-ab52-11e8-9e779b7a-b119b97a8973b3f8ca0bcb81/Vert/1716/11599557999/7911739561.pngjpg?apikey=YOUR_API_KEYYzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz
    

    Responses

    The possible responses to HTTP response status codes to the URL request are the same as the previous API.:

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

    Bad Request. Returned when the request is invalid. This means either the format is wrong, or a value is out of range.

    401

    Unauthorized. Returned when the API key is invalid.

    403

    Forbidden. Returned when not allowed to access the requested location.

    404Not Found. Returned when cannot find any tiles for the requested condition.
    429

    Too Many Requests. Returned when the rate limit is reached.

    5XX

    Server Error. Returned when something is wrong in the server side.

    Panorama Coordinate Systems

    Please refer to Panorama Coordinate Systems to get more background about Nearmap’s tile interface, including important tiling parameters.