Content API

The Content API returns the Nearmap imagery and AI content that is available for a location, and gives you the links and the token to download it. You can search by street address or by parcel.

Before you start:

  • Confirm that your subscription includes Property Intelligence.
  • Create an API key: in MyAccount, open Integrations → API Keys, choose an API application, and select CREATE KEY. If no application is available, ask your organization's Nearmap administrator to create one. See Create an API Key.
  • Choose a location in the United States or Australia that your subscription covers.
  • Run the commands below in Bash with curl installed.

Nearmap imagery of other countries, such as Canada and New Zealand, is available through other Nearmap APIs, such as the Tile API, with a Location Intelligence subscription.

This quick start guide takes you from getting an API key to a downloaded image in two requests - search and download. It provides a step by step walkthrough for the two requests from choosing an endpoint to downloading content.

If you're a Property API user, it is recommended that you review the "Migrating from the Property API" section at the end of this article.

1. Searching for a property

Read your API key into an environment variable so the commands below can use it. Paste the key at the prompt and press Enter; your input is hidden:

read -r -s -p "Nearmap API key: " NEARMAP_API_KEY
printf '\n'
export NEARMAP_API_KEY

Keep your API key private. Do not commit it to source control or include it in shared logs.

Then search. This example asks for vertical imagery of an address in Sydney:

curl --fail --show-error -X POST "https://api.nearmap.com/content/v1/search/address" \
  -H "Authorization: Apikey $NEARMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [ { "namespace": "raster", "type": "vert" } ],
    "address": { "address": "6-8 Bulletin Pl, Sydney NSW 2000", "country": "AU" }
  }'

If your subscription covers the United States rather than Australia, replace the example address with a covered US address and set country to US.

The request body has two parts:

FieldWhat it is
resourcesThe content you want. Here, vertical imagery (raster, vert). See Build the search request below for the other types.
addressThe street address and its country, US or AU. The address is only looked up in that country.

A successful search returns 200 with a JSON body. It lists the property it found, a transactionToken for that property and the content that is available, each item with download links.

Searching for a property you haven’t unlocked yet uses one Property Credit, and searching for it again later is free.

If the request fails, curl exits with a nonzero status and reports the HTTP error. Use the Errors section below to choose your next step. For the complete error list, see Content API Error Codes. If no property or content matches, the API returns 404; check the address and country before searching again.

2. Downloading the content

The step 1 response contains everything you need. The following code snippet is trimmed to the parts you use:

{
  "properties": [
    { "transactionToken": "eyJhbGciOiJkaXICJjdHkiOiJKV1..." }
  ],
  "resources": [
    {
      "type": "vert",
      "attributes": {
        "surveyId": "4917c780-facc-11e8-b671-33ff07a8dfbe",
        "firstObservationTime": "2023-05-01T10:30:00Z"
      },
      "links": {
        "staticmap": "https://api.nearmap.com/staticmap/v3/surveys/4917c780-facc-11e8-b671-33ff07a8dfbe/Vert.{format}?x={tileX}&y={tileY}&tileSize=4096x4096"
      }
    }
  ]
}

The token above is shortened for readability and cannot authorize a download. Copy the complete transactionToken from your own search response, without the surrounding JSON quotes. If the response has no resources, there is no content to download from that response; check your location and requested content types before continuing.

Each resource comes from one survey: one aerial capture of the area on one date. A property captured several times has one resource per survey, so pick the one with the capture date you want (firstObservationTime). Its staticmap link is already built for that survey; you only fill in the placeholders in curly brackets:

Part of the linkWhat it isWhat you do
surveys/4917c780-…The survey the imagery comes from, the same ID as surveyIdNothing, it's already filled in
VertThe content type, here vertical imageryNothing
{format}The image formatReplace with jpg (or png, tif)
{tileX}The tile's column, counting from the westReplace with 0
{tileY}The tile's row, counting from the northReplace with 0
tileSize=4096x4096The tile size in pixelsLeave it as it is

Then, request the completed link with the token in the Authorization header. Run the following commands in the same Bash session. At the first prompt, paste your resource's staticmap link after replacing {format} with jpg, {tileX} with 0, and {tileY} with 0. At the second prompt, paste the complete token from your search response:

read -r -p "Completed staticmap URL: " NEARMAP_STATICMAP_URL
read -r -s -p "Complete transactionToken: " NEARMAP_TRANSACTION_TOKEN
printf '\n'
curl --fail --show-error --output tile.jpg \
  "$NEARMAP_STATICMAP_URL" \
  -H "Authorization: Transaction $NEARMAP_TRANSACTION_TOKEN"

On success, curl exits with status 0 and saves the image to tile.jpg. On an HTTP error, curl exits with a nonzero status; do not treat an existing tile.jpg from a previous request as a successful download. Check the status using the Errors section below.

You get tile.jpg: the north-west tile of the property, up to 4096 x 4096 pixels. Larger properties have more tiles; see the "Static map tiles" section below. A 401 usually means the token has expired (tokens last 1 hour): run the search again.

