Skip to main content
The permits filter finds parcels by the building permits tied to them. Use it in POST /v1/search or the mireye_search MCP tool, next to your other filters.
  • A Search with a permits filter costs the normal Search query price: $0.20 on Free. See Pricing.
  • 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

Values are illustrative. Over hosted MCP, send the same body inside req of mireye_search:

Filter shape

The filter is one entry in filters:
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

  • Tag, category and status values are the Permits API 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

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.
  • You can also name any Enrich permit field 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:
  • 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): Branch on code and path only. The message is written for people and can change.

Errors

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.