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

# Permits coverage

> Which permit offices are collected, what complete, partial and not_collected mean, and a coverage label for each state.

US building permits are issued by thousands of local permit offices:

* cities;
* counties, for the areas outside cities.

Each office publishes its records in its own way. We collect them office by office,
so coverage is measured **per office**.

## Where permits come from

* Permits come from public records published by permit offices and other public
  agencies.
* Each permit carries its `source.citation_url`, and the source's `attribution` text
  when it needs one. Show that text wherever you show the permits.
* Some sources are held back until their terms let us serve them. Their permits are
  not in any answer or count.
* Work tags, categories and parcel links are made by Mireye from the records. They can
  be wrong.
* Work tags carry a measured confidence (`work_tag_confidence`). Categories carry no
  confidence.
* In the Permits API, a parcel link carries the word `high` or `medium`
  (`parcel.confidence`). The Enrich permit fields give a measured number
  (`parcel_permit_latest.link_confidence`). Links of `medium` confidence are not
  measured today, so their number is `null`.

## The coverage words

Every permit answer uses the same three words:

| Word | Meaning | How to read a count |
| - | - | - |
| `complete` | The office's permit records are collected in full. | A real count. |
| `partial` | Collected, but the feed is partial or covers only some permit types. | A lower bound. A `0` is not proof of no permits. |
| `not_collected` | Not collected yet. | Unknown. A `0` is not proof that no permits exist. |

How each surface uses them:

* [Permits API](https://docs.mireye.ai/api-reference/permits.md): one word for the offices behind a search.
  Complete only when every office is complete. A search by point, polygon, parcel or
  ZIP is never `complete`: an office we do not collect can also serve the area. An id
  lookup gives each permit its own office's word.
* [Search permits filter](https://docs.mireye.ai/api-reference/search-permits-filter.md): the coverage remark
  says how many offices in the county are not fully collected.
* [Enrich permit fields](https://docs.mireye.ai/api-reference/enrich-permit-fields.md): `complete` also needs
  most of the office's permits to be tied to parcels. With `not_collected`, counts are
  left out.

## Check coverage before you search

[`GET /v1/permits/coverage`](https://docs.mireye.ai/api-reference/permits#coverage) lists every
permit office in a state. It is free and needs no API key. Each office comes with:

* its word;
* its date range;
* its permit counts;
* its sources.

```bash theme={null}
curl -sS "https://api.mireye.com/v1/permits/coverage?state=TX&status=complete" \
  | jq '.summary, [.offices[] | {id, name, dates_covered}][0:3]'
```

* `summary` counts the state's offices per word.
* `dates_covered` is the date range of the permits we hold for an office.
* Use an office `id` as `where.authority_id` in a Permits API search.

## Coverage by state

Each state has one label. It tells you how much of the state the permit data covers.

* **full**: the state passes all four tests below.
* **partial**: the state passes the volume test and misses one or two other tests.
* **thin**: every other state.

The four tests:

| Test | A state passes when |
| - | - |
| Volume | We serve at least 50,000 dated permits from July 1, 2024. |
| Offices | The offices we serve issue at least 40% of the state's new housing permits. This is measured by the Census Building Permits Survey. |
| Located | At least 65% of the permits we serve have a map point. |
| Complete records | At least 35% of the permits have a map point, an exact date, a category other than `other`, a known status and a usable description. |

> [!NOTE]
>
> The located test counts every map point we serve, including points found from a
> linked parcel. Those points are available to licensed callers, and every Permits API
> search is licensed. Without them, fewer states pass.

| Label | States |
| - | - |
| full (9) | AZ, CO, DE, FL, LA, MD, NC, TX, WA |
| partial (21) | AR, CA, DC, GA, IA, IL, KS, MA, MI, MN, MO, NJ, NV, NY, OH, OR, PA, SC, TN, VA, WI |
| thin (21) | AK, AL, CT, HI, ID, IN, KY, ME, MS, MT, ND, NE, NH, NM, OK, RI, SD, UT, VT, WV, WY |

What the partial states miss:

* Offices only: AR, CA, GA, IL, MA, MI, MN, NV, NY, OH, OR, PA, SC, TN, VA, WI.

* Complete records only: DC, KS.

* Offices and complete records: IA, MO.

* Located and complete records: NJ. The statewide source gives no address or
  description.

* A state label is a summary. Coverage inside a state differs by office.

* Check the office before you trust a count: use
  [`GET /v1/permits/coverage`](https://docs.mireye.ai/api-reference/permits#coverage).

* The labels are measured on each data update and can change.

## Dates covered

* Permits are served when they were issued on or after July 1, 2024. A permit with no
  issued date counts by its filed date. Such a permit can have a filed date before
  July 1, 2024.
* Older records (history records) are available for some offices with
  `include_history` in the Permits API. The Search permits filter and the Enrich
  permit fields do not count them.
* `last_refresh` says when an office's data was last collected.

## Known issues

The issues we know about, and how to work around them, are on
[Permits known issues](https://docs.mireye.ai/api-reference/permits-known-issues.md).

## Report a problem

When a permit answer looks wrong, send us the request and what identifies the answer:

* **Permits API:** the `X-Mireye-Data-Version` response header and the `permit_id`.
  The header names the version of the permit data that made the answer.
* **Search permits filter:** the `request_id` and the `permits_as_of` value of a
  match. Search sends no `X-Mireye-Data-Version` header.
* **Enrich permit fields:** the `billing.operation_id` and the
  `parcel_permit_latest.permit_id`, when present. Enrich sends no
  `X-Mireye-Data-Version` header.
