Widget Documentation
Add nearby school data to your property listing pages with just two lines of HTML.
Quick Start
Paste the following into your property listing page template, replacing SW18 1SSwith the property’s postcode (from your CMS or listing data):
<div id="school-atlas-widget" data-postcode="SW18 1SS"></div>
<script src="https://www.schoolatlas.co.uk/widget/school-atlas-widget.js" async></script>The script loads asynchronously and will not block your page from rendering. It creates a shadow DOM inside the container div to prevent any style conflicts with your existing CSS.
Configuration
All configuration is done via data- attributes on the container div. Only data-postcode is required.
| Attribute | Default | Description |
|---|---|---|
data-postcode | — | Required. UK postcode for the property. |
data-limit | 8 | Maximum number of schools to display (1–20). |
data-phases | all | Comma-separated list of school phases to include:primary, secondary, nursery. |
data-key | — | API key (optional during beta). |
data-accent | #4f46e5 | Accent colour (hex). Used for tabs, links, and branding. |
data-font | system font | CSS font-family value (e.g. Georgia, serif). |
data-radius | 8 | Border radius in pixels. |
data-theme | auto | light, dark, or auto(follows user’s system preference). |
Examples
Primary schools only, green accent
<div id="school-atlas-widget"
data-postcode="SW11 5AL"
data-phases="primary"
data-accent="#059669"
data-limit="5"></div>
<script src="https://www.schoolatlas.co.uk/widget/school-atlas-widget.js" async></script>Dark theme with custom font
<div id="school-atlas-widget"
data-postcode="SE1 7QY"
data-theme="dark"
data-font="'Playfair Display', serif"
data-radius="12"></div>
<script src="https://www.schoolatlas.co.uk/widget/school-atlas-widget.js" async></script>Advanced CSS Customisation
The widget uses shadow DOM, so your page styles cannot leak in. However, you can override internal tokens using CSS custom properties on the container:
#school-atlas-widget {
--sa-accent-color: #0ea5e9;
--sa-font-family: 'Inter', sans-serif;
--sa-border-radius: 12px;
}API Reference
The widget calls the School Atlas API internally. You can also use the API directly if you want to build a custom integration.
GET /api/widget/schools
| Parameter | Type | Description |
|---|---|---|
postcode | string | UK postcode (required) |
limit | number | Max results (1–20, default 8) |
phases | string | Comma-separated phase filter |
key | string | API key (optional during beta) |
Response format
{
"postcode": "SW18 1SS",
"latitude": 51.4465,
"longitude": -0.1928,
"total": 8,
"schools": [
{
"urn": 101234,
"name": "Example Primary School",
"slug": "example-primary-school",
"phase": "primary",
"type": "Community school",
"is_private": false,
"postcode": "SW18 2AB",
"distance_miles": 0.3,
"ofsted_grade": "Outstanding",
"ofsted_rating": 1,
"la_name": "Wandsworth",
"latitude": 51.4470,
"longitude": -0.1935
}
],
"attribution": "Powered by School Atlas"
}Rate limits
During the beta period, requests are rate-limited to 100 per hour per IP address. If you exceed this limit, the API returns a429 status with a Retry-After header.
CORS
The API supports CORS from all origins, so the widget can be embedded on any domain.
FAQ
Does the widget slow down my page?
No. The script loads asynchronously and the widget renders after your page content. It makes a single API call and the response is cached for one hour.
Will it conflict with my CSS?
No. The widget uses shadow DOM to fully encapsulate its styles. Your CSS cannot affect the widget and the widget cannot affect your page.
What data does it show?
School name, distance from the postcode, Ofsted inspection grade, and school phase (Primary, Secondary, Nursery). All data comes from official government sources (GIAS and Ofsted).
How do I get an API key?
During the beta, no API key is required. When we launch paid plans, you will receive an API key when you subscribe. Contact hello@schoolatlas.co.uk to register your interest.
Can I use multiple widgets on one page?
Currently the widget targets the #school-atlas-widget element ID, so only one instance per page is supported. Contact us if you need multiple widgets on a single page.
Support
For technical questions, integration help, or to report a bug, email hello@schoolatlas.co.uk.