- Each permit returned costs $0.012 on Free, $0.0086 on Build and $0.0072 on Growth.
- A parcel search page costs $0.036 on Free when it returns permits. One page holds up to 100 of the parcel’s permits.
- Counts and empty answers are free. See Price and Pricing.
- Search and lookup need accepted terms and licensed access with the
earth.searchscope, the same scope as Search. See Authentication. - Coverage and vocabulary need no API key.
- Permits stats: counts grouped by month, tag, category or office.
- Permits parcels: one row per parcel with permits.
- Permits coverage: what
complete,partialandnot_collectedmean, and a coverage label for each state. - Permits known issues: what can be wrong in the data today, and how to work around it.
- Search permits filter: find parcels by
their permits in
POST /v1/search. - Enrich permit fields: permit counts for one
parcel in
POST /v1/enrich.
How to read an answer
Every search answer has two keys about completeness (an id lookup has them per permit):coverageis one word:complete,partialornot_collected. It isnullwhen no permit office is known for the area.noteis plain text, ornull. It says what a count may miss. It can hold several sentences.
- With
partial,not_collectedornullcoverage, a count is a lower bound. A0is then not proof that no permits exist. - A search by point, polygon, parcel or ZIP is never
complete. It can see only the offices that have permits in the area. An office we do not collect can also serve the area. - A source in the search may never record the date or status you filter on. Then
coverage is never
complete, on every page of the search. Thenotenames the missing date or status. - Branch on
coverageandtotal. Thenotetext is written for people and can change.
Search permits
POST /v1/permits/search
Example: solar permits in one county
- Values are illustrative.
- Response headers include
X-Operation-IdandX-Mireye-Data-Version. See Headers.
Example: the same search over hosted MCP
The tool ismireye_permits_search. Send the request body inside req:
permits, total, next_cursor, coverage,
note and billing.
Request shape
- Any other key, at any level, is rejected with
422. - Numbers must be JSON numbers.
true,"5"andNaNare rejected. - Text values are trimmed.
where
Send exactly one of these shapes:
Limits:
stateis a two-letter code. The 50 states and DC are accepted.cityis 1 to 120 characters. Case is ignored.zipis exactly five digits. A ZIP+4 is rejected. A ZIP search matches the permit’s address, not its map point. So it also finds permits with no map point. Like a point search, it is nevercomplete.latis -90 to 90 andlngis -180 to 180.radius_mis above 0 and at most 50,000.- A polygon has at most 2,000 positions and fits in a 1 degree by 1 degree box.
Its rings are closed: the last position equals the first. Positions are
[lng, lat]in WGS84. An empty, zero-area or self-crossing polygon is rejected. - A point or polygon search matches only permits that have a map point. The
notecounts the permits it could not place. - A parcel search also matches the permits tied to the parcel that have no map point. See Parcel selector.
Parcel selector
parcel takes one of:
{"address": "…"}: a street address, such as"1234 Example Dr, Example, TX 77479". It is resolved the same way as in Enrich. See Parcel by address.{"lat": …, "lng": …}: the parcel that contains this point.{"parcel_id": "…"}: the parcel’s id, a lowercase UUID such as"11111111-2222-3333-4444-555555555555". It is theparcel.parcel_idof a permit record.
note can also appear on a parcel search. It
counts the permits without a map point in the offices that have permits here. Some of
them can still match through their parcel link.
- If no parcel contains the point, or more than one does, the answer is empty. The
notesays why, and the call is free. With several parcels, send aparcel_id. - The same is true for an address that selects no single parcel.
- If a
parcel_idsearch finds no permits, the call is free. Thenotesays why:- When the parcel has linked permits that your filters left out: “Permits in this data are linked to this parcel_id, but none match the filters. This search is not charged.”
- Otherwise: the id may be wrong, or the parcel may have no linked permits.
Parcel by address
An address goes through the same steps as an Enrich address: a geocode, the rooftop rule, the parcel match and the unit tie-break.- The answer has two more keys:
geocode(how the address was geocoded) andparcel.parcelholdsstatus(matched,ambiguousorno_match),parcel_id,match_type,address,candidates(a count) andreason. - When the address selects no single parcel, the answer has no permits. The
notesays why, and the call is free. For example: “More than one parcel matches this address; send a parcel_id.” - In some buildings, the units share one parcel outline. When the address names one
such unit, only the permits linked to that unit are returned. The
notesays so. - An address the geocoder cannot use returns the same errors as an Enrich address. See Enrich.
filters
- Dates are
YYYY-MM-DD. - Lists take 1 to 20 values. An empty list is rejected, except
status,categoryandwork_tags, where[]means no filter. - An unknown
status,category,use_classorwork_tagsvalue is rejected. The error names the nearest valid values, such asDid you mean pool_spa?. detail_tagsvalues are not checked against the vocabulary. An unknown detail tag is accepted and matches no permit. Check the values inGET /v1/permits/vocabularyfirst.statusfilters on the record’sstatus. The source’s finer status is instatus_detail.- A valuation range leaves out permits whose source gives no valuation. The
notecounts them.
Dates
A permit can have three dates:filed_date, issued_date and finaled_date.
earliest_dateis the earliest of the three. When a permit has none of them, it is the date we first saw the permit. Thenundatedistrue.latest_dateis the latest of the three.date_fieldnames the date the bounds apply to:filed,issuedandfinaledreturn only permits that have that date, with or without bounds. Exception: withinclude_undated: true, permits with no date are returned too.earliest(the default) applies the bounds toearliest_date.
- Undated permits are left out unless
include_undatedistrue. Thenotesays how many were left out. - Dates match as stored.
date_precisionsays how exact they are:day: an exact date.month: the source gives the month only. The date is the 1st of that month.year: the source gives the year only. The date is January 1 of that year.null: not known.
- A search on a milestone that a source never records cannot match that source’s
permits. The
notesays so: for those offices a0does not mean none happened.
History
By default the API returns the permits 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, and so an
earliest_date, before July 1, 2024. Anearliestsearch with no date bounds returns it. include_history: truealso returns older records where we have them.- A history record has the same fields. It was issued before July 1, 2024, or, with no issued date, filed before that date.
- When the data holds no history records, the
notesays the filter has no data yet.
Re-issued permits
A re-issued permit is an old permit issued again. It is not new work. It is issued on or after July 1, 2024, and either:- it was filed more than 5 years before that issue date, or
- it was finaled more than 1 year before that issue date.
- Its
date_flagsholds"reissued". issued_since, anddate_field: "issued"with adate_from, leave it out. Thenotesays how many were left out.- Set
include_reissued: trueto keep it in those searches. - Every other search returns it.
earliestandfiledsearches use its old dates.
sort
- Permits with no value for the sort key come last in either direction.
- Ties are ordered by
permit_id.
Response
totalcounts permit records, not unique permits. Some jobs are filed as several linked records. An example is a New York City job and its work permits. Here each record counts once. Undated and history records reported by two sources can also count twice. Dated permits from July 1, 2024 are already merged across sources, with the exceptions in known issues.- The Search permits filter and the Enrich permit fields count unique permits: each
linked job and each merged permit counts once. So
totalfor a parcel can be higher thanpermits_matchedorparcel_permit_count. coveragedescribes the offices of the whole search, on every page. A milestone that a source never records keeps it belowcompleteon every page too.
Count for free
Sendlimit: 0 to count without permits. It is not charged.
- While it runs, one permit row ($0.012 on Free) is held and then released.
- Your balance and
max_cost_usdmust cover that hold.
total,coverageandnote;- an empty
permitslist; next_cursor: null.
- A count takes no
cursor.limit: 0with acursoris rejected with422. - Count first, then pay for pages only when the count is worth it.
Paging
next_cursorisnullon the last page.- Send it as
cursorwith the samewhere,filtersandsort.limitandmax_cost_usdmay change. - A cursor expires after one hour.
- A cursor also expires when the permit data is refreshed. Start again without a
cursor. Check
X-Mireye-Data-Versionto see the data version. - Each page is a new paid call with its own
Idempotency-Key.
note sentences
Thenote joins these sentences. The numbers below are examples.
When a count is not known, the sentence starts with “Some”. A count of 1 is
singular: “1 permit has no date and was left out; set include_undated to get them.”
Batch of parcels
Sendwhere.parcels to read the permits of up to 100 parcels in one call. Each entry
is a parcel selector: {"address": …}, {"lat": …, "lng": …} or
{"parcel_id": …}. Each one is answered exactly as its own single parcel search.
parcelsholds 1 to 100 entries.filtersandsortapply to every parcel.limit_per_parcelis the most permits per parcel, 0 to 100. The default is 25.0counts each parcel’s permits without returning them, for free.- A batch takes no
limitand nocursor. Each is rejected with422.
parcels in the answer, in the order you sent:
summary counts the entries:
inputsmatchedwith_permits: parcels with at least one permit that matches the filters. It is filled in a count (limit_per_parcel: 0) too.not_matched:no_match,ambiguousandrefused.unavailabletime_limit_reached
- A batch costs one permit property ($0.036 on Free) for each distinct parcel that returns a permit. The same parcel sent twice is charged once.
- A parcel with no permits, an entry that is not matched and a count
(
limit_per_parcel: 0) cost nothing. - When parcel matching is down for every entry, the whole call fails with
503 parcel_unavailableandretryable: true. Send it again with the sameIdempotency-Key.
Look up permits by id
GET /v1/permits?id=… returns 1 to 50 permits by their permit_id, such as
pmt_tx_0a1b2c3d4e5f60718293a4b5. Repeat id for each permit.
Example
Example over hosted MCP
The tool ismireye_permits_get. Its arguments are top level, not inside req:
Request and response
The two extra keys on each found permit:
- A lookup costs one permit row ($0.012 on Free) for each permit found.
- When no id is found, the answer is
permits: []with every id inmissing, and it is not charged. - A malformed id, no id, or more than 50 ids is rejected with
422 permits_invalid_requestbefore any charge.problemsnames the badidentry.
Permit record
- Every key except
distance_mis always present. - A missing value is
null. - In an id lookup, each permit also has
coverageandnote.
location_method values:
source: the source gives it.parcel: the linked parcel.address: an address match to a parcel.census: a public address geocoder.
parcel.join says how the permit was tied to the parcel:
parcel_id: the permit names the parcel’s number.point_in_parcel: the permit’s map point is inside the parcel.address: the permit’s address matches the parcel’s.
parcel.confidence is high or medium.
date_flags values:
Coverage
GET /v1/permits/coverage lists which permit offices in one state are collected. Public: no API key, no charge.
Example
Query parameters
Response
Each office:
See Permits coverage and
Permits known issues.
Vocabulary
GET /v1/permits/vocabulary lists the values the search filters accept, and the measured confidence of each tag. Public:
no API key, no charge.
Example
Response
Headers
Price
You pay for what a call returns:- A parcel search page (by address, point or
parcel_id) is one property, up to 100 permits. Each further page of the same parcel is one more property. - The most a call can return is reserved first. Set
max_cost_usdat or above it. See Pricing.
- a count (
limit: 0); - a page with no permits;
- a batch of parcels in which no parcel returns a permit;
- a parcel address or point that selects no single parcel;
- a
parcel_idsearch that finds no permits; - an id lookup that finds no permit;
- an unknown
authority_id(404 office_not_found); - a call that fails;
GET /v1/permits/coverageandGET /v1/permits/vocabulary.
Retries
- Send a stable
Idempotency-Keyheader for each search page and each lookup. - The key is 8 to 128 characters: letters, digits,
_,.,:or-. - The same key with the same request returns the saved answer and its receipt. There is no second charge.
- Reusing a key for a changed request returns
409 idempotency_conflict. - A paid call that fails after it starts finishes its key. The same key then returns the same failure. Send a new key. See Errors.
- Hosted MCP takes the same value as
idempotency_key.
Errors
Errors returndetail.error, detail.message and, for most, detail.retryable:
Two kinds of failure:
- Before the paid call starts.
permits_busy, andpermits_unavailableorparcel_unavailablewithretryable: true. The response hasRetry-After(permits_unavailable: 30 seconds,parcel_unavailable: 5 seconds). Wait, then send the same request with the sameIdempotency-Key. - After the paid call starts.
permits_timeout, andpermits_unavailableorparcel_unavailablewithretryable: false. Nothing is charged, but theIdempotency-Keyis finished: the same key returns the same failure. The response has noRetry-After. To try again, send the request with a newIdempotency-Key.
retryable, not on the code alone.
Search and lookup also return the shared account, billing and rate-limit errors. See
Errors. For example:
401 auth_missing403 terms_required402 max_cost_too_low402 insufficient_balance409 idempotency_conflict429 rate_limited
422.
Data and terms
- Permits come from public records published by permit offices.
- Some sources are held back until their terms let us serve them. Their permits are not in any answer or count.
- Show a source’s
attributiontext wherever you show its permits. - Work tags and parcel links are made by Mireye. They can be wrong. Read
work_tag_confidenceandparcel.confidence.