> For the complete documentation index, see [llms.txt](https://docs.unisphere.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unisphere.io/nova/vertiport/developers-guide.md). # Developers Guide Access vertiport sensor data programmatically via the NOVA REST API This guide is for developers who want to integrate NOVA vertiport data into external systems — for example, flight management software, analytics pipelines, or custom dashboards. ## Authentication All requests require a JWT bearer token issued. Contact your Unisphere representative to obtain credentials. Pass the token in the `Authorization` header: ```http Authorization: Bearer ``` ### Required Permissions | Goal | Permission | | --------------------------------- | -------------------------- | | List and read vertiports | `vertiport.vertiport.read` | | Read sensor data and observations | `vertiport.readings.read` | Contact your administrator if you receive `403 Forbidden` responses. ## Getting Sensor Data The typical workflow for reading sensor data from an external system: {% stepper %} {% step %} ### Find your vertiport ID List all vertiports in your organization to obtain the UUID of the target vertiport. ```http GET https://prod.unisphere.rocks/api/v1/vertiport/ Authorization: Bearer ``` ```json { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Vertiport Berlin Mitte", "vertiport_code": "VPBIC1", "latitude": 52.520, "longitude": 13.405 } ], "total": 1 } ``` {% endstep %} {% step %} ### Discover available parameters Retrieve the metric keys available for your vertiport. The available parameters depend on which sensors are installed. ```http GET https://prod.unisphere.rocks/api/v1/vertiport/{vertiport_id}/parameters Authorization: Bearer ``` ```json [ { "sensor_id": "a1b2c3d4-...", "parameters": [ { "key": "air_temperature", "name": "Air Temperature", "unit": "°C" }, { "key": "wind_speed_average", "name": "Wind Speed (Average)", "unit": "m/s" }, { "key": "wind_direction_average", "name": "Wind Direction", "unit": "°" }, { "key": "air_pressure", "name": "Air Pressure", "unit": "Pa" }, { "key": "relative_humidity", "name": "Relative Humidity", "unit": "%" }, { "key": "rain_intensity", "name": "Rain Intensity", "unit": "mm/h" } ] } ] ``` Use the `key` values to filter responses in subsequent requests. {% endstep %} {% step %} ### Fetch data Choose the endpoint that fits your use case — see the sections below. {% endstep %} {% endstepper %} ## Data Endpoints ### Latest Observations Returns the most recent value for each metric across all sensors in the vertiport. Use this for live dashboards and status displays. ```http GET https://prod.unisphere.rocks/api/v1/vertiport/{vertiport_id}/latest-observations Authorization: Bearer ``` Filter to specific metrics using the `filter` query parameter: ```http GET .../latest-observations?filter=air_temperature,wind_speed_average ``` ```json [ { "sensor_id": "a1b2c3d4-...", "parameters": [ { "parameter": "air_temperature", "unit": "°C", "timestamp": "2026-05-27T12:00:00Z", "value": 18.4 } ] } ] ``` ### Historical Observations Returns raw time-series data. Defaults to the last 24 hours; maximum range is 30 days. ```http GET https://prod.unisphere.rocks/api/v1/vertiport/{vertiport_id}/observations ?start=2026-05-26T00:00:00Z &end=2026-05-27T00:00:00Z &filter=air_temperature,wind_speed_average Authorization: Bearer ``` ```json [ { "sensor_id": "a1b2c3d4-...", "parameters": [ { "parameter": "air_temperature", "unit": "°C", "observations": [ { "timestamp": "2026-05-26T00:00:10Z", "value": 14.2 }, { "timestamp": "2026-05-26T00:01:10Z", "value": 14.3 } ] } ] } ] ``` {% hint style="warning" %} For continuous data integration, poll on a **10–60 second interval** and request only the data since the last poll — for example, `?start=&end=`. The endpoint returns `416` if the requested range is too big. {% endhint %} {% hint style="info" %} There is currently no bulk data export endpoint. If you need a historical data export covering a larger time range, contact . {% endhint %} ### Aggregated Observations Returns time-bucketed statistics. Use this for trend charts, reports, or reduced-resolution data. ```http GET https://prod.unisphere.rocks/api/v1/vertiport/{vertiport_id}/aggregations ?start=2026-05-26T00:00:00Z &end=2026-05-27T00:00:00Z &bucket=1h &aggregation=avg,min,max &filter=air_temperature Authorization: Bearer ``` | Parameter | Required | Description | Examples | | --------------- | -------- | --------------------------------------- | ------------------------------------ | | `bucket` | Yes | Time bucket size | `15m`, `1h`, `1d` | | `aggregation` | Yes | Comma-separated functions | `avg`, `min`, `max`, `count`, `sum` | | `start` / `end` | No | ISO 8601 timestamps; default: last 24 h | — | | `filter` | No | Comma-separated metric keys | `air_temperature,wind_speed_average` | ```json [ { "sensor_id": "a1b2c3d4-...", "parameters": [ { "parameter": "air_temperature", "unit": "°C", "aggregations": [ { "timestamp": "2026-05-26T00:00:00Z", "avg": 14.5, "min": 13.1, "max": 16.2 } ] } ] } ] ``` ## Vertiport Meteorological Report (VMR) The VMR endpoint returns a structured aviation-compatible weather string (similar to METAR) for the vertiport. ```http GET https://prod.unisphere.rocks/api/v1/vertiport/{vertiport_id}/vmr Authorization: Bearer ``` ```json { "vmr": "VMR VPBIC1 270900Z AUTO 24006G12KT RA 08/04 CALC Q1016 RMK NOT_OFFICIAL;NO_VIS_SENSOR;NO_CLOUDS_SENSOR;WX_CODE_RAIN_ONLY", "tier": 1, "timestamp": "2026-05-27T09:00:00Z" } ``` The `tier` field indicates which sensor tier produced the report (see [Sensor Tiers](/nova/vertiport/vertiport-meteorological-report-vmr/sensor-tiers.md)). {% hint style="info" %} The VMR is computed once per 10-minute window. Subsequent calls within the same window return the cached result instantly. {% endhint %} {% hint style="warning" %} The endpoint returns `404` if the vertiport has no WXT536 sensor configured or if the vertiport elevation has not been set. Ensure both are configured before calling this endpoint. {% endhint %} See the [VMR reference](/nova/vertiport/vertiport-meteorological-report-vmr.md) for a full description of the string format and group definitions. ## Per-Sensor Access All data endpoints are also available scoped to a single sensor, useful when multiple sensors are installed at one vertiport and you need to distinguish between them. ```http GET .../vertiports/{vertiport_id}/sensors/{sensor_id}/latest-observations GET .../vertiports/{vertiport_id}/sensors/{sensor_id}/observations GET .../vertiports/{vertiport_id}/sensors/{sensor_id}/aggregations ``` These accept the same query parameters (`start`, `end`, `filter`, `bucket`, `aggregation`) as the vertiport-level endpoints.