# Search

> One full-text search across agenda items, motions, transcripts, documents, bylaws and posts.

Search finds where a subject has come up, newest first. Each hit names its family, its id, its jurisdiction and date, a snippet, and its `source_url` and `read_at`. Read the record itself from its family's endpoint.

Within a jurisdiction, a search covers every family. Without one, it covers transcripts, bylaws and posts for now; asking for agenda items, motions or documents without a jurisdiction answers `400` with `param` set to `in`. The query echo's `in` says which families were searched.

A search is billed on the search meter, not the records meter. See [Billing](https://data.heytownhall.com/docs/billing).

## Search the records

### `GET /v1/search`

**Search the records.** One full-text search (English) across agenda items, motions, meeting transcripts, document and bylaw titles, and posts, newest first. Billed as one search request a page.

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

| Parameter      | What it takes                                                                                                                                                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` (required) | Words to find. Quotes keep a phrase; a leading minus leaves a word out (Postgres web search syntax).                                                                                                                                         |
| `in`           | What to search, comma-separated: agenda_items, motions, transcripts, documents, bylaws, posts. Default all within a jurisdiction; without one, transcripts, bylaws, posts (agenda items, motions and documents need a jurisdiction for now). |
| `jurisdiction` | A jurisdiction id.                                                                                                                                                                                                                           |
| `region`       | A two-letter province or state code.                                                                                                                                                                                                         |
| `from`         | On or after this date (YYYY-MM-DD).                                                                                                                                                                                                          |
| `to`           | On or before this date (YYYY-MM-DD).                                                                                                                                                                                                         |

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

| Field             | Type           | What it holds                                                   |
| ----------------- | -------------- | --------------------------------------------------------------- |
| `family`          | string         |                                                                 |
| `id`              | string         |                                                                 |
| `jurisdiction_id` | string         |                                                                 |
| `meeting_id`      | string or null |                                                                 |
| `date`            | string or null | YYYY-MM-DD.                                                     |
| `title`           | string or null |                                                                 |
| `snippet`         | string or null |                                                                 |
| `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.                                               |