The example above used one endpoint, one content type and one tile. The four steps below go through the same two requests in full. After them come the rules that apply to every request.

Step by step searching and downloading

Choosing an endpoint

Choose one of the two search endpoints below based on what you already know about the location. Both use POST requests with the base URL https://api.nearmap.com/content/v1.

EndpointUse it whenYou sendYou get
/search/addressYou know the street address.The address and its country (US or AU)The one property at that address.
/search/parcelsYou have coordinates and want the single land parcel at that spot.A GeoJSON PointThe parcel that contains the point. If the point matches more than one parcel you get MULTIPLE_PARCELS_FOUND.

Each endpoint has its own guide with the fields it takes, an example and common variations: Search by Address and Search by Parcel.

GeoJSON coordinates are always longitude first, then latitude: [151.209, -33.862] is Sydney. Swapping them is the most common cause of INVALID_POINT and INVALID_GEOMETRY errors.

For request and response schemas, see the API reference for address searches and parcel searches.

Build the search request

Whichever endpoint you choose, the request body works the same way: it specifies the content you want and narrows the results. Every search names the content you want in a resources array. Each entry has a namespace and a type:

namespacetypeWhat you getDownload link
rastervertVertical imagery (top-down aerial photos)staticmap, tiles
rastertrueorthoTrue Ortho imagerystaticmap, tiles
rasterdetaildsmDigital Surface Model: elevation including buildings and treesstaticmap (tif only)
rasterdetaildtmDigital Terrain Model: bare-ground elevationstaticmap (tif only)
rasterpanoramaPanorama (oblique) imagerySee the Content API search reference.
aivector_predictionAI features as shapes (for example roofs, pools)aifeatures
airaster_predictionAI layers as map tilestiles

An entry can also carry selectors to narrow the results, for example by survey ID, capture date or release status. See the Content API search reference for the supported selectors.

Optional fields that apply to the whole search:

FieldWhat it doesDefault
since, untilOnly surveys captured in this date range. YYYY-MM-DD or relative: 10D, 5M, 1Y. Content is available from the last 2 years; an earlier since is treated as 2 years ago.The last 2 years
overlappartial returns content that covers part of your area; full only content that covers all of it.partial
limitResults per page, up to 300.20
cursorFetch the next page. Copy it from the previous response unchanged.

Read the response

Every endpoint returns the same shape of response. It tells you what was found and how to get it.

FieldWhat it is
properties[]What the search matched. Each item has an id, a type (parcel for a land parcel, aoi for a searched area), an address, a point and its own transactionToken.
resources[]attributes holds the capture times, the surveyId and the tile grid size (scale); links holds the download links.
cursorPresent when there are more results. Send it back in your next search to get the next page.

Download the content

To get the content itself, use a link from resources[] together with the token from properties[]. Each resource's links object contains one or more of these:

LinkHow to use it
aifeaturesComplete. Call it as is.
tilesStandard web map tiles: fill in {z}/{x}/{y} and {format} as you would for any slippy map.
staticmapAn image of the property area, split into tiles for larger properties. Fill in {format} (jpg, png or tif; DSM and DTM are tif only), {tileX} and {tileY}. Keep tileSize as it is.

Every download request needs the header Authorization: Transaction <transactionToken>.

A token in the URL (?transactionToken=) is rejected with 401.

Static map tiles

A large property doesn't fit in one image, so staticmap splits the area into a grid of 4096 x 4096 pixel tiles. {tileX} and {tileY} choose one tile:

  • {tileX} is the column, from 0 to scale.widthInTiles - 1, counting west to east
  • {tileY} is the row, from 0 to scale.heightInTiles - 1, counting north to south

So x=0&y=0 is the north-west corner. A property with widthInTiles: 4 and heightInTiles: 4 has 16 tiles. Tiles on the east and south edges can be smaller than 4096 pixels.

Rules for every request

These apply whichever endpoint you use.

Transaction tokens

The token from a search is your permission to download. Three rules apply to it:

  • Validity: 1 hour from the search. After that, run the same search again for a new token. Searching again for a property you already unlocked costs nothing.
  • Scope: A token works only with the download links returned by a Content API search.
  • Size: About 2,800 characters, all sent in one header. Most tools accept that. If downloads fail with 431 Request Header Fields Too Large or 400 Bad Request but work from curl, a proxy or library in your setup limits header size: raise its limit to at least 8 KB.

Property credits

You pay for searches, with Property Credits. Downloading the content you find is free.

  • Unlocking a property uses one Property Credit.
  • Searching again for an address or parcel you already unlocked is free for the rest of your subscription period.
  • If an address can’t be matched to a parcel, the search treats the address as a point and covers a square extending 30 meters in each direction (60 × 60 m). Every property inside that square uses a credit, so one address can use more than one credit.
  • Retrying a request that failed doesn’t charge you twice.
  • Property Intelligence usage counts only against Property Credits, not against a Daily API Rate Allowance.

