Schools

Autocomplete school names by prefix. Returns the URN (unique reference number), postcode, phase of education, and coordinates.

Try it

—

Endpoint

GET/v1/school/<query>

Base URL: https://autocomplete.namedone.com

SDK Usage

schools()

1import { createClient } from "@namedone/autocomplete"
2
3const nd = createClient("nd_...")
4const { results } = await nd.schools("st mary")

curl

1# Exchange your API key for a token
2curl -X POST https://token.namedone.com/v1 \
3  -H "Content-Type: application/json" \
4  -d '{"apiKey":"nd_..."}'
5
6# Query the schools endpoint
7curl "https://autocomplete.namedone.com/v1/school/st mary?token=<jwt>"

Response Format

JSON

{
  "results": [
    {
      "id": "school-0",
      "text": "St Mary's Primary School",
      "subtitle": "London, SW1A",
      "type": "school"
      "data": {
        "urn": <string>,
        "postcode": <string>,
        "lat": <number>,
        "lng": <number>,
        "phase": <string>
      }
    }
  ],
  "query": "st mary"
}

Data Fields

Field	Type	Description
urn	string	Unique Reference Number (DfE identifier)
postcode	string	School postcode
lat	number	WGS84 latitude
lng	number	WGS84 longitude
phase	string	Education phase (Primary, Secondary, etc.)

API Query Parameters

Sent as query string parameters on the HTTP request to the API.

Parameter	Type	Default	Description
token	string	—	JWT obtained from the token API. Required for authentication.

SDK Options

Passed to the SDK methods (e.g. firstNames(query, opts)). These are processed client-side and never sent to the API.

Option	Type	Default	Description
limit	number	10	Maximum number of results (1–50). Applied client-side by the SDK.
simple	boolean	false	Simplify response: deduplicate by text and strip to {text, type}.
sortByProximity	array	—	Sort results by proximity to coordinates. Client-side only.

Examples

Query: st mary

{
  "results": [
    {
      "id": "school-0",
      "text": "St Mary's Primary School",
      "subtitle": "London, SW1A",
      "type": "school",
      "data": {
        "urn": "123456",
        "phase": "Primary"
      }
    },
    {
      "id": "school-1",
      "text": "St Mary's Secondary School",
      "subtitle": "Manchester, M1",
      "type": "school",
      "data": {
        "urn": "123457",
        "phase": "Secondary"
      }
    }
  ],
  "query": "st mary"
}

Notes

The URN is included as the id field for each result, allowing you to reference the school uniquely.
Coordinates are derived from the school's postcode via ONSPD lookup (~99.97% match rate).
Source: Department for Education licensed under the Open Government Licence v3.0.