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

# Search permits filter

> Find parcels in one county by the building permits tied to them, in POST /v1/search.

The `permits` filter finds parcels by the building permits tied to them. Use it in
[`POST /v1/search`](https://docs.mireye.ai/api-reference/search) or the `mireye_search` MCP tool, next to
your other filters.

> [!NOTE]
>
> * A Search with a permits filter costs the normal Search query price: **\$0.20** on
>   Free. See [Pricing](https://docs.mireye.ai/pricing.md).
> * It searches one county at a time.
> * It counts only permits tied to a parcel. Read the coverage remark on every page.

## Example: parcels with a solar permit issued since 2025

```bash theme={null}
curl -sS --max-time 630 https://api.mireye.com/v1/search \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "filters": [
      {"field": "state2", "op": "eq", "value": "TX"},
      {"field": "geoid", "op": "eq", "value": "48157"},
      {"field": "permits", "op": "match", "value": {
        "date_field": "issued",
        "since": "2025-01-01",
        "work_tags": ["solar"]
      }}
    ],
    "fields": ["owner"],
    "limit": 1,
    "max_cost_usd": "0.20"
  }' | jq
```

```json theme={null}
{
  "matches": [
    {
      "parcelnumb": "0001-00-000-0000-907",
      "address": "1234 EXAMPLE DR, EXAMPLE, TX 77479",
      "state2": "TX",
      "county": "Fort Bend",
      "scity": "Example",
      "szip5": "77479",
      "source": "PARCEL_VENDOR",
      "pvd_gisacre": 0.21,
      "analysis_point": {"lat": 29.5901, "lng": -95.6402, "method": "parcel_stored_lat_lon"},
      "fields": {
        "owner": "EXAMPLE HOMEOWNER",
        "permits_matched": 1,
        "permits_date_field": "issued",
        "permits_latest_date": "2025-03-11",
        "permits_latest_date_precision": "day",
        "permits_link_confidence": "high",
        "permits_work_tag_confidence": 0.97,
        "permits_work_tag_confidence_scope": "global",
        "permits_as_of": "2026-11-17"
      }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjoi...",
  "remarks": [
    {
      "code": "candidates_not_checked",
      "message": "Matches come only from permits linked to a parcel, dated from 2025-01-01. candidates counts permit records, not parcels: 214 permit records in this county were not counted for this filter: 190 not placed on a parcel (not linked to a parcel); 9 excluded by link confidence (linked below the confidence floor); 15 excluded by date precision (unknown precision or a month or year date that only partly overlaps the window). Undated permits (3) are not counted. Older history records (before 2024-07-01) are not searched. 15 of 21 permit offices in this county are not fully collected.",
      "path": "filters[2]",
      "hint": "This reflects which permits the permit data could tie to a parcel; running the same search again returns the same coverage until the permit data is refreshed.",
      "candidates": 214
    }
  ],
  "request_id": "req_7f3a9c2e41b84d0f",
  "billing": {
    "operation_id": "op_4b1d…",
    "currency": "USD",
    "charged_usd": "0.200000",
    "pricing_version": "earth-usd-v1",
    "replayed": false
  }
}
```

Values are illustrative.

Over hosted MCP, send the same body inside `req` of `mireye_search`:

```json theme={null}
{
  "req": {
    "filters": [
      {"field": "state2", "op": "eq", "value": "TX"},
      {"field": "geoid", "op": "eq", "value": "48157"},
      {"field": "permits", "op": "match", "value": {"date_field": "issued", "since": "2025-01-01", "work_tags": ["solar"]}}
    ],
    "limit": 5,
    "max_cost_usd": "0.20"
  },
  "idempotency_key": "tx-48157-solar-parcels-0001"
}
```

## Filter shape

The filter is one entry in `filters`:

```json theme={null}
{"field": "permits", "op": "match", "value": {"date_field": "issued", "since": "2025-01-01"}}
```

Rules:

* `field` is `permits` and `op` is `match`. `value` is an object.
* A Search takes **one** permits filter.
* The Search needs exactly one `state2` filter, as every Search does.
* It also needs **exactly one county filter with `eq`**:
  * `geoid` with a five-digit county FIPS, such as `"48157"`; or
  * `county` with a five-digit FIPS or a county name in the `state2` state.
* The county must be in the `state2` state. A FIPS from another state is rejected:
  "County 06037 is not in TX: a permits filter needs a county in the state2 state."
* Every other Search filter still applies. All filters are AND.

### value keys

| Key | Type | Required | Default | Meaning |
| - | - | - | - | - |
| `date_field` | string | yes | | `filed`, `issued`, `finaled` or `earliest`. The permit date that `since` and `until` apply to. |
| `since` | date | no | | The date is on or after this. `YYYY-MM-DD`. |
| `until` | date | no | | The date is on or before this. Not before `since`. |
| `work_tags` | list | no | | Work tags, such as `solar` or `roof`. A parent tag also matches its child tags. At most 20. |
| `tags_match` | string | no | `any` | `any`: a permit needs one of the tags. `all`: it needs every tag. |
| `category` | list | no | | Permit categories. At most 20. |
| `status` | list | no | | `in_review`, `active`, `final`, `inactive` or `unknown`. At most 20. |
| `min_count` | integer | no | `1` | A parcel matches when at least this many permits count. 1 to 100. |
| `min_link_confidence` | string | no | `medium` | `high` or `medium`. The weakest permit-to-parcel link that counts. |

* Tag, category and status values are the [Permits API vocabulary](https://docs.mireye.ai/api-reference/permits.md#vocabulary).
* An unknown value is rejected with the nearest valid values, for example
  "Did you mean pool\_spa? Valid work tag values: …".
* Any other key is rejected. `null` means the key is left out.
* There is no `include_undated`, `include_history` or `include_reissued` here. See
  [What counts](#what-counts).

## What counts

A permit counts for a parcel when all of these are true:

* It is tied to that parcel at or above `min_link_confidence`.
* It matches `work_tags`, `category` and `status`.
* It has the `date_field` date. With `earliest`, that is the earliest of the filed,
  issued and finaled dates.
* That date lies wholly inside `since` to `until`. A `month` date covers its whole
  month and a `year` date its whole year. A date that only partly overlaps the range,
  or whose precision is not known, does not count.
* It has a date. Undated permits never count.
* It is not an older history record. A history record was issued before July 1, 2024,
  or, with no issued date, filed before that date. History records are not searched.
* A permit issued on or after July 1, 2024 can have a filed date before July 1, 2024.
  Then its `earliest` date is before that date too. With no `since`, or a `since`
  before that date, such a permit counts.
* With `date_field: "issued"` and a `since`, it is not a re-issued permit. A re-issued
  permit was issued on or after July 1, 2024. But it was filed more than 5 years
  before, or finaled more than 1 year before. It is old work issued again.

**The count unit is unique permits.**

* A permit reported by two sources counts once.
* A job filed as several linked records counts once.
* A parcel matches when its count is at least `min_count`.
* Only permits tied to a parcel can count. A permit we hold but could not tie to a
  parcel is reported in the remark, not counted.

## Output fields

Each match gets these values in its `fields` map. They are in the query price and you
do not need to name them.

| Field | Meaning |
| - | - |
| `permits_matched` | The unique permits that count for this parcel. |
| `permits_date_field` | The `date_field` you sent. |
| `permits_latest_date` | The latest `date_field` date among those permits. |
| `permits_latest_date_precision` | `day`, `month` or `year`. A month or year date is the 1st of the month or January 1. |
| `permits_link_confidence` | The weakest parcel link among those permits: `high` or `medium`. |
| `permits_work_tag_confidence` | The lowest measured confidence of the tags you asked for, from 0 to 1. `null` when not measured or when you sent no `work_tags`. |
| `permits_work_tag_confidence_scope` | `source`: measured on these permits' own source, used only when lower. `global`: measured on all sources together. `null` when `permits_work_tag_confidence` is `null`. |
| `permits_as_of` | The date the permit data was built. It is not the date the permits reach: see [The coverage remark](#the-coverage-remark). |

* You can also name any [Enrich permit field](https://docs.mireye.ai/api-reference/enrich-permit-fields.md) in
  `fields`, such as `parcel_permit_count`.
* Enrich permit fields are output fields only: you cannot filter on them.

## The coverage remark

A page with a permits filter usually carries one remark about it:

| Key | Value |
| - | - |
| `code` | `candidates_not_checked` |
| `path` | `filters[i]`, the permits filter |
| `candidates` | Permits in the county that this filter could not count. Absent when 0. |
| `message` | What was not counted, and why. |
| `hint` | The same search returns the same coverage until the permit data is refreshed. |

* `candidates` counts **permits, not parcels**. It is the sum of the reasons in the
  message.
* The message calls every count "permit records", but the units differ:
  * "not placed on a parcel" counts records. A job filed as several linked records
    counts once per record.
  * Every other count in the message counts unique permits, the unit of
    `permits_matched`: a linked job or a merged permit counts once.
* A parcel with 0 permits here may still have had work. Read the message before you
  say a parcel had none.
* The remark never changes the price.
* Counts of 1 are singular: "1 permit record comes from a source that never records
  an issued date (…)".
* `permits_as_of` is the date the permit data was built. It is not the date the
  permits reach. The remark names each office whose collected permits end before it.

The message can hold these sentences (numbers are examples):

| Sentence | Meaning |
| - | - |
| "Matches come only from permits linked to a parcel, dated from 2025-01-01." | Always present. The date is your `since`, or the county's first collected date when that is later. With no `since` and no later county date it reads "dated over the whole collected period". With an `until` it ends " to 2025-12-31". |
| "candidates counts permit records, not parcels: 214 permit records in this county were not counted for this filter: …" | Split by reason. Each reason is one of: not placed on a parcel; below the link confidence floor; date precision does not fit the range. |
| "Undated permits (3) are not counted. Older history records (before 2024-07-01) are not searched." | Undated permits and older records never count. On older permit data the sentence is "Undated permits (3) and older history records (12) are not counted." |
| "1,204 permit records come from sources that never record an issued date (…); this filter cannot count them, so a parcel with 0 here may still have had one." | A source that does not record your `date_field`. Up to 10 sources are named. |
| "88 permit records come from sources that record no final status (…); this filter cannot count them as final, so a parcel with 0 here may still have finished work." | A `final` status filter and a source that does not record it. |
| "A source can lack both, so the two counts can include the same records." | Both sentences above appear. |
| "38 re-issued permit records (issued in range, filed more than 5 years or finaled more than 1 year before) are not counted." | See [What counts](#what-counts). |
| "Collected permits in this county start on 2024-07-01." | The county's first collected permit date. It appears only when you sent no `since`, or a `since` before this date. The collected permits may not reach back to your `since`. |
| "permits\_as\_of (2026-11-17) is the date the permit data was built, not the date it reaches. The latest collected permit of each office in this county that ends before that date: City of Example 2025-09-17; City of Other 2026-10-31. Later permits from these offices are not collected yet." | Some offices' collected permits end before `permits_as_of`. Their later work cannot count. Up to 10 offices are named, oldest end first. More are counted: "; 3 more offices from 2026-11-01 to 2026-11-10" (or "on 2026-11-10" when the dates are the same). The list includes an office from another county when it has permits tied to parcels in this county. |
| "15 of 21 permit offices in this county are not fully collected." | Some offices are partly or not collected. See [Permits coverage](https://docs.mireye.ai/api-reference/permits-coverage.md). |
| "City of Example's permits are not collected: …" | You filtered `scity` to a city whose own permit office is not collected, or only partly. A wider search does not add that office's permits. |

**Branch on `code` and `path` only.** The message is written for people and can change.

## Errors

| HTTP | Code | Meaning | What to do |
| - | - | - | - |
| 422 | `search_invalid_filter` | The permits filter is not valid. See the causes below the table. `issues[0].path` names the key, such as `filters[2].value.date_field`. | Fix the request. |
| 422 | `search_invalid_filter` | "There are no permit links for this county in the current permit data." `issues[0].path` names the county filter. | Search another county. Permit links cover only the counties we collect. |
| 422 | `search_query_too_broad` | "This county has more linked permits than a permits filter can search." | A narrower permits filter does not help in this county. Search another county, or search without the permits filter. |
| 422 | `search_query_too_broad` | "This permits filter matches too many parcels to search within the time limit." | Narrow it: a later `since`, more specific `work_tags`, or a higher `min_count`. |
| 422 | `search_invalid_request` | The cursor no longer fits, because the permit data was refreshed. | Start again without a cursor. |
| 503 | `search_unavailable` | Permit search is at capacity (`retryable: true`, `Retry-After: 2`), or permit data could not be read (`retryable: false`). Not charged. No no-match conclusion was made. | Retry. If `retryable` is `false`, retry with a new idempotency key. |

Causes of an invalid permits filter:

* a second permits filter;
* a missing or second county filter;
* a county value that is not a five-digit FIPS or a county name;
* a county outside `state2`;
* a `value` that is not an object;
* a missing `date_field`;
* an unknown key or value.

Search also returns its usual errors. See [Search errors](https://docs.mireye.ai/api-reference/search.md#errors).

## Related pages

* [Permits API](https://docs.mireye.ai/api-reference/permits.md): the permit records themselves.
* [Enrich permit fields](https://docs.mireye.ai/api-reference/enrich-permit-fields.md): counts for one parcel.
* [Permits coverage](https://docs.mireye.ai/api-reference/permits-coverage.md).
* [Permits known issues](https://docs.mireye.ai/api-reference/permits-known-issues.md).
