Skip to main content

​
Overview

Search for schools within a defined geographic boundary (polygon). Useful for finding schools within specific postcodes, administrative areas, or custom-drawn boundaries.

​
Query Parameters

ParameterTypeRequiredDescription
polygonstringYesGeoJSON polygon coordinates (URL-encoded) or WKT format
statusstringNoSchool status: open, closed
typestringNoSchool type (e.g., Academy, Community)
phasestringNoEducation phase: Primary, Secondary
ratingstringNoOfsted rating: Outstanding, Good
localAuthoritystringNoFilter by local authority
limitnumberNoMaximum results (default: 50, max: 500)
cursorstringNoPagination cursor

​
Polygon Format

Provide polygon coordinates in one of these formats: 
{
  "type": "Polygon",
  "coordinates": [
    [
      [-0.1278, 51.5074],
      [-0.1278, 51.5174],
      [-0.1178, 51.5174],
      [-0.1178, 51.5074],
      [-0.1278, 51.5074]
    ]
  ]
}

​
WKT (Well-Known Text)

POLYGON((-0.1278 51.5074, -0.1278 51.5174, -0.1178 51.5174, -0.1178 51.5074, -0.1278 51.5074))

​
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"
      },
      "location": {
        "latitude": 51.5074,
        "longitude": -0.1278
      },
      "ofstedRating": "Good",
      "numberOfPupils": 1200
    }
  ],
  "search": {
    "areaKm2": 2.45,
    "resultsCount": 23
  },
  "pagination": {
    "cursor": "eyJpZCI6InNjaF9hYmMxMjMifQ",
    "hasMore": true,
    "total": 23
  }
}

​
Example Requests

​
Search by Postcode Area

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

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

// Get postcode boundary first
const postcode = await vepler.location.getPostcode('SW1A');

// Find schools within postcode
const schools = await vepler.schools.searchWithin({
  polygon: postcode.boundary,
  status: 'open'
});

console.log(`${schools.search.resultsCount} schools in ${postcode.outcode}`);

​
Search by Custom Boundary

const customArea = {
  type: 'Polygon',
  coordinates: [
    [
      [-0.1400, 51.5000],
      [-0.1400, 51.5200],
      [-0.1000, 51.5200],
      [-0.1000, 51.5000],
      [-0.1400, 51.5000]
    ]
  ]
};

const schools = await vepler.schools.searchWithin({
  polygon: JSON.stringify(customArea),
  phase: 'Primary',
  rating: 'Outstanding',
  limit: 100
});

​
Analyse Local Authority Provision

// Get local authority boundary
const authority = await vepler.location.getLocalAuthority('Westminster');

// Find all schools in authority
const schools = await vepler.schools.searchWithin({
  polygon: authority.boundary,
  status: 'open'
});

// Group by phase
const byPhase = schools.data.reduce((acc, school) => {
  acc[school.phase] = (acc[school.phase] || 0) + 1;
  return acc;
}, {});

console.log('Schools by phase:', byPhase);

​
Use Cases

Identify schools within specific catchment areas:
const catchmentSchools = await vepler.schools.searchWithin({
  polygon: catchmentBoundary,
  phase: 'Primary',
  status: 'open'
});
Assess school provision for new developments:
const existingSchools = await vepler.schools.searchWithin({
  polygon: developmentArea,
  phase: 'Primary,Secondary'
});

const pupilCapacity = existingSchools.data.reduce(
  (sum, school) => sum + school.numberOfPupils, 0
);
Analyse education infrastructure in areas:
const areaSchools = await vepler.schools.searchWithin({
  polygon: researchArea,
  status: 'open'
});

const ratings = areaSchools.data.reduce((acc, school) => {
  acc[school.ofstedRating] = (acc[school.ofstedRating] || 0) + 1;
  return acc;
}, {});

​
Performance Tips

  • Keep polygon complexity reasonable (< 100 vertices)
  • Use pagination for large areas
  • Consider radius search for simple circular areas
  • Cache results when boundaries don’t change frequently