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
req of mireye_search:
Filter shape
The filter is one entry infilters:
fieldispermitsandopismatch.valueis an object.- A Search takes one permits filter.
- The Search needs exactly one
state2filter, as every Search does. - It also needs exactly one county filter with
eq:geoidwith a five-digit county FIPS, such as"48157"; orcountywith a five-digit FIPS or a county name in thestate2state.
- The county must be in the
state2state. 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.
nullmeans the key is left out. - There is no
include_undated,include_historyorinclude_reissuedhere. 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,categoryandstatus. - It has the
date_fielddate. Withearliest, that is the earliest of the filed, issued and finaled dates. - That date lies wholly inside
sincetountil. Amonthdate covers its whole month and ayeardate 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
earliestdate is before that date too. With nosince, or asincebefore that date, such a permit counts. - With
date_field: "issued"and asince, 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.
- 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 itsfields 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 asparcel_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:candidatescounts 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_ofis 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.
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
valuethat is not an object; - a missing
date_field; - an unknown key or value.
Related pages
- Permits API: the permit records themselves.
- Enrich permit fields: counts for one parcel.
- Permits coverage.
- Permits known issues.