Product Documentation

Access Nearmap Fire Risk Data

Fire risk data can be accessed using the Transactional Content API and downloaded as a CSV file.

Accessing fire risk data

To access Nearmap Fire Risk AI data, complete the following steps:

Generate a transaction token and aiResourceid - The parameters that need to be
passed to generate a transaction token are explained below. The transaction token is valid for 30 days and can be used any number of times in that duration.
Request Fire Risk AI data using the API - You must have a transaction token to do this. The parameters that need to be passed to generate an output file are explained below.

Mandatory parameters are indicated with a ✔️, while ❌ indicates optional parameters.

Authentication

Access to Nearmap Fire Risk data is only available to authenticated subscribers. Fire Risk AI data may be requested from Nearmap servers with an API Key. Refer to the API Key Authentication article for details.

Generating the transaction token

Required	Name	Type	Description
✔️	address	string	Complete address of the property including the country. For example, `333 Guadalupe St, Austin, TX 78701, USA`. Note that you can specify this in any case.
✔️	resources	string	Set this to one of the following: `aiFireRisk:defensibleSpace` `aiFireRisk:3dtopo` `aiFireRisk:auxRiskData` Depending upon your subscriptions, you may be able to access one or all resources. More details about resources are provided below. NOTE: `3dtopo` and `auxRiskData` are only available to US customers.
❌	since	string	Survey date range start to for the data to be retrieved. Format: `2022-01-01`
❌	until	string	Survey date range end for the data to be retrieved. Format: `2023-01-01`
❌	unit	string	Unit in which to present results. The available options are `foot` or `meter` If not specified, the default is `foot`.

NOTE: If both since and until dates are not specified, all the dates for the address where Fire data is found will be included in the results.

❗️IMPORTANT: 3D Topography data is always displayed based on the latest date for which data is available. Date parameters are ignored for 3D data.

Resources

The Nearmap Fire Data AI returns certain base content regardless of the value of you specify for the resources parameter. However, you must set this parameter to specify the additional content you want returned.

❗️IMPORTANT: You cannot access only the base without the additional resource content. Set this parameter as shown in the table above to return defensible space data, 3D topography data or both.

NOTE: Resources are charged in credits depending upon your subscriptions and usage. Refer to the credit table in MyAccount to check the number of credits that will be charged for each resource type.

Example URL to request the transaction token

https://api.nearmap.com/coverage/v2/tx/address?country={country}&city={city}&state={state}&postcode={postcode}&streetAddress={streetAddress}&resources={resources}&dates={dates}&apikey={APIKEY}

Once generated, the transaction token is a long sequence of numbers, letters and symbols which is stored in the transactionToken field.

