urban-heat-API-docs

Smart Urban Heat Map API Documentation

de en

This documentation describes the Open-Data API of the Smart Urban Heat Map Bern Project.

The Smart Urban Heat Map is an initiative of the Smart City Verein Bern to visualize urban heat in the city and region of Bern. Valuable pioneering work has been done by the Climatology Group at the Geographical Institute of the University of Bern (GIUB), which has been operating an urban measurement network since 2018, consisting of around 80 stations. The Smart City Verein Bern, together with the company Abilium GmbH, the Bern University of Applied Sciences and the company Meteotest, has extended this measuring network into the Bern region by around 40 measuring stations.

Based on this measurement network, the Smart Urban Heat Map API offers access to detailed city climate data for the region of Bern, Switzerland. Users can retrieve current measurements of temperature, relative humidity, and location metadata, as well as location-bound time series data. The data provides valuable insights for urban planning and environmental studies.

The documentation is complemented by an interactive OpenAPI specification and a Jupyter Notebook which includes examples of how to request and visualize the data using Python. The notebook can be run locally or directly in the browser using Binder or Colab.

Licensing Information The data from the API is available under the Creative Commons Attribution License (CC-BY). Please ensure that you provide proper attribution when using or redistributing this data in your projects or applications. Attribution Example: Data provided by the Smart Urban Heat Map Project for Bern, Switzerland.

Contact Information For questions regarding the data, please contact the BFH. For questions regarding the locations and data of the project “Urban Climate Bern”, please contact GIUB - Urban Climate Bern. For technical questions regarding the API, please contact Meteotest.

Table of Contents

Changelog

API Version 1.0

This is the first version of the Smart Urban Heat Map API published on 09.10.2023.

Remark: In the initial version, the GeoJSON end point /stations returned the lat/lon coordinates in the wrong order ([lat, lon] rather than [lon, lat]).

Stations, Sensors and Temperature Bias

The measuring stations are built by Abilium GmbH and are based on the SHT41A Sensorion sensors. The self-sufficient stations are outfitted with a small solar panel and measure temperature and relative humidity every 10 minutes. The measurement data is sent out via the Helium LoRaWAN network. To reduce the potential temperature bias when stations are exposed to direct sunlight, all stations are ventilated before measuring. However, in some cases, especially during the day, measured temperatures might still be slightly higher than actual temperatures.

Endpoints

stations

Retrieves station data including most recent measured value for:

URL: https://smart-urban-heat-map.ch/api/1.0/stations Response Formats: GeoJSON (default), CSV

timeseries

Retrieves time series based on stationId for:

URL: https://smart-urban-heat-map.ch/api/1.0/timeseries Response Formats: JSON (default), CSV URL Parameter:

Codebook

stations

timeseries

Example Requests

Request list of stations and most recent measurements

GET https://smart-urban-heat-map.ch/api/1.0/stations

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          7.43141,
          46.94067
        ]
      },
      "properties": {
        "stationId": "3A0551FEFF6E959E",
        "name": "Eigerplatz-Bern",
        "dateObserved": "2023-10-05T11:36:29Z",
        "temperature": 18.925001,
        "relativeHumidity": 60.971848
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          7.439139,
          46.96681
        ]
      },
      "properties": {
        "stationId": "140551FEFF6E959E",
        "name": "Worblen-Ostermundigen",
        "dateObserved": "2023-10-05T11:36:27Z",
        "temperature": 18.791485,
        "relativeHumidity": 62.507286
      }
    },
    ...
  ]
}

Request timeseries for a station

GET https://smart-urban-heat-map.ch/api/1.0/timeseries?stationId=D33FCBFEFFE70FFE&timeFrom=2023-10-01T00:00:00Z&timeTo=2023-10-31T23:00:00Z

{
  "stationId": "D33FCBFEFFE70FFE",
  "values": [
    {
      "dateObserved": "2023-10-01T00:05:45Z",
      "temperature": 14.193179,
      "relativeHumidity": 86.94652
    },
    {
      "dateObserved": "2023-10-01T00:15:45Z",
      "temperature": 14.20386,
      "relativeHumidity": 87.801025
    },
    {
      "dateObserved": "2023-10-01T00:25:45Z",
      "temperature": 14.03563,
      "relativeHumidity": 88.541084
    },
    ...
  ]
}