Page tree

Versions Compared

Key

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

...

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:

...

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.

...

You can use the Coverage API in conjunction with the Tile API to retrieve coverage (surveys):

...

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.

...

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, etc.

...

Read more about the API URL format.

Filter Surveys

By adding a filter, you can restrict the surveys which are considered for rendering. You can filter by date or by tag or by a combination of both, for a more powerful restriction.

Filter by date

Use the Since and Until parameters to restrict surveys by a date range.

Filter by tag

Use the Include and Exclude parameters to filter on tags. Tags are additional metadata attributes available for a small number of surveys that were flown after select events.

While each tag must have a type and a name, you can filter on any or both type and name. For example, post catastrophe captures are tagged with type “disaster” with the name corresponding to the nature of the event, e.g. “hurricane”, “tornado”, etc.
Example tags:

  • disaster:hurricane
  • disaster:tornado
  • disaster:misc (Property damage for other reasons)

The include and exclude parameters only filter on tags, not on any other metadata.

For example:

Code Block
themeEclipse
/tiles/v3/Vert/10/940/613.img?include=disaster&exclude=disaster:fire

Only includes surveys that have a disaster type with at least one disaster name, but exclude surveys with a disaster name fire.


Parameters

RequiredNameAPI / queryTypeDescription

(tick)

tileResourceTypeAPIstring

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.

(tick)

zAPIinteger

The zoom level. Uses the Google Maps Tile Coordinates.

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

(tick)

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

(tick)

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

(tick)

formatAPIstring

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, however it will increase the size of the response.

(tick)

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

(error)

tertiaryquerystring

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

The available values are:

  • 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'.

(error)

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

The 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 before the specified date

    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.

(error)

untilquerystring

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

The 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 after before the specified date.
  • If neither since nor until are specified, the request returns the latest imagery.

(error)

mosaicquerystring

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.

(error)includequerystring

Filters surveys so that only those tagged with the type and name specified are returned.

Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names.

  • type:name, e.g. disaster:hurricane
  • type, e.g. disaster
  • name, e.g. hurricane

Refer to Coverage API - Filter Surveys for further detail on tags.

(error)excludequerystring

Filters surveys so that only those not tagged with the type and name specified are returned.

Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names.

  • type:name, e.g. disaster:hurricane
  • type, e.g. disaster
  • name, e.g. hurricane

Refer to Coverage API - Filter Surveys for further detail on tags.

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:Australia

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

...

Code Block
themeEclipse
https://api.nearmap.com/tiles/v3/Vert/21/1855981/1265938.jpg?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz&until=2018-08-01


US

Code Block
themeEclipse
https://api.nearmap.com/tiles/v3/Vert/19/119799/215845.jpg?apikey=ZGE4MTdmNWYtZTdiNS00ZDRkLTg3MzItYjYwMzAyMzM5MjI0


Responses

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

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.

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.

...

Read more about the API URL format.


Info

This API will retrieve tiles up to the maximum zoom level of that tile set. To allow to zoom beyond the resolution at which the survey was captured in your application, we recommend you investigate client side up-scaling. Some of the popular applications and mapping frameworks support this functionality.

The advantage of doing this is that it allows the app to be more bandwidth efficient and to upscale on the client. This is more responsive and will consume less network traffic (and less usage for users).


Parameters

RequiredNameAPI / queryTypeDescription

(tick)

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.

(tick)

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.

(tick)

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

(tick)

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

(tick)

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

(tick)

formatAPIstring

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, however it will increase the size of the response.

(tick)

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

Example

...

Examples

Australia

Code Block
themeEclipse
https://api.nearmap.com/tiles/v3/surveys/100-4c51ffe8-ab52-11e8-9b7a-b3f8ca0bcb81/Vert/16/57999/39561.jpg?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz


US

Code Block
themeEclipse
https://api.nearmap.com/tiles/v3/surveys/88f1c072-0bdd-11ea-b266-130e886a3ec4/Vert/19/119799/215845.jpg?apikey=ZGE4MTdmNWYtZTdiNS00ZDRkLTg3MzItYjYwMzAyMzM5MjI0

Responses

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

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.