services
Sensors
Overview

Sensors Service

The Sensors service exposes the sensor catalog and MCP endpoints for listing sensors, resolving connected services, and calling MCP tools per sensor or via the registry.

Overview

The Sensors service provides:

  • REST API — List sensors (with optional map/region filters: bounding box or center+radius), get types/statuses, registry, and sensor details
  • Sensor MCP — POST /api/v1/sensors/:id/mcp — Run MCP protocol for one sensor (UUID); forwards to that sensor’s connected service (e.g. NDBC, AirNow)
  • Registry MCP — POST /api/v1/sensors/registry/mcp — Catalog-wide tools: list_sensors, sensor_connected_services, sensor_cleaned_stream

Data Normalization

Sensors and readings support data_types (what parameters a sensor collects), data_format (raw vs. cleaned), and canonical measurements for cross-service comparison. See Data Normalization for details.

Available Tools

See the Tools Reference for MCP tool documentation.

REST Endpoints

MethodPathDescription
GET/api/v1/sensorsList sensors (filters including data_types, pagination, map: bbox or lat/lon/radius_km; minimal or fields for reduced payloads on large lists)
GET/api/v1/sensors/typesDistinct sensor types
GET/api/v1/sensors/statusesDistinct statuses
GET/api/v1/sensors/registryRegistry (id, external_id, latitude, longitude, feed_id, connected_service; same map filters)
GET/api/v1/sensors/:idSensor by UUID or external_id
GET/api/v1/sensors/:id/readings/latestLatest reading (data_format: cleaned | raw)
GET/api/v1/sensors/:id/readingsTime-series readings (data_format, parameter filter)
POST/api/v1/sensors/:id/mcpMCP for one sensor (UUID only)
POST/api/v1/sensors/registry/mcpMCP for registry tools

Full REST details: API Reference → Sensors.

Quick Example — List Sensors

curl -H "x-api-key: dev-key-12345" "http://localhost:3001/api/v1/sensors?limit=5"

Quick Example — List sensors in a map region

Pass a bounding box (viewport) or center + radius to return only sensors with a location in that region:

# Bounding box: min_lat, min_lon, max_lat, max_lon
curl -H "x-api-key: dev-key-12345" "http://localhost:3001/api/v1/sensors?min_lat=32&min_lon=-87&max_lat=33&max_lon=-86&limit=20"
 
# Center + radius (km)
curl -H "x-api-key: dev-key-12345" "http://localhost:3001/api/v1/sensors?lat=32.44&lon=-86.47&radius_km=50&limit=20"

Quick Example — Sensor MCP (e.g. NDBC latest observation)

Use a sensor UUID from the list or registry. The request is forwarded to that sensor’s connected_service (e.g. NDBC).

curl -X POST http://localhost:3001/api/v1/sensors/{sensor-uuid}/mcp \
  -H "x-api-key: dev-key-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ndbc.latest_observation",
      "arguments": {}
    }
  }'

When using the sensor MCP endpoint, context (sensor_id, sensor_external_id, sensor_name, feed_slug) is injected; tools like ndbc.latest_observation can use sensor_external_id when station_id is omitted.

Examples

See Sensors Examples for more usage examples.

ExamplesTools Reference