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 and Panorama Imagery via 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, as per the de-facto web mapping standard (EPSG:3857; also known as EPSG:3785 and EPSG:900913). Nearmap’s Web Map Service (WMS 2.0) is recommended for other projections.
There are two ways you can use this API to retrieve tiles:
- Retrieve tiles for a specified location
- Retrieve tiles of a specified survey for a specified location
You can use the Coverage API in conjunction with the Tile API to retrieve coverage (surveys):
- Retrieve Coverage for a Given Polygon
- Retrieve Coverage for a Given Point
- Retrieve Coverage for a Given Tile Coordinate
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), 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.
NOTE: 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. Click here to view sample code for this.
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 OpenLayers, Leaflet, Google Maps JavaScript API, etc.
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. 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.
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:
/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
Required | Name | API / query | Type | Description |
|---|
✔️ | tileResourceType | API | string | 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. |
✔️ | z | API | integer | The zoom level. Uses the Google Maps Tile Coordinates. Note: the maximum zoom level is available from the Coverage API. |
✔️ | x | API | integer | The X tile coordinate (column). Uses the Google Maps Tile Coordinates. |
✔️ | y | API | integer | The Y tile coordinate (row). Uses the Google Maps Tile Coordinates. |
✔️ | format | API | string | 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. |
✔️ | apikey | query | string | Your API key. See API Key Authentication for more information. |
❌ | tertiary | query | string | 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'. |
❌ | since | query | string | The 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, 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. |
❌ | until | query | string | 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 before the specified date. ◾️ If neither since nor until are specified, the request returns the latest imagery. |
❌ | mosaic | query | string | 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. |
❌ | include | query | string | 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. |
❌ | exclude | query | string | 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.
Australia
https://api.nearmap.com/tiles/v3/Vert/21/1855981/1265938.jpg?apikey={YOUR_API_KEY}
The following example shows a URL request that specifies the dates for which to retrieve the imagery using the until optional parameter:
https://api.nearmap.com/tiles/v3/Vert/21/1855981/1265938.jpg?apikey={YOUR_API_KEY}&until=2018-08-01
US
https://api.nearmap.com/tiles/v3/Vert/19/119799/215845.jpg?apikey={YOUR_API_KEY}
Responses
The possible HTTP response status codes to the URL request are:
|
Code | Description |
|---|
| 200 | OK. 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. |
| 404 | Not 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.
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.
NOTE: 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
Required | Name | API / query | Type | Description |
|---|
✔️ | surveyid | API | string | 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. |
✔️ | contentType | API | string | 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.
|
✔️ | z | API | integer | The zoom level. The highest resolution is typically 21. Uses the Google Maps Tile Coordinates. |
✔️ | x | API | integer | The X tile coordinate (column). Uses the Google Maps Tile Coordinates. |
✔️ | y | API | integer | The Y tile coordinate (row). Uses the Google Maps Tile Coordinates. |
✔️ | format | API | string | 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. |
✔️ | apikey | query | string | Your API key. See API Key Authentication for more information. |
Examples
Australia
https://api.nearmap.com/tiles/v3/surveys/100-4c51ffe8-ab52-11e8-9b7a-b3f8ca0bcb81/Vert/16/57999/39561.jpg?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz
US
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:
Code | Description |
|---|
| 200 | OK. 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. |
| 404 | Not 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.
