# Public word

> News, notices and events, engagement projects, and local press headlines.

What governments post for the public, and what the local press says about them. For press, only the headline, the publisher and the link: never the article's text.

## News, notices and events

### `GET /v1/news`

**List news, notices and events.** What a government posts: news, public notices, council recaps, events and alerts. Billed as one records request a page. Filters: jurisdiction, region, country, kind, from, to, since.

[Reference and playground for list news, notices and events](https://data.heytownhall.com/docs/reference/posts/get-v1-news)

| Parameter      | What it takes                                                            |
| -------------- | ------------------------------------------------------------------------ |
| `jurisdiction` | A jurisdiction id.                                                       |
| `region`       | A two-letter province or state code.                                     |
| `country`      | CA or US.                                                                |
| `kind`         | news, notice, recap, event, alert.                                       |
| `from`         | On or after this date (YYYY-MM-DD).                                      |
| `to`           | On or before this date (YYYY-MM-DD).                                     |
| `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                  | news, notice, recap, event, alert.                              |
| `title`           | string                  |                                                                 |
| `summary`         | string or null          |                                                                 |
| `starts_at`       | string or null          | ISO 8601 instant, UTC.                                          |
| `ends_at`         | string or null          | ISO 8601 instant, UTC.                                          |
| `all_day`         | boolean or null         |                                                                 |
| `location`        | string or null          |                                                                 |
| `address`         | string or null          |                                                                 |
| `published_at`    | string or null          | ISO 8601 instant, UTC.                                          |
| `closes_at`       | string or null          | ISO 8601 instant, UTC.                                          |
| `categories`      | array of string or null |                                                                 |
| `cancelled`       | boolean or null         |                                                                 |
| `first_seen_at`   | string                  | 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.                                               |

## Engagement projects

### `GET /v1/engagements`

**List engagement projects.** Open public engagement: surveys, consultations and open houses. Billed as one records request a page. Filters: jurisdiction, region, country, from, to, since.

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

| Parameter      | What it takes                                                            |
| -------------- | ------------------------------------------------------------------------ |
| `jurisdiction` | A jurisdiction id.                                                       |
| `region`       | A two-letter province or state code.                                     |
| `country`      | CA or US.                                                                |
| `from`         | On or after this date (YYYY-MM-DD).                                      |
| `to`           | On or before this date (YYYY-MM-DD).                                     |
| `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          |                                                                 |
| `title`           | string                  |                                                                 |
| `summary`         | string or null          |                                                                 |
| `published_at`    | string or null          | ISO 8601 instant, UTC.                                          |
| `closes_at`       | string or null          | ISO 8601 instant, UTC.                                          |
| `categories`      | array of string or null |                                                                 |
| `first_seen_at`   | string                  | 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.                                               |

## Local press

### `GET /v1/press`

**List local press.** Local press about a government: the headline, the publisher and the link. Never the article's text. Billed as one records request a page. Filters: jurisdiction, from, to, since.

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

| Parameter      | What it takes                                                            |
| -------------- | ------------------------------------------------------------------------ |
| `jurisdiction` | A jurisdiction id.                                                       |
| `from`         | On or after this date (YYYY-MM-DD).                                      |
| `to`           | On or before this date (YYYY-MM-DD).                                     |
| `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         |                                                                 |
| `title`           | string         |                                                                 |
| `publisher`       | string or null |                                                                 |
| `published_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.                                               |