Overview
The Roof Condition score and associated details are generated based on Gen 5 AI data. All you need to do is provide the required parameters as the initial input subsequent to which the Transactional API coverage will return a transaction token. With this token, you can access the assessment API to retrieve the roof condition data in the one or more of the following formats: CSV, JSON and PDF.
NOTE: The roof condition generated for a particular combination of address and date is counted as one transaction. You can generate roof condition artefacts for this combination as many times as you like within 30 days without incurring credits. Changing one or both the address and the date will result in additional credits being consumed.
Generating the Roof Condition output is a two-step process:
- Generate a transaction token. 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.
- Generate the output as CSV/JSON/PDF. 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 green tick, while a red cross indicates optional parameters.
Authentication
Access to Nearmap data and imagery is only available to authenticated subscribers, currently limited to US customers. Roof Condition data and imagery may be requested from Nearmap servers with an API Key. Refer to the API Key Authentication guide for details on how to obtain and use an API Key.
Generating the transaction token
To generate the transaction token, provide the following information.
|
Required | Name | Type | Description |
|---|
✔️ | address | string | Complete address of the parcel including the country. For example, 333 Guadalupe st, Austin, TX 78701, USA. Note that you can specify this in any case. |
✔️ | country | string | This can take the value US only as this product is not yet available in other regions. This is not case sensitive. |
✔️ | dates | string | Set this to "single", which is the only acceptable value for this parameter. This uses the latest survey as a default. |
❌ | since and until | string | Use these optional parameters to specify a date range to access historical surveys. Specify the dates in the format YYYY-MM-DD. For example, since=2010-01-01&until=2012-01-01 will return the latest survey in this date range while since=2010-01-01&until=2010-01-01 will return a survey on that specific date. |
✔️ | resources | string | Set this to aiAssessment:nearmap_roof_cond. |
Example URL to request the transaction token
https://api.nearmap.com/coverage/v2/tx/address?country=US&address=<address>&apikey=<your API key for authentication>&dates=single&resources=aiAssessment:nearmap_roof_cond
Once generated, the transaction token is a long sequence of numbers, letters and symbols stored in the transactionToken field as shown in the illustration below.
Generating the CSV/JSON/PDFYou must provide the following information.
|
Required | Name | Type | Description |
|---|
✔️ | fileType | string | This can take one of the following values: CSV, JSON or PDF. |
✔️ | aiResourceId | string | The ID of the survey required to for completing the assessment obtained from the initial call. For example, 6c6abf86-1727-4472-8e91-7defb3c7ae3c. This is case sensitive. |
✔️ | transactionToken | string | The transaction token obtained from the initial call. This is case sensitive. |
Example URL to request the assessment document
Copy the aiResourceid and transactionToken returned in the initial call and paste them into the URL below as shown in the illustration.
https://api.nearmap.com/ai/assessment/v1/tx/surveyresources/<aiResourceId>/nearmap_roof_cond.<fileType>?transactionToken=<transactionToken>