"surveys": [

{

"captureDate": "2023-06-16",

"captureDateTime": "2023-06-16T14:27:53Z",

"firstPhotoTime": "2023-06-16",

"id": "05696b84-0dc2-11ee-b13f-871e2884ab9e",

"lastPhotoTime": "2023-06-16",

"contentTypes": [

      "aiFireRisk:defensibleSpace"

],

"aiResourceId": "469eea41-dea9-5173-b7b1-8e4959575003"

}

],

  "limit": 20,

  "offset": 0,

  "total": 1,

  "transactionToken": "eyJhbGciOiJkaXIiLCJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoidHgvZW5jcnlwdC8yMDIzLTAzLTEzIiwiemlwIjoiREVGIn0..4MfExs4dMptO7dHG.wzk1AyfzN6gfZD2ZZaupwz6qFwJ2JBgdD-oU1yYHrMCtxx1oH5G9HRvvBSOQwIEIoYgh2nHUDgaB3ldrzEzPgvHZGnTxClRESaq8ulDNPBU4__Cc3poxzvINdZooCZ1_RPNhEVsYwekTaZLf-edOO9JufDOQK5IQA5DYyuauVo7L1zL8kcO6v1nCDIqu4QRdrY_Q-MvgbvU4faFmWUuxSMpjSOvdgigRT_PhPLRcDVwB4QBliYhepucrISgVdvEO1SH24Hq0tfR8BxEl9J1t7dKVpxq7T2sk0dYW8Lig6Zgklw2kSa1VLLCAvM8RDdpPfSAydeGIXi1BfMoTfsuiA9iGUT3tKQDCR-puKoFEEXKWhXN0zM0PdDI_imGQAPz0rFK8h7fViyOPT3MLay4-EcCpkkk8EYR22ET3JqokOCEjckEE53rW2whdkKrYakkXI2gnJd9W2YmUs8ZJ8JCIh2vZ_yOcatUpRgG9qdidqBfUYoepVllrGBl-WbCFqPRxH-fYfiq4ZzVMpDc012aj1GReuBZyag4O5u2waajTzQNBSNVOZvKd5x8z084sbAoXe8Ol5TP96AU84zTED51K00NAf04adG2JxBYNN-WdnzMz6OLkvv7_YpY9E3xeHLgDCQ30CvI31OuWClHnkR7m9qX1pz1j0Jho_0jIHPKsD_E00pmKPl74bm-Cg2G4FIsgqyYXsQz3FFqOOncASztpq3gcUIy7YbH_FO8xukHw0fzAgXl-EpR1Z4XIhqCPIGFYRkto_qHaF7VpPjvQArvvJ-cjV8lqmFciywN4dqzuLaDU54FMmSvqokY2xnFHsR6uNIM3JkHkAiWjsM_NR3eOWJa-0YNiI3Pg5-k5J8e_AAxFRi2F4KwduiNNhfFSDUTsADWK3eG6r5uL-jm41SoavHcniIar8d8kcyuCXZzjU-nvCxAv95LFdHzvb7e_SaQd61-XwI5Hf3ttv2QSfqc2KoM38MsY8iU07J_n1LcZCnXAVFvSs_gn4jQjdxJz2xVrl8Bp6E4WZRkuB4yMo1J122_gDhM_K8zb3-7MMQ4X0mJHVOEPwzwxRB3iUUkbG6oUo8HEe3JaYSQrvf7CV1Bkp_XNejRmHi9576hsImu4qpXOuxpfnDNpTuWuddoFPxRuw6RZ9UatJFKxycPB-nOrcR7xvpTa2uL8dM091NURzZk2cYp8eBm43CV5a1M-zieQru4amuN2DBRRi2nK4H4bDnOypiL_tSHE.HIVstO8FwmHEpM8zUCEF7g",

  "costOfTransaction": 525,

  "reference": "",

  "bbox": "-100.79944735,36.39782701,-100.79891465,36.39800099",

  "geocodedAddress": "214 S Cedar St Perryton Perryton TX 79070-2649 United States of America",

  "resourceServers": {

  "aiFireRisk": "https://api.nearmap.com/ai/fire/v1/tx/surveyresources/{aiResourceId}/data.csv?transactionToken={transactionToken}"

},

"tileSizeInPixels": 4096

}

Adding a custom reference

You can add your own reference to display in the CSV output. Include this in the above API call with the header as shown in the example below:

curl --location 'https://api.nearmap.com/coverage/v2/tx/address?country=US&city=AUSTIN&state=TX&postcode=78741&streetAddress=1413%20MONTOPOLIS%20DR%20&resources=aiFireRisk%3AdefensibleSpace%2CaiFireRisk%3A3dtopo&dates=single&apikey={apiKey}' \ --header 'X-Nearmap-Ext-Reference: Your Reference'

Requesting data

To access the fire data, you will need to call the endpoint below with the aiResourceId and transactionToken from the first call.

https://api.nearmap.com/ai/fire/v1/tx/surveyresources/{aiResourceId}/data.csv?transactionToken={transactionToken}

Data is returned as a CSV file, the contents of which are described below.

CSV file contents

The first row contains the headers, followed by any number of result rows with values. Each result row corresponds to one subject roof feature.

The columns included will depend on the resourceTypes query parameter.
The columns with a `ds` prefix will be included if the resourceTypes parameter includes defensibleSpace, or if the transaction token includes this resource type.
The columns with a 3dtopo prefix will be included if the resourceTypes parameter includes 3dtopo, or if the transaction token includes this resource type.

Example CSV output with a custom reference

FireRiskAI_Sample_CSV.zip

Downloadable sample CSV in ZIP format

Base attributes

The following attributes will be included in every request regardless of the resource you choose to use.

Attribute	Description
reference	Reference value as specified in the header. This is your reference for the API call/transaction
id	Unique ID for a subject roof feature (UUID).
system_version	Version of the AI Feature data used to produce the presented values (string). This will be the same for all rows.
survey_date	The date of the survey capture that the features are derived from (string). This will be the same for all rows.
longitude	Longitude of the centroid of the subject roof feature (decimal).
latitude	Latitude of the centroid of the subject roof feature (decimal).
mapbrowser_link	URL to the feature's location in MapBrowser (URL).
unit	The units in which the values are generated. Can be `foot` or `meter` (string). This will be the same for all rows.
[metal, shingle, tile]_area	Area of the subject roof that's of this material (decimal).
[hip, gable, dutch_gable, flat, turret]_area	Area of the subject roof that's of this shape (decimal).

