Request
This example is a date-based request for an address.
GET https://api.nearmap.com/ai/features/v4/features.json?packs=damage&include=damage&systemVersionPrefix=gen6-&since=2025-01-12&until=2025-01-13&streetAddress=15102 ALBRIGHT ST&city=PACIFICPALISADES&state=CA&zip=90272&country=US&parcelMode=true&rapid=true&excludeTilesWithOcclusion=true
The query parameters are as follows:
packs=damage: Requests the feature classes contained within the damage pack. The damage pack is a post-cat pack that includes the Building Lifecycle classes. As this is a post-cat pack, only post-cat resources will be considered.include=damage: Requests inclusion of the real-time damage data. Returned building lifecycle features will include damage classifications.systemVersionPrefix=gen6-: Filters survey resources with a system version prefix of gen6-, which includes gen6-glowing_grove-1.0 and gen6-glowing_lantern-1.0.system versions since=2025-01-12&until=2025-01-13: Limits results to survey resources after 2025-01-12, and on or before 2025-01-13.streetAddress=15102 ALBRIGHT ST&city=PACIFICPALISADES&state=CA&zip=90272&country=US: Provides address parameters for the parcel, which will be used as the AOI. parcelMode=true: Enables Parcel Mode.- The AOI from the address will be treated as a parcel.
- Clipping and filtering logic will ensure that damage classifications are only associated with the features determined to belong to the parcel.
- Multi-parcel buildings will be clipped to the input parcel and this clipped footprint will be used for determining damage classifications.
rapid=true: Enables Rapid mode. Both rapid and standard survey resources are considered in the survey resource resolution process. If Rapid mode is not enabled, only standard (full pipeline with all Gen6 classes available) survey resources are considered.excludeTilesWithOcclusion=true: Excludes survey resources where the required tile
for the AOI is marked as occluded.
Response
An example response is provided below. Some larger fields (such as geometry) have been truncated to accommodate the values.
{
"credits": 1,
// surveyResourceId of the survey resource used to fulfil this request,
// either using the surveyResourceId provided or resolved using date-based criteria
"resourceId": "09aee77b-3f6e-5077-b9ec-036da962642e",
// surveyId of the survey resource used to fulfil this request,
// either using the surveyResourceId provided or resolved using date-based criteria
"surveyId": "857d656e-d2dd-11ef-a707-b7e79eec4f45",
"surveyDate": "2025-01-13",
"3dDate": "",
// systemVersion of the survey resource
"systemVersion": "gen6-glowing_lantern-1.0",
// Mapbrowser link
"link": "https://apps.nearmap.com/maps/#/@34 .0486655,-118.5238042,20.00z,0d/V/20250113?locationMarker",
// geomatched address that was used for an address-based request. Not present if an AOI was provided.
"geomatchedAddress": "15102 Albright St Pacific Palisades CA 90272-2510 US",
"extentMinX": -118.5240398621885,
"extentMaxX": -118.5235681378115,
"extentMinY": 34.04856,
"extentMaxY": 34.048771,
// the perspective used to generate the AI data.
"perspective": "Vert",
// Indicates whether the resource is post-cat or non-post-cat
"postcat": true,
"features": [
{
// unique ID of feature
"id": "6f5fbd84-8a60-517b-8c76-24d1fd2d8051",
// classId of feature
"classId": "91987430-6739-5e16-b92f-b830dd7d52a6",
"description": "Building lifecycle",
"confidence": 0.8876989,
"parentId": "",
// geometry of the feature. If feature is a connected feature class, the geometry is clipped to the AOI.
// Connected classes represent large feature areas (such as lawn grass, vegetation and so on) that may span
// large areas.
"geometry": {
"type": "Polygon",
"coordinates": [
[]
]
},
// geometry of the feature. If feature is a connected feature class, the geometry is clipped to the AOI.
// Connected classes represent large feature areas (such as lawn grass, vegetation and so on) that may span
// large areas. Otherwise, this represents an unclipped geometry.
"geometry": {
"type": "Polygon",
"coordinates": [
[]
]
},
// clipped geometry of the feature based on the parcel mode algorithm. This field is set if and only if parcel mode
// is true. If parcel mode is true, request AOI is treated as a parcel boundary. If a building-like feature is considered
// belonging to multiple parcels, the building feature clipped to the parcel boundary will be populated in this field.
// If clippedGeometry is present, supplementary data sources including damage will use this clipped geometry as the geometry
// for the supplementary data calculation.
"clippedGeometry": {
"type": "Polygon",
"coordinates": [
[]
]
},
// belongs to parcel is set if and only if parcel mode is true. The parcel logic algorithm determines whether a building is
// likely to belong to a parcel and set this flag accordingly. A large structure on a neighbour parcel may appear to slightly
// overhang the requested parcel, for example, but may be excluded based on the parcel logic algorithm.
// If parcel mode is true, only features with `belongsToParcel` flag marked true will be used in supplementary data
// calculations.
"belongsToParcel": true,
// the area of a feature. Connected feature classes are clipped to the request AOI, so this will equal `clippedArea`
// if the feature class is connected.
"areaSqm": 7291.8,
"areaSqft": 78489,
// the area of a feature clipped to the request AOI. If the feature is of a connected feature class,
// this will equal `area`.
// This is distinct from `clippedGeometry` provided when parcel mode is active.
"clippedAreaSqm": 374.5,
"clippedAreaSqft": 4031,
// the unclipped area of a feature is the unclipped area of the feature. If the feature is not of a connected feature class
// (so it is a discrete feature), this will equal `area`.
"unclippedAreaSqm": 7291.8,
"unclippedAreaSqft": 78489,
"attributes": [],
"surveyDate": "2025-01-13",
"meshDate": "",
// this is added if the `damage` supplementary data source is included. This will be present on building lifecycle
// features. In parcel mode is active, only Building Lifecycle features marked `belongsToParcel` as true will
// have damage scores produced and attached. If `clippedGeometry` is set (meaning the feature is clipped as a part of
// the parcel logic algorithm), `clippedGeomtery` will be used in the real-time damage calculation.
//
// There are three tiers of classification provided:
// - 5-tier (or `raw`), based on the FEMA 5-tier classification system composed of `Undamaged`,
// `Affected`, `Minor`, `Major` and `Destroyed`
// - 3-tier, composed of `UndamagedOrAffected`, `Minor` and `MajorOrDestroyed`
// - 2-tier, composed of `UndamagedOrAffectedOrMinor` and `MajorOrDestroyed`
//
// The confidence values are rounded to three decimal places.
"damage": {
"confidences": {
"raw": {
"Undamaged": 0.001,
"Affected": 0,
"Minor": 0.001,
"Major": 0.001,
"Destroyed": 0.997
},
"3tier": {
"UndamagedOrAffected": 0.001,
"Minor": 0.001,
"MajorOrDestroyed": 0.998
},
"2tier": {
"UndamagedOrAffectedOrMinor": 0.002,
"MajorOrDestroyed": 0.998
}
},
// The ratios array is explained below.
"ratios": [
{
"classId": "2322ca41-5d3d-5782-b2b7-1a2ffd0c4b78",
"description": "Exposed Underlayment",
"ratioAbove50PctConf": 0
},
{
"classId": "2905ba1c-6d96-58bc-9b1b-5911b3ead023",
"description": "Exposed Roof Deck",
"ratioAbove50PctConf": 0
},
{
"classId": "3534a1fc-2e12-51a7-b2dc-1c850bc69fc1",
"description": "Building with Structural Damage",
"ratioAbove50PctConf": 0
},
{
"classId": "4794d3ec-0ee7-5def-ad56-f82ff7639bce",
"description": "Building Under Construction",
"ratioAbove50PctConf": 0
},
{
"classId": "584188c4-4f77-5724-a782-f13865ab0dbc",
"description": "Building Structural Loss",
"ratioAbove50PctConf": 0.99
},
{
"classId": "6832955f-89c6-5cfd-874d-40c22aead943",
"description": "Vegetation Debris",
"ratioAbove50PctConf": 0
},
{
"classId": "abb1f304-ce01-527b-b799-cbfd07551b2c",
"description": "Roof with Temporary Repair",
"ratioAbove50PctConf": 0
},
{
"classId": "c46e75a6-7b3c-5910-9f3f-742dd668025b",
"description": "Building Damage by Tree",
"ratioAbove50PctConf": 0
},
{
"classId": "dec855e2-ae6f-56b5-9cbb-f9967ff8ca12",
"description": "Missing Roof Tile or Shingle",
"ratioAbove50PctConf": 0
},
{
"classId": "f8abc8e3-6af3-5a1d-9a8e-1793419455bb",
"description": "Junk and Wreckage",
"ratioAbove50PctConf": 0.491
},
{
"classId": "f907e625-26b3-59db-a806-d41f62ce1f1b",
"description": "Structural Damage",
"ratioAbove50PctConf": 0
}
]
}
}
],
// version information is included if any eligible supplementary data only if the supplementary data is included in the response.
// Eligible sources are roof spotlight index and real-time damage.
"versions": {
"damage": {
// version of the real-time damage model
"modelVersion": "B.1",
// version of data presentation
"presentationVersion": "1"
}
}
}
An additional field isRapidSurveyResource will be present if the survey resource selected is a rapid survey resource. Otherwise, a standard survey resource has been used.
Ratios output
In addition to the tiered damage confidence levels, a ratios array is provided in the damage response. The ratios array is a list of detection areas within the footprint where the confidence is at least 50%. This means detections occurring with a low confidence, that is, below 50%, are excluded.
Currently the following classes are provided:
Note that not all of the provided detection classes are used in the damage model.
Each entry in the ratios array corresponds to a single class of detection, with the following fields:
{ "classId": "f8abc8e3-6af3-5a1d-9a8e-1793419455bb", "description": "Junk and Wreckage", "ratioAbove50PctConf": 0.491}
classId: Unique ID corresponding to the class of detection. For example, f8abc8e3-6af3-5a1d-9a8e-1793419455bb corresponds to the Junk and Wreckage class.description: Text description of the detection class.ratioAbove50PctConf: Ratio of the detection area to the footprint, for which the detection is at least 50% confident. This value is rounded to 3 decimal places.