# Places

> Jurisdictions, who governs a point, and the software each government runs.

Every public body held, from municipalities and regional districts to school districts and First Nations. A jurisdiction's id is what every other list takes as `jurisdiction`.

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

## Jurisdictions

### `GET /v1/jurisdictions`

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

[Reference and playground for list jurisdictions](https://data.heytownhall.com/docs/reference/jurisdictions/get-v1-jurisdictions)

| Parameter | What it takes                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------ |
| `region`  | A two-letter province or state code.                                                             |
| `country` | CA or US.                                                                                        |
| `kind`    | municipality, regional_district, school_district, first_nation, improvement_district, library, … |
| `parent`  | The regional district or county a jurisdiction sits in.                                          |
| `name`    | Words in the name.                                                                               |

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

| Field            | Type           | What it holds                                                                                                                                                                                      |
| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.                                                                                                                                                                                  |

### `GET /v1/jurisdictions/{id}`

**Retrieve a jurisdiction.** One jurisdiction. Billed as one records request.

[Reference and playground for retrieve a jurisdiction](https://data.heytownhall.com/docs/reference/jurisdictions/get-v1-jurisdictions-id)

Path: `{id}` such as victoria.

## Who governs a point

### `GET /v1/jurisdictions/at`

**Who governs a point.** Every jurisdiction whose boundary covers the point: the municipality, the regional district or county, the school district, the health authority and so on. Billed as one records request.

[Reference and playground for who governs a point](https://data.heytownhall.com/docs/reference/jurisdictions/get-v1-jurisdictions-at)

| Parameter        | What it takes |
| ---------------- | ------------- |
| `lat` (required) |               |
| `lng` (required) |               |

| Field       | Type           | What it holds          |
| ----------- | -------------- | ---------------------- |
| `id`        | string         |                        |
| `kind`      | string         |                        |
| `name`      | string         |                        |
| `country`   | string or null |                        |
| `region`    | string or null |                        |
| `area_kind` | string         |                        |
| `area_name` | string or null |                        |
| `read_at`   | string or null | ISO 8601 instant, UTC. |

## The software each government runs

### `GET /v1/platforms`

**List the software each government runs.** The platform census: which vendor each government uses for meetings, permits, payments and more, verified. Billed as one records request a page. Filters: jurisdiction, region, country, kind, since.

[Reference and playground for list the software each government runs](https://data.heytownhall.com/docs/reference/jurisdictions/get-v1-platforms)

| Parameter      | What it takes                                                            |
| -------------- | ------------------------------------------------------------------------ |
| `jurisdiction` | A jurisdiction id.                                                       |
| `region`       | A two-letter province or state code.                                     |
| `country`      | CA or US.                                                                |
| `kind`         | meetings, permits, payments, garbage, parking, feeds, video.             |
| `since`        | Records read at or after this instant: what is new since your last read. |

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

| Field             | Type           | What it holds                                                   |
| ----------------- | -------------- | --------------------------------------------------------------- |
| `id`              | string         |                                                                 |
| `jurisdiction_id` | string         |                                                                 |
| `country`         | string or null |                                                                 |
| `region`          | string or null |                                                                 |
| `kind`            | string         | meetings, permits, payments, garbage, parking, feeds, video.    |
| `vendor`          | string         |                                                                 |
| `verified_at`     | string or null | ISO 8601 instant, UTC.                                          |
| `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.                                               |

## Vendor tenants

Each meeting vendor's tenant matched to a government and verified: the vendor, its name for the tenant, its host, and how it was matched.

### `GET /v1/platform-tenants`

**List vendor tenants.** Each meeting vendor's tenant matched to a government and verified by a read of it: the vendor census by tenant. Billed as one records request a page. Filters: jurisdiction, region, country, kind, since.

[Reference and playground for list vendor tenants](https://data.heytownhall.com/docs/reference/jurisdictions/get-v1-platform-tenants)

| Parameter      | What it takes                                                            |
| -------------- | ------------------------------------------------------------------------ |
| `jurisdiction` | A jurisdiction id.                                                       |
| `region`       | A two-letter province or state code.                                     |
| `country`      | CA or US.                                                                |
| `kind`         | The vendor, such as legistar or civicweb.                                |
| `since`        | Records read at or after this instant: what is new since your last read. |

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

| Field              | Type           | What it holds                                                   |
| ------------------ | -------------- | --------------------------------------------------------------- |
| `id`               | string         |                                                                 |
| `jurisdiction_id`  | string         |                                                                 |
| `country`          | string or null |                                                                 |
| `region`           | string or null |                                                                 |
| `vendor`           | string         |                                                                 |
| `tenant_key`       | string         | The vendor's own name for the tenant.                           |
| `host`             | string or null |                                                                 |
| `match_method`     | string or null |                                                                 |
| `match_confidence` | number or null |                                                                 |
| `verified_at`      | string or null | ISO 8601 instant, UTC.                                          |
| `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.                                               |