Defensible space

NOTE: Nearmap calculated zones include distances used commonly in the industry, as well as additional levels to add more granularity and risks over greater distances. Please note that the zone numbering is Nearmap specific and the mapping for zone number to distance ranges varies in the industry.

Attribute	Description
ds_[zone1, zone2, zone3, zone4, zone5]_length	Distance between the subject roof and the boundary of the defensible space zone (decimal). The distances are defined as follows: ▪️ zone1: 0-5 foot / 0-1.524 meter ▪️ zone2: 0-10 foot / 0-3.048 meter ▪️ zone3: 0-30 foot / 0-9.144 meter ▪️ zone4: 0-100 foot / 0-30.48 meter ▪️ zone5: 0-300 foot / 0-91.44 meter
ds_[zone1, zone2, zone3, zone4, zone5]_area	Area of the defensible zone around the subject roof (decimal).
ds_[zone1, zone2, zone3, zone4, zone5]_complete	Whether or not the defensible zone is completely covered by the available feature data (boolean).
ds_[zone1, zone2, zone3, zone4, zone5]_[water_body, swimming_pool, roof, medium_and_high_vegetation, low_vegetation, very_low_vegetation, leaf_off_vegetation, vegetation_debris, junk_and_wreckage, wooden_decking, power_line, road, lawn_grass, natural, car, tyre]_area	Total area of this feature in the defensible zone around the subject roof (decimal).
ds_[zone1, zone2, zone3, zone4, zone5]_pole_count	Number of poles in the defensible space around the subject roof (integer).
ds_version	The version of the defensible space data (string)

3D topography data

Attribute	Description
3dtopo_nondir_[zone1, zone2]_length	Radius of the (non-directional) circular zone of interest around the center point of the subject roof (decimal). The distances are defined as follows: ▪️ zone1: 100 feet / 30.48 meters ▪️ zone2: 300 feet / 91.44 meters
3dtopo_nondir_[zone1, zone2]_elevation_mean	Mean elevation in the zone around the center point of the subject roof (decimal).
3dtopo_nondir_[zone1, zone2]_slope_mean	Mean slope in the zone around the center point of the subject roof in degrees (decimal).
3dtopo_nondir_[zone1, zone2]_aspect_mean	Slope-weighted mean aspect in the zone around the center point of the subject roof in degrees (decimal).
3dtopo_nondir_[zone1, zone2]_terrain_ruggedness_index	Mean deviation in elevation between the center point of the subject roof and the zone around the subject roof (decimal).
3dtopo_nondir_[zone1, zone2]_topographic_position_index	Difference between the elevation at the center point of the subject roof and the mean of the zone around the subject roof (decimal).
3dtopo_dir_[zone1, zone2]_length	Length of the (directional) rectangular zone emanating from the center point of the subject roof (decimal). The distances are defined as follows: ▪️ zone1: 100 by 300 feet / 30.48 by 91.44 meters ▪️ zone2: 100 by 2000 feet / 30.48 by 609.6 meters
3dtopo_dir_[zone1, zone2]_[north, northeast, east, southeast, south, southwest, west, northwest]_slope_mean	Mean slope in the zone emanating from the center point of the subject roof in this wind direction (decimal).
3dtopo_version	The version of the 3d topographic data (string)

Auxiliary Risk Data

Attribute	Description
wui_version	The version of the Wildland Urban Interface (WUI) data (string).
wui_[neighbourhood1, neighbourhood2, neighbourhood3, neighbourhood4, neighbourhood5, neighbourhood6]_length	Radius of the circular neighbourhood around the center point of the subject roof (in ft or m, decimal). The distances are defined as follows: ▪️ wui_neighbourhood1: 328.08 foot / 100 meter ▪️ wui_neighbourhood2: 820.21 foot / 250 meter ▪️ wui_neighbourhood3: 1640.42 foot / 500 meter ▪️ wui_neighbourhood4: 2460.63 foot / 750 meter ▪️ wui_neighbourhood5: 3280.84 foot / 1000 meter ▪️ wui_neighbourhood6: 4921.26 foot / 1500 meter
wui_[neighbourhood1, neighbourhood2, neighbourhood3, neighbourhood4, neighbourhood5, neighbourhood6]_category	WUI category for the subject roof in the relevant neighbourhood (one of `not wui`, `intermix`, `interface` or `no data`, string).
whp_version	The version of the Wildfire Hazard Potential (WHP) data (string).
whp_category	WHP category for the subject roof (one of `very low`, `low`, `moderate`, `high`, `very high`, `non-burnable land`, `water` or `no data`, string).