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

# Permits stats

> Count US building permits in one area, grouped by month, work tag, category or permit office, with valuation and time-to-issue measures.

`POST /v1/permits/stats` counts permits and groups them. It counts the permits that a
[Permits API](https://docs.mireye.ai/api-reference/permits.md) search of the same area and filters would match.
Use it to see trends without paging through every permit.

> [!NOTE]
>
> * Each group returned costs one permit row: **\$0.012** on Free, **\$0.0086** on
>   Build and **\$0.0072** on Growth. See
>   [Pricing](https://docs.mireye.ai/pricing.md).
> * A call that returns no group is free. That includes a count (`limit: 0`), an area
>   with no matching permits, and a parcel address or point that selects no single
>   parcel.
> * It needs accepted terms and licensed access with the `earth.search` scope, the same
>   as a permits search. See [Authentication](https://docs.mireye.ai/authentication.md).

## Example: solar permits per month in one county

```bash theme={null}
curl -sS --max-time 60 https://api.mireye.com/v1/permits/stats \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "where": {"state": "TX", "county_fips": "48157"},
    "filters": {"date_field": "issued", "date_from": "2025-01-01", "work_tags": ["solar"]},
    "group_by": "month",
    "measures": ["permits", "valuation_usd_median"],
    "limit": 2,
    "max_cost_usd": "0.20"
  }' | jq
```

```json theme={null}
{
  "groups": [
    {"key": "2025-01", "permits": 31, "valuation_usd_median": 24500},
    {"key": "2025-02", "permits": 27, "valuation_usd_median": 23800}
  ],
  "total_groups": 22,
  "truncated": true,
  "total_permits": 412,
  "coverage": "partial",
  "note": "Of the 21 permit offices here, 6 are complete, 3 are partly collected and 12 are not collected, so counts are a lower bound.",
  "billing": {
    "operation_id": "op_4b1d…",
    "currency": "USD",
    "charged_usd": "0.024000",
    "pricing_version": "earth-usd-v1",
    "replayed": false
  }
}
```

Values are illustrative.

Over hosted MCP, the tool is `mireye_permits_stats`. Send the same body inside `req`:

```json theme={null}
{
  "req": {
    "where": {"state": "TX", "county_fips": "48157"},
    "filters": {"date_field": "issued", "date_from": "2025-01-01", "work_tags": ["solar"]},
    "group_by": "month",
    "limit": 2,
    "max_cost_usd": "0.20"
  },
  "idempotency_key": "tx-48157-solar-months-0001"
}
```

## Request

| Field | Type | Required | Default | Notes |
| - | - | - | - | - |
| `where` | object | yes | | One area, with the same shapes as a permits search. It can be an office, a city, a county or a state. It can also be a ZIP code, a point and radius, a polygon or a parcel. See [where](https://docs.mireye.ai/api-reference/permits.md#where). |
| `filters` | object | no | `{}` | The same filters as a permits search. See [filters](https://docs.mireye.ai/api-reference/permits.md#filters). |
| `group_by` | string | yes | | `month`, `tag`, `category` or `office`. See [Groups](#groups). |
| `measures` | list | no | `["permits"]` | Any of `permits`, `valuation_usd_total`, `valuation_usd_median` and `median_days_to_issue`. See [Measures](#measures). |
| `limit` | integer | no | `100` | The most groups to return, 0 to 500. `0` is a free count; it holds one row while it runs. |
| `max_cost_usd` | decimal string | no | | Spending ceiling for this call, such as `"0.20"`. |

* Any other key is rejected with `422`. There is no `sort` and no `cursor`.
* An unknown `group_by` or measure is rejected with the valid values.

## Groups

| `group_by` | `key` | Order |
| - | - | - |
| `month` | The month of the `filters.date_field` date, as `YYYY-MM`. With `include_undated: true`, permits with no date are in a group with key `null`. | Oldest month first. |
| `tag` | A work tag, such as `solar`. Permits with no tag are in a group with key `null`. | Most permits first. |
| `category` | A permit category, such as `electrical`. | Most permits first. |
| `office` | The permit office id. The group also has `name`, the office name. | Most permits first. |

* With `tag`, a permit with two tags counts in both groups. So the tag groups can add
  up to more than `total_permits`. The `note` says so.
* Groups with the same count are ordered by `key`.

## Measures

| Measure | Value |
| - | - |
| `permits` | The number of permits in the group. |
| `valuation_usd_total` | The sum of the declared valuations in the group, in US dollars. Permits with no valuation are left out of the sum. |
| `valuation_usd_median` | The median declared valuation, in US dollars, of the permits that have one. |
| `median_days_to_issue` | The median of `days_to_issue` (days from filed to issued) of the permits that have it. |

A measure is `null` when no permit in the group has a value for it.

## Response

| Key | Type | Meaning |
| - | - | - |
| `groups` | array | One object per group: `key`, `name` (office groups only) and one key per measure. |
| `total_groups` | integer | How many groups there are in all. |
| `truncated` | boolean | `true` when `limit` left some groups out. |
| `total_permits` | integer | The permits matched: the same number as the `total` of a permits search with this `where` and these `filters`. |
| `coverage` | string or `null` | `complete`, `partial`, `not_collected` or `null`, as for a permits search. See [How to read an answer](https://docs.mireye.ai/api-reference/permits.md#how-to-read-an-answer). |
| `note` | string or `null` | What the counts may miss, as for a permits search. See [note sentences](https://docs.mireye.ai/api-reference/permits.md#note-sentences). |
| `billing` | object | The receipt. |
| `geocode`, `parcel` | object | Only when `where.parcel` is an address. See [Parcel by address](https://docs.mireye.ai/api-reference/permits.md#parcel-by-address). |

* With `partial`, `not_collected` or `null` coverage, every count is a lower bound.
  A `0` is then not proof that no permits exist.
* Branch on `coverage`, not on the `note` text.

## Count for free

Send `limit: 0` to get `total_groups` and `total_permits` with no groups. It is not
charged.

## Price

* One permit row for each group returned.
* The most it can cost, `limit` rows, is reserved first. Set `max_cost_usd` at or
  above it.
* A call with no group is free:
  * a count (`limit: 0`);
  * an area with no matching permits;
  * a parcel address or point that selects no single parcel;
  * a call that fails.
* Send a stable `Idempotency-Key` to retry without a second charge. See
  [Retries](https://docs.mireye.ai/api-reference/permits.md#retries).

## Errors

The same as a permits search. See [Errors](https://docs.mireye.ai/api-reference/permits.md#errors). A request
that is not valid gets `422 permits_invalid_request` with a `problems` list.

## Related pages

* [Permits API](https://docs.mireye.ai/api-reference/permits.md): the permit records themselves.
* [Permits parcels](https://docs.mireye.ai/api-reference/permits-parcels.md): one row per 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).
