← Back to Widget

Widget Documentation

Embed live, four-nation UK school data on any site — for estate agents and property portals, schools’ own websites, and local press or community pages. Two lines of HTML, no build step.

Quick Start

Drop a container element on your page and include the script once. The script auto-initialises every container, loads asynchronously (never blocking your page), and renders inside a shadow DOM so your styles and the widget’s never collide.

<div data-school-atlas="nearby" data-postcode="SW18 1SS"></div>
<script src="https://www.schoolatlas.co.uk/widget/school-atlas-widget.js" async></script>

The legacy form <div id="school-atlas-widget" data-postcode="…"> still works and is automatically upgraded — existing embeds need no changes.

Widget types

Choose a variant with the data-school-atlas attribute:

You can place as many widgets as you like on one page — each container is initialised independently.

Four-nation inspection grades

Every school shows the grade from its owninspectorate — Ofsted (England), Estyn (Wales), Education Scotland, ETI (Northern Ireland), and ISI (independents) — never a wrong-nation label. Where an inspectorate doesn’t publish a summative grade (e.g. Estyn since Sept 2024), the widget shows “Inspected by Estyn” rather than inventing one (verified-source-or-NULL).

Configuration

All configuration is done via data- attributes on the container.

Examples

Single school profile

<div data-school-atlas="school" data-urn="101043"></div>
<script src="https://www.schoolatlas.co.uk/widget/school-atlas-widget.js" async></script>

Verified badge for a school’s own site

<div data-school-atlas="badge" data-urn="101043"></div>
<script src="https://www.schoolatlas.co.uk/widget/school-atlas-widget.js" async></script>

Nearby primary schools, green accent

<div data-school-atlas="nearby"
  data-postcode="SW11 5AL"
  data-phases="primary"
  data-accent="#059669"
  data-limit="6"></div>
<script src="https://www.schoolatlas.co.uk/widget/school-atlas-widget.js" async></script>

Versioning & integrity

The default URL above is evergreen: we ship only backward-compatible changes to it, so your embed stays current automatically. Breaking changes will ship under a new path (e.g. /widget/v2/) — existing embeds are never broken.

If your site requires Subresource Integrity (a pinned hash), use the immutable /widget/v1/ build:

<script
  src="https://www.schoolatlas.co.uk/widget/v1/school-atlas-widget.js"
  integrity="sha384-U51vL6vld3sgWfvcyakwwp3ss9IDCfLB3CIq14J3cLgCDtnaCq6qYpR/J/qBq9Rg"
  crossorigin="anonymous" async></script>

The pinned build is frozen, so SRI never breaks — but it does not receive new features. Most sites should use the evergreen URL.

API Reference

The widget calls these public endpoints internally; you can also call them directly. Both are GET, CORS-open, and rate-limited to 100 requests/hour per IP during beta (higher with a key).

GET /api/widget/schools

Params: postcode (required), limit(1–20, default 12), phases, key.

GET /api/widget/school

Params: urn or slug (one required), key. Returns a single school.

Response (schools)

{
  "postcode": "EH1 1RE",
  "total": 12,
  "schools": [
    {
      "urn": 5512345,
      "name": "Example High School",
      "slug": "example-high-school",
      "phase": "secondary",
      "is_private": false,
      "distance_miles": "0.4",
      "nation": "scotland",
      "inspectorate": "Education Scotland",
      "grade_label": "Very Good",
      "grade_value": 5,
      "grade_color": "#059669",
      "inspected": true,
      "report_url": "https://…",
      "profile_url": "https://www.schoolatlas.co.uk/edinburgh/schools/example-high-school",
      "la_name": "City of Edinburgh"
    }
  ],
  "attribution": "Powered by School Atlas"
}

ofsted_grade / ofsted_ratingare also returned for England (back-compatibility). Only public, non-gated school data is served — CORS origin is not an access boundary.

FAQ

Does the widget slow down my page?

No. The loader is ~7 KB gzipped, loads asynchronously, reserves its space before rendering (no layout shift), and times out gracefully if our API is slow — it never blocks or breaks your page.

Will it conflict with my CSS?

No. Each widget renders in its own shadow DOM, so your CSS can’t affect it and it can’t affect your page. It’s also keyboard- accessible and honours prefers-reduced-motion.

Can I use multiple widgets on one page?

Yes. The script initialises every [data-school-atlas] element (and the legacy #school-atlas-widget) independently, so you can mix variants freely on one page.

How do I get an API key?

Keys are free during beta and self-serve: go to Account › Widget Embeds, enter your site’s domain, and generate a key. Keys are pinned to that domain and unlock per-embed analytics (impressions → clicks).

What data does it show?

School name, distance, phase, state/independent status, and the nation-correct inspection grade. Data comes from official sources — GIAS/Ofsted (England), Estyn & Stats Wales, Education Scotland & the Care Inspectorate, DE NI & ETI, and ISI for independents.

Support

For technical questions, integration help, or to report a bug, email hello@schoolatlas.co.uk.

Try the interactive configurator →