> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Schools index

> Search the optional schools reference dataset in Omneo Discovery, including its filterable and sortable attributes.

The `schools` index is a reference dataset of schools held in [Discovery](/concepts/platform-surfaces/omneo-discovery). Unlike the `profiles` and `products` indexes, it is not built from Omneo records: it is a lookup list, used for things like a school picker on a sign-up form or a school field on a Profile.

The index is optional. Contact your Omneo account manager to have it enabled and populated on your tenant.

## Minting a token for the index

Include `schools` in the `rules` object. Because the dataset is public reference data rather than customer data, an unrestricted rule is normally correct.

```bash theme={null}
curl -X POST "https://api.[tenant].getomneo.com/api/v3/auth/discovery" \
  -H "Authorization: Bearer ${OMNEO_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"rules": {"schools": {}}}'
```

See [Minting search tokens](/dev-guides/discovery/search-tokens) for caching and refresh behaviour.

## Searching

```bash theme={null}
POST https://discovery.[tenant].getomneo.com/indexes/schools/search
```

```json theme={null}
{
  "q": "riverside",
  "filter": "SchoolType = 'Primary' AND OperationalStatus = 'Open'",
  "sort": ["SchoolName:asc"],
  "limit": 10
}
```

```json theme={null}
{
  "hits": [
    {
      "id": "48213",
      "SchoolName": "Riverside Primary School",
      "SchoolType": "Primary",
      "SchoolSector": "Government",
      "OperationalStatus": "Open"
    }
  ],
  "query": "riverside",
  "processingTimeMs": 1,
  "limit": 10,
  "offset": 0,
  "estimatedTotalHits": 6
}
```

An empty `q` with only a `filter` is valid, which is what you want for a cascading picker where the user chooses a state and then browses the schools in it.

## Index reference

* **Primary key:** `id`
* **Searchable attributes:** all attributes

<Warning>
  Attribute names on this index are PascalCase, for example `SchoolName`. The `profiles` and `products` indexes use snake\_case. Filters and sorts are case sensitive, so `schoolName` fails where `SchoolName` succeeds.
</Warning>

### Filterable attributes

Only these attributes can appear in a `filter` expression or be requested as a facet.

| Attribute                  | Description                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `SchoolType`               | The type of school, for example primary or secondary.                              |
| `SchoolSector`             | The sector the school belongs to, for example government or independent.           |
| `OperationalStatus`        | Whether the school is currently operating.                                         |
| `IndependentSchool`        | Whether the school is independent.                                                 |
| `SchoolGeographicLocation` | The geographic classification of the school, for example metropolitan or regional. |
| `SchoolDistrict`           | The district the school sits in.                                                   |
| `SessionType`              | The session pattern the school runs.                                               |
| `StateProvinceId`          | The state or province the school is in.                                            |
| `LocalGovernmentArea`      | The local government area the school is in.                                        |

Filter examples:

```text theme={null}
SchoolType = 'Primary'
SchoolSector IN ['Government', 'Independent']
SchoolType = 'Primary' AND OperationalStatus = 'Open'
StateProvinceId = 'NSW' AND (SchoolSector = 'Catholic' OR IndependentSchool = 'Yes')
```

See [Running a search](/dev-guides/discovery/searching) for the full filter expression syntax.

### Sortable attributes

| Attribute    | Usage                                                 |
| ------------ | ----------------------------------------------------- |
| `SchoolName` | `"sort": ["SchoolName:asc"]` or `["SchoolName:desc"]` |

### Finding the values an attribute can take

The values in this dataset vary by region and by how the index was populated, so read them from the data rather than hard-coding them. Request the attributes as facets:

```json theme={null}
{ "q": "", "facets": ["SchoolType", "SchoolSector", "StateProvinceId"], "limit": 0 }
```

The response's `facetDistribution` lists every value with its document count, which is exactly what a filter menu needs.

## curl example

```bash theme={null}
curl -X POST "https://discovery.[tenant].getomneo.com/indexes/schools/search" \
  -H "Authorization: Bearer ${SEARCH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "riverside",
    "filter": "SchoolType = '\''Primary'\''",
    "sort": ["SchoolName:asc"],
    "limit": 10
  }'
```

## JavaScript example

```js theme={null}
const DISCOVERY_HOST = 'https://discovery.[tenant].getomneo.com';

export async function searchSchools(token, query, options = {}) {
  const response = await fetch(`${DISCOVERY_HOST}/indexes/schools/search`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ q: query, ...options })
  });

  if (!response.ok) {
    throw new Error(`School search failed: ${response.status}`);
  }

  return response.json();
}

// Usage
const token = await getSearchToken(); // or fetched from your own backend endpoint
const results = await searchSchools(token, 'riverside', {
  filter: "SchoolType = 'Primary' AND OperationalStatus = 'Open'",
  sort: ['SchoolName:asc'],
  limit: 10
});
console.log(results.hits);
```

In browser code, request the token from your own backend rather than minting it client-side, and re-request it when a search returns `401` or `403`.

## Related

* [Running a search](/dev-guides/discovery/searching)
* [Minting search tokens](/dev-guides/discovery/search-tokens)
* [Discovery indexes](/dev-guides/discovery/indexes)