Hat Yai Transit API

Every route, stop, departure and fare in Hat Yai Transit, as a free JSON API. Use it without a key at the keyless limits, or get a free key for higher limits and the journey planner.

Use it in AI assistants (MCP)

Quick start

Base URL: https://hatyaitransit.techmavie.digital. Every response is JSON. Names come in Thai, English and Malay ({ "th", "en", "ms" }) and times are Thailand time (Asia/Bangkok, GMT+7).

Without a key:

curl https://hatyaitransit.techmavie.digital/api/stops/SRT_HAT_YAI/departures

With your key (header X-API-Key):

curl -H "X-API-Key: hyt_your_key_here" https://hatyaitransit.techmavie.digital/api/routes/HY3

Plan a journey (needs a key):

curl -X POST https://hatyaitransit.techmavie.digital/api/journey/plan \
  -H "X-API-Key: hyt_your_key_here" -H "Content-Type: application/json" \
  -d '{"origin":{"stopId":"HY3_19"},"destination":{"stopId":"SRT_HAT_YAI"},"options":{"language":"en"}}'

Keys and rate limits

A key is optional. Without one you can use every data endpoint at a lower limit; a free key raises the limits and unlocks the journey planner. Keys are free, and we email them to you.

Keys and rate limits
Without a keyWith a free key
Requests per minute60 per IP address300 per key
Requests per dayNo daily cap10,000 per key
Journey plannerNot available30 a minute, 500 a day
Place searchOnly in the Hat Yai Transit appOnly in the Hat Yai Transit app

Sending your key: put it in the X-API-Key header (best). Authorization: Bearer <key> and ?api_key= work too. A wrong or revoked key gets HTTP 401; it doesn’t fall back to the keyless limit.

Limit headers: every response says which tier you’re on (X-API-Tier) and how much is left (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset in seconds; with a key also X-RateLimit-Limit-Day and X-RateLimit-Remaining-Day). Over a limit you get HTTP 429 with a Retry-After header. Daily limits reset at midnight Thailand time.

Your key: check it with GET /api/developer/key; if it leaks, revoke it with DELETE /api/developer/keys (send the key) and request a new one. Up to 2 active keys per email address.

CORS: GET endpoints and POST /api/journey/plan send Access-Control-Allow-Origin: *. Keep your key on a server where you can: a key in browser code can be copied.

Endpoints

