Docs/Place Data Format

Place Data Format

The JSON schema for data/places/*.json: every field, the id-prefix convention, and the 6 place types.

StudentSuite Team · 2026-08-22 · 3 min read

The JSON schema behind every entry in data/places/<type>.json. For the GitHub issue/PR process itself, see Contributing Places instead - this page is only about the data shape.

The 6 place types

One JSON file per type, under data/places/

File	Type key	Label
library.json	library	Library
other_places.json	other_places	Other places
airport.json	airport	Airport
sat_centre.json	sat_centre	SAT centre
foreign_lang_exam_centre.json	foreign_lang_exam_centre	Foreign lang exam centre
gov_offices.json	gov_offices	Government offices

Fields

Generated from data/places.schema.json, the file scripts/validate-places.mjs validates every record against

idstringrequired<city-prefix>-<type>-<number>, unique within the file, e.g. mum-library-07

namestringrequired

typestringrequiredMust match the filename it lives in, e.g. data/places/library.json -> "library"

citystringrequiredLowercase, underscore-separated slug, e.g. "mumbai", "navi_mumbai". Any city worldwide is welcome, not a fixed enum.

latnumberrequiredRange: -90 to 90.

lngnumberrequiredRange: -180 to 180.

addressstringoptionalOptional, short, human-readable

gmaps_linkstringrequiredA Google Maps link (maps.google.com, maps.app.goo.gl, or a full google.com/maps URL).

added_bystringrequiredGitHub username of the contributor

verifiedobjectoptionalOptional proof a contributor re-checked this place. Verified places show a badge. Expiry: 12 months, or 6 months for exam centres (sat_centre / foreign_lang_exam_centre); see data/CONTRIBUTING.md.

examstringoptionalOptional. Only for sat_centre / foreign_lang_exam_centre, e.g. "SAT", "IELTS", "Goethe-Zertifikat (A1-C2)"

valid_tillstringoptionalOptional. Only for sat_centre / foreign_lang_exam_centre. ISO date (YYYY-MM-DD) the entry should be reconfirmed by.

Nothing outside this list is allowed on a committed record - proof of quality (source, rating, review count, verified date) goes in the pull request only.

Example record

{
  "id": "mum-library-07",
  "name": "City Library, Dadar branch",
  "type": "library",
  "city": "mumbai",
  "lat": 19.0176,
  "lng": 72.8562,
  "address": "Gate 2, Gokhale Road, Dadar West",
  "gmaps_link": "https://maps.app.goo.gl/xxxx",
  "added_by": "your-github-handle"
}

ID prefix convention

<city-prefix>-<type>-<number>

The prefix is a short slug for the city (e.g. mum, thane, jkt), and the number increments from the highest one already used for that prefix in the same file - never reuse an ID.

A handful of older bulk-imported entries don't follow this exact format (see Data Sources & Provenance), but every new place should.

Adding a new field?

Update the schema, not just the docs

If a place type ever needs a new field, add it to data/places.schema.json first. This page and scripts/validate-places.mjs read that file directly, so they update automatically - only data/CONTRIBUTING.md needs a manual edit to match.

Ready to use what you just read?

Open the map Check the calendar