User Guide

Data Portal – User Guide

Welcome to the User Guide for our Data Portal. This document will help you understand how to effectively access data from our network of IoT sensors.

What is the Data Portal?

The Data Portal is your central hub for accessing sensor data. It allows you to download data for analysis, visualization in map applications (GIS), or integration into your own applications.

Data is organized into data views. Each view is a pre-configured dataset, such as "City Center Temperatures" or "Main Road Traffic Congestion."

Getting Started

  1. Browse Views: Start on the main portal page, where you'll find a list of all available data views.
  2. View Details: Clicking on a specific view will take you to its detail page, where you will find:
    • A detailed description of the data.
    • Live API links in various formats.
    • Code examples for programmatic access.
    • A description of the data structure (which measured quantities the view contains).

Types of Data Views (PortalView)

There are two basic types of views that determine what data you get:

1. Last Value

This is the simplest type of view. It returns the last recorded value for each device in the view. It is ideal for displaying the current status, for example, on a map.

2. Time Series

This type of view is used for working with historical data. It returns aggregated data (e.g., average, minimum, maximum) over a specific time period. Time series views can be:

  • Fixed: They have a fixed time range and aggregation function.
  • Dynamic: They allow you to specify parameters directly in the query URL to customize the output.

Parameters for Dynamic Time Series:

  • start: The beginning of the time period. You can use a relative time (e.g., -7d for the last 7 days) or an absolute time in ISO 8601 format (2023-10-26T00:00:00Z).
  • stop: The end of the time period (defaults to now()).
  • window: The time "window" over which the data is aggregated (e.g., 1h for hourly averages, 1d for daily).
  • agg_func: The aggregation function to be used (mean, max, min, sum, count).

Data Formats (Tags)

Each view can provide data in several formats. You can choose the format using the ?format=<format_name> parameter in the URL.

  • JSON (?format=json): The standard format for web and mobile applications. It is the default if you do not specify the parameter.
  • GeoJSON (?format=geojson): An extension of JSON for geographic data. Ideal for map libraries like Leaflet, OpenLayers, or Mapbox. Not available for "Time Series" views.
  • CSV (?format=csv): A tabular format that you can easily open in programs like Microsoft Excel, Google Sheets, or in analytical tools (R, Python/Pandas).
  • ArcGIS FeatureLayer (?format=arcgis): A special JSON format optimized for direct loading as a layer in Esri tools (ArcGIS Pro, ArcGIS Online).

Access and API Keys (Public/Private)

Views can be public or private.

  • Public Views: Are accessible to anyone without needing to log in.
  • Private Views: Require authentication using an API key (token).

What is an API Key and Why Do I Need It?

An API key is your personal "password" for accessing the API. You need it to: 1. Access private (non-public) data views. 2. Increase the limits on the number of API queries.

How to Get and Use an API Key?

  1. Register and log in to the system.
  2. In your user profile, you will find the "API Access" section.
  3. Click the "Generate New Token" button.
  4. Copy the generated key. Save it in a safe place, it will not be shown again!
  5. When communicating with the API, insert the key into the Authorization HTTP header.

Limits and Restrictions

To ensure stability and fair use of resources, certain limits are applied to API queries:

  • Anonymous Users: May have a limited number of requests per time period (e.g., 100 requests per hour).
  • Authenticated Users (with an API key): Have significantly higher limits, which may vary depending on the account type or agreement (e.g., 10,000 requests per hour).
  • Data Size: The maximum number of records returned in a single response may be limited. For larger data volumes, we recommend using pagination (if available) or data filtering.

If you exceed the allowed limits, the API will return an error status (e.g., HTTP 429 Too Many Requests). In that case, wait and try the request again later. For higher limits, please contact the system administrator.