This guide describes the DSM and True Ortho API. This product makes DSM and True Ortho content available for rapid access via API.

Overview

The DSM and True Ortho API provides access to a subset of Nearmap 3D content, namely the Digital Surface Model and the True Ortho. Additionally, users of the API can access Nearmap's vertical content. This API is designed to work with smaller areas, such as typical residential and small commercial properties. For such small areas, this API provides low latency access, typically completed in under a second. 

Before you start

The DSM and TrueOrtho API requires a special subscription. Contact your Nearmap Account Manager for more information.

Before you start using your DSM and TrueOrtho API key, if there are multiple subscriptions on your Nearmap account, you need to ensure that you are allocated the correct license.

Your Nearmap administrator needs to do this for you by following the steps in this article: Change a Nearmap Licence.

How to use the API

The DSM and True Ortho API uses the new Staticmap API. The new Staticmap API has a path prefix of /staticmap/v2/. The v2 designation is to distinguish it from the existing legacy staticmap end point (Image API).

The sequence of calling the APIs is important and is as follows:

1. Coverage API Call

  • This API provides the details on the available coverage for the requested area.
  • The area is given bounding box, defined by a point and a distance from the point.
  • This is separate from the existing Coverage APIs
  • The Coverage call creates a transaction token that should be used to retrieve the image.

API URL Format

https://api.nearmap.com/staticmap/v2/coverage.json?point={x},{y}&radius={radiusMetres}&apikey={YOUR_API_KEY}

Read more about the API URL format.

Find out about how to obtain your API key here: Managing API Keys

Parameters

RequiredNameTypeDescription
(tick)pointstring

The point for which the surveys are retrieved. The point is the longitude and latitude of the location on which to centre the image, in the format LONG,LAT.

For example, -74.044831,40.689669

Note:

  • LONG comes before LAT
  • There should be no spaces between the LONG, the comma "," and the LAT
(tick)radiusintegerDistance from the point in metres. Used in conjunction with point to define a bounding box (not a circle). Radius range between 1-100.
(error)overlapstring

Whether or not to return metadata for imagery that only partially intersects the requested area. Default is to return all, such that surveys that only partially intersect the AOI will still be returned. If full is specified, then only surveys completely within the given AOI are included.

Options include:

  • full
  • all
(error)sincestring

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

The two possible formats are:

  • For a specific date: YYYY-MM-DD
     E.G. 2015-10-31 to retrieve surveys since this date

  • For a relative date: xxY, xxM or xxD
     E.G. 5M to retrieve surveys since 5 months ago.


The since and until parameters are used to further restrict the surveys that are returned.

(error)untilstring

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

The two possible formats are:

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

The since and until parameters are used to further restrict the surveys that are returned.

(tick)resourcesstring

Comma separated list of resource types indicating the survey resources to return in the response.

This can be any or all of:

  • DetailDsm
  • TrueOrtho
  • Vert

Example: DetailDsm,TrueOrtho,Vert

(error)fieldsstring

Comma separated list of field names that will appear in the response. The id field will always be among the returned fields, even if it is not specified. If this parameter is not present, then all fields are returned.

This can be any or all of:

  • id
  • captureDate
  • firstPhotoTime
  • lastPhotoTime
  • pixelSizes

Example: id,captureDate,firstPhotoTime,lastPhotoTime,pixelSizes

Note: the fields values are case sensitive.

(error)limitinteger

Limit the number of surveys in the result.

Default is 100, Maximum is 1000.

(error)offsetinteger

The offset of the first survey to be displayed.

With no offset, the first survey to be displayed is the most recent one. If the offset is '3', the first survey to be displayed will be the 4th most recent survey.


Example

https://api.nearmap.com/staticmap/v2/coverage.json?point=151.2144030%2C-33.8580750&radius=100&since=12M&resources=DetailDsm%2CTrueOrtho%2CVert&limit=200&apikey={YOUR_API_KEY}

Replace '{YOUR_API_KEY}' with your API Key.

Response


{
  "surveys": [
    {
      "captureDate": "2021-01-24",
      "firstPhotoTime": "2021-01-24T02:44:42Z",
      "id": "32003632-642d-11eb-90c6-1fc3caf0ce28",
      "lastPhotoTime": "2021-01-26T02:37:25Z",
      "pixelSizes": {
        "DetailDsm": 0.15,
        "TrueOrtho": 0.055,
        "Vert": 0.055
      }
    }
  ],
  "limit": 200,
  "offset": 0,
  "total": 1,
  "transactionToken": "{YOUR_TRANSACTION_JWT_HERE}"
}


2. Read the Survey ID and Transaction Token from the coverage response

The transaction token encodes the user credentials and restricts the image to be returned for the same area as the one requested by the coverage request.


IMPORTANT: Keep your Transaction Token in a safe place. Persist your token if you want to reuse it and download multiple images.

