# Querying collections

The resource collections — locations, location groups, districts, location categories and users —
share one set of query parameters for pagination, filtering, sorting and including related
records. The data endpoints (`/api/v1/data/*`), risk findings and orders take their own parameters,
described on each endpoint's reference page.

## Pagination

Collections are paginated by page number.

| Parameter | Meaning | Default |
|-----------|---------|---------|
| `page[size]` | Results per page, up to 100 | 30 |
| `page[number]` | Which page to return, starting at 1 | 1 |

```bash
curl "https://app.franchisesee.com/api/v1/locations?page[size]=25&page[number]=2" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
```

Every paginated response carries `links` to the neighbouring pages and a `meta` block with the
totals:

```json
{
  "data": [
    { "id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e", "name": "Downtown Austin" }
  ],
  "links": {
    "first": "https://app.franchisesee.com/api/v1/locations?page[number]=1",
    "last": "https://app.franchisesee.com/api/v1/locations?page[number]=10",
    "prev": "https://app.franchisesee.com/api/v1/locations?page[number]=1",
    "next": "https://app.franchisesee.com/api/v1/locations?page[number]=3"
  },
  "meta": {
    "current_page": 2,
    "from": 26,
    "last_page": 10,
    "path": "https://app.franchisesee.com/api/v1/locations",
    "per_page": 25,
    "to": 50,
    "total": 250
  }
}
```

To read a whole collection, follow `links.next` until it is `null`.

## Filtering

Add `filter[field]=value` to narrow a collection. Several filters combine with AND:

```bash
GET /api/v1/districts?filter[district_group_id]=e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90&filter[external_id]=CTX
```

> [!WARNING]
> Filters match **part** of a value and ignore case. `filter[external_id]=STR-1` also returns
> `STR-10` and `STR-1042`. When you look a record up by its external id or email to change it,
> check the exact value in the results before you act on one.

To match any of several values, separate them with commas: `filter[external_id]=STR-1042,STR-1043`
returns records matching either.

## Sorting

Pass `sort` with a field name. Prefix it with `-` for descending order, and separate several fields
with commas; later fields break ties in earlier ones:

```bash
GET /api/v1/locations?sort=-created_at,name
```

## Including related records

Pass `include` to return related records nested inside each result, instead of fetching them one
by one:

```bash
GET /api/v1/locations?include=district,locationGroups
```

```json
{
  "data": [
    {
      "id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
      "external_id": "STR-1042",
      "name": "Downtown Austin",
      "city": "Austin",
      "region": "TX",
      "district": {
        "id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
        "name": "Central Texas",
        "external_id": "CTX"
      },
      "locationGroups": [
        { "id": "a3c5e7f9-2b4d-4f6a-8c1e-3d5f7a9b1c20", "name": "Austin Metro" }
      ]
    }
  ]
}
```

`include` also works on the single-record endpoints, such as `GET /api/v1/locations/{id}`.

## What each collection accepts

Each collection allows its own fields. Asking for anything else returns
[`400 Bad Request`](https://franchisesee.com/docs/api/errors.md#400-bad-request) naming the values it does accept.

| Collection | `filter[...]` | `sort` (default first) | `include` |
|------------|---------------|------------------------|-----------|
| `/api/v1/locations` | `external_id` | `name`, `created_at`, `updated_at` | `locationCategory`, `district`, `district2`, `locationGroups` |
| `/api/v1/location-groups` | `external_id` | `name`, `created_at`, `updated_at` | `locations` |
| `/api/v1/districts` | `external_id`, `district_group_id` | `name`, `created_at`, `updated_at` | `districtGroup` |
| `/api/v1/location-categories` | `external_id`, `location_category_group_id` | `sort_order`, `name`, `created_at`, `updated_at` | `locationCategoryGroup` |
| `/api/v1/users` | `email`, `perspective` | `email`, `first_name`, `last_name`, `created_at`, `updated_at` | `locationGroups`, `location` |

## Putting it together

Pagination, filters, sorting and includes combine freely in one request:

```bash
GET /api/v1/locations?include=district,locationGroups&filter[external_id]=STR-1042&sort=-created_at&page[size]=20
```

## Tips

- Ask for the largest page you can use (`page[size]=100`) when you read a whole collection; it
  means fewer requests against the [rate limit](https://franchisesee.com/docs/api/errors.md#429-too-many-requests).
- Include only the relations you need: each one adds work to every row.
- Cache reference data such as districts and categories on your side; it changes rarely.
