# Similar Schools Nearby — Design **Date:** 2026-09-21 **Status:** awaiting review **Scope:** school detail pages, both phase templates ## Goal Give a school detail page an answer to the question every reader arrives with after the results tables: *and what else is around here?* Today a school page links outward to its place pages through `components/school/NearbyPlaces.tsx` and nowhere else. It never links to another school. This section adds that edge — up to six nearby schools of the same phase and a comparable intake, three at a time in a carousel, each a crawlable link and each addable to the comparison basket in one click. Mockup, with all three tier states live in both themes: Source of the same page in the repo: `mockups/similar-schools-nearby.html`. ## The constraint that shapes everything **A nearby school is not automatically a comparable school.** The section's whole value is that a reader treats what it shows as a shortlist. That makes every card an implicit claim that the school is a realistic alternative, and there are three ways that claim goes wrong: 1. A **selective** school beside a non-selective one. Their intakes are different by construction, so putting their Attainment 8 figures side by side invites a conclusion the data cannot support. 2. A **special school, PRU or AP** beside a mainstream school. This is the same error PR #70 fixed for the England benchmark, where Greenmead (URN 101099) rendered "0% — 62 below England". 3. A **single-sex** school of the opposite sex. Not a weak match — not an option at all. So the design separates two kinds of rule, and never confuses them: - **Hard filters** encode the claims above. They are never relaxed, at any distance, even if that means the section does not render. - **Soft preferences** describe how closely the intake resembles this school's. They relax in tiers, and the card's own text always states what survived. Everything below follows from that split. ## Selection algorithm A backend helper, `_similar_schools_payload(urn)` in `backend/app.py`, modelled on the existing `_places_payload(urn)` and operating on the cached `load_latest_school_data()` frame — one row per URN, already carrying `latitude`, `longitude`, `phase`, `gender`, `religious_denomination`, `admissions_policy`, `school_type` and `status`. ### Hard filters | Filter | Rule | |---|---| | Self | `urn` is excluded | | Status | GIAS status must be open | | Coordinates | both `latitude` and `longitude` present on both schools | | Phase | same phase group via the existing `PHASE_GROUPS` map | | Provision | special/PRU/AP match only each other | | Selectivity | selective matches selective; non-selective matches non-selective | | Gender | Boys never matches Girls; Mixed is compatible with both | `PHASE_GROUPS` is reused rather than re-derived so an all-through school is offered correctly on both the primary and secondary sides, exactly as it already behaves in search. The provision filter needs a backend counterpart to the frontend's `isSpecialSchool()` in `nextjs-app/lib/utils.ts:897`, reading the same GIAS establishment types through `backend/gias_codes.py`. The two must agree: a school the frontend treats as special for benchmarking but the backend treats as mainstream for matching would be dropped from its own England comparison and then offered as a peer to a mainstream school on the next page along. **Up to six cards, three visible.** Six is a cap, not a quota: the section shows every school that qualifies at the tiers it used, up to six. Three fit the row, and the rest are reached with the carousel arrows. Two is the minimum that renders at all. ### Soft preferences, relaxed in tiers | Tier | Additionally requires | Radius | |---|---|---| | 1 | exact gender equality **and** same religious character | 3 miles | | 2 | exact gender equality | 5 miles | | 3 | nothing beyond the hard filters | 10 miles | **Tiers relax to reach a usable set, never to fill the last slots.** Work down the tiers until the schools found so far reach three. Call the tier that got there T. The section then shows up to six schools drawn from tiers 1 to T, nearest first — and does not open tier T+1 merely because six slots are not yet full. Worked through: | Qualifying | T | Shown | |---|---|---| | 14 at tier 1 | 1 | the 6 nearest tier-1 schools | | 4 at tier 1 | 1 | all 4 — tier 2 is never opened | | 2 at tier 1, 7 more at tier 2 | 2 | the 6 nearest of those 9 | | 2 at tier 1, 1 at tier 2 | 2 | all 3 | | 2 across all three tiers | 3 | both, since 2 is the minimum | Without that stopping rule, a cap of six would reliably drag in tier-3 schools ten miles away to fill a row that three good matches had already earned. The old cap of three hid this; six exposes it, which is why the rule is stated rather than left to the loop. **Faith relaxes before gender.** A faith mismatch changes the character of a school; a gender mismatch can mean the school is not available to the reader's child at all. Ordering them the other way would fill the section with schools that cannot be applied to. ### Two decisions that are easy to get wrong later **Selected by tier, displayed by distance.** Tier decides *which* three schools earn a slot. The rendered order is then distance ascending, because "nearby" is the promise in the heading and a reader scanning the row reads the first card as the closest. A tier-2 school at 0.4 miles therefore appears above a tier-1 school at 2.9 miles, and the chips explain the difference in match quality. **Past the sixth school, the rest are dropped without a count.** In inner London dozens clear tier 1, and a parent there will notice three is not the neighbourhood — hence six. Beyond that the section does not try to be the list: `NearbyPlaces` sits directly beneath and already leads to the place pages, which are built for browsing a full set and which the school page exists to feed. **Fewer than two results renders nothing.** Not an empty state, not a single lonely card, not padding with schools that failed the hard filters. The section is absent, the nav item is absent, and the page is unchanged from today. A page with one weak match is better off without the section than with it. ### Distance Straight-line, from the vectorised haversine already used for postcode search at `backend/app.py:831`, computed over the ~27k-row frame in numpy. Reported to one decimal place in miles, consistent with the rest of the site. Straight-line distance is not road distance and is not measured from the reader's home. The section says so in its disclosure rather than leaving the reader to assume otherwise. ## API `/api/schools/{urn}` gains a `similar_schools` array. Each row: | Field | Notes | |---|---| | `urn` | for the link and the compare basket | | `school_name` | link text | | `distance_miles` | one decimal place | | `school_type` | GIAS type, translated, for the card's meta line | | `age_range` | for the meta line | | `shared` | the chip strings the tier actually justifies — see below | | `tier` | 1, 2 or 3 — drives the lede's wording and the chip styling | | `metric_value` | the phase-appropriate headline figure, or null | | `metric_key` | `rwm_expected_pct` or `attainment_8_score` — see below | | `metric_year` | the year the figure is from | The metric follows the template the page is rendering, not the neighbour's own phase, so a row of cards never mixes two scales. Primary and **all-through** pages use `rwm_expected_pct`, matching `PrimarySchoolSections`, which is the template all-through schools render with; secondary pages use `attainment_8_score`. Where the neighbour has no value for that key, the card reads "Not published" rather than falling back to the other key. `tier` is carried explicitly rather than inferred from the contents of `shared`, because the frontend needs it for two separate decisions — whether the lede may claim a similar intake, and whether a chip renders as a brand-tinted fill or a muted outline — and inferring it from chip count would couple those decisions to the copy. Up to six rows of roughly 130 bytes each. It rides in the existing detail payload rather than a new endpoint because the page already makes exactly one server fetch for its data, and `/school/[slug]` regenerates at most weekly (`revalidate = 604800`), so the per-request cost is paid once per school per week. **The key is absent, not null, on a backend that does not have this code.** The frontend treats absent and empty identically, which is what allowed `NearbyPlaces` to ship without a lockstep deploy of the two images. `shared` is computed on the backend beside the tier that produced it, not re-derived on the frontend. Deriving it twice is how a card comes to claim a match the selection did not actually make. ## Frontend ### Components `components/school/SimilarSchoolsSection.tsx` — a server component wrapped in the shared `Section` shell from `sectionShared.tsx`. It renders the heading, the lede, the card grid, the footer CTA and one caption line. Every card's title is an `` to the school's canonical slug URL via `schoolUrl()`. `components/school/AddToCompareButton.tsx` — calls `addSchool` from `ComparisonProvider` and reports the selection with a `from: 'similar_schools'` attribution, mirroring `addSchoolFromSearch` in `HomeView.tsx:442`. `components/school/SimilarSchoolsCarousel.tsx` — the scroller and its arrows. It takes the server-rendered cards as `children` and the server-rendered heading and lede as a `header` prop, so those stay server components while the client component owns only the ref, the scroll handler and the arrows' disabled state. The split matters: the links — the part with SEO value and the part that must work without JavaScript — are server-rendered into the initial HTML, and only the basket interaction and the arrows are hydrated. ### The carousel **Every card is in the initial HTML.** The arrows scroll a list; they never swap a view. Six `` elements are in the markup whether or not anything is hydrated, which is the whole reason the section exists — a paginated widget that mounts cards on click would put four of the six links beyond a crawler and beyond a reader with no JavaScript. So the scroller is a plain overflowing `