{
  "openapi": "3.1.0",
  "info": {
    "title": "Schools Near Me Public API",
    "version": "1.0.0",
    "description": "Read-only access to the public subset of Schools Near Me school data. Public calls require no API key. Fields reserved for signed-in Pro users or commercial feeds are not included in anonymous responses.",
    "contact": {
      "name": "Schools Near Me",
      "url": "https://schoolsnearme.ai/about#contact",
      "email": "hello@schoolsnearme.ai"
    },
    "license": {
      "name": "Source datasets include Open Government Licence data",
      "url": "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
    }
  },
  "servers": [
    {
      "url": "https://schoolsnearme.ai",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Schools",
      "description": "Search for schools and retrieve public school records."
    }
  ],
  "paths": {
    "/api/v1/search": {
      "get": {
        "operationId": "searchSchools",
        "summary": "Search schools",
        "description": "Search open schools by name, local authority or type. Supply a UK postcode or outward code to sort by distance. At least one of query or postcode is required.",
        "tags": ["Schools"],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "School name, local authority or school type.",
            "schema": { "type": "string", "minLength": 2 }
          },
          {
            "name": "postcode",
            "in": "query",
            "description": "Full UK postcode or outward code.",
            "schema": { "type": "string", "minLength": 2 }
          },
          {
            "name": "phase",
            "in": "query",
            "description": "Optional phase filter.",
            "schema": {
              "type": "string",
              "enum": ["primary", "secondary", "nursery", "sixth form", "all-through"]
            }
          },
          {
            "name": "radius_miles",
            "in": "query",
            "description": "Optional maximum distance from postcode.",
            "schema": { "type": "number", "minimum": 0.1, "maximum": 100 }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum results to return.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching public school summaries.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchResponse" }
              }
            }
          },
          "400": {
            "description": "Missing search input or an unknown postcode.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "500": {
            "description": "The search service is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/v1/schools/{urn}": {
      "get": {
        "operationId": "getSchool",
        "summary": "Get one school",
        "description": "Returns the current public record for a school. The schema is intentionally open because available fields vary by phase, school type, source coverage and suppression rules. An anonymous call never returns premium-only fields.",
        "tags": ["Schools"],
        "parameters": [
          {
            "name": "urn",
            "in": "path",
            "required": true,
            "description": "Six-digit DfE Unique Reference Number.",
            "schema": { "type": "string", "pattern": "^\\d{6}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "The school record.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SchoolRecord" }
              }
            }
          },
          "400": {
            "description": "Invalid URN.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "School not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/get-school": {
      "get": {
        "operationId": "getSchoolLegacy",
        "summary": "Get one school (legacy route)",
        "deprecated": true,
        "description": "Compatibility route. New integrations should use /api/v1/schools/{urn}.",
        "tags": ["Schools"],
        "parameters": [
          {
            "name": "urn",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "pattern": "^\\d{6}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "The school record.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SchoolRecord" }
              }
            }
          },
          "400": {
            "description": "Invalid URN.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "School not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" }
        },
        "additionalProperties": true
      },
      "SchoolSearchResult": {
        "type": "object",
        "required": ["urn", "name", "url"],
        "properties": {
          "urn": { "type": "integer" },
          "name": { "type": "string" },
          "phase": { "type": ["string", "null"] },
          "type": { "type": ["string", "null"] },
          "localAuthority": { "type": ["string", "null"] },
          "location": {
            "oneOf": [
              {
                "type": "object",
                "required": ["latitude", "longitude"],
                "properties": {
                  "latitude": { "type": "number" },
                  "longitude": { "type": "number" }
                },
                "additionalProperties": false
              },
              { "type": "null" }
            ]
          },
          "distanceMiles": { "type": "number" },
          "ofstedRating": {
            "type": ["integer", "null"],
            "minimum": 1,
            "maximum": 4,
            "description": "1 Outstanding, 2 Good, 3 Requires Improvement, 4 Inadequate."
          },
          "snmScore": {
            "type": ["number", "null"],
            "minimum": 0,
            "maximum": 100
          },
          "scoreSuppressed": { "type": "boolean" },
          "url": { "type": "string", "format": "uri" }
        },
        "additionalProperties": false
      },
      "SearchResponse": {
        "type": "object",
        "required": ["query", "postcode", "phase", "radiusMiles", "total", "limit", "results"],
        "properties": {
          "query": { "type": ["string", "null"] },
          "postcode": { "type": ["string", "null"] },
          "phase": { "type": ["string", "null"] },
          "radiusMiles": { "type": ["number", "null"] },
          "total": { "type": "integer", "minimum": 0 },
          "limit": { "type": "integer", "minimum": 1, "maximum": 25 },
          "results": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/SchoolSearchResult" }
          }
        },
        "additionalProperties": false
      },
      "SchoolRecord": {
        "type": "object",
        "required": ["urn", "name"],
        "properties": {
          "urn": { "type": "integer" },
          "name": { "type": "string" },
          "postcode": { "type": ["string", "null"] },
          "town": { "type": ["string", "null"] },
          "phase": { "type": ["string", "null"] },
          "type": { "type": ["string", "null"] },
          "snmScore": { "type": ["number", "null"], "minimum": 0, "maximum": 100 },
          "scoreSuppressed": { "type": "boolean" },
          "scoreSuppressedReason": { "type": "string" }
        },
        "additionalProperties": true
      }
    }
  }
}