Damage Conflation API

About the Damage Conflation API

The Damage Conflation API returns a single damage assessment per building for a whole catastrophe event. After an event, Nearmap flies the affected area several times over the following days. Damage Conflation combines every observation of the event into one dataset, with a final damage rating, the probability for each of the five damage classes and a building outline for each building. More detail on how ratings are determined is covered in this Help Center article.

You can use this API to retrieve the latest conflated result for an event, within an area or at an address. For the first hours of an event, before conflation has finished, you can view damage using the AI Feature API. When using AI Feature API to retrieve singular/non-conflation values from catastrophe surveys, use packs=postcat, and add include=damage to get the damage ratings.

The Damage Conflation API is available only for catastrophe events that Nearmap has captured and tagged, in the United States and Australia.

Key features

• Event-based: Combines every observation of an event, across overlapping passes and surveys, into one result per building.
• Evidence with the rating: Each result includes the probability for each damage class and the evidence classes observed.
• Building outline: Each building has one outline that stays usable even when the post-event image shows rubble.
• Area or address: Query by area of interest, or send an address to retrieve damage for the buildings at that property.
• Latest-result endpoint: Returns the most recently processed result for the event.
• Output format: GeoJSON.

Endpoints

POST /ai/damage/v2/events/{eventId}/latest.geojson returns the latest conflated result for an event within the area you send, as GeoJSON. Send either an aoi or an address. Results are paged. See the reference page for the request body, paging, responses and errors.

To read a large event faster, split your area into smaller areas and read them at the same time. See Large events in Damage Conflation API in this Help Center article.

For all parameters and fields, see the API reference.

Retrieving the event ID from the Coverage API

The event ID (eventId) identifies a catastrophe event. There is no endpoint that lists events, so you need the eventId before you call the Damage Conflation API.

Retrieve the eventId via the Coverage API. Query surveys that intersect your area and fall within your event dates, then read the postCatEventId value in the tags object of each survey.

Your AOI as a closed ring of longitude, latitude pairs separated by commas, for example -100.01,40.01,-100.00,40.01,-100.00,40.02,-100.01,40.02,-100.01,40.01.

GET /coverage/v2/poly/{polygon}?since={start_date}&until={end_date}&fields=tags&include=postCatEventId

Surveys without postCatEventId are not part of an event. The full walkthrough, with examples and the event boundary, is covered later in this article.

1. In each survey, read tags object. postCatEventId is the event ID. postCatEventName and postCatEventDate tell you which event it is.
2. Pass the ID of the event you want as the event ID. If your area returns several events, query each one you need separately.

An area can fall inside more than one event, for example when two hurricanes crossed the same coast. Each survey's tags show which event it belongs to:

`"tags": `{
  "disaster": "hurricane",
  "postCatEventDate": "2024-10-09",
  "postCatEventId": "ac504814-a897-5f32-84dc-928f4ff0ac2f",
  "postCatEventName": "Sample event"
}

Use since and until to search around the dates of the event you want. Then choose the event ID by its postCatEventName and postCatEventDate. The Damage Conflation API returns damage for your area for any event ID that has coverage there, so check the name and date before you use the ID.

This call uses /coverage/v2/poly/{polygon} because you are looking for events in an area. Once you have the event ID, the coverage call
uses /coverage/v2/surveys to list every survey in the event.

Getting the event boundary

The event boundary is the footprint of the event. Use it to check whether your AOI falls within the coverage before calling the Damage Conflation API. To get the event boundary:

1. Call the Coverage API for the event. Add resources=tiles:Vert to get vertical imagery, fields=resources,resources:boundary,tags so that each survey includes its boundary and tags, and include=postCatEventId:{eventId} to return only the surveys for your event. This request has no polygon, so it returns every survey in the event:

   GET /coverage/v2/surveys?since={start_date}&resources=tiles:Vert&fields=resources,resources:boundary,tags&include=postCatEventId:{eventId}&limit=100&offset=0

   Results are paged. The response includes total, the number of surveys in the event. Add the number of surveys you received to offset and repeat the request until you have total. Without limit, a request returns 20 surveys, which can be a small part of a large event.
   This route needs the include=postCatEventId filter. A request to /coverage/v2/surveys with only dates, or with a polygon parameter, returns 400 MISSING_QUERY. The polygon parameter is ignored on this route. To filter by area, use /coverage/v2/poly/{polygon}.

2. Take the boundary of each survey, from resources.tiles, and join them into a single (multi) polygon. This polygon is the event footprint at that point in time.

   GET /coverage/v2/surveys?since={start_date}&resources=tiles:Vert&fields=resources,resources:boundary,tags&include=postCatEventId:ac504814-a897-5f32-84dc-928f4ff0ac2f&limit=100&offset=0

   JSON

   {
     "surveys": [
       {
         "id": "4b7f1c2e-6d3a-5e90-8a14-0c9d2f7b3e68",
         "resources": {
           "tiles": [
             {
               "boundary": {
                 "type": "MultiPolygon",
                 "coordinates": [[[[-100.012, 40.008], [-99.998, 40.008],
    [-99.998, 40.022],[-100.012, 40.022], [-100.012, 40.008]]]]
               }
             }
           ]
         },
         "tags": {
           "postCatEventId": "ac504814-a897-5f32-84dc-928f4ff0ac2f",
           "postCatEventName": "Sample event"
         }
       }
     ]
   }

Note that the values in the sample code above are not from a real event.