Errors

When a request fails, the status code tells you what to do next: fix the request, search again or retry. This section covers the common cases. For the complete list, see Content API Error Codes.

Check the HTTP status and Content-Type before parsing the body. API errors return JSON with a human-readable error; gateway errors and the 429 and 503 responses described below can return plain text. Every 400 and the ALLOWANCE_EXCEEDED 403 also carry a code; 404s have only the message.

Search errors

StatusCodeWhat it meansWhat to do
400REQUEST_PARSE_FAILUREThe body isn't valid JSON for this endpoint, a required field is missing, or a value in it (such as the address or an AI content type) couldn't be processed.Check it against the API reference.
400INVALID_ADDRESSThe address is blank or only spaces.Send the street address.
400INVALID_RESOURCE, INVALID_SELECTORA content type or selector isn't supported.Use the values in the "Build the search request" section above.
400INVALID_POINT, INVALID_GEOMETRY, INVALID_RADIUSThe location isn't valid.Check longitude/latitude order and the radius (a whole number from 1 to 100, both included).
400INVALID_COUNTRYThe address country isn't US or AU, or is a point, parcel or area not in US or AU.Search only in the United States or Australia.
400INVALID_DATE, INVALID_DATE_RANGEsince or until is invalid.Use YYYY-MM-DD or a relative value such as 10D, 5M, or 1Y. Check that since is not later than until.
400INVALID_LIMIT, INVALID_OVERLAP, INVALID_CURSORA paging or filter value is invalid.Use a positive integer no greater than 300 for limit, partial or full for overlap, and send the cursor back exactly as received.
400MULTIPLE_PARCELS_FOUNDThe address, or the point sent to /search/parcels, matched more than one parcel.Make the address more specific, or move the point inside the parcel you want.
401The API key is missing or invalid.Send the key as Authorization: Apikey <key>.
403API_NOT_ENTITLED, SUBSCRIPTION_NOT_SUPPORTEDYour subscription, or its type, doesn’t include the Content API.Contact your account manager.
403AI_NOT_ENTITLEDYou asked for AI content and your subscription doesn’t include AI.Remove the ai entries, or check with your account manager about AI access.
403AREA_NOT_AUTHORIZEDThe location is outside the areas your subscription covers.Check the location is inside your subscription’s area.
403ALLOWANCE_EXCEEDEDYour Property Credits are used up.Contact your account manager.
404No property or no content was found for the search.For address searches, check country matches the country the address is in.
429Too many requests: you used your 3,000 searches for this hour. The body is plain text.Wait until the time in X-RateLimit-Reset. See Rate limits below.
500SYSTEM_ERRORSomething went wrong on our side.Retry a few times with exponential backoff. If the same request keeps failing, contact support with the request ID.
503The service is busy: too many requests are being handled at once. The body is plain text (Service rate limit exceeded).Retry with exponential backoff, and send fewer requests in parallel.

Timeouts: Most searches return in well under a second, but allow at least 60 seconds before your client gives up.

Contacting support: Include the X-Hyperweb-Requestid header, request time and time zone, URL, HTTP method, request body, HTTP status, response body, and response time. Include X-Amz-Cf-Id if present. Remove API keys and transaction tokens before sharing details. See Capturing Information for Failed API Requests for the full checklist.

Rate limits

Separately from what you pay, the number of search requests you can send is limited: up to 3,000 requests per hour. For how rate limits work across Nearmap APIs, see API Rate Limits. The following are specific to the Content API:

  • The limit is per user, not per API key: all your keys share one allowance.
  • Requests to the old /property/resources/v1 URLs count toward the same limit.
  • The 429 body is plain text (Rate limit exceeded), not JSON, so check the status before parsing the body.
  • The hour starts with your first request; it’s a fixed hour, not a rolling one. If you use the whole limit early, further searches are refused until the hour resets, so spread large batches out.
  • Separately, the service limits how many requests it handles at the same time. If you send many requests in parallel, some can return 503 with the plain-text body Service rate limit exceeded. Retry those with exponential backoff and lower your parallelism.

Every response tells you where you stand:

HeaderMeaning
X-RateLimit-LimitYour hourly limit (3,000).
X-RateLimit-RemainingRequests left this hour.
X-RateLimit-ResetWhen the limit resets, as a Unix timestamp in seconds.

There’s no Retry-After header: wait until the time in X-RateLimit-Reset. Retries count toward the limit, so cap how often your client retries a failing request. If a response has no rate-limit headers, don’t assume there’s no limit.

Migrating from the Property API

The Content API is the Property API with a new name and URL. The old /property/resources/v1 endpoints are deprecated and will be switched off; the date will be announced ahead of time. Move your integration now. Only the URL changes:

Old POST endpointNew POST endpoint
/property/resources/v1/properties/address/content/v1/search/address
/property/resources/v1/properties/parcels/content/v1/search/parcels

Request bodies, responses, authentication and tokens are the same on both.


Did this page help you?