# Weather API — Instant Weather by City Name

> Pass a city name, get structured weather data. No API keys, no geocoding setup,
> no rate limits. Current conditions and daily forecasts for any city worldwide.
> $0.001 per request (1/5 the price of weather.hugen.tokyo).

## API Base URL

https://weather-data-api.kasanegi123.workers.dev

## Authentication

x402 micropayments (USDC on Base mainnet, eip155:8453). Real settlement via
Coinbase CDP facilitator. No signup, no account, no API key.

## Why This Instead of a Free Weather API?

Free weather APIs (OpenWeatherMap / NWS / Open-Meteo direct) require:
- Separate geocoding call (city → lat/lon)
- API key registration + rotation
- Rate limit management
- Response shape parsing

This API handles all of that. Pass a city name, get structured JSON in one
call, ready for agent consumption. Pay $0.001 per call via x402 —
no subscription, no monthly minimum, no auth.

## Endpoints — $0.001 per request

- GET /weather/current?city={name}          — Current weather (temperature, humidity, wind, precipitation, condition)
- GET /weather/current?lat={lat}&lon={lon}  — Current weather by coordinates
- GET /weather/forecast?city={name}&days={1-7}  — Daily forecast
- GET /weather/forecast?lat={lat}&lon={lon}&days={1-7}

## Update Cadence

- **Current endpoint** — updated every 15 minutes, following Open-Meteo's
  current-weather cadence.
- **Forecast endpoint** — updated approximately every hour, following
  Open-Meteo's forecast refresh cadence.

Caching policy:

- Paid endpoint responses are fetched fresh from upstream on every
  request — no server-side caching on our side.
- The unpaid 402 preview peek (_live_sample in the 402 body) may be
  cached for up to 15 minutes to reduce upstream load.

## Agent Use Cases

- Travel / itinerary agents: "is it going to rain in Paris on Wednesday?"
- Scheduling bots: "next business day with good weather in Tokyo"
- News / content bots: "today's weather summary for 5 major cities"
- Trading / logistics agents: precipitation signals for ag / commodities

## Three Ways to Call

1. **Direct x402** — any x402-compatible client (see SDK below) hits the
   paid URL, pays inline, receives JSON.
2. **Free preview (no wallet needed)** — same source code runs at
   https://weather-data-api-preview.kasanegi123.workers.dev with
   X402_MODE=stub. Unlimited free trial during agent evaluation.
3. **MCP gateway** — https://mcp-data-gateway.kasanegi123.workers.dev/mcp
   exposes this + 13 other Japanese data tools via MCP 2025-06-18.

## SDK (one-line, Python)

```
pip install x402
from x402 import Client
r = Client().get('https://weather-data-api.kasanegi123.workers.dev/weather/current?city=Tokyo')
```

Node: `npm install @x402/fetch`.

## Discovery

- /.well-known/x402  — x402 manifest (resources, instructions)
- /openapi.json      — OpenAPI 3.1.0 spec
- /sitemap.xml       — Crawler sitemap
- /health            — Service health (free)
- /ops/live-status.json — Operational metrics

## Attribution

Weather data by Open-Meteo.com (CC BY 4.0, https://open-meteo.com).
Thin wrapper, no modification of upstream data.