{ "openapi": "3.1.0", "info": { "title": "open-signals", "version": "0.1.0", "description": "Public data signals with provenance and licence on every reading. Read-only. The same data is available over MCP at /mcp.", "license": { "name": "Apache-2.0 (code); each source keeps its own data licence", "identifier": "Apache-2.0" } }, "paths": { "/v1/sources": { "get": { "summary": "Search the source catalogue", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Free text", "schema": { "type": "string" } }, { "name": "topic", "in": "query", "required": false, "description": "One topic", "schema": { "type": "string" } }, { "name": "license", "in": "query", "required": false, "description": "One licence", "schema": { "type": "string", "enum": [ "public_domain", "open", "non_commercial", "restricted", "unknown" ] } }, { "name": "fetchable", "in": "query", "required": false, "description": "true | false", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/sources/{id}": { "get": { "summary": "One catalogue entry", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown source, place or layer" } } } }, "/v1/hubs": { "get": { "summary": "Projects and catalogues that collect sources", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/places": { "get": { "summary": "Named places as GeoJSON", "parameters": [ { "name": "tag", "in": "query", "required": false, "description": "Only places with this tag", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/readings": { "get": { "summary": "Current readings from one source", "parameters": [ { "name": "source", "in": "query", "required": true, "description": "Source id with a fetcher", "schema": { "type": "string" } }, { "name": "place", "in": "query", "required": false, "description": "Comma-separated catalogue place ids.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Catalogue places with this tag.", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Ad-hoc point latitude (with lng).", "schema": { "type": "string" } }, { "name": "lng", "in": "query", "required": false, "description": "Ad-hoc point longitude (with lat).", "schema": { "type": "string" } }, { "name": "coops", "in": "query", "required": false, "description": "NOAA CO-OPS station id(s).", "schema": { "type": "string" } }, { "name": "usgs", "in": "query", "required": false, "description": "USGS monitoring location id(s).", "schema": { "type": "string" } }, { "name": "ebird", "in": "query", "required": false, "description": "eBird region code(s).", "schema": { "type": "string" } }, { "name": "metric", "in": "query", "required": false, "description": "Only this metric", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "ISO date or datetime", "schema": { "type": "string" } }, { "name": "forecast", "in": "query", "required": false, "description": "false drops forecasts", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "epa-echo: two-letter US state", "schema": { "type": "string" } }, { "name": "bbox", "in": "query", "required": false, "description": "noaa-nwps: xmin,ymin,xmax,ymax", "schema": { "type": "string" } }, { "name": "elevated", "in": "query", "required": false, "description": "usgs-volcanoes: true | false", "schema": { "type": "string" } }, { "name": "window", "in": "query", "required": false, "description": "usgs-earthquakes: hour | day | week", "schema": { "type": "string" } }, { "name": "min", "in": "query", "required": false, "description": "usgs-earthquakes: all | 1.0 | 2.5 | 4.5 | significant", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1-1000, default 100", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "off_season", "not_configured" ] }, "detail": { "type": "string" }, "generated_at": { "type": "string" }, "count": { "type": "integer" }, "readings": { "type": "array", "items": { "type": "object", "required": [ "id", "at", "metric", "value", "summary", "source" ], "properties": { "id": { "type": "string" }, "at": { "type": "string", "description": "Observation date or datetime (ISO)." }, "metric": { "type": "string" }, "value": { "type": [ "number", "null" ], "description": "null = reported without a number, never zero." }, "unit": { "type": [ "string", "null" ] }, "summary": { "type": "string" }, "place": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "state": { "type": "string" } } }, "forecast": { "type": "boolean" }, "fields": { "type": "object" }, "source": { "type": "object", "required": [ "id", "name", "fetched_at", "license" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "fetched_at": { "type": "string" }, "license": { "type": "string", "enum": [ "public_domain", "open", "non_commercial", "restricted", "unknown" ] } } } } } } } } } } }, "400": { "description": "Bad parameter" }, "404": { "description": "Unknown source, place or layer" }, "429": { "description": "Rate limited" }, "451": { "description": "Source licence does not allow this server to republish it" }, "502": { "description": "Upstream failed" } } } }, "/v1/layers": { "get": { "summary": "Layer catalogue", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/layers/{id}": { "get": { "summary": "One layer as GeoJSON", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "temperature", "wind", "pressure_change", "snow_depth", "wsi", "water_level", "river_flow", "ice", "sightings", "volcanoes", "flood_gauges", "epa_facilities", "recalls", "contract_awards", "wildlife", "natural_events", "world_bank", "earthquakes_emsc", "tropical_cyclones", "power_plants", "eu_industrial_production", "fema_declarations", "earthquakes", "lock_traffic", "border_crossings", "toxic_releases", "power_emissions", "river_discharge", "air_quality", "volcanoes_world", "lock_delays", "snowpack", "drought", "storm_reports", "wildfire_incidents", "aircraft", "military_aircraft", "gps_interference", "weather_alerts", "reservoirs_west", "ships_baltic", "data_centers", "quake_corroboration", "fire_corroboration", "fires", "persistent_heat", "steel_plant_heat", "cement_plant_heat", "chemical_plant_heat", "oil_gas_field_heat" ] } }, { "name": "date", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "place", "in": "query", "required": false, "description": "Comma-separated catalogue place ids.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Catalogue places with this tag.", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Ad-hoc point latitude (with lng).", "schema": { "type": "string" } }, { "name": "lng", "in": "query", "required": false, "description": "Ad-hoc point longitude (with lat).", "schema": { "type": "string" } }, { "name": "coops", "in": "query", "required": false, "description": "NOAA CO-OPS station id(s).", "schema": { "type": "string" } }, { "name": "usgs", "in": "query", "required": false, "description": "USGS monitoring location id(s).", "schema": { "type": "string" } }, { "name": "ebird", "in": "query", "required": false, "description": "eBird region code(s).", "schema": { "type": "string" } }, { "name": "window", "in": "query", "required": false, "description": "event layers", "schema": { "type": "string" } }, { "name": "min", "in": "query", "required": false, "description": "event layers", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "epa_facilities, weather_alerts", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "reservoirs_west: Reclamation region", "schema": { "type": "string" } }, { "name": "operator", "in": "query", "required": false, "description": "data_centers: operator name", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "ships_baltic: cargo | tanker | passenger | fishing | tug | other", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "weather_alerts: warning | watch | advisory", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "weather_alerts: NWS event name", "schema": { "type": "string" } }, { "name": "marine", "in": "query", "required": false, "description": "weather_alerts: true adds marine alerts", "schema": { "type": "string" } }, { "name": "bbox", "in": "query", "required": false, "description": "flood_gauges, fires, persistent_heat, wildlife", "schema": { "type": "string" } }, { "name": "elevated", "in": "query", "required": false, "description": "volcanoes", "schema": { "type": "string" } }, { "name": "indicator", "in": "query", "required": false, "description": "world_bank, eu_industrial_production", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "power_plants (ISO alpha-3)", "schema": { "type": "string" } }, { "name": "fuel", "in": "query", "required": false, "description": "power_plants", "schema": { "type": "string" } }, { "name": "min_mw", "in": "query", "required": false, "description": "power_plants", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "power_plants: operating | construction", "schema": { "type": "string" } }, { "name": "erupted_since", "in": "query", "required": false, "description": "volcanoes_world: year, default 1900", "schema": { "type": "string" } }, { "name": "continuing", "in": "query", "required": false, "description": "volcanoes_world: true keeps eruptions in progress", "schema": { "type": "string" } }, { "name": "radius", "in": "query", "required": false, "description": "aircraft, gps_interference: nautical miles, 1-250", "schema": { "type": "string" } } ], "responses": { "200": { "description": "GeoJSON FeatureCollection", "content": { "application/geo+json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad parameter" }, "404": { "description": "Unknown source, place or layer" }, "429": { "description": "Rate limited" }, "451": { "description": "Source licence does not allow this server to republish it" }, "502": { "description": "Upstream failed" } } } }, "/v1/zip/{zip}": { "get": { "summary": "Centre of a US ZIP code area (Census ZCTA)", "parameters": [ { "name": "zip", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown source, place or layer" } } } }, "/v1/datasets": { "get": { "summary": "Static public datasets", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/datasets/{id}": { "get": { "summary": "One dataset described", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown source, place or layer" } } } }, "/v1/datasets/{id}/{part}": { "get": { "summary": "One part of a dataset as GeoJSON (a state, or all)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "part", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GeoJSON FeatureCollection", "content": { "application/geo+json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown source, place or layer" }, "451": { "description": "Source licence does not allow this server to republish it" } } } }, "/mcp": { "post": { "summary": "MCP (JSON-RPC 2.0, streamable HTTP, stateless)", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/health": { "get": { "summary": "Liveness", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }