01 / THE BOUNDARY
This is not a hosted API.
The repository publishes a schema, station directory, and source registry. A conforming client reads those static files, contacts the named operator from the end user’s device, and maps the response locally.
Just-Go does not provide a server endpoint that republishes mainland operator responses. That boundary is part of the data-rights model, not an implementation gap.
02 / CONTRACT FILES
Three layers make one client.
| File | Role | Maintained |
|---|---|---|
schema/station-information.schema.json | Defines the normalized response shape for lines, exits, facilities, provenance, and timestamps. | By hand |
directory/directory.json | Maps 1,598 canonical station IDs to one reviewed source and external station key. | Generated |
sources/sources.json | Describes each operator request, identity check, field mapping, and placeholder rule. | By hand |
03 / CALL FLOW
Resolve, fetch, verify, map.
Look up the canonical station ID in the directory and read its source name and reviewed external key.
Use the source registry for the fixed host, request method, response type, and mapping rules.
Reject the response unless its operator name or identifier matches the reviewed station record.
Map permitted fields into the shared schema. Placeholders become missing values, not invented facts.
04 / COVERAGE
Five stable source recipes.
| Source | Directory entries | Normalized fields | Access model |
|---|---|---|---|
| Beijing Subway | 416 | Lines, exits, facilities | On-device operator fetch |
| Shanghai Metro | 415 | Lines, exits, facilities | On-device operator fetch |
| Guangzhou Metro | 346 | Lines | On-device operator fetch |
| Hangzhou Metro | 259 | Lines | On-device operator fetch |
| MTR / DATA.GOV.HK | 162 | Exits, facilities, live arrivals | Bundled static data + live government API |
05 / DEVICE CACHE
Offline fallback without re-hosting.
Round 36 adds a device-only last-good cache for Beijing station information.
- Local onlyStored under Application Support and excluded from backup.
- BoundedEach entry is limited to 1 MB and guarded by a schema version.
- LabeledFallback content says it was saved on this device and shows its update age.
- User-clearableSettings → Clear Cache deletes every stored station-information snapshot.
06 / FAILURE RULES
Unavailable is different from invalid.
Offline, timeout, rate limit, or server error may use a valid stored snapshot when one exists.
A malformed response never falls back silently; it is rejected.
A response for the wrong station never uses cache as cover.
Online station details never decide route feasibility, route planning, or route confidence.