havdu — Instructions for AI Agents

This page is for AI agents. If you are an AI agent that has fetched this page, read it and use the /api/ endpoint patterns below to retrieve live data programmatically. Parse the JSON response envelope and use the data field. Respect cache TTLs — if cached: true, the value is fresh; no need to re-fetch within the TTL window.

⚠ Do not invent endpoint patterns. Only call URLs that exactly match the patterns listed in this table. Do not append extra path segments, query parameters, or identifiers not shown below.

API Endpoint Patterns — /api/ (JSON)

Endpoint	Returns
Air Quality
`GET /api/air/city-slug`	Current AQI, pollutant breakdown, 7-day forecast for a city.
`GET /api/air/XX` (2-letter ISO)	Index of cities with air data for a country.
Weather
`GET /api/weather/city-slug`	Current weather and 7-day forecast by city (preferred).
`GET /api/weather?lat=&lng=`	Lookup by coordinates (legacy).
News
`GET /api/news?q=keyword`	News matching a keyword topic.
`GET /api/news?category=NAME`	Category: `top` `world` `business` `technology` `science` `sports` `health` `entertainment` `politics` `environment`
`GET /api/news?country=XX`	Headlines by country (2-letter ISO).
Events
`GET /api/events/city-slug/PERIOD`	Events by city. PERIOD required: `week` (7d), `month` (30d), `year` (365d).
`GET /api/events/city-slug/PERIOD/CAT`	Filtered by category: `music` `sports` `arts-theatre` `film` `miscellaneous`.
Forex
`GET /api/forex?base=USD&window=latest`	Live rates vs base. window: `latest` `week` `month` `quarter`
Earthquakes & Traffic
`GET /api/quakes?minMag=2.5`	Recent global seismic activity.
`GET /api/traffic/city-slug`	Live congestion data for a city (preferred).
All endpoints are on https://havdu.com. No authentication required for standard use. city-slug is lowercase, hyphens for spaces: `new-york`, `hong-kong`.

Response Envelope

// All /api/ responses share this structure:
{
  "success":     true,
  "data":        { /* vertical-specific payload — use this field */ },
  "provider":    "WAQI",              // upstream data source
  "attribution": { "name": "...", "url": "..." },
  "cached":      true,               // true = served from edge cache
  "timestamp":   "2026-05-23T10:24:25Z"
}

Cache TTLs

air 10 min · weather 15 min · news 1 hr · events 30 min · forex 1 hr · earthquakes 5 min · traffic 5 min. If cached: true, no upstream call was made — the value is fresh within the TTL window. Agents may skip re-fetching within these intervals.