3. Image API Call

  • This API returns raster content based on the requested location, content type and output format.
  • Construct any number of image type requests for the same area as coverage using the Survey ID and Transaction Token.
  • Access to DSM, True Ortho, and Vertical imagery 
  • Image returns using Web Mercator projection
  • Able to be used in bulk.
  • Support images of up to 5,000 x 5,000 pixels
  • The same request with different content types returns an image of the same area.

API URL Format

https://api.nearmap.com/staticmap/v2/surveys/{surveyId}/{imageType}.{format}?point={x},{y}&radius={radiusMetres}&size={imageSize}&transactionToken={TRANSACTION_TOKEN_FROM_COVERAGE_RESPONSE}

Read more about the API URL format.

Parameters

RequiredNamePath / QueryTypeDescription
(tick)surveyIDpathstring

Identifier of the survey to retrieve content for, as obtained from the coverage response.

This will correspond to a specific date

(tick)typepathstring

Type of raster content to return.

This corresponds to the requested types in the coverage end point.

It can be one of:

  • DetailDsm
  • TrueOrtho
  • Vert
(tick)formatpathstring

File format of the resulting raster image.

It can be one of:

  • tif
  • jpg
  • png
  • jgw
  • pgw
  • tfw
(tick)pointquerystring

The point for which the surveys are retrieved. The point is the longitude and latitude of the location on which to centre the image, in the format LONG,LAT.

For example:

-74.044831,40.689669

Note:

  • LONG comes before LAT
  • There should be no spaces between the LONG, the comma "," and the LAT
(tick)radiusqueryintegerDistance from the point in metres. Used in conjunction with point to define a bounding box (not a circle). Radius range between 1-100.
(tick)sizequerystring

Size of the resultant image in pixels.

It is the responsibility of the caller to maintain the aspect ratio of the requested image.

The format is '{width}x{height}', however only equal width and height values are currently supported.

Maximum image size is "5000x5000".

(tick)transactionTokenquerystring

Transaction token to use in an image request.

This token is returned in the staticmap coverage response and contains the authentication information for the request.

Multiple image requests made using the same transaction token do not incur additional usage costs within 30 days since the coverage call was made.

Example

https://api.nearmap.com/staticmap/v2/surveys/dc26410e-6331-11ea-9feb-eb1617c46d8e/TrueOrtho.tif?point=151.0904291%2C-33.724291&radius=100&size=5000x5000&transactionToken={TRANSACTION_TOKEN}

Response

Image requested

Validity and Usage

The coverage response provides a Transaction Token. This token is valid 30 days form the coverage call.

Once you've successfully requested the first image, this is counted against your monthly transaction allowance. You can subsequently make multiple calls to retrieve DSM/TrueOrtho/Vertical imagery within the original AOI without being charged, until the Transaction Token expires.

Service Limits

As you use the API, you should be aware of the following limits:


ValueNotes
Maximum Image Width/Height5000 pxReturned images may be at most 5000 px on either side
Maximum radius100 mA maximum radius of 100 m implies a maximum 200x200 m
Maximum rate limitAs per response headersThe API is rate limited and the rate limit is reported via API headers, see Rate Limiting section for more information.
Maximum transaction validity30 daysTransactions expire 30 days after the transaction token is issued
Available content types
  • DSM
  • True Ortho
  • Vertical

Datum and Projection Information

DSM and True Ortho content is delivered using the following specifications:


 

DSM

True Ortho

Projection

EPSG:3857 (Web Mercator)

Horizontal Datum

WGS84 (ITRF2014 realisation)

Epoch

date of the imagery.
E.g. epoch of imagery captured on June 30 2017 is 2017.492

Vertical DatumAU: AHD (AusGeoid09)
US: EGM2008
Canada: CGVD2013 		 
 
N/A


Interactive API Documentation

Below section provides interactive documentation for the API, allowing you to test the API live and inspect the requests and responses. 


