{"openapi":"3.1.0","info":{"title":"Moca Platform API","version":"0.1.0","summary":"P7 read API for MocaMap places, nearby, parking, routes, and transit.","description":"Web clients must call this API instead of Photon, Valhalla, Nominatim, OSM search, or Transitous APIs. Missing upstream coverage returns 502 or an empty list and never fabricates records.","license":{"name":"ODbL attribution required for OSM-derived results"}},"servers":[{"url":"https://maps.gotooi.com/api/v1"}],"paths":{"/health":{"get":{"summary":"Worker health","responses":{"200":{"description":"API process is up"}}}},"/cities":{"get":{"summary":"Curated GeoNames city directory with honest transit coverage summaries","responses":{"200":{"description":"Curated cities with GeoNames ids (CC BY). Not cities5000.zip and not a top-5000 fame ranking. Transit summary is derived from per-operator feeds."}}}},"/cities/search":{"get":{"summary":"Search the curated city directory","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Subset of the curated directory. Full GeoNames dump import is a later ops step."}}}},"/cities/{id}":{"get":{"summary":"City detail plus derived coverage","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"City record and feed coverage"},"404":{"description":"Unknown city id — never invented"}}}},"/cities/{id}/coverage":{"get":{"summary":"Per-operator transit coverage for a city","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Feeds with schedule/realtime status labels. One feed is never reported as city-wide live transit. Global OTP is a federation of regional graphs under /journeys — not one planet process."},"404":{"description":"Unknown city id"}}}},"/places":{"get":{"summary":"Search places or look up a batch of Moca place ids","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"ids","in":"query","schema":{"type":"string"},"description":"Comma-separated Moca place ids. Cannot be combined with q. Max 20."},{"name":"region","in":"query","schema":{"enum":["TW","HK","WORLD"]},"description":"Omit or WORLD for worldwide Photon search without countrycode/bbox. TW/HK still apply the regional gate."},{"name":"lat","in":"query","schema":{"type":"number"},"description":"Optional origin latitude; with lng enables distance term in unified ranking."},{"name":"lng","in":"query","schema":{"type":"number"},"description":"Optional origin longitude; with lat enables distance term in unified ranking."},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Moca places from unified ranked merge (HK Location Search / Photon / optional Pelias / Google). Each place may include optional altNames / addressAlt from real upstream bilingual fields only — never invented. ids= lookup is identity-preserving; invalid ids in a batch are skipped. No fake places."},"400":{"description":"Invalid query"},"502":{"description":"Photon unavailable; no fake places"}}}},"/places/{id}":{"get":{"summary":"Get a place by Moca ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Place bound to the requested Moca id (OSM type+id). Photon reverse may fill the name when it is the same OSM object; otherwise OSM element tags are used. A nearby different object is not substituted. Cache-Control max-age=300."},"400":{"description":"Invalid id"}}}},"/nearby":{"get":{"summary":"Nearby places and/or parking snapshot","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number"}},{"name":"radiusMeters","in":"query","schema":{"type":"integer"}},{"name":"include","in":"query","schema":{"type":"string","example":"place,parking"}}],"responses":{"200":{"description":"Nearby results with coverage notes"}}}},"/parking":{"get":{"summary":"Parking snapshot (Tainan motorcycle lots), a map bbox, or a batch of Moca parking ids","parameters":[{"name":"city","in":"query","schema":{"enum":["tpe","tnn","hkg"]}},{"name":"ids","in":"query","schema":{"type":"string"},"description":"Comma-separated Moca parking ids. Cannot be combined with city, lat/lng, or bbox. Max 20."},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"radiusMeters","in":"query","schema":{"type":"integer"}},{"name":"west","in":"query","schema":{"type":"number"},"description":"Bbox west longitude. Must be sent with south, east, north."},{"name":"south","in":"query","schema":{"type":"number"}},{"name":"east","in":"query","schema":{"type":"number"}},{"name":"north","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Snapshot lots; occupancyLive is always false. Batch ids skip invalid/unknown/uninhabited-city tokens. Bbox returns Tainan lots inside the rectangle; a Taipei/HK view is an honest empty list. Each lot includes canonical maps.gotooi.com links."},"400":{"description":"ids/city/lat/lng mixed with each other or with bbox; incomplete or inverted bbox"}}}},"/parking/{id}":{"get":{"summary":"One parking snapshot record","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Parking site with canonical map and /parking/?id= links"},"404":{"description":"Not in catalog"}}}},"/routes":{"get":{"summary":"Route (walk, bicycle, motorcycle, drive, transit, ferry, mixed)","parameters":[{"name":"fromLat","in":"query","required":true,"schema":{"type":"number"}},{"name":"fromLng","in":"query","required":true,"schema":{"type":"number"}},{"name":"toLat","in":"query","required":true,"schema":{"type":"number"}},{"name":"toLng","in":"query","required":true,"schema":{"type":"number"}},{"name":"mode","in":"query","schema":{"enum":["walk","bicycle","motorcycle","drive","transit","ferry","mixed"]}},{"name":"preference","in":"query","schema":{"enum":["fastest","safest","lowest_cost","least_walking","least_transfers","easiest_parking","accessible"]},"description":"Road modes: fastest/lowest_cost/safest map to Valhalla costing_options; others unsupported (no fake guarantee). Transit uses client/OTP ranking only."},{"name":"tolls","in":"query","schema":{"enum":["avoid","normal"]},"description":"Optional. avoid overlays use_tolls=0 + toll_booth_penalty (not guaranteed). Invalid values → 400. Ignored for walk/bicycle/ferry with a note."}],"responses":{"200":{"description":"Valhalla (walk/bike/moto/drive/ferry OSM). Road modes include meta.{preference,tolls,preferenceApplied,notes}. item.restrictions copies Valhalla trip.summary has_toll/has_highway/has_ferry only when present. Transit/mixed prefers same-region OTP when a federation graph URL is configured, else Transitous MOTIS. alternatives are real upstream itineraries only."},"400":{"description":"Invalid query (including tolls not avoid|normal)"},"502":{"description":"Upstream unavailable or no coverage; no fake route"}}}},"/journeys":{"get":{"summary":"Global OTP federation entry — regional graphs by bbox, optional MOTIS fallback","parameters":[{"name":"fromLat","in":"query","required":true,"schema":{"type":"number"}},{"name":"fromLng","in":"query","required":true,"schema":{"type":"number"}},{"name":"toLat","in":"query","required":true,"schema":{"type":"number"}},{"name":"toLng","in":"query","required":true,"schema":{"type":"number"}},{"name":"mode","in":"query","schema":{"enum":["transit","mixed","ferry"]}},{"name":"fallback","in":"query","schema":{"enum":["motis","none"]},"description":"When OTP cannot cover the trip (offline graph, cross-region, uncovered). Default motis."},{"name":"preference","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Same-region OTP itineraries when the regional graph URL is set. Cross-region stitching is not invented in v1 — use fallback=motis or receive 502 with federation details."},"400":{"description":"Invalid query"},"502":{"description":"No OTP coverage / graph offline / upstream error; no fake journey"}}}},"/transit":{"get":{"summary":"Nearby OSM stations plus Hong Kong stop ETAs and Transitous MOTIS stop times","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Photon OSM stations; Hong Kong KMB/LWB + Citybus + GMB stop ETAs and MTR Next Train (official public APIs, Worker-side 15–30s cache); plus Transitous reverse-geocode + stoptimes. Macau DSAT scaffold returns empty departures with meta.macauDsat reason codes until authorised ETA mapping — never invented minutes. realtime=true only for live predictions (never timetable remarks). Stop ETAs are not A-to-B journey times. Not worldwide line ownership."}}}},"/transit/nearby":{"get":{"summary":"Nearby HK operator stops for markers / place panel (no ETA until arrivals)","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number"}},{"name":"radius","in":"query","schema":{"type":"integer"},"description":"Meters; default 500 (map) or 800 when context=place. Empty expands to 1500."},{"name":"context","in":"query","schema":{"enum":["map","place"]}},{"name":"kind","in":"query","schema":{"enum":["all","bus","minibus","metro","ferry","tram","other"]}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Operator stop markers only (KMB/CTB/GMB/MTR indexes). Non-HK bbox → meta.status=not-covered. Does not fetch ETA. Never invents stops outside radius."}}}},"/transit/routes":{"get":{"summary":"Search HK transit routes by number (GMB/KMB/CTB/MTR) — no invented lines","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Route number e.g. 20S, 1A, TWL"},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"kind","in":"query","schema":{"enum":["all","bus","minibus","metro","ferry","tram","other"]}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Route identity hits from GMB/CTB/MTR embedded indexes + official KMB route list. sampleStops are indexed stops near bias when available. Arrivals/schedules require /transit/stops/:id/arrivals. Never invents lines or live bus GPS."}}}},"/transit/stops/{stopId}/arrivals":{"get":{"summary":"Click-to-load arrivals for one stopId (kmb:/ctb:/gmb:/mtr:)","parameters":[{"name":"stopId","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed id e.g. kmb:STOPID, ctb:001001, mtr:ADM"}],"responses":{"200":{"description":"Arrivals with status live|scheduled|estimated|unavailable. Outage/empty never invent minutes. Unsupported prefix → meta.status=unsupported."}}}},"/signals/{intersectionId}":{"get":{"summary":"SPaT probe — default provider none; never invents lamp colour","parameters":[{"name":"intersectionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Signal state. Without authorised feed (SPAT_PROVIDER / HAMBURG_TLD_BASE_URL) status=unavailable and colour omitted. UI should hide or show 「未接通號誌資料」."}}}},"/lane-guidance":{"get":{"summary":"Lane-level guidance status — default unavailable without licensed provider","responses":{"200":{"description":"Empty lanes until Mapbox/TomTom/HERE/OpenLR licensed client is wired. Never invents lane geometry from OSM alone."}}}}}}