---
title: "Get Coverage"
method: GET
path: "/meta/coverage"
tags: ["Meta"]
---

# Get Coverage

`GET /meta/coverage`

## Request

- Base URL: `https://api.shovels.ai/v2`
- URL: `https://api.shovels.ai/v2/meta/coverage`
- Auth: API key in header `X-API-Key`

Returns per-field data coverage tiers (partial or missing) for the specified geography and date range. Coverage is counted over the exact inclusive date_from–date_to window, on each permit's start_date — the same column and bounds permit search applies. ZIP coverage is reported at five-digit granularity; a ZIP+4 input is truncated to its five-digit prefix and therefore describes a broader population than a ZIP+4 permit search. Fields classified as reliable (fill rate >= 80%) are omitted. Empty windows return every tracked field as missing with permits_total=0.

## Query parameters

- `geo_type` 'state' | 'county' | 'city' | 'zipcode' | 'jurisdiction', required: One of 'state', 'county', 'city', 'zipcode', 'jurisdiction'. Determines how geo_id is parsed.
- `geo_id` string, required: 2-letter state code, 5-digit ZIP, or base64 geolocation ID for city/county/jurisdiction.
- `date_from` string, date, required: Inclusive lower bound of the window. Format: YYYY-MM-DD.
- `date_to` string, date, required: Inclusive upper bound of the window. Format: YYYY-MM-DD. Must be >= date_from.

## Response `200`

Per-field coverage rows ordered by tier then field.

- CoverageResponse: Response envelope for `/v2/meta/coverage`. Bounded to one item per tracked field; no pagination.
  - `items` CoverageItem[], required: Per-field coverage rows for fields in the partial or missing tier, ordered by tier then field.
    - `field` 'fees' | 'job_value' | 'description' | 'contractor_id' | 'property_legal_owner' | 'property_type' | 'property_year_built' | 'property_building_area' | 'property_assess_market_value' | 'property_lot_size' | 'property_story_count' | 'property_unit_count' | 'issue_date' | 'file_date', required: Tracked permit field name (without 'has_' prefix).
    - `criterion` 'populated' | 'positive_value': Criterion counted by fill_pct: populated = the field has a value, and for text fields the value is not empty; positive_value = the value is greater than 0.
    - `tier` 'missing' | 'partial' | 'reliable', required: Coverage classification: 'missing' (fill_pct < 0.10), 'partial' (0.10 <= fill_pct < 0.80), 'reliable' (fill_pct >= 0.80). The endpoint omits 'reliable' rows from the response.
    - `fill_pct` number, required: Fraction of permits_total meeting this field's criterion, rounded to 3 decimals. permits_total counts permits whose start_date falls within the inclusive date_from–date_to window. 0.0 when permits_total is 0.
    - `permits_total` integer, required: Count of permits for this geography whose start_date falls within the inclusive date_from–date_to window — the same population an exact start_date-filtered permit search over that window returns.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-13** `e9f48948b723`: 1 info
  - added the optional property `items/items/criterion` to the response with the `200` status
- **2026-08-22** `64df4c8074f5`: 4 warning
  - added the new `property_assess_market_value` enum value to the `items/items/field` response property for the response status `200`
  - added the new `property_lot_size` enum value to the `items/items/field` response property for the response status `200`
  - added the new `property_story_count` enum value to the `items/items/field` response property for the response status `200`
  - added the new `property_unit_count` enum value to the `items/items/field` response property for the response status `200`
- **2026-08-19** `f89e7c1abc2d`: 1 warning, 1 info
  - added the new `property_legal_owner` enum value to the `items/items/field` response property for the response status `200`
  - removed the `owner_name` enum value from the `items/items/field` response property for the response status `200`
- **2026-08-04** `685b8866c451`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-07-13** `b476ae3c7417`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shovels/apis/the-shovels-api-v2/changes/meta/coverage/get.md)

---

[API](https://skmtc.dev/shovels/apis/the-shovels-api-v2.md) - [All operations](https://skmtc.dev/shovels/apis/the-shovels-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/shovels/apis/the-shovels-api-v2/revisions/e9f48948b723?raw)