> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mireye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrich permit fields

> Building permit counts, dates and tags for one parcel, with a coverage word that says how far to trust them.

The `parcel_permit_*` fields describe the building permits tied to one parcel. Request
them by name in any of these:

* [`POST /v1/enrich`](https://docs.mireye.ai/api-reference/enrich);
* the `mireye_enrich` MCP tool;
* the `fields` of [`POST /v1/search`](https://docs.mireye.ai/api-reference/search).

> [!NOTE]
>
> * They are licensed Enrich fields, in the normal Enrich parcel price: **\$0.02** per
>   enriched parcel on Free. See [Pricing](https://docs.mireye.ai/pricing.md).
> * 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

```bash theme={null}
curl -sS --max-time 210 https://api.mireye.com/v1/enrich \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 29.5901, "lng": -95.6402,
    "fields": ["parcel_permit_count", "parcel_permit_solar_count", "parcel_permit_latest"],
    "max_cost_usd": "0.02"
  }' | jq '.fields'
```

```json theme={null}
{
  "parcel_permit_count": {
    "value": 4,
    "source": "MIREYE_PERMITS",
    "confidence": "high",
    "interpretation_hints": "Number of building permits Mireye linked to THIS parcel, all work types. …"
  },
  "parcel_permit_solar_count": {
    "value": 1,
    "source": "MIREYE_PERMITS",
    "confidence": "high",
    "interpretation_hints": "…"
  },
  "parcel_permit_latest": {
    "value": {
      "permit_id": "pmt_tx_0a1b2c3d4e5f60718293a4b5",
      "date": "2025-03-04",
      "date_precision": "day",
      "status": "final",
      "category": "electrical",
      "work_tags": ["solar"],
      "work_tag_confidence": {"solar": 0.97},
      "link_method": "parcel_id",
      "link_confidence": 0.93
    },
    "source": "MIREYE_PERMITS",
    "confidence": "high",
    "interpretation_hints": "…"
  },
  "parcel_permit_coverage": {
    "value": {
      "coverage": "complete",
      "note": "City of Example permits are collected in full, and 87% of them are tied to a parcel. 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."
    },
    "source": "MIREYE_PERMITS",
    "confidence": "unknown",
    "interpretation_hints": "…"
  }
}
```

Values are illustrative.

Over hosted MCP, send the same request inside `req` of `mireye_enrich`:

```json theme={null}
{
  "req": {"lat": 29.5901, "lng": -95.6402, "fields": ["parcel_permit_count", "parcel_permit_latest"]},
  "idempotency_key": "parcel-permits-0001"
}
```

## The fields

| Field | Type | Meaning |
| - | - | - |
| `parcel_permit_coverage` | object | `{coverage, note}`: how far the permit data covers this parcel. See [Coverage](#coverage). |
| `parcel_permit_count` | integer | Permits tied to this parcel, all work types. |
| `parcel_permit_new_building_count` | integer | Of those, permits tagged `new_building`. |
| `parcel_permit_solar_count` | integer | Of those, permits tagged `solar`. |
| `parcel_permit_roof_count` | integer | Of those, permits tagged `roof`. |
| `parcel_permit_latest_date` | string | The latest first-recorded date among those permits. |
| `parcel_permit_latest_date_precision` | string | `day`, `month` or `year`: how exact `parcel_permit_latest_date` is. |
| `parcel_permit_tags` | object | Per work tag: `count`, `latest_date`, `latest_date_precision` and `confidence`. |
| `parcel_permit_latest` | object | The latest permit. See [parcel\_permit\_latest](#parcel_permit_latest). |

### 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

```json theme={null}
{
  "electrical": {"count": 2, "latest_date": "2025-03-04", "latest_date_precision": "day", "confidence": 0.95},
  "solar": {"count": 1, "latest_date": "2025-03-04", "latest_date_precision": "day", "confidence": 0.97}
}
```

* 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

| Key | Meaning |
| - | - |
| `permit_id` | The permit's id. Look it up with [`GET /v1/permits?id=…`](https://docs.mireye.ai/api-reference/permits#look-up-permits-by-id). |
| `date`, `date_precision` | Its first recorded date and how exact it is. |
| `status` | `in_review`, `active`, `final`, `inactive` or `unknown`. |
| `category` | The permit category. |
| `work_tags`, `work_tag_confidence` | Its work tags, and one confidence per tag (`null`: not measured). |
| `link_method` | How it was tied to the parcel. See below. |
| `link_confidence` | A number: a conservative estimate of the share of permits tied this way that are tied to the right parcel. `0.93` means at least about 93%. It comes from a hand check of a national sample, not of this county. `null` means not measured: today links of `medium` confidence are not measured, so their `link_confidence` is `null`. |

`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}`.

| `coverage` | Meaning | Counts |
| - | - | - |
| `complete` | Two things must both be true. The parcel's permit office is collected in full. At least half of its permits in the county are tied to parcels. That share is not known when the office has no dated permits in the county. Then a fully collected office still counts as complete. When the office is not known, every office in the county must be complete by the same test. | Real counts. A `0` means no counted permit. |
| `partial` | The office is only partly collected. Or most of its permits are not tied to parcels. Or the office is not known, and not every office in the county is complete. | A lower bound. A `0` is not proof of no permits. |
| `not_collected` | The parcel's office, or its county, is not collected yet. Or its permits are not tied to parcels yet. | Left out: unknown, never 0. |

`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`](https://docs.mireye.ai/api-reference/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:

| You see | Meaning |
| - | - |
| A count of `0` with `complete` | No counted permit is tied to this parcel. |
| A count of `0` with `partial` | No counted permit was found, but some may be missing. |
| Counts left out, with `not_collected` | Unknown. Not 0. |
| `parcel_permit_latest`, `parcel_permit_latest_date` left out | No counted permit, or counts are unknown. Read the coverage. |
| The field named in `permit_fields_unavailable` | The permit data failed for this request. Not a finding of no permits. |

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:

```json theme={null}
{"permit_fields_unavailable": [{"field": "parcel_permit_count", "retryable": true}]}
```

* `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](https://docs.mireye.ai/api-reference/permits.md#filters).
Send `{}` for no filter.

```bash theme={null}
curl -sS --max-time 210 https://api.mireye.com/v1/enrich \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "address": "1234 Example Dr, Example, TX 77479",
    "fields": ["parcel_permit_count"],
    "permits": {"work_tags": ["roof"]},
    "permits_limit": 5,
    "max_cost_usd": "0.06"
  }' | jq '.permits'
```

```json theme={null}
{
  "permits": [{"permit_id": "pmt_tx_0a1b2c3d4e5f60718293a4b5", "…": "the full permit record"}],
  "total": 7,
  "coverage": "partial",
  "note": "An area search sees only permit offices with permits in the area; an office we do not collect may also serve it, so counts are a lower bound.",
  "next": {
    "where": {"parcel": {"address": "1234 Example Dr, Example, TX 77479"}},
    "filters": {"work_tags": ["roof"]},
    "limit": 5,
    "cursor": "q9cS0k1u…"
  }
}
```

Values are illustrative.

Request:

| Field | Type | Meaning |
| - | - | - |
| `permits` | object | Permits API filters for the list. `{}` means every filter at its default. An invalid filter is rejected with `422` before any charge. |
| `permits_limit` | integer | Permits in the list, 0 to 100. The default is 100. Needs `permits`. |

The response has a top-level `permits` object when you sent `permits` and the parcel
matched:

| Key | Meaning |
| - | - |
| `permits` | The parcel's [permit records](https://docs.mireye.ai/api-reference/permits.md#permit-record). |
| `total`, `coverage`, `note` | The same as a [Permits API parcel search](https://docs.mireye.ai/api-reference/permits.md#parcel-selector) with the same address or point and these filters. |
| `next` | When there are more permits: the parcel search that continues the list, with its `cursor`. Values at their default are left out. Send it as is to `POST /v1/permits/search` (a paid search page). Else `null`. |
| `geocode`, `parcel` | Only for an address request. See [Parcel by address](https://docs.mireye.ai/api-reference/permits.md#parcel-by-address). |

* 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](#the-permits-list).

## Related pages

* [Permits API](https://docs.mireye.ai/api-reference/permits.md): the permit records themselves.
* [Search permits filter](https://docs.mireye.ai/api-reference/search-permits-filter.md): find parcels by their
  permits.
* [Permits coverage](https://docs.mireye.ai/api-reference/permits-coverage.md).
* [Permits known issues](https://docs.mireye.ai/api-reference/permits-known-issues.md).
