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:

CallWhat it does
Find parcelsLooks 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 siteMeasures 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"
    }
  }'
Response
{
  "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 CreateParcelSite is 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 CreateParcelSite again with the same externalId and the same parcelId changes nothing. A different parcelId fails with already_exists, and so does CreateParcelSite for a site that CreateSite already measured. Use a new externalId to measure another parcel; it is a separate site and a separate charge.
  • A parcelId that Duranta does not know fails with not_found.
  • An empty parcels list means the address does not resolve to any parcel. CreateSite reports the same address as ADDRESS_NOT_FOUND.

On this page