# Other Schools Nearby — Design **Date:** 2026-09-21, revised 2026-09-22 **Status:** revised after staging review **Scope:** school detail pages, both phase templates > **Revision, 2026-09-22.** The first build ranked by intake similarity and used > distance as a tiebreak. On staging a Catholic primary showed six Catholic > primaries, none of them close enough to be a real option, and omitted the > community school down the road. Distance now decides the order and nothing > else does; the tier system is gone. The reasoning is kept below rather than > quietly overwritten, because the mistake is the instructive part. ## 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, in both themes (drawn against the original tiered design, so its ledes and chip fallbacks are one revision behind the copy specified below): 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 fact, and never confuses them: - **Hard filters** encode the claims above. They decide eligibility, and are never relaxed at any distance, even if that means the section does not render. - **Shared characteristics** — gender, religious character, selectivity — describe how closely an intake resembles this school's. They are *reported on the card and never ranked on*, so the reader weighs them rather than having them weighed for them. Everything below follows from that split. The revision at the top of this document is what happens when the second kind is treated as the first. ## Selection algorithm A backend helper, `_nearby_schools_payload(urn)` in `backend/app.py`, modelled on the existing `_places_payload(urn)` and delegating to `backend/nearby_schools.select_nearby(frame, urn)`, which operates 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.** Three fit the row; the rest are reached with the carousel arrows. Two is the minimum that renders at all. ### Order: distance, and nothing else The nearest eligible schools, closest first. Similarity does not enter the ranking at any point. **Why not, having built it the other way first.** The original design ranked by tiers — same gender and faith within 3 miles, then same gender within 5, then anything within 10 — and used distance only to order the result. Two things followed, and both showed up on the first Catholic primary anyone looked at: - A faith match at 2.9 miles outranked a community school at 0.3 miles. For a primary, whose catchment is routinely under a mile, the far school is not a weaker option; it is not an option. - Because the row filled from the best tier before widening, three Catholic schools within 3 miles were enough to fill all six slots with Catholic schools. The stopping rule that produced this had been added to prevent the *opposite* failure — padding a row with weak distant matches — and made this one certain. The premise was backwards. **Distance is a constraint and intake is a preference.** A parent cannot act on a school outside their reach however well it matches, and they are perfectly capable of noticing a shared denomination for themselves if we show it to them. So similarity moved from the ranking to the card: `shared` reports what a school genuinely has in common, and the reader applies their own weighting. The hard filters above were always where the defensibility lived. They are untouched. ### Reach: a sanity bound, not a target | Phase | Reach | |---|---| | Primary, middle deemed primary, all-through | 2 miles | | Secondary, middle deemed secondary | 6 miles | | 16 plus | 10 miles | Ordering by distance already handles density — a school in inner London fills all six slots inside a mile and never approaches the cap. The cap decides one thing: what happens where the area is sparse. It differs by phase because catchments do, and because people travel furthest for post-16. **A primary with nothing inside two miles renders no section**, and that is the intended answer rather than a gap. The alternative is a section headed "nearby" listing a school four miles from a five-year-old. **Past the sixth school, the rest are dropped without a count.** 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. The section is absent, the nav item is absent, and the page is unchanged from before it existed. ### 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` | what this school genuinely shares with the subject; may be empty | | `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 subject school's phase side, not the neighbour's own phase, so a row of cards never mixes two scales. The secondary side uses `attainment_8_score`; the primary side uses `rwm_expected_pct`. Where the neighbour has no value for that key, the card reads "Not published" rather than falling back to the other key. Which side a school takes is decided once, in `similar_schools.is_secondary_phase`, by membership of `PHASE_GROUPS["secondary"]` minus all-through — never by testing for the substring "secondary", which misses `16 plus` (GIAS phase 6) and hands a sixth-form college the primary bucket. All-through is the exception in the other direction: `PHASE_GROUPS` lists it on both sides, but it takes the primary metric. This is usually the same thing as "the template the page renders", but not always. `computeSchoolFlags` decides the template with that same substring test, so a `16 plus` school renders `PrimarySchoolSections` while being matched — correctly — against secondaries. The section therefore takes its lede noun from the school's own phase rather than from its template, or it would print "Other primary schools near " above a row of secondaries. 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 data it is derived from, not re-derived on the frontend. Deriving it twice is how a card comes to claim something the selection never established. An empty list is a real answer and renders no chips: a bare card costs a school nothing but the likeness it does not have, since the order was already settled by distance. ## 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 `