Chelaile API (chelaile-api-server)

A read-only HTTP JSON API for Chelaile realtime transit data: line schedules, live vehicle positions, nearby stops, keyword search, route geometry, and bus/metro journey planning. No login or account is required. The original MCP service remains available for Claude Code and Cursor.

• Hosted services (previously verified): Cloudflare Workers https://ts-api.tundrey.com | Vercel https://chelaile-api-server.vercel.app

• User guide (Wiki): https://github.com/Justintunsday/chelaile-api-server/wiki

• Full documentation: docs/API.md | Documentation site: https://chelaile-api-docs.tundrey.com/

• Default address: http://127.0.0.1:8787

• Endpoint index: GET /

Features

• Zero configuration: no upstream account or API key needed.

• REST interface: GET endpoints with simplified JSON, grouped line directions, normalized coordinates, and irrelevant fields removed.

• Two interfaces: HTTP API and MCP stdio service share the same core logic.

• Static data on GitHub: GitHub Actions periodically syncs city lists and other infrequently changing data for loading from the repository/CDN, reducing upstream requests.

• Operational controls: optional API key, CORS allowlist, per-IP rate limiting, request logs, and health checks.

Related MCP server: transport12 MCP Server

Quick start

git clone https://github.com/Justintunsday/chelaile-api-server.git
cd chelaile-api-server
npm install
npm run build
npm start

curl "http://127.0.0.1:8787/v1/health"
curl "http://127.0.0.1:8787/v1/search?city_id=034&keyword=71"

API endpoints

See docs/API.md for parameters, response examples, coordinate systems, and error codes.

Request examples

# Realtime arrivals for bus 71 (line_id / target_order / station_id come from /v1/search or /v1/stops/nearby).
curl "http://127.0.0.1:8787/v1/lines/realtime?city_id=034&line_id=21283603183&target_order=2&station_id=021-15232&lat=31.2304&lng=121.4737"

# People's Square → Hongqiao Railway Station (GCJ-02 coordinates, available from search POIs).
curl "http://127.0.0.1:8787/v1/transit/plan?city_id=034&origin_name=人民广场&origin_lat=31.233021&origin_lng=121.49073&dest_name=虹桥火车站&dest_lat=31.197&dest_lng=121.327&strategy=0"

Data hosted on GitHub

A script fetches data/cities.json from the upstream and commits it to the repository. .github/workflows/sync-data.yml updates it daily at 03:17 UTC, with three retries, a city-count drop safeguard, and no commits for unchanged data. It also runs when the sync script changes, or manually from Actions. Data loading priority:

Memory cache → DATA_BASE_URL (GitHub raw / jsDelivr) → local data/cities.json → upstream

npm run sync-data   # Manually sync the city list.

Point deployments at your repository (jsDelivr is recommended for CDN caching):

DATA_BASE_URL="https://cdn.jsdelivr.net/gh/Justintunsday/chelaile-api-server@main/data" npm start

Before the first workflow run, open Settings → Actions → General → Workflow permissions and enable Read and write permissions.

Deployment

GitHub Pages and Actions cannot serve this API directly. Pages serves static files and cannot make upstream requests, sign with MD5, or decrypt with AES. Actions cannot expose a permanent public port. pages.yml hosts only the documentation: https://justintunsday.github.io/chelaile-api-server/

Use the repository as a deployment source so a hosting platform builds and runs the application:

Cloudflare Workers reuses the core logic in worker/. Run locally with npm run dev:worker:

npx wrangler login
npx wrangler deploy -c worker/wrangler.toml
# After deployment: Dashboard → Workers & Pages → chelaile-api → Settings → Domains & Routes
# Bind a custom domain for mainland access; *.workers.dev is blocked there.

Optional key: npx wrangler secret put API_KEY -c worker/wrangler.toml. Configure DATA_BASE_URL and CORS_ORIGIN under [vars] in worker/wrangler.toml.

For Vercel, vercel.json uses Services (runtime: "container" plus an all-path rewrite). Import the repository to build the Dockerfile; no manual Framework Preset setting is needed. For Production, set DATA_BASE_URL=https://cdn.jsdelivr.net/gh/Justintunsday/chelaile-api-server@main/data.

Render deployment: https://render.com/deploy?repo=https://github.com/Justintunsday/chelaile-api-server

For Docker:

docker build -t chelaile-api .
docker run -d --name chelaile-api -p 8787:8787 chelaile-api

Environment variables

MCP service (optional)

All original MCP capabilities remain available. Start with:

npm run start:mcp   # node dist/index.js

Use in Claude Code / Claude Desktop (15 tools with the bus_* prefix). HTTP equivalents are listed in docs/API.md.

Development

npm run dev          # API hot reload with tsx
npm run build        # Build with tsc
npm test             # Unit tests (bun test tests/unit)
npm run test:e2e     # End-to-end tests (network required; CHELAILE_E2E=1)
npm run sync-data    # Sync city data

License

MIT

Data comes from Chelaile public interfaces. This project adapts the protocol for learning and research. Follow the upstream terms of service and avoid high-frequency scraping and commercial use.