Skip to main content
The parcel_permit_* fields describe the building permits tied to one parcel. Request them by name in any of these:
  • They are licensed Enrich fields, in the normal Enrich parcel price: $0.02 per enriched parcel on Free. See Pricing.
  • They are not in any preset, and a request with no fields or preset does not include them. Name each one in fields.
  • Every response with a permit field also carries parcel_permit_coverage. Read it first.

Example

Values are illustrative. Over hosted MCP, send the same request inside req of mireye_enrich:

The fields

Which permits count

A permit counts when all of these are true:
  • Mireye tied it to this parcel with high or medium link confidence.
  • It has a day, month or year date.
  • It is not undated and not an older history record. A history record was issued before the start date named in the coverage note (today July 1, 2024). With no issued date, it was filed before that date.
One permit reported by two sources counts once. The date is the permit’s first recorded date:
  • It is the earliest of its filed, issued and finaled dates.
  • It is not always the filing date.
  • A month date is the 1st of the month. A year date is January 1.
Tags:
  • Tags are assigned by Mireye from each permit’s own text and can be wrong.
  • A parent tag includes its child tags: electrical includes solar.

parcel_permit_tags

  • Only tags with at least one permit appear. {} means no counted permit has a tag.
  • confidence is from 0 to 1. It is the measured share of permits given the tag that really are that kind of work. null means not measured, never 0.

parcel_permit_latest

link_method values:
  • parcel_id: the permit names the parcel’s number.
  • point_in_parcel: its map point is inside the parcel.
  • address: its address matches the parcel’s.
Also:
  • work_tags and work_tag_confidence are left out when tag data is missing.
  • The cell’s own confidence (outside value) is the weakest link behind the value: high, medium or unknown.

Coverage

parcel_permit_coverage.value is {coverage, note}. note is a few plain sentences, or null. Examples:
  • “City of Example permits are collected in full, and 87% of them are tied to a parcel.”
  • “City of Example permits are collected in full but only 32% of them are tied to a parcel, so counts are a lower bound and a 0 is not proof of no permits.”
  • “City of Example permits are only partly collected, so counts are a lower bound and a 0 is not proof of no permits.”
  • “This parcel’s permit office, City of Example (by 2020 city limits), is not collected yet; only 3 of 21 permit offices in this county have collected permits, so counts are omitted: a missing count means unknown, not 0.”
  • “Permits in this county are collected but not yet tied to parcels, so counts are omitted: a missing count means unknown, not 0.”
  • “Counts include permits issued on or after 2024-07-01, or, with no issued date, filed on or after it. Older permits are history records: they are not counted here.”
  • “3 permits tied to this parcel have no usable date and are not counted.”
  • “1 permit tied to this parcel has no usable date and is not counted.”
How to read the note:
  • The “Counts include permits issued on or after” sentence names the date the counts start. It is left out with not_collected, because counts are left out too.
  • The note does not say where an office’s collected permits end. To see it, read dates_covered.to for the office in GET /v1/permits/coverage.
  • “(by 2020 city limits)” means the office was found from the parcel’s 2020 Census block. An annexation since 2020 can make it wrong.
  • Branch on coverage. The note text is written for people and can change.

What a missing value means

Enrich leaves a field out of fields when it has no value. For permit fields: In Search fields, a permit field with no value is null instead of left out. Read it the same way.

permit_fields_unavailable

When a permit field fails while other fields are returned, the Enrich response has a top-level list:
  • retryable: true means a temporary failure, such as a timeout. Retry.
  • retryable: false means the permit data is not available for this parcel right now.
  • The key is absent when no permit field failed.
  • When nothing at all could be returned and a permit field failed, Enrich answers 503 permits_unavailable. It is not charged. Retry with a new idempotency key if you sent one.

The permits list

Add permits to an Enrich request to get the matched parcel’s permit records next to its fields. permits is an object of Permits API filters. Send {} for no filter.
Values are illustrative. Request: The response has a top-level permits object when you sent permits and the parcel matched:
  • The list is the permits of the parcel Enrich matched. An address can name one unit of a building with shared units. Then the list holds only that unit’s linked permits.
  • When the list cannot be read, the rest of the answer is still returned. The permits object then has:
    • permits: [];
    • total, coverage, note and next as null;
    • error (permits_unavailable, retryable: true);
    • retry: the parcel search that reads the list on its own.
  • The list costs one permit property ($0.036 on Free) when it returns at least one permit. It is charged even when no field is returned.
  • The property is reserved with the parcel price before the call runs. Set max_cost_usd to cover both, such as "0.06" on Free.
  • An empty list, a count (permits_limit: 0) and a list that cannot be read cost nothing extra.

Price

  • A parcel is charged once, at the Enrich price, when a field you named is returned.
  • parcel_permit_coverage and parcel_permit_latest_date_precision are added for you. Added this way, they never make a parcel chargeable on their own. If you name them yourself, they count like any other field.
  • In Search, permit fields are in the query price.
  • The permits list adds one permit property when it returns a permit. See The permits list.