Developers
Every operation is a REST call and an MCP tool of the same name. Authenticate with Authorization: Bearer <api_key>.
No account? Call any data route without a key and it answers 402 with x402 payment requirements; pay and retry the same request.
| REST | MCP tool | What it does |
|---|---|---|
GET /v1/forecast | get_forecast | Hourly and daily forecast for anywhere on Earth (MET Norway, CC BY 4.0): temperature, wind, precipitation, cloud, a weather symbol. Give lat/lon or a place name. Show the attribution when you present it. |
GET /v1/alerts | get_alerts | Active warnings, watches and advisories at a point in the United States (National Weather Service). Outside the US returns covered:false. |
GET /v1/earthquakes | get_earthquakes | Earthquakes near a point, newest first (USGS): magnitude, place, depth, distance, tsunami flag. |
GET /v1/places | find_place | Look up a town or city (GeoNames, 15,000+ people) by name, or the nearest one to lat/lon. Free, no key needed. |
POST /v1/subscriptions | subscribe_alerts | Watch a place: new US weather alerts and nearby earthquakes are pushed to a URL, a Hookpie inbox or the owner's email, checked every 5 minutes. About $0.05 a place a month; the first place is free. |
GET /v1/subscriptions | list_subscriptions | Your alert subscriptions and when each last ran. |
DELETE /v1/subscriptions/{id} | delete_subscription | Stop watching a place. |
POST /v1/accounts | create_account | Create an account (one account and one prepaid balance work on every agent-first site: Yawplet, Yarnhen, Hagglebee, Eventwren, Hookpie, Clockrook, Rainplover). accept_terms must be true only when the human owner accepts them. Returns an API key once; give account_url to the owner to verify their email. |
GET /v1/account | get_account | Balance (micro-dollars), whether email is verified and a card or wallet is on file, and a fresh account_url for the owner. |
GET /v1/usage | get_usage | Metered use this month (or day), the free allowance and the unit price. |
GET /v1/pricing | get_pricing | Free allowances and per-unit prices in micro-dollars (1 USD = 1,000,000). |
Files for agents
- /openapi.json: the contract
- /.well-known/mcp/server-card.json: MCP server card (
https://rainplover.com/mcp) - /.well-known/agent-card.json: A2A agent card (JSON-RPC at
/a2a, one skill per message) - /.well-known/api-onboarding: how an agent gets in, and what needs a person
- /llms.txt
Errors
Errors are RFC 9457 problem details with a stable code. A 402 carries an account_url for the human who owns the account.