API Reference

v4 /features.json

post
https://api.nearmap.com/ai/features/v4/features.json

Returns features, their attributes and optional supplementary data within the given AOI or address, and date range.

Operates semantically the same way as the GET variant but allows the AOI and classes to be passed inside the request body rather than as a polygon query parameter. This may be required for AOIs and classes whose representations are large, in order to avoid URL length limitations.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
string

Represents the Area Of Interest (AOI) to query against. It is depicted by a set of points (longitude/latitude pairs) where the first and last point must be the same. The polygon must not self-intersect.

It cannot be used with the address geocoding parameters (streetAddress, city, state, zip and country), or with an aoi defined in the request body for the HTTP POST variant endpoints.

Must be omitted when TXv3 token authorization is used.

string

Since is a date (YYYY-MM-DD) specifying that the capture must be on or after the given date (if not provided then the first available survey date in the location is assumed).

string

Until is a date (YYYY-MM-DD) specifying that the capture date must be on or before the given date (if not provided then the current date is assumed).

enum
Defaults to latest

The order by which the surveys are sorted (using capture date) when the API selects the survey resource to use for serving the request.

Allowed:
boolean
Defaults to false

Bulk determines whether if the request is part of a large batch of requests, meaning requests will not be rate-limited.

string

Packs accepts a list of comma-separated product packs. This returns specific features and attributes under the pack. The response will return all features and attributes that the user is entitled to if no packs are provided.

It cannot be used with the classes query parameter. This parameter is ignored if used with an empty value.

string

Classes accepts a list of comma-separated feature class IDs. Features classes not requested will be filtered out of the response. The full list of available feature classes can be obtained by using the classes.json endpoint (Feature class IDs are in the id field for classes of type Feature). The response will include all feature classes that the user is entitled to if the query parameter is not specified.

It cannot be used with the packs query parameter. This parameter is ignored if used with an empty value.

string

The street address for a geocoded request. Should consist of the street number, street name, and street type.

It cannot be used with the polygon query parameter.

Must be omitted when TXv3 token authorization is used.

string

The city, suburb, or locality for a geocoded request.

It cannot be used with the polygon query parameter.

Must be omitted when TXv3 token authorization is used.

string

The two-letter state code for a geocoded request.

It cannot be used with the polygon query parameter.

Must be omitted when TXv3 token authorization is used.

string

The five-digit ZIP code or nine-digit ZIP+4 code for US addresses or the four-digit postal code for AU addresses for a geocoded request.

It cannot be used with the polygon query parameter.

Must be omitted when TXv3 token authorization is used.

string
enum

The two-letter country code for the geocoded request. Only supports US and AU. Defaults to US when geocoding is used without supplying the country code.

It cannot be used with the polygon query parameter.

Must be omitted when TXv3 token authorization is used.

Allowed:
string

If specified, causes the API to only consider the given system version when choosing which survey resource to use for serving the request.

string

If specified, causes the API to only consider system versions that match the prefix when choosing which survey resource to use for serving the request.

boolean
Defaults to false

When set to true, causes alpha classes to be included in results.

boolean
Defaults to false

When set to true, causes beta classes to be included in results.

boolean
Defaults to false

Use the 3D attribute boundary when the API selects the survey resource to use for serving the request. Othewise, the regular resource boundary will be used.

boolean
Defaults to false

When set to true, the API will treat the input AOI (or address) as a parcel boundary. In this mode, the API will mark the features that are considered to be part of the parcel with the belongsToParcel flag. Features that are part of single-parcel structures will be returned in their entirety, while features that are part of multi-parcel structures will be clipped to the parcel boundary. In this case, the clippedGeometry field will be added to the feature containing the geometry clipped to the parcel boundary.

In this mode, supplementary data calculations will also take into account the parcel boundary and use the clipped geometry.

Parcel mode is only supported for gen6 system versions. If the resource does not resolve to a gen6 resource, the API will not include parcel mode data in the response and will not calculate supplementary data using the clipped geometry.

See: https://developer.nearmap.com/docs/parcel-mode-user-guide for a technical guide of the parcel mode algorithms.

boolean
Defaults to false

When set to true, the API will consider survey resources from rapid AI pipelines when matching date-based criteria. Rapid AI pipelines provide only a limited set of content, so rapid can only be used when requesting the Building lifecycle feature class and (optionally) the damage supplementary data source.

If additional classes are requested, if packs containing any feature classes other than Building lifecycle are requested, or if any other supplementary data sources are requested, the API will return an error.

Rapid is only supported for gen6 system versions and when date-based criteria is used.

string

A comma-separated list of supplementary data to include in the response. The currently supported values are: roofSpotlightIndex, roofConditionConfidenceStats, damage, defensibleSpace, hurricaneScore, windScore, hailScore, wildfireScore, windHailRiskScore, or all for all types of supplementary data available given the user's entitlements and request type (bulk requests may support a subset of supplementary data sources).

Inclusion of supplementary data is only supported for gen6 system versions. If the resource does not resolve to a gen6 resource, the API will not include supplementary data in the response.

boolean
Defaults to false

Partial resources are AI resources that only has prediction generated at certain areas of the survey boundary as compared to our conventional fully processed resource. These types of resources are generally available by default. This flag opts-out from serving partial resources.

string
enum

When set, the API will consider only postcat resources (true), only non-postcat resources (false), or any resource (any) for results. This parameter is only available for users on the new pricing platforms. For users on the legacy pricing platform, the selection of postcat or non-postcat resources is determined by the packs (or classes) requested.

Allowed:
string

When set, the API will use the specified damage model version when calculating damage supplementary data. If not set, the latest damage model version available will be used.

Currently supported model versions are: B.0 and B.1 (latest).

Body Params
aoi
object

A GeoJSON object representing the requested AOI. Must be a GeoJSON polygon with no interior rings.

It cannot be used with the polygon query parameter.

classes
array of strings

Classes accepts a list of class IDs. Features classes not requested will be filtered out of the response. The full list of available feature classes can be obtained by using the classes.json endpoint (Feature class IDs are in the id field for classes of type Feature). The response will include all feature classes that the user is entitled to if the query or body parameter is not specified.

It cannot be used with the packs query parameter. This parameter is ignored if used with an empty value. It cannot be used with the classes query parameter.

classes
Headers
string

Allows a reference string to be echoed back opaquely in the body of the response.

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Updated 4 months ago

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
text/plain

Updated 4 months ago