Custom Connector
Urban Observatory Sensor Connector
UK
The Urban Observatory Sensor Connector integrates with the Urban Observatory Sensor API, providing access to sensor locations, sensor data, variable metadata, and theme metadata. It acts as a proxy for listing sensor locations, downloading sensor data, retrieving pagination info, and accessing variable/theme metadata — in JSON, CSV, and ESRI Shapefile, for GCP.
Overview
Integration Overview
This document provides a detailed guide for each integration point using the Urban Observatory Sensor Connector within a GCP environment.
- listSensorsJson. List sensor locations in JSON, with optional bounding-box filtering and pagination.
- getSensorsPage. Retrieve pagination metadata for sensor datasets (total count, navigation URLs).
- downloadSensorsCsv. Download sensor locations as CSV, with optional filtering and pagination.
- downloadSensorsShp. Download sensor locations as a zipped ESRI Shapefile.
- getSensorsDataJson / getSensorsDataCsv. Retrieve sensor data with time-range, variable, and bounding-box filters.
- getSensorIndDataJson / getSensorIndDataCsv. Retrieve data for a specific sensor, with filters.
- listVariables. List available measurement types and their metadata.
- listThemes. List available themes for sensor variables.
Documentation
Detailed Integration Documentation
List Sensors (JSON)
| Action | listSensorsJson |
|---|---|
| Purpose | Retrieves a comprehensive list of sensor locations in JSON, optionally filtered by bounding box — for geospatial applications and dashboards. |
| Configuration | Set CONNECTOR_ENV_URBANOBSERVATORY_BASE_URL in GCP (e.g. https://api.v2.urbanobservatory.ac.uk). |
| Parameters | Optional: bbox_p1_x, bbox_p1_y (lower-left lon/lat); bbox_p2_x, bbox_p2_y (upper-right lon/lat); limit (default 1000, -1 disables pagination); offset (default 0). |
| Output | Successful: JSON with sensor details (name, location, centroid coordinates, height, broker, ID) and pagination metadata. Failure: JSON validation errors (HTTP 422). |
| Workflow example | Call listSensorsJson with limit=10, then populate a geospatial visualization (e.g. Google Maps). |
Get Sensors Page
| Action | getSensorsPage |
|---|---|
| Purpose | Retrieves pagination metadata for sensor datasets — total count and page-navigation links — for managing large datasets. |
| Configuration | Set CONNECTOR_ENV_URBANOBSERVATORY_BASE_URL in GCP (e.g. https://api.v2.urbanobservatory.ac.uk). |
| Parameters | Optional: bbox_p1_x, bbox_p1_y (lower-left lon/lat); bbox_p2_x, bbox_p2_y (upper-right lon/lat); limit (default 1000, -1 disables pagination); offset (default 0). |
| Output | Successful: JSON with total sensors, limit, offset, and next/previous page URLs. Failure: HTTP 422. |
| Workflow example | Call getSensorsPage with limit=100 and use Total/Next to implement paginated retrieval. |
Download Sensors (CSV / Shapefile)
| Action | downloadSensorsCsv / downloadSensorsShp |
|---|---|
| Purpose | Downloads sensor locations as a CSV file, or as a zipped ESRI Shapefile (.shp, .shx, .dbf, .prj, .cpg) for GIS. |
| Configuration | Set CONNECTOR_ENV_URBANOBSERVATORY_BASE_URL in GCP (e.g. https://api.v2.urbanobservatory.ac.uk). Use header Accept: text/csv (CSV) or Accept: application/zip (Shapefile). |
| Parameters | Optional: bbox_p1_x, bbox_p1_y (lower-left lon/lat); bbox_p2_x, bbox_p2_y (upper-right lon/lat); limit (default 1000, -1 disables pagination); offset (default 0). |
| Output | Successful: CSV (sensor_name, Location_WKT, centroid, heights, broker, raw ID) or zipped Shapefile. Failure: HTTP 422. |
| Workflow example | Call downloadSensorsCsv with limit=100, then store the CSV in Cloud Storage for BigQuery processing. |
Get Sensors Data (JSON / CSV)
| Action | getSensorsDataJson / getSensorsDataCsv |
|---|---|
| Purpose | Retrieves sensor data (JSON or CSV) with filters for time range, variables, and bounding box — for real-time analysis or bulk export. |
| Configuration | Set CONNECTOR_ENV_URBANOBSERVATORY_BASE_URL in GCP (e.g. https://api.v2.urbanobservatory.ac.uk). Start with small limits (e.g. 10) to avoid server 500 errors. |
| Parameters | Optional: start, end (UTC datetimes); last_n_hours / last_n_days (override time range); variables (e.g. [“O3”,“NO2”]); bbox_p1_x, bbox_p1_y (lower-left lon/lat); bbox_p2_x, bbox_p2_y (upper-right lon/lat); limit (default 1000, -1 disables pagination); offset (default 0). |
| Output | Successful: Readings (Sensor_Name, Variable, Value, Timestamp, Flagged), Sensors metadata, Start/End, and pagination. Failure: HTTP 422. |
| Workflow example | Call getSensorsDataCsv with limit=10 and last_n_hours=24, store in Cloud Storage, analyze in BigQuery. |
Get Individual Sensor Data (JSON / CSV)
| Action | getSensorIndDataJson / getSensorIndDataCsv |
|---|---|
| Purpose | Retrieves data for a specific sensor (JSON or CSV) with optional filters — detailed, sensor-specific analysis. |
| Configuration | Set CONNECTOR_ENV_URBANOBSERVATORY_BASE_URL in GCP (e.g. https://api.v2.urbanobservatory.ac.uk). |
| Parameters | Required: sensor_name (e.g. PER_AIRMON_MESH1916150). Optional: start, end; last_n_hours / last_n_days; variables; limit; offset. |
| Output | Successful: JSON/CSV with the same structure as the aggregate data endpoints. Failure: HTTP 422. |
| Workflow example | Call getSensorIndDataJson with sensor_name=PER_AIRMON_MESH1916150 and last_n_hours=24 for sensor-specific monitoring. |
List Variables & Themes
| Action | listVariables / listThemes |
|---|---|
| Purpose | Retrieves available measurement types (with units, limits, and theme) and the list of themes — ideal for populating UI filter menus. |
| Configuration | Set CONNECTOR_ENV_URBANOBSERVATORY_BASE_URL in GCP (e.g. https://api.v2.urbanobservatory.ac.uk). |
| Parameters | Required: None. |
| Output | Successful: JSON with Variables (Name, Units, Upper_Limit, Lower_Limit, Theme) or Themes (Name). Failure: HTTP 422. |
| Workflow example | Call listVariables and listThemes to populate variable and category dropdowns in a web app. |
Example Workflow: Sensor Data Collection & Analysis
| Retrieve sensor locations | Use listSensorsJson with limit=10 and bounding box, then store the JSON in Cloud Storage. |
|---|---|
| Query sensor data | Execute getSensorsDataCsv with limit=10, last_n_hours=24, variables=[“O3”], save to Cloud Storage and load into BigQuery. |
| Analyze & visualize | Use listVariables and listThemes for UI filters, then visualize with Google Maps and Data Studio on App Engine. |
Support
For technical support, contact custom-connectors-support@isolutions.sa.