# Coverage

> What the data holds and where: two endpoints that need no key and are never billed.

Coverage today is British Columbia. The United States is being added.

These two endpoints say what the live data holds. They need no key, are never billed and do not count against a rate limit. They always read the live data, never the sandbox, and their answers are cached for an hour.

## Counts and coverage

### `GET /v1/stats`

**What the data holds.** Counts and the span of the live data. No key needed; not billed.

[Reference and playground for what the data holds](https://data.heytownhall.com/docs/reference/coverage/get-v1-stats). No key needed.

| Field                         | Type            | What it holds          |
| ----------------------------- | --------------- | ---------------------- |
| `jurisdictions`               | number          |                        |
| `jurisdictions_with_meetings` | number          |                        |
| `meetings`                    | number          |                        |
| `first_meeting_on`            | string or null  | YYYY-MM-DD.            |
| `last_meeting_on`             | string or null  | YYYY-MM-DD.            |
| `read_at`                     | string or null  | ISO 8601 instant, UTC. |
| `countries`                   | array of string |                        |
| `regions`                     | array of string |                        |

### `GET /v1/coverage`

**Coverage by jurisdiction.** Each jurisdiction with how much of it is read (ingest_profile), its meetings and their span, its meeting vendors, and what is held now in each family (held): what is held, never what a body is expected to have. Every family is offered for every country. No key needed; not billed.

[Reference and playground for coverage by jurisdiction](https://data.heytownhall.com/docs/reference/coverage/get-v1-coverage). No key needed.

| Parameter | What it takes                                             |
| --------- | --------------------------------------------------------- |
| `region`  | A two-letter province or state code.                      |
| `country` | CA or US.                                                 |
| `kind`    | The record kind; each endpoint says which kinds it holds. |

Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)).

| Field              | Type            | What it holds                                                                                                                                                                                                                       |
| ------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | string          |                                                                                                                                                                                                                                     |
| `kind`             | string          |                                                                                                                                                                                                                                     |
| `name`             | string          |                                                                                                                                                                                                                                     |
| `country`          | string or null  |                                                                                                                                                                                                                                     |
| `region`           | string or null  |                                                                                                                                                                                                                                     |
| `meetings`         | number or null  |                                                                                                                                                                                                                                     |
| `first_meeting_on` | string or null  | YYYY-MM-DD.                                                                                                                                                                                                                         |
| `last_meeting_on`  | string or null  | YYYY-MM-DD.                                                                                                                                                                                                                         |
| `read_at`          | string or null  | ISO 8601 instant, UTC.                                                                                                                                                                                                              |
| `meeting_vendors`  | array of string |                                                                                                                                                                                                                                     |
| `ingest_profile`   | string or null  |                                                                                                                                                                                                                                     |
| `held`             | object          | Records held now, by family (meetings, motions, recordings, documents, bylaws, financial_reports, posts, permits, officials, departments, platforms): what is held, never what is expected. Posts count only those still published. |