Skip to main content
The Permits API returns US building permit records from public permit offices. Every answer says how complete the data behind it is.
  • 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.search scope, the same scope as Search. See Authentication.
  • Coverage and vocabulary need no API key.
Related pages:

How to read an answer

Every search answer has two keys about completeness (an id lookup has them per permit):
  • coverage is one word: complete, partial or not_collected. It is null when no permit office is known for the area.
  • note is plain text, or null. It says what a count may miss. It can hold several sentences.
Rules:
  • With partial, not_collected or null coverage, a count is a lower bound. A 0 is 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. The note names the missing date or status.
  • Branch on coverage and total. The note text 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-Id and X-Mireye-Data-Version. See Headers.

Example: the same search over hosted MCP

The tool is mireye_permits_search. Send the request body inside req:
The tool returns the same body as REST: 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" and NaN are rejected.
  • Text values are trimmed.

where

Send exactly one of these shapes: Limits:
  • state is a two-letter code. The 50 states and DC are accepted.
  • city is 1 to 120 characters. Case is ignored.
  • zip is 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 never complete.
  • lat is -90 to 90 and lng is -180 to 180.
  • radius_m is 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 note counts 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 the parcel.parcel_id of a permit record.
A parcel search returns the permits tied to the parcel, with or without a map point. With an address or a point, it also returns permits whose map point is inside the parcel. The “no map location” sentence in the 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 note says why, and the call is free. With several parcels, send a parcel_id.
  • The same is true for an address that selects no single parcel.
  • If a parcel_id search finds no permits, the call is free. The note says 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) and parcel. parcel holds status (matched, ambiguous or no_match), parcel_id, match_type, address, candidates (a count) and reason.
  • When the address selects no single parcel, the answer has no permits. The note says 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 note says 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, category and work_tags, where [] means no filter.
  • An unknown status, category, use_class or work_tags value is rejected. The error names the nearest valid values, such as Did you mean pool_spa?.
  • detail_tags values are not checked against the vocabulary. An unknown detail tag is accepted and matches no permit. Check the values in GET /v1/permits/vocabulary first.
  • status filters on the record’s status. The source’s finer status is in status_detail.
  • A valuation range leaves out permits whose source gives no valuation. The note counts them.

Dates

A permit can have three dates: filed_date, issued_date and finaled_date.
  • earliest_date is the earliest of the three. When a permit has none of them, it is the date we first saw the permit. Then undated is true.
  • latest_date is the latest of the three.
  • date_field names the date the bounds apply to:
    • filed, issued and finaled return only permits that have that date, with or without bounds. Exception: with include_undated: true, permits with no date are returned too.
    • earliest (the default) applies the bounds to earliest_date.
  • Undated permits are left out unless include_undated is true. The note says how many were left out.
  • Dates match as stored. date_precision says 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 note says so: for those offices a 0 does 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. An earliest search with no date bounds returns it.
  • include_history: true also 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 note says 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.
How the API treats it:
  • Its date_flags holds "reissued".
  • issued_since, and date_field: "issued" with a date_from, leave it out. The note says how many were left out.
  • Set include_reissued: true to keep it in those searches.
  • Every other search returns it. earliest and filed searches 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

  • total counts 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 total for a parcel can be higher than permits_matched or parcel_permit_count.
  • coverage describes the offices of the whole search, on every page. A milestone that a source never records keeps it below complete on every page too.

Count for free

Send limit: 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_usd must cover that hold.
The answer has:
  • total, coverage and note;
  • an empty permits list;
  • next_cursor: null.
  • A count takes no cursor. limit: 0 with a cursor is rejected with 422.
  • Count first, then pay for pages only when the count is worth it.

Paging

  • next_cursor is null on the last page.
  • Send it as cursor with the same where, filters and sort. limit and max_cost_usd may 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-Version to see the data version.
  • Each page is a new paid call with its own Idempotency-Key.

note sentences

The note 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

Send where.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.
Values are illustrative. Request rules:
  • parcels holds 1 to 100 entries. filters and sort apply to every parcel.
  • limit_per_parcel is the most permits per parcel, 0 to 100. The default is 25. 0 counts each parcel’s permits without returning them, for free.
  • A batch takes no limit and no cursor. Each is rejected with 422.
Each entry of parcels in the answer, in the order you sent: summary counts the entries:
  • inputs
  • matched
  • with_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, ambiguous and refused.
  • unavailable
  • time_limit_reached
Price and failures:
  • 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_unavailable and retryable: true. Send it again with the same Idempotency-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

Values are illustrative.

Example over hosted MCP

The tool is mireye_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 in missing, and it is not charged.
  • A malformed id, no id, or more than 50 ids is rejected with 422 permits_invalid_request before any charge. problems names the bad id entry.

Permit record

  • Every key except distance_m is always present.
  • A missing value is null.
  • In an id lookup, each permit also has coverage and note.
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

There is no MCP tool for coverage. Agents can call this HTTPS endpoint directly: it needs no key.

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

There is no MCP tool for the vocabulary. Agents can call this HTTPS endpoint directly.

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_usd at or above it. See Pricing.
These are free:
  • 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_id search 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/coverage and GET /v1/permits/vocabulary.

Retries

  • Send a stable Idempotency-Key header 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 return detail.error, detail.message and, for most, detail.retryable:
Two kinds of failure:
  • Before the paid call starts. permits_busy, and permits_unavailable or parcel_unavailable with retryable: true. The response has Retry-After (permits_unavailable: 30 seconds, parcel_unavailable: 5 seconds). Wait, then send the same request with the same Idempotency-Key.
  • After the paid call starts. permits_timeout, and permits_unavailable or parcel_unavailable with retryable: false. Nothing is charged, but the Idempotency-Key is finished: the same key returns the same failure. The response has no Retry-After. To try again, send the request with a new Idempotency-Key.
Branch on 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_missing
  • 403 terms_required
  • 402 max_cost_too_low
  • 402 insufficient_balance
  • 409 idempotency_conflict
  • 429 rate_limited
Do not retry an unchanged 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 attribution text wherever you show its permits.
  • Work tags and parcel links are made by Mireye. They can be wrong. Read work_tag_confidence and parcel.confidence.