Access to Damage Classifications AI via the AI Feature API is possible in one of these ways:
- Date-based access
- Resource-based access
Date-based access
The AI Feature API will resolve the best resource based on provided criteria such as
date parameters and system versions. The date-based endpoint offers the several optional parameters for choosing the most appropriate resource. These are described below.
Date and version parameters
since - This is a date query parameter in the format YYYY-MM-DD for specifying that the capture must be on or after the given date.until - This is a date until query parameter in the format YYYY-MM-DD for specifying that the capture date must be on or before the given date.- System versions - This parameter can be specified using the
systemVersion or the systemVersionPrefix query parameter. These parameters are mutually exclusive and cannot be used together.systemVersion will select a resource matching the provided system version.systemVersionPrefix will select a resource with a system version prefix that matches the provided prefix. For example, gen6- will match gen6-glowing_grove-1.0 and gen6-glowing_lantern-1.0.
Examples
since=2024-01-01&until=2024-12-31since=2024-01-01&until=2024-12-31&systemVersionPrefix=gen6-since=2025-01-01&systemVersion=gen6-glowing_lantern-1.0
Supplementary data sources such as damage and RSI are only available on gen6 system versions. The systemVersionPrefix or systemVersion query parameters must be set for access to specific versions.
Rapid mode
Date-based requests include an additional parameter - the Boolean rapid query parameter that indicates whether rapid survey resources will be considered in the survey resource resolution process. Rapid survey resources are run on a fast pipeline that includes limited content, allowing for AI insights to be available as soon as possible. These are often present in post-cat scenarios, where damage data is made available even faster to assist with decision-making.
By default, the rapid query parameter is set to false. When rapid is set to true, rapid survey resources may be selected if they are the most recent resource available. When both rapid and standard (full pipeline) resources are available, the standard survey resource will be selected.
Note: Rapid mode is only available on survey resources of system version prefix gen6-. This needs to be specified in the request as rapid cannot be true for older system versions.
If a rapid survey resource is available, the isRapid flag in the response is set to true to indicate a rapid survey resource has been selected. Additional information on available content and data sources when rapid is set to true are detailed in the sections below.
Examples
since=2024-01-01&until=2024-12-31&systemVersionPrefix=gen6-&rapid=truesince=2024-01-01&until=2024-12-31&systemVersion=gen6-glowing_lantern-1.0&rapid=true
As rapid survey resources are restricted in terms of content availability, only the Building Lifecycle class is available, and can be accessed using:
packs=damagepacks=damage_non_postcatclasses=91987430-6739-5e16-b92f-b830dd7d52a6
Rapid mode only supports damage as a supplementary data source. Requests with rapid=true are only valid if include=damage or if the include parameter is not set.
Example
include=damage
Content resolution
You must also specify the content (AI features) you require using the packs (packs of classes) or classes (specifying individual classes by classId) query parameter. Only one of packs or classes can be specified in a single request - these cannot be combined.
If no packs or classes are specified, all feature classes available to the user will be included - note that this option may result in a very large number of features which can impact performance and usability, and users should generally specify only the content that is required.
These parameters have special requirements when accessing damage.
Real-time damage classifications are only available on Building Lifecycle class (91987430-6739-5e16- b92f-b830dd7d52a6) features. You must therefore include content that includes Building Lifecycle when requesting features. For example, when using the packs parameter, damage or damage_non_postcat are available. When using the classes parameter the Building Lifecycle class (91987430-6739-5e16-b92f-b830dd7d52a6) must be included.
Examples
packs=damagepacks=damage_non_postcatpacks=solar,pool,roof_char,damage_non_postcatclasses=91987430-6739-5e16-b92f-b830dd7d52a6classes=91987430-6739-5e16-b92f-b830dd7d52a6,c08255a4-ba9f-562b-932c-ff76f2faeeeb
Resource-based access
The AI Feature API retrieves features based on the provided surveyResourceId. This is useful for retrieving data using a known survey resource.
For example, fetching additional data from the same survey resource as in a previous request, or using the surveyResourceId obtained from the Coverage API.
Area of Interest (AOI)
Lastly, the AOI geometry must be provided. This may include general search areas, parcels or building footprints. See the Parcel mode section below for details of parcel mode clipping behavior. AOIs can be specified using one of two methods:
- By address geocoded to a parcel geometry, specifying the following query parameters:
streetAddresscitystate
zipcountry, using a 2-digit country code (e.g. US)
- By AOI polygon, specifying the
polygon query parameter or the aoi property in a POST-based request body. Both AOI polygon and address cannot be provided simultaneously.
For performance reasons, real-time damage classifications are only produced on features with an area of 10,000sqm (~107,639 sqft) or smaller. Buildings with a footprint larger than 10,000sqm will not be assigned a damage classification.
In exceedingly rare cases features may have unsupported geometries (such as a point or linestring). These unsupported features will also be skipped.
Examples
As query parameters:
polygon=-96.15764,41.22445,-96.15716,41.22444,-96.15716,41.22461,-96.15764,
41.22461,-96.15764,41.22445streetAddress=4438+East+Creosote+Dr&city=Cave+Creek&state=AZ&zip=85331&country=US
As a POST request body:
{"aoi": {"type": "Polygon","coordinates": [[[151.2033748626709,-33.8645716016701],[151.20710849761963,-33.8645716016701],[151.20710849761963,-33.86086547534525],[151.2033748626709,-33.86086547534525],[151.2033748626709,-33.8645716016701]]]}}
Parcel mode
By default, the AI Feature API treats the input AOI (whether a polygon or an address) as a search area of interest. The API returns all features that intersect with the AOI.
The parcelMode boolean query parameter changes how the AOI is interpreted, treating it as a parcel rather than just a search area. By default, parcelMode=false. When parcelMode=true:
- Each returned feature includes a
belongsToParcel field, indicating whether that feature is considered part of the parcel. - If a building-like feature spans multiple parcels, the API adds a
clippedGeometry field. This field contains the feature’s geometry clipped to the parcel boundary.- Building-like features include: Building, Building Lifecycle, Building Under Construction, and Roof.
- The
clippedGeometry field only appears if the clipped geometry differs from the original geometry.
When parcelMode is active, data calculations such as damage and RSI apply only to features where belongsToParcel = true.
If a clippedGeometry field is present, the API uses the clipped geometry (not the original) for these calculations.
Occlusion
When excludeTilesWithOcclusion=true, any survey resource that is occluded (for example, covered by smoke or cloud) will be ignored.
- For date-based requests, the API omits occluded resources during the resource resolution process. This can lead to two possible outcomes:
- The API falls back to the next matching resource that is not marked as occluded within the requested region.
- If no non-occluded resources are available, the API returns 404 – Not Found.
- For resource-based requests, if a required tile is marked as occluded, the API returns 404 – Not Found.
Recommended parameters for accessing Damage Classifications
For input AOI, we recommend using the following order of preference - building footprint (most precise), parcel boundary, address in this order.
- Using building footprint will narrow down to the specific building you would like to retrieve. Building footprint should be used in conjunction with parcel mode so the system clips to
the building footprint. Avoid using buffers as it may unintentionally capture unrelated damage. - Use date-based query (to avoid having to find the
resourceId for the resourceId endpoint)
Recommended parameters:parcelMode=true - The request AOI will be treated as a parcel boundary, and building footprints will be clipped to the request AOI.rapid=true - Allows access to rapid survey resources, and will default to standard survey resources once available.include=damage - Allows including damage classifications.excludeTilesWithOcclusion=true - Allows including occluded surveys, which may result in inaccurate damage results.