openapi: 3.0.0 info: title: Staticmap description: The staticmap API returns coverage and image information for arbitrary AOIs. version: "v2" contact: email: support@nearmap.com servers: - description: Production url: https://api.nearmap.com/staticmap/v2 paths: /coverage.json: get: tags: - staticmap summary: Return surveys that are available at the requested location. description: | Query survey resources of the requested type that are available in the given AOI. Surveys are returned in order of most to least recent. parameters: - $ref: "#/components/parameters/point" - $ref: "#/components/parameters/radius" - $ref: "#/components/parameters/overlap" - $ref: "#/components/parameters/since" - $ref: "#/components/parameters/until" - $ref: "#/components/parameters/resources" - $ref: "#/components/parameters/fields" - $ref: "#/components/parameters/limit" - $ref: "#/components/parameters/offset" security: - ApiKeyAuth: [] responses: '200': description: Surveys matching the given criteria content: application/json: schema: $ref: '#/components/schemas/CoverageResult' '400': description: On bad input parameter. '403': description: point outside of coverage. '429': description: Rate limit exceeded. Exponential backoff is recommended.Retry the request later. '5XX': description: Internal server error. '503': description: Service is unavailable due to overloaded.Exponential backoff is recommended. Retry the request later. /surveys/{surveyId}/{type}.{format}: get: tags: - staticmap summary: Returns raster content based on the location, image type and output format. description: | This call returns raster content based on the location, content type and output format. The same request with different content types will return an image of the same area. parameters: - $ref: "#/components/parameters/surveyId" - $ref: "#/components/parameters/type" - $ref: "#/components/parameters/format" - $ref: "#/components/parameters/point" - $ref: "#/components/parameters/radius" - $ref: "#/components/parameters/size" - $ref: "#/components/parameters/transactionToken" security: - ApiKeyAuth: [] responses: '200': description: Image or world file response. content: image/*: schema: type: string format: binary '400': description: On bad input parameter. '403': description: transaction token is invalid. '429': description: Rate limit exceeded. Exponential backoff is recommended.Retry the request later. '5XX': description: Internal server error. '503': description: Service is unavaiable due to overloaded.Exponential backoff is recommended. Retry the request later. components: securitySchemes: ApiKeyAuth: type: apiKey in: query name: apikey parameters: point: name: point in: query required: true description: | The point for which the surveys are retrieved. The point is the longitude and latitude of the location on which to center the image, in the format LONG,LAT. For example, -74.044831,40.689669. example: -73.557105,40.806290 schema: type: string radius: name: radius in: query required: true description: | Distance from the point in metres. Used in conjunction with point to define a bounding box (not a circle). Radius range between 1 - 100. example: 100 schema: type: integer format: int64 overlap: name: overlap in: query required: false description: | Whether or not to return metadata for imagery that only partially intersects the requested area. Default is to return all, such that surveys that only partially intersect the AOI will still be returned. If full is specified then only surveys completely within the given AOI are included. schema: enum: - full - all since: name: since in: query required: false description: | The first day from which to retrieve the surveys (inclusive). example: '2015-01-31' schema: type: string until: name: until in: query description: | The last day from which to retrieve the surveys (inclusive). example: '2019-12-31' schema: type: string resources: name: resources in: query required: true description: | Comma separated list of resource types indicating the survey resources to return in the response. example: DetailDsm,TrueOrtho,Vert schema: type: string fields: name: fields in: query required: false description: | Comma-separated list of field names that will appear in the response. The id field will always be among the returned fields, even if not specified. If not present then all the fields are returned. example: id,captureDate,firstPhotoTime,lastPhotoTime,pixelSizes schema: type: string limit: name: limit in: query required: false description: | Limit the number of surveys in the result. Default is 100, Maximum is 1000. example: 200 schema: type: integer format: int64 offset: name: offset in: query required: false description: | Zero-based index of first record in the result. example: 0 schema: type: integer format: int64 surveyId: name: surveyId in: path required: true description: | Identifier of the survey to retrieve content for as obtained from the coverage response. This will correspond to a specific date. example: schema: type: string type: name: type in: path required: true description: | Type of raster content to return. This corresponds to the requested types in the coverage end point. schema: enum: - DetailDsm - TrueOrtho - Vert format: name: format in: path required: true description: | File format of the resulting raster image. schema: enum: - tif - jpg - png - jgw - pgw - tfw size: name: size in: query required: true description: | Size of the resultant image in pixels. It is the responsibility of the caller to maintain the aspect ratio of the requested image. The format is {width}x{height}, however only equal width and height values are currently supported. Maximum image size is "5000x5000". schema: type: string example: 1024x1024 transactionToken: name: transactionToken in: query required: true description: | Transaction token to use in an image request. This token is returned in the staticmap coverage response and contains the authentication information for the request. Multiple image requests made using the same transaction tokens do not incur additional usage costs within 30 days since the coverage call was made. schema: type: string schemas: CoverageResult: type: object properties: surveys: type: array items: $ref: '#/components/schemas/SurveyResult' limit: type: integer format: int64 description: Limit as specified in the request offset: type: integer format: int64 description: Offset of the first survey returned, as specified in the request total: type: integer format: int64 description: Total number of surveys available for the request transactionToken: type: string description: Transaction token to use in subsequent staticmap image requests. The coverage response gives you a Transaction Token. This token is valid 30 days form the coverage call. Once you've successfully requested the first image, this is counted against your monthly transaction allowance. You can subsequently make multiple calls to retrieve DSM/TrueOrtho/Vertical imagery within the original AOI without being charged, until the Transaction Token expires. SurveyResult: type: object properties: id: type: string description: Unique id of survey captureDate: type: string description: Date that survey was captured on, in the format "YYYY-MM-DD" firstPhotoTime: type: string description: Date and time in UTC of the first photo taken in the survey lastPhotoTime: type: string description: Date and time in UTC of the last photo taken in the survey pixelSizes: type: object additionalProperties: type: string description: Resource type pixel sizes

FAQs