Public API endpoints
Endpoint What it returns
GET/api/routes All routes with fares, operating hours, directions and data-confidence notes. 
curl https://hatyaitransit.techmavie.digital/api/routes
GET/api/routes/{id} One route and all of its stops. 
curl https://hatyaitransit.techmavie.digital/api/routes/HY3
GET/api/routes/{id}/geometry Route lines as encoded polylines (Google format, precision 5). Optional ?direction=0|1. 
curl "https://hatyaitransit.techmavie.digital/api/routes/HY3/geometry?direction=0"
GET/api/routes/{id}/departures?direction=&stopId= Upcoming departures on a route. Optional direction (0/1) and stopId. 
curl "https://hatyaitransit.techmavie.digital/api/routes/HY3/departures?direction=0&stopId=HY3_01"
GET/api/stops Every stop with Thai, English and Malay names, coordinates and the routes serving it. 
curl https://hatyaitransit.techmavie.digital/api/stops
GET/api/stops/search?q= Search stops by name in any of the three languages (up to 20 results). 
curl "https://hatyaitransit.techmavie.digital/api/stops/search?q=airport"
GET/api/stops/nearby?lat=&lon=&radius= Stops near a point. radius is in metres (default 800, max 5000). 
curl "https://hatyaitransit.techmavie.digital/api/stops/nearby?lat=7.0086&lon=100.4747&radius=800"
GET/api/stops/{id} One stop. 
curl https://hatyaitransit.techmavie.digital/api/stops/SRT_HAT_YAI
GET/api/stops/{id}/departures Next departures from a stop (optional count, max 20, and routeId). 
curl https://hatyaitransit.techmavie.digital/api/stops/SRT_HAT_YAI/departures
GET/api/fares?date=YYYY-MM-DD Fares in force on a date (Bangkok date, default today), including the EV City Loop free-trial period. 
curl "https://hatyaitransit.techmavie.digital/api/fares?date=2026-11-13"
GET/api/meta Region info, today’s date, fare period, route list and the disclaimer text. 
curl https://hatyaitransit.techmavie.digital/api/meta
GET/api/sources The data sources listed on the Sources page (publishers, links, what each supports, last checked). 
curl https://hatyaitransit.techmavie.digital/api/sources
GET/api/gtfs/feeds GTFS feed index: versions, validity dates, sizes and SHA-256 checksums. 
curl https://hatyaitransit.techmavie.digital/api/gtfs/feeds
GET/api/gtfs/{feedId}/{file} One file from a GTFS feed as JSON rows (for example stops.txt or trips.txt).
feedId: hatyai-ev-loop · hatyai-airport-minibus · srt-hatyai-padang-besar · ktm-mysawasdee
curl https://hatyaitransit.techmavie.digital/api/gtfs/hatyai-ev-loop/stops.txt
POST/api/journey/plan Key needed Plan a trip. origin and destination can each be { lat, lng }, { stopId } or { text }. Options: language (th/en/ms), departAt (ISO time) and modes. Trips into Malaysia or Singapore return a hand-off to our sister apps. 
curl -X POST https://hatyaitransit.techmavie.digital/api/journey/plan \
  -H "X-API-Key: hyt_your_key_here" -H "Content-Type: application/json" \
  -d '{"origin":{"stopId":"SRT_HAT_YAI"},"destination":{"text":"Hat Yai Airport"},"options":{"language":"en"}}'
GET/api/developer/key Key needed Your key’s tier, when it was made, when it was last used and its limits. 
curl -H "X-API-Key: hyt_your_key_here" https://hatyaitransit.techmavie.digital/api/developer/key
DELETE/api/developer/keys Key needed Revoke the key you send (for example if it leaked), then request a new one on this page. 
curl -X DELETE -H "X-API-Key: hyt_your_key_here" https://hatyaitransit.techmavie.digital/api/developer/keys

Route IDs: HY3 EV City Loop (Route 3) · HY8299 Airport Minibus · SRT_741 / SRT_SE45 SRT trains to Padang Besar · KTM_MYSAWASDEE KTM MySawasdee (seasonal)

MCP server for AI assistants

Connect Claude, ChatGPT and other AI assistants that support the Model Context Protocol to Hat Yai Transit: they can look up routes, stops, departures and fares, and plan journeys. No key needed.

Server URL (Streamable HTTP):

https://mcp.techmavie.digital/hatyaitransit/mcp

Client configuration:

{
  "mcpServers": {
    "hatyai-transit": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/hatyaitransit/mcp"
    }
  }
}

Tools

ToolWhat it does
get_service_infoWhat Hat Yai Transit covers, today's date and fare period, and the disclaimer.
list_routesAll routes with fares, hours and directions.
get_routeOne route and its stops in order.
get_route_departuresUpcoming departures on a route.
get_route_geometryA short summary of a route's line (the full line only when asked).
search_stopsFind stops by name in Thai, English or Malay.
get_stopOne stop and the routes that serve it.
find_nearby_stopsStops near a point or a place.
get_stop_departuresNext departures from a stop.
get_faresFares in force on a date, including the EV City Loop free trial.
plan_journeyPlan a trip between stops, places or coordinates.
search_placesLook up a place by name, to use in plan_journey.
list_gtfs_feedsThe open GTFS downloads (ODbL), with versions and dates.
get_sourcesWhere the data comes from, plus the disclaimer.

Source code: github.com/hithereiamaliff/mcp-hatyaitransit.

Terms of use