Skip to main content

​
Overview

The Schools API provides access to detailed information about schools across the UK, including:
  • Primary and secondary schools
  • Independent and state schools
  • Ofsted ratings and inspection data
  • Performance metrics and statistics
  • Geographic location and catchment areas

​
Base URL

https://api.vepler.com/v1/schools

​
Authentication

All endpoints require authentication via API key: 
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.vepler.com/v1/schools

​
Available Endpoints

List All Schools

GET /v1/schools

Get School by ID

GET /v1/schools/{id}

Get by URN

GET /v1/schools/by-urn/{urn}

Get by Slug

GET /v1/schools/by-slug/{slug}

Search Nearby

GET /v1/schools/search/nearby

Search Within Area

GET /v1/schools/search/within

Get Metrics

GET /v1/schools/metrics

Get Profiles

GET /v1/schools/metrics/profiles

​
Quick Start

​
Find Schools Near a Location

import { Vepler } from 'vepler-sdk';

const vepler = new Vepler({ apiKey: process.env.VEPLER_API_KEY });

// Search for schools within 2km of a coordinate
const schools = await vepler.schools.searchNearby({
  latitude: 51.5074,
  longitude: -0.1278,
  radius: 2000,
  unit: 'meters'
});

console.log(schools.data);
// [
//   {
//     id: 'sch_123',
//     name: 'Westminster Academy',
//     distance: 450,
//     ofstedRating: 'Good',
//     ...
//   }
// ]

​
Get School Details

// Get by school ID
const school = await vepler.schools.get('sch_123');

// Get by URN (Unique Reference Number)
const schoolByUrn = await vepler.schools.getByUrn('100000');

// Get by slug
const schoolBySlug = await vepler.schools.getBySlug('westminster-academy');

console.log(school.data);
// {
//   id: 'sch_123',
//   urn: '100000',
//   name: 'Westminster Academy',
//   type: 'Academy',
//   phase: 'Secondary',
//   address: '...',
//   postcode: 'SW1A 2AA',
//   latitude: 51.5074,
//   longitude: -0.1278,
//   ofstedRating: 'Good',
//   lastInspection: '2023-09-15',
//   ...
// }

​
Response Structure

All responses follow a consistent structure: 
{
  "data": {
    "id": "sch_123",
    "urn": "100000",
    "name": "Westminster Academy",
    "type": "Academy",
    "phase": "Secondary",
    "status": "Open",
    "address": "123 School Street, Westminster, London",
    "postcode": "SW1A 2AA",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "localAuthority": "Westminster",
    "ofstedRating": "Good",
    "lastInspection": "2023-09-15",
    "numberOfPupils": 1200,
    "ageRange": {
      "from": 11,
      "to": 18
    },
    "website": "https://westminsteracademy.example.com",
    "telephone": "020 1234 5678",
    "headteacher": "Dr. Jane Smith",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-03-20T14:45:00Z"
  }
}

​
Filtering Options

Most endpoints support filtering via query parameters:
ParameterTypeDescriptionExample
statusstringSchool statusopen, closed
typestringSchool typeAcademy, Community
phasestringEducation phasePrimary, Secondary
ratingstringOfsted ratingOutstanding, Good
localAuthoritystringLocal authorityWestminster
minPupilsnumberMinimum pupils500
maxPupilsnumberMaximum pupils2000

​
Expanding Responses

Use the expand parameter to include related data: 
const school = await vepler.schools.get('sch_123', {
  expand: 'ratings,performance,catchment'
});
Available expansions:
  • ratings - Detailed Ofsted ratings
  • performance - Exam results and progress measures
  • catchment - Catchment area details
  • demographics - Pupil demographics
  • finance - Financial information

​
Pagination

List endpoints support cursor-based pagination: 
const schools = await vepler.schools.list({
  limit: 50,
  cursor: 'eyJpZCI6InNjaF8xMjMifQ=='
});

console.log(schools.pagination);
// {
//   cursor: 'eyJpZCI6InNjaF80NTYifQ==',
//   has_more: true,
//   total: 32000
// }

​
Error Responses

{
  "error": {
    "code": "SCHOOL_NOT_FOUND",
    "message": "School with ID 'sch_999' not found",
    "details": {
      "id": "sch_999"
    }
  }
}

​
Rate Limits

Schools API endpoints are subject to the following limits:
  • Standard endpoints: 1000 requests/hour
  • Search endpoints: 500 requests/hour
  • Metrics endpoints: 100 requests/hour

​
Use Cases

Include nearby school quality in property valuations:
const nearbySchools = await vepler.schools.searchNearby({
  latitude: property.latitude,
  longitude: property.longitude,
  radius: 1000,
  rating: 'Good,Outstanding'
});

const schoolScore = calculateSchoolScore(nearbySchools.data);
Analyze education provision in an area:
const areaSchools = await vepler.schools.searchWithin({
  polygon: boundaryCoordinates,
  type: 'Primary'
});

const metrics = await vepler.schools.metrics({
  schoolIds: areaSchools.data.map(s => s.id)
});
Compare schools for relocation decisions:
const schoolIds = ['sch_123', 'sch_456', 'sch_789'];

const comparisons = await Promise.all(
  schoolIds.map(id =>
    vepler.schools.get(id, { expand: 'ratings,performance' })
  )
);

​
Next Steps

Search Nearby Schools

Find schools near coordinates

School Metrics

Access performance data