Skip to content

Schools

Property pages list the schools closest to a property. The schools come from OpenStreetMap, which in New Zealand carries the Ministry of Education’s school number, year levels, authority and gender for almost every state, state-integrated and private school.

Geofabrik extract (.osm.pbf)
│
▼
connectors -mode schools-sync ──► POST /connectors/schools/batch ──► schools table (PostGIS)
osmschools: extract → classify → dedupe │
▼
GET /api/v1/properties/{id}/nearby-schools
│
▼
Nearby Schools card (pillow-app)

connectors/schools/osmschools reads an extract in up to three passes: school features first, then the member ways of school relations, then the coordinates of the nodes those ways use. Ways and relations are placed at the centroid of their nodes.

Every amenity=school feature with a name is classified:

Field Source tags
Type MOE:years or grades (NZ: Years 1–8 primary, 7–8 intermediate, 9–13 or 7–13 secondary, 1–13 composite, special), then isced:level, school=*, and finally the name (“Intermediate”, “College”, “Area School”, …)
Authority MOE:authority (State, State : Integrated, Private, Charter) or operator:type
Gender MOE:gender, school:gender
School number MOE:id (NZ, linked to the Education Counts profile) and ref:edubase (GB, linked to Get Information about Schools)
Website, phone, address website, contact:*, addr:*

Tutoring businesses, driving and swim schools, hostels and disused schools are dropped. Features that describe one school, such as a point inside the school grounds, are merged when they share a name or school number within 1 km; the grounds polygon is kept and missing fields are filled from the duplicates. In countries whose register numbers are tagged (New Zealand and Great Britain), a merged school with neither a number nor a recognisable type is dropped.

The New Zealand extract yields about 2,540 schools: 1,745 primary, 349 secondary, 140 composite, 123 intermediate, 26 special and 160 others (schools without year levels tagged, such as Kura Kaupapa Māori, small rural schools and private Christian schools).

Terminal window
cd connectors
# Download the default region (australia-oceania/new-zealand) and print schools
go run . -mode schools-sync -dry-run -output /tmp/schools.jsonl
# Use a local extract and send to a local Mill
go run . -mode schools-sync -schools-pbf /tmp/new-zealand-latest.osm.pbf -mill-api http://localhost:4000
Flag Purpose
-schools-region Comma-separated Geofabrik regions. Append :CC when the country cannot be inferred.
-schools-pbf Read a local extract instead of downloading
-schools-country Country code for -schools-pbf
-schools-data-dir Where downloads are kept while they are processed (they are deleted afterwards)
-schools-batch-size Schools per Mill request (default 500, Mill accepts up to 2,000)

k8s/connectors/schools-sync-cronjob.yaml runs the sync every Sunday at 04:00 NZT.

Migration 17 creates the schools table, unique on (source, source_id), with a PostGIS point and a GiST index.

Endpoint Purpose
POST /connectors/schools/batch Up to 2,000 schools and/or a sync marker. Needs a service token with the connector role. Invalid records are reported per row; the rest are stored.
GET /api/v1/properties/{id}/nearby-schools Schools near a property, closest first. radius_m defaults to 5,000 (max 25,000) and limit to 8 (max 25). 404 when the property does not exist.

The connector sends the sync marker only after every batch of a region has been delivered. Mill then deletes that source and country’s schools that were not seen since the sync started, so schools removed from OpenStreetMap disappear. Nothing is deleted if no school was seen during the sync.

The nearby list always includes the closest primary, intermediate, secondary and composite school within the radius, then fills the remaining places with the next nearest schools of any type.

The Nearby Schools card on property pages shows each school’s name, level, year range, authority (State, State-integrated, Private), gender and special character, with the straight-line distance and an estimated walking time under 2.5 km. Links go to the Ministry of Education profile and the school’s website. The card credits OpenStreetMap contributors, as the ODbL licence requires.

Deciles were replaced by the Equity Index in 2023 and are no longer shown. Enrolment zones are not yet included, so the card reminds buyers to check zones with each school.