Skip to main content

Overview

Returns a paginated list of schools across the UK. Supports filtering by various criteria including status, type, phase, and Ofsted ratings.

Query Parameters

ParameterTypeRequiredDescription
limitnumberNoResults per page (default: 20, max: 100)
cursorstringNoPagination cursor
statusstringNoSchool status: open, closed
typestringNoSchool type (e.g., Academy, Community)
phasestringNoEducation phase: Primary, Secondary
ratingstringNoOfsted rating: Outstanding, Good, Requires Improvement, Inadequate
localAuthoritystringNoLocal authority name
minPupilsnumberNoMinimum number of pupils
maxPupilsnumberNoMaximum number of pupils

Response

{
  "data": [
    {
      "id": "sch_abc123",
      "urn": "100000",
      "name": "Westminster Academy",
      "slug": "westminster-academy",
      "type": "Academy",
      "phase": "Secondary",
      "status": "Open",
      "address": {
        "line1": "123 School Street",
        "town": "London",
        "postcode": "SW1A 2AA",
        "county": "Greater London"
      },
      "location": {
        "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"
    }
  ],
  "pagination": {
    "cursor": "eyJpZCI6InNjaF9hYmMxMjMifQ",
    "hasMore": true,
    "total": 32000
  }
}

Example Requests

List All Schools

import { Vepler } from '@vepler/sdk';

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

const schools = await vepler.schools.list({
  limit: 50
});

console.log(`Found ${schools.pagination.total} schools`);

Filter by Ofsted Rating

const topSchools = await vepler.schools.list({
  rating: 'Outstanding',
  phase: 'Primary',
  limit: 100
});

Filter by Local Authority

const localSchools = await vepler.schools.list({
  localAuthority: 'Westminster',
  status: 'open',
  minPupils: 500
});

Pagination Example

let cursor = null;
const allSchools = [];

do {
  const response = await vepler.schools.list({
    limit: 100,
    cursor,
    status: 'open'
  });

  allSchools.push(...response.data);
  cursor = response.pagination.cursor;
} while (response.pagination.hasMore);

console.log(`Total schools: ${allSchools.length}`);