The include filter takes a tag name and a value, separated by a colon. Here it returns only the surveys with that postCatEventId. An event ID that does not exist returns no surveys. Tag filters passed as tags=, tag= or postCatEventId= are ignored. For other filters, see Filter Surveys.

If you use /coverage/v2/poly/{polygon} with the same parameters instead, only the surveys that touch your polygon are returned. The union of their boundaries covers only that part of the event, not the full footprint.

The event boundary may change as new surveys are captured. Requests for areas outside the event footprint return a normal response with no buildings. An area inside the footprint can also return no buildings if Nearmap has no pre-event data for it.

Making a request

Send an aoi polygon or an address, not both, to receive a GeoJSON response.

POST /ai/damage/v2/events/{eventId}/latest.geojson

The eventId is the postCatEventId value you obtained from the Coverage API.

The request body is JSON. For an aoi, send a GeoJSON Polygon or MultiPolygon, with coordinates as longitude, latitude. For an address, send all five fields. Optionally add limit (the number of buildings per page, 1 or more, default 1000) and cursor (see below).

By area example

{
  "limit": 1000,
  "aoi": {
    "type": "Polygon",
    "coordinates": [[[-100.01,40.01],[-100.00,40.01],[-100.00,40.02],[-100.01,40.02],[-100.01,40.01]]]
  }
}

By address example

{
  "address": {
    "streetAddress": "123 Main Street",
    "city": "Springfield",
    "state": "TX",
    "zip": "75001",
    "country": "US"
  }
}

Results are paged, with up to 1000 buildings per page by default. If more results are available, the response includes nextCursor. To retrieve the next page, send the same request again with that value as cursor. Continue requesting pages until the response no longer includes nextCursor.

Use the same area for every page of a query. Pages of one query are read in order, because each page needs the cursor from the one before.

For full parameters and fields, see the Damage Conflation API specification here.

Large events

To read a large event faster, split your area into several smaller areas and read them at the same time. Page through each area sequentially.

One way to split an event is to use the survey boundaries from the Coverage API. Call the Coverage API with resources=tiles:Vert, fields=resources,resources:boundary,tags and include=postCatEventId:{eventId}, as described in "Getting the event boundary". Then send the boundary of each survey as the aoi of a Damage Conflation request. You can use a variety of other area types such as your own geometries, H3 hexagons or geohashes.

A building in the overlap between two areas, or on the edge of one, is returned by both requests with the same id and rating. Remove duplicates by id when you combine the results.

Response

The response is a GeoJSON feature collection with one feature per building. Each feature includes:

• The final damage rating - the rating is the damage class with the highest probability. The five probabilities in rawRatings add up to 1, and the confidence is the probability of the chosen class.
• The probability for each of the five damage classes
• The evidence observed
• A building outline that stays usable even when the post-event image shows rubble

damage.preEvent is returned only where Nearmap has a pre-event observation of the building, so some buildings have no preEvent block. latestCaptureDate is returned only inside preEvent.

Responses you might see

The table below lists the responses the API returns and the action you need to take based on the response you see.

Sample response

The response below shows one building.

• The event rating is Destroyed, with a probability of 0.978.
• Before the event, the building was rated NoDamage.
• rawRatings gives the probability for each damage class, and classRatios lists the evidence behind the rating.

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [-100.00008971405619, 40.00000461033479],
        [-99.99998896584611, 40.00002172018569],
        [-100.00001028594382, 40.00009538966521],
        [-100.00011103415389, 40.00007827981431],
        [-100.00008971405619, 40.00000461033479]
      ]
    ]
  },
  "id": "3f6c2a10-8d47-5b21-9a3e-0c5d7e1b4f92",
  "properties": {
    "areaSqft": 796,
    "areaSqm": 73.92,
    "confidence": 0.9257812,
    "damage": {
      "event": {
        "rating": "Destroyed",
        "confidence": 0.97835683,
        "rawRatings": {
          "Affected": 0.0012413142,
          "Destroyed": 0.97835683,
          "Major": 0.012051237,
          "Minor": 0.0049820816,
          "NoDamage": 0.0033685421
        },
        "classRatios": [
          {
            "classId": "f8abc8e3-6af3-5a1d-9a8e-1793419455bb",
            "description": "Junk and Wreckage",
            "ratio": 0.55210361,
            "confidence": 0.6210938
          },
          {
            "classId": "584188c4-4f77-5724-a782-f13865ab0dbc",
            "description": "Building Structural Loss",
            "ratio": 0.94100347,
            "confidence": 0.9257812
          },
          {
            "classId": "91987430-6739-5e16-b92f-b830dd7d52a6",
            "description": "Building lifecycle",
            "ratio": 0.95330148,
            "confidence": 0.9257812
          }
        ]
      },
      "preEvent": {
        "rating": "NoDamage",
        "confidence": 0.97298833,
        "rawRatings": {
          "Affected": 0.016204737,
          "Destroyed": 0.00041386574,
          "Major": 0.0019217365,
          "Minor": 0.0084713306,
          "NoDamage": 0.97298833
        },
        "classRatios": [
          {
            "classId": "30fc0c55-2b61-569f-b424-44082987ecb9",
            "description": "Medium and High Vegetation with Woody Vegetation",
            "ratio": 0.041203761,
            "confidence": 0.5908203
          },
          {
            "classId": "91987430-6739-5e16-b92f-b830dd7d52a6",
            "description": "Building lifecycle",
            "ratio": 0.99010215,
            "confidence": 0.9404297
          }
        ],
        "latestCaptureDate": "2025-01-15"
      }
    },
    "hilbertId": "13650079281234567890"
  }​