{"openapi":"3.0.3","info":{"title":"Environmental sensors (Agent Data API)","description":"Readings from open environmental networks: air quality (OpenAQ), US river gauges (USGS), tides and water levels (NOAA CO-OPS) and earthquakes (USGS), in one station id scheme, one unit set and one quality flag, with nearest-station search by coordinates and derived flags (AQI category, flood stage, recent quakes within a radius).","version":"2026.11.09"},"paths":{"/api/v1/stations/near":{"get":{"tags":["Environmental sensors"],"summary":"Stations near a point","description":"Stations of every network (usgs, coops, openaq) within radius_km of a point, nearest first, with the parameters each reports and the distance in metres. Refreshes every 24 hours.","operationId":"sensors_stations_near","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"example":-33.87,"title":"Lat"},"example":-33.87},{"name":"lon","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"example":151.21,"title":"Lon"},"example":151.21},{"name":"radius_km","in":"query","required":false,"schema":{"type":"number","maximum":500,"exclusiveMinimum":0,"example":10,"default":25,"title":"Radius Km"}},{"name":"parameter","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Parameter","examples":["pm25"]}},{"name":"network","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Network","examples":["openaq"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"sensors_stations_near","x-cadence":"Refreshes every 24 hours."}},"/api/v1/air/near":{"get":{"tags":["Environmental sensors"],"summary":"Air quality near a point","description":"Air quality monitors within radius_km of a point with their latest readings (PM2.5, PM10, O3, NO2, SO2, CO as integers in the stated scale) and the US EPA AQI of the worst pollutant, nearest first. Refreshes every 60 minutes.","operationId":"sensors_air_near","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"example":-33.87,"title":"Lat"},"example":-33.87},{"name":"lon","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"example":151.21,"title":"Lon"},"example":151.21},{"name":"radius_km","in":"query","required":false,"schema":{"type":"number","maximum":500,"exclusiveMinimum":0,"example":10,"default":25,"title":"Radius Km"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"sensors_air_near","x-cadence":"Refreshes every 60 minutes."}},"/api/v1/air/{station_id}":{"get":{"tags":["Environmental sensors"],"summary":"Air quality at a monitor","description":"Latest readings at one OpenAQ monitor (station_id openaq_{location_id}) with the US EPA AQI. An id that is not tracked returns status pending with known false; find ids with /stations/near. Refreshes every 60 minutes.","operationId":"sensors_air","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"station_id","in":"path","required":true,"schema":{"type":"string","title":"Station Id"},"example":"openaq_2178"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"sensors_air","x-cadence":"Refreshes every 60 minutes."}},"/api/v1/water/gauge/{site}":{"get":{"tags":["Environmental sensors"],"summary":"River gauge latest","description":"Latest gage height (feet), discharge (cubic feet per second) and water temperature at a USGS site, with the NWS flood categories and the current flood status. Refreshes every 15 minutes.","operationId":"sensors_water_gauge","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string","title":"Site"},"example":"01646500"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"sensors_water_gauge","x-cadence":"Refreshes every 15 minutes."}},"/api/v1/water/gauge/{site}/history":{"get":{"tags":["Environmental sensors"],"summary":"River gauge history (Pro)","description":"Readings for the last 7 days at a USGS site, newest first, every parameter, with observed_at and ingested_at so a backtest can select what was known at a time. Refreshes every 15 minutes.","operationId":"sensors_water_history","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string","title":"Site"},"example":"01646500"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"title":"From","examples":["2026-11-08T00:00:00Z"]}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"title":"To"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"default":500,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.02","x-price":{"price_micro":20000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"sensors_water_history","x-cadence":"Refreshes every 15 minutes.","x-cache-ttl-s":1800}},"/api/v1/tides/{station}":{"get":{"tags":["Environmental sensors"],"summary":"Tide station latest","description":"Latest observed water level at a NOAA CO-OPS station in metres above MLLW (milli), with the next predicted high and low and whether the tide is rising or falling. Refreshes every 6 minutes.","operationId":"sensors_tides","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"station","in":"path","required":true,"schema":{"type":"string","title":"Station"},"example":"8518750"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"sensors_tides","x-cadence":"Refreshes every 6 minutes."}},"/api/v1/tides/{station}/predictions":{"get":{"tags":["Environmental sensors"],"summary":"Tide predictions for a day","description":"Predicted high and low tides (metres above MLLW, UTC) at a NOAA CO-OPS station for one UTC date, today by default, up to 7 days ahead. Refreshes every 24 hours.","operationId":"sensors_tide_predictions","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"station","in":"path","required":true,"schema":{"type":"string","title":"Station"},"example":"8518750"},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date","nullable":true,"title":"Date","examples":["2026-11-09"]}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"sensors_tide_predictions","x-cadence":"Refreshes every 24 hours."}},"/api/v1/quakes/recent":{"get":{"tags":["Environmental sensors"],"summary":"Recent earthquakes","description":"Earthquakes from the USGS feed in the last `hours` (1 to 720), optionally at or above `min_mag` and within radius_km of a point, newest first, with magnitude and depth as integers (milli). Refreshes every 60 seconds.","operationId":"sensors_quakes","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"min_mag","in":"query","required":false,"schema":{"type":"number","maximum":10,"minimum":-2,"nullable":true,"title":"Min Mag","examples":[4]}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":720,"minimum":1,"example":24,"default":24,"title":"Hours"}},{"name":"lat","in":"query","required":false,"schema":{"type":"number","maximum":90,"minimum":-90,"nullable":true,"title":"Lat"}},{"name":"lon","in":"query","required":false,"schema":{"type":"number","maximum":180,"minimum":-180,"nullable":true,"title":"Lon"}},{"name":"radius_km","in":"query","required":false,"schema":{"type":"number","maximum":20000,"exclusiveMinimum":0,"nullable":true,"title":"Radius Km"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"sensors_quakes","x-cadence":"Refreshes every 60 seconds."}}},"components":{"schemas":{"APIKeyCreate":{"properties":{"email":{"type":"string","title":"Email","description":"Where this key belongs. Agents: your human's real address, else your own mailbox.","example":"owner@yourcompany.com"}},"type":"object","required":["email"],"title":"APIKeyCreate"},"AgentSubscribeRequest":{"properties":{"plan":{"type":"string","title":"Plan","description":"pass_1h, pass_1d or pass_7d","example":"pass_1d"}},"type":"object","required":["plan"],"title":"AgentSubscribeRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"servers":[{"url":"https://agentdataapi.com/sensors"}],"tags":[{"name":"Environmental sensors","description":"Air quality, river gauges, tides and earthquakes from open public sensor networks, one schema and nearest-station lookup."}]}