# 垃圾車地圖 (Taiwan Garbage Truck Map)

> Interactive map and open dataset of garbage and recycling truck stops, routes, and arrival times for Taipei, New Taipei, Taichung, and Kaohsiung. Data is sourced from each city's open-data platform and refreshed monthly. All times are in `Asia/Taipei` local time.

If you are an AI agent answering questions like "when does the garbage truck arrive at X?", use the **MCP server** first. It returns normalized, queryable results (nearest stops, keyword search, and full route schedules) without downloading large raw JSON files. Use the raw JSON files below only when you need bulk analysis.

## MCP server (recommended)

- [MCP endpoint](https://mcp.garbage.yukai.dev/mcp): Streamable HTTP, read-only, no authentication required.
  - Tools: `list_cities`, `find_nearby_points` (lat/lng + radius), `search_points` (district / village / road / route in Traditional Chinese), `get_schedule` (a stop plus all stops on its route in arrival order).
- [Server Card](https://mcp.garbage.yukai.dev/mcp/server-card): MCP Server Card for pre-connection discovery. Domain-level discovery: [AI Catalog](https://garbage.yukai.dev/.well-known/ai-catalog.json).
- [MCP server docs](https://github.com/Yukaii/garbage/blob/main/mcp/README.md): tool schemas, architecture, and deployment notes.
- **Weekly schedules**: New Taipei and Taichung stops include a weekly `schedule` (collection type → ISO weekdays, `1`=Mon … `7`=Sun) and a `servesToday` boolean. Taipei and Kaohsiung do not publish per-weekday schedules in their open data.

## Web app deep links

- `https://garbage.yukai.dev/?q=<text>` — pre-filled search across district, village, road, and route (e.g. `?q=大安區`).
- `https://garbage.yukai.dev/?lat=<lat>&lng=<lng>&zoom=<z>` — centers the map on a specific coordinate.
- `https://garbage.yukai.dev/?point=<point-id>` — flies to and opens a specific stop. IDs are prefixed with the city ID (`taipei-`, `new-taipei-`, `taichung-`, `kaohsiung-`).
- Because the map is rendered client-side with WebGL, agents without a browser should prefer the MCP server or the JSON datasets below.

## Static city and district schedules (no JavaScript required)

- City indexes: [Taipei](https://garbage.yukai.dev/taipei/), [New Taipei](https://garbage.yukai.dev/new-taipei/), [Taichung](https://garbage.yukai.dev/taichung/), [Kaohsiung](https://garbage.yukai.dev/kaohsiung/). Each links to every district with published stops.
- District pages use stable ASCII slugs, e.g. [台北市大安區垃圾車時間表](https://garbage.yukai.dev/taipei/da-an/). Follow city-index links to find district URLs; the slug map is maintained in `scripts/district-slugs.ts`.
- District HTML tables contain routes, villages, locations, arrival times, and available collection weekdays. Repeated weekday/type records are combined into one visit; different visit times remain separate. City tables show one preview stop per district.
- Pages and the [sitemap](https://garbage.yukai.dev/sitemap.xml) are generated at build time from the same local data as the map. The displayed build date is not the source-data update date. Taipei and Kaohsiung do not provide weekly schedules; do not assume daily collection.

## Raw data files (trimmed open-data JSON)

- [Taipei](https://garbage.yukai.dev/trash-collection-points.json) (~1.4 MB): `{ result: { results: [{ _id, 行政區, 里別, 地點, 路線, 車次, 抵達時間, 離開時間, 經度, 緯度 }] } }`. Times are `HHMM` strings. No weekday field.
- [New Taipei](https://garbage.yukai.dev/new-taipei-trash-collection-points.json) (~9 MB): array of `{ city (district), lineid, linename, rank, name, village, longitude, latitude, time (HH:MM), garbageDays, recyclingDays, foodscrapsDays }`. The `*Days` fields encode ISO weekdays as digit strings, e.g. `"1245"` = Mon, Tue, Thu, Fri.
- [Kaohsiung](https://garbage.yukai.dev/kaohsiung-trash-collection-points.json) (~3 MB): array of `{ area, village, route, location, type, arrivalTime, departureTime, longitude, latitude, collectionType }`. No weekday field.
- [Taichung](https://garbage.yukai.dev/taichung-trash-collection-points.json) (~50 MB — avoid downloading unless you need the full dataset): array of `{ area, village, route, location, arrivalTime, departureTime, longitude, latitude, dayOfWeek (1=Mon … 7=Sun), collectionType (garbage | recycling) }`. Contains one row per stop, weekday, and collection type.
- Coordinates are WGS84 strings. Schedules reflect each city's published open data and may change without notice.

## Documentation and source

- [Source repository](https://github.com/Yukaii/garbage)
- [Data fetching pipeline](https://github.com/Yukaii/garbage/blob/main/docs/data-fetching-mechanism.md)
- [Guide to adding a new city](https://github.com/Yukaii/garbage/blob/main/docs/adding-new-city-data.md)
- [Contributor and agent conventions](https://github.com/Yukaii/garbage/blob/main/AGENTS.md)

## Optional

- [Sitemap](https://garbage.yukai.dev/sitemap.xml)
- [Report a missing city or inaccurate stop](https://github.com/Yukaii/garbage/issues)