# List jurisdictions

> Every public body held: municipalities, regional districts and counties, school districts, First Nations, special districts. Each with its kind, parent, population, time zone, register ids and whether its boundary is held. Billed as one records request a page. Filters: region, country, kind, parent, name.

`GET /v1/jurisdictions`

Every public body held: municipalities, regional districts and counties, school districts, First Nations, special districts. Each with its kind, parent, population, time zone, register ids and whether its boundary is held. Billed as one records request a page. Filters: region, country, kind, parent, name.

Authentication: `Authorization: Bearer <key>`, an `htd_test_` (sandbox) or `htd_live_` (live) key.

```bash
curl "https://data.heytownhall.com/v1/jurisdictions" \
  -H "Authorization: Bearer $HTD_KEY"
```

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `region` | query | no | A two-letter province or state code. |
| `country` | query | no | CA or US. |
| `kind` | query | no | municipality, regional_district, school_district, first_nation, improvement_district, library, … |
| `parent` | query | no | The regional district or county a jurisdiction sits in. |
| `name` | query | no | Words in the name. |
| `limit` | query | no | Results a page, 1 to 100. Default 25. |
| `cursor` | query | no | next_cursor from the previous page. |

## Fields of each result

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The jurisdiction id (e.g. `victoria`, `capital-regional-district`). |
| `kind` | string | municipality, regional_district, school_district, first_nation, county, township, special_district, … |
| `name` | string |  |
| `name_fr` | string or null |  |
| `country` | string or null |  |
| `region` | string or null |  |
| `parent_id` | string or null | The regional district or county it sits in. |
| `population` | number or null |  |
| `time_zone` | string or null |  |
| `legal_form` | string or null |  |
| `website` | string or null |  |
| `register_ids` | object | Ids registers give it, by scheme (census, GNIS, OCD, Wikidata, …). |
| `has_boundary` | boolean |  |
| `ingest_profile` | string or null | How much of it is read: resident_full (everything, for residents and business), records_full (every public record), meetings_only (its meetings alone). A family not read is absent, never "none". |
| `dissolved_at` | string or null | When the body was dissolved, if it was. |
| `source_url` | string or null | The page, document, video or platform the record was read from. |
| `read_at` | string or null | When it was read. |

## Answers

| Status | Meaning |
| --- | --- |
| `200` | A page. |
| `400` | invalid_request: a parameter is missing or not valid; `param` names it. |
| `401` | unauthorized: no key, or not a valid one. |
| `402` | billing_required (a live key without a payment method, or paused for an unpaid invoice) or spend_cap_reached. |
| `429` | rate_limited: past the key's requests per minute. Retry-After says when to try again. |
| `503` | upstream_unavailable: the data could not be read. Not an empty answer; try again. |