Nearmap Documentation
Page tree
Skip to end of metadata
Go to start of metadata

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. 

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

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 (i.e. make a coverage call).

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.

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 an 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

How many image requests can I make with one Transaction Token?
For the 30 day life of your Transaction Token, you can make any number of image requests on any or all three content types (DSM, TrueOrtho, Vertical) and of any vintage.


How can I check my monthly usage?

Yes. If you are a Nearmap Administrator, in the Self Service Portal you can see your monthly allowance and your usage, expressed as number of transactions. Learn how to View Account Data Usage.


What does "Error: invalid aoi claim: requested AOI is not within allowed AOI in transaction token" mean?

Your coverage radius is smaller than your image call radius. Ensure your coverage radius is as large as you require.


I want to retrieve imagery for an area larger than 100 metres. Can I do this with the DSM API?

To do this, you will need to make multiple coverage calls (i.e. with a Transaction Token for each), make the image calls and stitch together the images.

Is the radius a true radius

The radius is not a radial dimension with location as centre point. The radius defines a square bounding box with location as the centre. Note also that the units are real world and not Web Mercator metres.


What happens if the radius and size combination I enter would mean an image of much higher resolution than is possible?

In this case the image returned is the highest resolution Nearmap imagery. 

How can I control the resolution of the image retrieved?

The image resolution is determined by the image length (2 x radius) and the size in pixels. This allows us to maintain the location as the centre point of the image. Refer to the examples below as an illustration of how radius and size values determine image resolution.

ParametersImage retrieved
radius: 10 m
length: 20 m
size: 100x100 px
pixel size: 5 m

radius: 10 m
length: 20 m
size: 1000x1000 px
pixel size: 0.05 m

Is it possible to simply request the image and have the API return an image using the best possible resolution? 

The physical and pixel size of the image are deliberately explicit to give you control over the image that will be returned. This is further complicated by the fact that True Ortho and DSM are of different native resolutions (0.055 m versus 0.15 m).

Request the imagery by inspecting the coverage response and then calculating the pixel size based on the metadata.

If, for example, you want an image of 100m radius. The total width or height is 200m.

DSM image size is 200 m / 0.15 m/px = 1333 px

True Ortho Image size is 200 m / 0.055 m/px = 3636 px

You can then request content types at their maximum resolution or, for example, upscale the DSM to match the True Ortho image pixel by pixel.


  • No labels