Choosing the parcel
What to do when an address could be on more than one parcel, and how to measure exactly the parcel you mean.
Duranta measures a parcel: the lot recorded by the county. An address is not a parcel, so before measuring, Duranta has to find which parcel the address is on.
Create a site does that for you. It looks the address up with several address lookup services and measures the parcel most of them place it on. For almost every address this is all you need.
Sometimes the services disagree. One places the pin on the house, another on the lot next door, and none of them wins. Measuring a guess would measure, and charge you for, the wrong parcel, so Duranta does not measure the site. It ends with SITE_STATUS_ISSUE and the error code PARCEL_AMBIGUOUS, and nothing is charged.
Two calls let you settle it:
| Call | What it does |
|---|---|
| Find parcels | Looks the address up and lists the parcels it may be on, most likely first. Each has a parcelId, a point inside the parcel and its area. It measures nothing and creates no site. |
| Create a parcel site | Measures exactly the parcel you pass as parcelId. Otherwise it works like Create a site. |
When to use them
Only when needed (recommended). Call CreateSite as usual. When a site comes back with PARCEL_AMBIGUOUS, call FindParcels for its address, pick a parcel and call CreateParcelSite with the same externalId. The site keeps your identifier and is measured on the parcel you picked.
Always. If you want to confirm the parcel before anything is measured, for example by showing the candidates to the homeowner, call FindParcels first and then CreateParcelSite for every address. You never get PARCEL_AMBIGUOUS this way. Find parcels is free, and Create a parcel site is charged like Create a site, see Billing.
Example
Placeholders in angle brackets stand for your own values.
The site reports the issue
GetSite for a site created with CreateSite returns:
{
"externalId": "<your externalId>",
"status": "SITE_STATUS_ISSUE",
"error": {
"code": "PARCEL_AMBIGUOUS",
"message": "The address matches more than one parcel."
}
}List the parcels
curl https://app.getduranta.com/duranta.api.public.v1.SiteService/FindParcels \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"address": {
"line1": "<street address>",
"city": "<city>",
"region": "<state>",
"postalCode": "<ZIP code>",
"country": "US"
}
}'{
"parcels": [
{
"parcelId": "<parcel id 1>",
"location": { "latitude": <latitude>, "longitude": <longitude> },
"areaSqM": <area>
},
{
"parcelId": "<parcel id 2>",
"location": { "latitude": <latitude>, "longitude": <longitude> },
"areaSqM": <area>
}
]
}call is the helper from the Quickstart, and address is the same address object you sent to CreateSite.
Pick one
The first parcel is the one most lookups placed the address on. To be sure, compare each location with what you know about the property: drop the points on a map, check the lot size against your records, or ask the customer which one is theirs. Boundaries are not returned, only a point inside each parcel and its area in square meters (a site reports its parcel area in square feet).
Measure it under the same ID
curl https://app.getduranta.com/duranta.api.public.v1.SiteService/CreateParcelSite \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"externalId": "<your externalId>",
"parcelId": "<parcel id 1>",
"tier": "RESULT_TIER_IMAGE",
"address": {
"line1": "<street address>",
"city": "<city>",
"region": "<state>",
"postalCode": "<ZIP code>",
"country": "US"
}
}'Then poll GetSite as in the Quickstart, or wait for the webhook. The site goes back to SITE_STATUS_ACCEPTED and then to SITE_STATUS_COMPLETED, or to SITE_STATUS_FAILED if the measurement fails.
Behavior and limits
- The address you pass to
CreateParcelSiteis stored with the site and shown in the Duranta app. It is not looked up again: the parcel decides what is measured. - Once a site is measured on a parcel, that parcel is fixed. Calling
CreateParcelSiteagain with the sameexternalIdand the sameparcelIdchanges nothing. A differentparcelIdfails withalready_exists, and so doesCreateParcelSitefor a site thatCreateSitealready measured. Use a newexternalIdto measure another parcel; it is a separate site and a separate charge. - A
parcelIdthat Duranta does not know fails withnot_found. - An empty
parcelslist means the address does not resolve to any parcel.CreateSitereports the same address asADDRESS_NOT_FOUND.