Build with school data

01

Quickstart

1. Create or sign into a SchoolsNearMe account.
2. Activate the free Developer plan and create a named live key.
3. Copy the key when it is revealed. It cannot be shown again.
4. Send it as a bearer token.

export SNM_API_KEY="snm_live_…"

curl "https://schoolsnearme.ai/api/v1/schools/search?q=Aldgate" \
  -H "Authorization: Bearer $SNM_API_KEY" \
  -H "Accept: application/json"

Keep keys server-side. Do not embed them in browser JavaScript, mobile bundles, public repositories, logs or URLs.

02

Authentication

Every commercial REST and MCP request requires Authorization: Bearer snm_live_…. X-API-Key exists for constrained legacy systems, but bearer authentication is preferred. Query-string keys are rejected.

Keys belong to an organisation and inherit its plan. Revoke a suspected key immediately, create a replacement and update every server that used it. SchoolsNearMe stores a domain-separated SHA-256 hash and a display prefix, never the full secret.

03

REST endpoints

Profile example

curl "https://schoolsnearme.ai/api/v1/schools/100000" \
  -H "Authorization: Bearer $SNM_API_KEY"

Compare example

curl "https://schoolsnearme.ai/api/v1/schools/compare" \
  -X POST \
  -H "Authorization: Bearer $SNM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urns":["100000","100049"]}'

04

Pagination and filters

List responses use page and per_page. The default page size is 20; the plan maximum is 25, 50 or 100. Sorts use a URN tie-breaker so paging is deterministic for a fixed data release.

{
  "data": [ … ],
  "meta": {
    "request_id": "4b8b73be-…",
    "data_updated_at": "2026-08-06T19:10:21.403Z",
    "pagination": {"page":1,"per_page":20,"total":181,"total_pages":10},
    "sources": [ … ]
  }
}

Supported list filters include q, postcode, latitude, longitude, radius_miles, local_authority, phase, type, gender, ofsted_rating, min_score and sort. Unknown parameters return 400 rather than being silently ignored.

05

Errors, rate limits and quotas

{
  "error": {
    "code": "feature_not_in_plan",
    "message": "The finance capability is not included in this plan.",
    "request_id": "4b8b73be-…",
    "details": {"feature":"finance"}
  }
}

Inspect X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset. On 429, use Retry-After and exponential backoff with jitter. Include X-Request-Id when contacting support.

06

Data freshness, coverage and licences

Call /data-freshness before making recency-sensitive claims. Each response also includes the dataset generation timestamp and source attribution. A null value means unavailable or suppressed; it never means zero.

Launch responses may include cleared GIAS/DfE/Ofsted facts and SchoolsNearMe-derived measures. They exclude ISI material, fees, catchment geometries, AI summaries, school-site content and other fields without confirmed commercial rights. See the Developer Terms for attribution and permitted use.

07

Remote MCP server

Connect to https://schoolsnearme.ai/mcp using stateless Streamable HTTP. The server uses the official TypeScript SDK v2 and the 2026-07-28 protocol, with SDK-managed stateless compatibility for supported 2025 clients.

import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";

const transport = new StreamableHTTPClientTransport(
  new URL("https://schoolsnearme.ai/mcp"),
  { authProvider: { token: async () => process.env.SNM_API_KEY } }
);
const client = new Client(
  { name: "my-product", version: "1.0.0" },
  { versionNegotiation: { mode: { pin: "2026-07-28" } } }
);
await client.connect(transport);
const result = await client.callTool({
  name: "search_schools",
  arguments: { q: "Aldgate", per_page: 5 }
});

Tools: search_schools, get_school, find_schools_near_location, compare_schools, get_school_inspection_history, get_school_results, get_school_admissions, get_school_finances, get_school_data_freshness and get_school_rankings.

One accepted tools/call consumes one request. Discovery, ping and tool listing authenticate but are not metered. Launch authentication is an API-key bearer flow. A conforming MCP OAuth 2.1 authorization server is a later interoperability milestone and is not advertised today.

08

Compatibility and change policy

Additive optional fields may appear in v1. Changing an existing field’s meaning or type, making an optional field required, or removing an enum value requires a new major API version. Self-serve deprecations normally receive at least six months’ notice unless a security or legal issue requires faster action.

Changelog: 2026-08-19 — commercial v1 REST API, current MCP server, self-serve keys, subscriptions, usage and licensed field policy launched.