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

# Get Coverage

`GET /meta/coverage`

Returns per-field data coverage tiers (partial or missing) for the specified geography and date range. Coverage is bucketed by each permit's start_date year; every calendar year the range touches is counted in full. For a whole-calendar-year window the totals equal a start_date-filtered permit search over the same window at 5-digit ZIP granularity. A sub-year window still counts its touched years in full, so it can report a broader population than the search. ZIP coverage is bucketed at the 5-digit level, so a search narrowed to a ZIP+4 extension returns a subset of that population. 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. The coverage year set includes every year the range touches.
- `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).
    - `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 with a populated value for this field, rounded to 3 decimals. The denominator counts permits whose start_date year falls in any calendar year the requested window touches (each touched year counted in full). 0.0 when permits_total is 0.
    - `permits_total` integer, required — Count of permits for this geography whose start_date year falls in a calendar year the requested window touches, summed across those touched years (each touched year counted in full). A sub-year window therefore counts its touched years wholly and can report a broader population than an exact start_date-filtered search.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/shovels/apis/the-shovels-api-v2.md) · [All operations](https://skmtc.net/shovels/apis/the-shovels-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shovels/the-shovels-api-v2/revisions/64df4c8074f5/schema)