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

> What can be wrong in the permit data today, what you see, and how to work around it.

This page lists the permit data issues we know about.

* Each row says what you see and what to do.
* We fix them in data updates. When an issue is fixed, we remove its row.
* Counts on this page are approximate. They change with each data update.

If you find an issue that is not on this page, see
[Report a problem](https://docs.mireye.ai/api-reference/permits-coverage.md#report-a-problem).

## Dates

| Issue | What you see | What to do |
| - | - | - |
| Philadelphia, Pennsylvania: permits recorded in the evening. | Some issued and finaled dates are one day late. This stays until the next data update. | Allow one day of error on Philadelphia dates. |
| Lee County, Florida: dates exact to the week. | The source gives some dates to the week only, but `date_precision` says `day`. | Treat Lee County dates as accurate to about one week. Do not use day-level durations such as `days_to_issue` there. |
| Cape Coral, Florida: issued dates in the future. | A small number of permits have an `issued_date` after the date of the data. | Leave out issued dates after `as_of` from [`GET /v1/permits/coverage`](https://docs.mireye.ai/api-reference/permits#coverage). |
| Re-issued permits: durations. | A re-issued permit (`date_flags` holds `"reissued"`) can have a very large `days_to_issue`. It can be more than 30 years, because the issue date is the new one. | Leave out permits with `"reissued"` in `date_flags` when you measure permit speed. |
| Enrich does not say where an office's data ends. | The `parcel_permit_coverage` note names the date the counts start, but not the date they end. A count can miss recent work when an office's data ends early. | Read `dates_covered.to` for the office in [`GET /v1/permits/coverage`](https://docs.mireye.ai/api-reference/permits#coverage). The Search permits filter remark names offices whose data ends early. |

## Status

| Issue | What you see | What to do |
| - | - | - |
| Chicago, Illinois: blank and suspended statuses. | About 219,000 permits with a blank or "SUSPENDED" source status are served with `status_detail` `issued`. | Read `status_original`. A blank value or "SUSPENDED" there means the source did not say the permit was issued. |
| Lee County, Florida: "Closed-Abandoned". | About 2,800 permits with the source status "Closed-Abandoned" have `status` `unknown`. | Read `status_original` to find them. |

## Categories

| Issue | What you see | What to do |
| - | - | - |
| Columbus, Ohio and Collier County, Florida: older history records. | Many history records (before July 1, 2024) have `category` `other`, also for plumbing, electrical, mechanical and alteration work. Permits from July 1, 2024 are not affected. | With `include_history`, filter on `permit_type`, `category_original` or `description` instead of `category` for these offices. |
| Washington, DC and Philadelphia, Pennsylvania: alterations. | Some alteration permits have `category` `other`. | Filter on `category_original` or `description` as well as `category`. |
| Mesa, Arizona: new hotels. | A few new hotel buildings have `category` `commercial_alteration`, not `new_commercial`. | For new commercial buildings in Mesa, also search `commercial_alteration` and read `description`. |

## Work tags

Work tags are assigned by Mireye from each permit's own text. Each tag carries a
measured confidence (`work_tag_confidence`). The issues below are part of that
measured error.

| Issue | What you see | What to do |
| - | - | - |
| Solar tag on battery-only permits. | About 2,700 permits for a battery alone have the `solar` tag. | When you need solar panels only, also check `description` for panel or PV words. |
| Solar tag on remove-and-reinstall work. | A reroof permit that removes and reinstalls existing solar panels has the `solar` tag. We count this as solar work. | When you need new solar installs only, check `description` for "remove", "reinstall" or "R\&R". |
| ADU tag on some other text. | A small number of permits have the `adu` tag when the text names an ADU without building one: a demolition, a reference to another permit, or some duplex text. | Read `description` before you count a permit as a new ADU. |
| A tag on text that says the work is not done. | A small number of permits have a tag such as `solar`, `pool_spa`, `ev_charger` or `demolition`. Yet the text says the work is removed, not included, or done somewhere else. | Read `description` when a single permit matters. |

## Parcel links and counts

| Issue | What you see | What to do |
| - | - | - |
| Medium-confidence parcel links are not measured. | `link_confidence` in Enrich is `null` for links of `medium` confidence. `null` means not measured, not 0. | Use `min_link_confidence: "high"` in the Search permits filter when a wrong link costs more than a missed permit. |
| The same address can give different counts. | A permit can have a map point inside one parcel and an address link to a nearby parcel. A Permits API parcel search by point returns it for the parcel that holds the point. Enrich and the Search permits filter count it only for the parcel it is linked to. | Use a Permits API search by point or polygon to see every permit near an address. |
| New York City: one job on more than one parcel. | A few New York City jobs are linked to two or more parcels. | Compare `permit_number` when you count jobs across parcels. |
| Harris County, Texas: duplicate permits. | About 600 permits appear twice: once from the county appraisal district's records, and again from the county's own permit system. | Compare `permit_number`, `address` and dates when exact counts matter. Each record names its source in `source.citation_url`. |
| The office count differs by surface. | The Search permits filter remark and a Permits API county search can disagree. For the same county, they can give a different number of permit offices. The two surfaces count different sets of offices. | Use [`GET /v1/permits/coverage`](https://docs.mireye.ai/api-reference/permits#coverage) for the full office list. |

## Permit offices

| Issue | What you see | What to do |
| - | - | - |
| Wichita area, Kansas: permits with no office. | About 2,200 permits have no permit office: `office_id` and `office_name` are `null`. A search by office does not find them. | Search by county or by area instead of by office. |
| Office from 2020 city limits. | When a parcel has no linked permits, Enrich can find its office from the parcel's 2020 Census block. The note then says "(by 2020 city limits)". An annexation since 2020 can make it wrong. | Treat the office name as a best guess. |

## Requests and field lists

| Issue | What you see | What to do |
| - | - | - |
| A Search error lists the first bad input only. | A `422 search_invalid_filter` for the permits filter names only the first problem it finds. A request with an unknown key and two unknown tags names only the key. | Fix the named problem and send the request again. Check tag values in [`GET /v1/permits/vocabulary`](https://docs.mireye.ai/api-reference/permits#vocabulary) first. |
| The field lists do not show the permit fields. | The Enrich and Search field lists do not list the `parcel_permit_*` fields or the `permits` filter. Nor does the `mireye_list_fields` MCP tool. Requests with them still work. | Use the names on [Enrich permit fields](https://docs.mireye.ai/api-reference/enrich-permit-fields.md) and [Search permits filter](https://docs.mireye.ai/api-reference/search-permits-filter.md). |

## Behaviour that is not a defect

These are how the data works. They are not errors.

**Re-issued permits**

* An old permit issued again after July 1, 2024 has `date_flags: ["reissued"]`.
* "New since" searches leave it out: `issued_since`, or `date_field: "issued"` with a
  `date_from`.
* Set `include_reissued: true` in the Permits API to keep it.
* The Search permits filter always leaves it out of an issued-since count.

**A source that never records a milestone**

* Some sources never record an issued date, a final date or a final status.
* Their permits cannot match a search on that milestone. The `note` or the remark
  says so.
* For those offices a `0` does not mean none happened.

**Permits not tied to a parcel**

* A permit that could not be tied to a parcel does not count per parcel.
* In Enrich, `partial` can mean many permits are not tied to parcels. Read the
  coverage note.
