Developer documentation

Make the first request.

Create a test key in the developer dashboard, then query the versioned API. Test keys are for non-commercial evaluation; live keys identify licensed production use.

curl

curl "https://abudhabischools.com/v1/schools?curriculum=British&page_size=3" \
  -H "X-API-Key: ads_test_your_key"

JavaScript / TypeScript

const response = await fetch(
  "https://abudhabischools.com/v1/schools?rating=Outstanding&page_size=5",
  { headers: { "X-API-Key": process.env.ABUDHABISCHOOLS_API_KEY } }
);
if (!response.ok) throw new Error(`AbuDhabiSchools API ${response.status}`);
const { data, pagination, meta } = await response.json();

Python

import os
import requests

response = requests.get(
    "https://abudhabischools.com/v1/schools",
    params={"curriculum": "British", "fee_max": 80000, "page_size": 5},
    headers={"X-API-Key": os.environ["ABUDHABISCHOOLS_API_KEY"]},
    timeout=15,
)
response.raise_for_status()
schools = response.json()["data"]

Download OpenAPI 3.1 specification

Authentication

Send a key in X-API-Key. Authorization: Bearer is also accepted for server-to-server and MCP clients that cannot set a custom key header.

X-API-Key: ads_test_...

Keep keys server-side. Do not embed them in browser JavaScript, mobile binaries, source control, analytics, URLs or logs. Name keys by integration, rotate on suspected exposure and revoke unused keys.

Secrets are displayed once. AbuDhabiSchools stores a keyed SHA-256 digest, visible prefix and last four characters, not the plaintext secret.

Environments and licences

ads_test_ keys identify non-commercial evaluation traffic. ads_live_ keys identify licensed production traffic and can only be created for an active paid developer entitlement.

Every response includes meta.licence as either evaluation_non_commercial or licensed_commercial_api. Consumer Pro is a separate one-time product and never grants Developer API rights.

Endpoints

GET/v1/schools

GET/v1/schools/search

GET/v1/schools/nearby

GET/v1/schools/{id}

GET/v1/schools/{id}/fees

GET/v1/schools/{id}/inspections

POST/v1/schools/compare

GET/v1/rankings

GET/v1/location/schools

GET/v1/meta

GET/v1/data-freshness

Identifiers may be a stable ads_ id, legacy numeric id, slug or exact name. New integrations should store the ads_ id.

Search and filtering

List and search endpoints accept query, curriculum, rating, fee_min, fee_max, age, year_group, score_min and sort.

curriculum and rating accept comma-separated alternatives.
Aliases include British/UK, American/US, IB, CBSE/Indian and Ministry of Education/MOE.
When a child stage is supplied, fee filters use a matched stage fee where available, falling back to the indicative average.
score_min refers to the independent AbuDhabiSchools Score, never the Irtiqaa rating.

GET /v1/schools?curriculum=British,IB&rating=Outstanding,Very%20Good
    &year_group=Year%204&fee_max=80000&sort=fee_asc

Nearby and property queries

Supply both latitude and longitude. Radius is in kilometres, defaults to 5 and is capped at 50.

GET /v1/location/schools?latitude=24.4539&longitude=54.3773
    &radius_km=8&year_group=Year%204&curriculum=British&fee_max=80000

Distance semantics: distance_km is the Haversine straight-line distance from the requested coordinates. It is not a drive-time, catchment or admissions guarantee.

Pagination

Use one-based page and page_size. The default page size is 20 and the maximum is 100. Responses return total, total_pages and has_next.

{
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true
  }
}

Rate limits and quotas

Limits are enforced atomically per key and account. Normal reads cost one request unit; ranking and location queries cost two; comparison costs one unit per requested school. The dashboard shows the same internal meter used for enforcement.

X-RateLimit-Limit and X-RateLimit-Remaining: per-minute key window.
X-Quota-Limit and X-Quota-Remaining: calendar-month account allowance in UTC.
Retry-After: 60: returned on HTTP 429.

Errors

Errors use a stable envelope. Include request_id when contacting support.

{
  "error": {
    "code": "invalid_parameter",
    "message": "radius_km must be between 0.1 and 50",
    "request_id": "...",
    "docs_url": "https://abudhabischools.com/developers/docs/#errors"
  }
}

400 invalid request
401 missing or invalid API key
402 billing grace expired
403 endpoint or field family not in the entitlement
404 record not found
422 valid syntax but insufficient records
429 rate or quota limit
503 configuration, launch gate or temporary service issue

Field model and profiles

Stable school objects group fields by meaning: regulatory_ids, curriculum, grades, location, adek, annual_fee_aed, data_quality, links and sources.

Core: identity, curriculum, approved location fields, current rating and fee summary.
Standard: fee schedules, inspection history, enrolment and AbuDhabiSchools-derived metrics.
Premium: approved capacity fields in addition to Standard.

Null means not available from the approved source. The API does not manufacture a default value.

Data freshness

GET /v1/data-freshness reports the dataset hash, record coverage and source-family dates. meta.dataset_version lets an integration identify whether the underlying snapshot changed.

Inspection cycles, registration checks and fee schedules have different clocks. A single misleading global “last updated” date is deliberately avoided.

Sources and attribution

Primary families come from the ADEK directory, ADEK Irtiqaa inspection reports and ADEK-approved fee schedules. AbuDhabiSchools normalises curriculum names and identifiers and computes labelled independent measures.

Every school response carries source envelopes and an attribution string. Display school and inspection claims with “Source: ADEK”; identify the AbuDhabiSchools Score as an independent AbuDhabiSchools.com measure. See the public methodology and Developer Terms.

Written source permission and legal approval cover the live allowlist. Community mappings, exam results, Google, imagery and AI/editorial families remain excluded even where they exist internally.

MCP server

Connect an authenticated Streamable HTTP client to https://abudhabischools.com/v1/mcp. Send the same API key in X-API-Key or Authorization: Bearer. The server implements MCP 2026-07-28 with the official TypeScript SDK v2 and a stateless compatibility path for 2025-era clients.

{
  "mcpServers": {
    "abudhabischools": {
      "type": "http",
      "url": "https://abudhabischools.com/v1/mcp",
      "headers": { "X-API-Key": "${ABUDHABISCHOOLS_API_KEY}" }
    }
  }
}

Tools: search_abu_dhabi_schools, find_schools_near_location, get_school, get_school_fees, get_school_inspections, compare_schools, rank_schools and get_data_freshness.

Tool discovery, calls and errors use the same account quotas and field profile as REST. MCP results include structured content as well as a JSON text representation.

Changelog

2026-08-20 — Approved commercial allowlist

Enabled the production API and MCP surface for confirmed-permission ADEK facts and AbuDhabiSchools-derived metrics. Removed community mapping and exam-result routes, filters, fields and MCP tools.

2026-08-19 — Developer Platform v1

Added stable REST models, versioned endpoints, geospatial and property matching, test/live hashed keys, quotas, dashboard, recurring-billing architecture, rights-aware field profiles and an authenticated MCP server.

Breaking response changes will use a new URL version. Additive fields may appear in existing versions; clients should ignore unknown properties.

Terms

Use is governed by the Developer/API Terms. Test keys do not grant commercial use. Live terms distinguish integration use from reselling or reconstructing the database and define caching and attribution.