API Reference

This section documents the main Building Operating System (BOS) API.
Below you can find the interactive documentation automatically generated from the OpenAPI file exposed by the FastAPI backend.

Base URL

All API requests must be made to the following base URL: https://api.bos.k8s.polito.it/

You can also access the API documentation directly through the following endpoints:

Swagger UI: https://api.bos.k8s.polito.it/docs
ReDoc: https://api.bos.k8s.polito.it/redoc
JSON Schema: https://api.bos.k8s.polito.it/openapi.json

POLITO Data API 1.0.3

The POLITO Data API allows users to interact with energy data collected by the Politecnico di Torino.

This API provides access to a variety of data sources, including electricity consumption, renewable energy production, and weather data. Users can retrieve data for specific time periods, locations, a nd energy sources. The API also supports the ability to retrieve interactive reports and more.

The POLITO Data API is designed to be easy to use and can be accessed via a simple RESTful interface. It is suitable for a wide range of applications, including data analysis, energy management, and research.

Terms of service: https://www.polito.it/ateneo/campus-sostenibile/monitoraggio/consumi-e-attivita-del-campus

Contact: Monitoraggio Campus monitoraggio.campus@polito.it

License: Apache 2.0

Developers

GET /health/live

Perform a Health Check on API Pod livenessProbe

Description

Endpoint to perform a healthcheck on liveness of the service. Other services which rely on proper functioning of the API service will not deploy if this endpoint returns any other HTTP status code except 200 (OK).

An example Dockerfile with a healthcheck capabilities enabled is available in this gist: - https://gist.github.com/Jarmos-san/11bf22c59d26daf0aa5223bdd50440da - https://gist.github.com/Jarmos-san/0b655a3f75b698833188922b714562e5

Response 200 OK

application/json

{
    "status": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "status": {
            "type": "string",
            "title": "Status",
            "description": "The status of the health check",
            "default": "OK"
        }
    },
    "type": "object",
    "title": "HealthCheck",
    "description": "Response model to validate and return when performing a health check."
}

Response 404 Not Found

GET /health/ready

Perform a Health Check on API Pod readinessProbe

Description

Endpoint to perform a healthcheck on readiness of the service. Other services which rely on proper functioning of the API service will not deploy if this endpoint returns any other HTTP status code except 200 (OK).

An example Dockerfile with a healthcheck capabilities enabled is available in this gist: - https://gist.github.com/Jarmos-san/11bf22c59d26daf0aa5223bdd50440da - https://gist.github.com/Jarmos-san/0b655a3f75b698833188922b714562e5

Response 200 OK

application/json

{
    "status": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "status": {
            "type": "string",
            "title": "Status",
            "description": "The status of the health check",
            "default": "OK"
        }
    },
    "type": "object",
    "title": "HealthCheck",
    "description": "Response model to validate and return when performing a health check."
}

Response 404 Not Found

GET /auth/protected

Perform a protected API call

Description

A private endpoint that requires a valid API key to be provided. It simply checks the api key is valid and returns a 200 OK response with a JSON body containing the authenticated status. In order to test this endpoint, you need to provide a valid API key as a header to the request. The header name must be x-api-key.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key

Response 200 OK

application/json

Schema of the response body

Response 404 Not Found

GET /auth/public

Perform a non protected API call

Description

A public endpoint that requires a no valid API key to be provided. It does not check any api key and returns a 200 OK response with a JSON body containing the authenticated status. In order to test this endpoint, you can just make a request without any header.

Response 200 OK

application/json

Schema of the response body

Response 404 Not Found

GET /auth/apikey/endpoints

Get authorized endpoints for current API key

Description

Get the list of endpoints that the current API key is authorized to access

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key

Response 200 OK

application/json

Schema of the response body

Response 404 Not Found

Data

GET /data/meters

Get single meter data

Description

Get data for a single meter in a given time range.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key
`aggregation`	query	None	15 m	No	Aggregation of data returned (mean).
`data_format`	query	None	raw	No	The format in which the data should be returned.
`end_datetime`	query	string	2025-11-10 15:00:00	No	Last timestamp of the query in the timezone provided
`ids`	query	array	[860]	No	The unique identifier of the meter
`start_datetime`	query	string	2025-11-09 15:00:00	No	First timestamp of the query in the timezone provided
`tag`	query	array	['ok']	No	Tag connected to data quality
`tz`	query	None	Europe/Rome	No	The timezone in which the data is queried and returned.

Response 200 OK

application/json

[
    {
        "time_15m": "2022-04-13T15:42:05.901Z",
        "meter_id": null,
        "avg_value": null,
        "min_value": null,
        "max_value": null,
        "sum_value": null,
        "count_value": null,
        "tag": "string"
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/Data15m"
    },
    "title": "Response Get Data Meter Id Data Meters Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /data/datacenter_1

Get data datacenter 'nodo 1'

Description

Get data for a datacenter 1 in a given time range.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key
`aggregation`	query	None	15 m	No	Aggregation of data returned (mean).
`data_format`	query	None	raw	No	The format in which the data should be returned.
`end_datetime`	query	string	2025-11-10 15:00:00	No	Last timestamp of the query in the timezone provided
`start_datetime`	query	string	2025-11-09 15:00:00	No	First timestamp of the query in the timezone provided
`tz`	query	None	Europe/Rome	No	The timezone in which the data is queried and returned.

Response 200 OK

application/json

⚠️ This example has been generated automatically from href="#__codelineno-11-1">[ { "time_15m": "2022-04-13T15:42:05.901Z", "tot_dc_aux": null, "tot_dc_gf": null, "tot_dc_i1": null, "tot_dc_i1_cabina": null, "tot_dc_i1_vent": null, "tot_dc_i1_it": null, "tot_dc_i2": null, "tot_dc_i2_vent": null, "tot_dc_i2_it": null, "tot_dc_i3": null, "tot_dc_i3_vent": null, "tot_dc_i3_it": null, "tot_dc": null, "tot_dc_it": null, "tot_dc_vent": null } ] the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/Datacenter15m"
    },
    "title": "Response Get Data Datacenter 15M Data Datacenter 1 Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /data/pv

Get photovoltaic plants data

Description

Get data for Polito photovoltaic plants in a given time range.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key
`aggregation`	query	None	15 m	No	Aggregation of data returned (mean).
`data_format`	query	None	raw	No	The format in which the data should be returned.
`end_datetime`	query	string	2025-11-10 15:00:00	No	Last timestamp of the query in the timezone provided
`start_datetime`	query	string	2025-11-09 15:00:00	No	First timestamp of the query in the timezone provided
`tz`	query	None	Europe/Rome	No	The timezone in which the data is queried and returned.

Response 200 OK

application/json

[
    {
        "time_15m": "2022-04-13T15:42:05.901Z",
        "tot_pv": null,
        "tot_pv_castelfidardo": null,
        "tot_pv_cit": null,
        "tot_pv_aule_p": null,
        "tot_pv_aule_p_i1": null,
        "tot_pv_aule_p_i2": null,
        "tot_pv_aule_r": null,
        "tot_pv_ec": null,
        "tot_pv_ec_inv1": null,
        "tot_pv_ec_inv2": null,
        "tot_pv_ec_inv3": null,
        "tot_pv_ec_inv4": null,
        "tot_pv_i3p": null,
        "tot_pv_i3p_est": null,
        "tot_pv_i3p_ovest": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/Pv15m"
    },
    "title": "Response Get Data Pv Data Pv Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /data/water

Get water data

Description

Get data for Polito water in a given time range.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key
`aggregation`	query	None	15 m	No	Aggregation of data returned (mean).
`data_format`	query	None	raw	No	The format in which the data should be returned.
`end_datetime`	query	string	2025-11-10 15:00:00	No	Last timestamp of the query in the timezone provided
`start_datetime`	query	string	2025-11-09 15:00:00	No	First timestamp of the query in the timezone provided
`tz`	query	None	Europe/Rome	No	The timezone in which the data is queried and returned.

Response 200 OK

application/json

[
    {
        "time_15m": "2022-04-13T15:42:05.901Z",
        "tot_sede_centrale": null,
        "tot_font_aula_magna": null,
        "tot_font_aule_p": null,
        "tot_font_corr_denerg": null,
        "tot_font_corr_sud": null,
        "tot_font_corr_nord": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/Water15m"
    },
    "title": "Response Get Data Water Data Water Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /data/weather

Get weather station data

Description

Get data for Polito weather station in a given time range.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key
`aggregation`	query	None	15 m	No	Aggregation of data returned (mean).
`data_format`	query	None	raw	No	The format in which the data should be returned.
`end_datetime`	query	string	2025-11-10 15:00:00	No	Last timestamp of the query in the timezone provided
`start_datetime`	query	string	2025-11-09 15:00:00	No	First timestamp of the query in the timezone provided
`tz`	query	None	Europe/Rome	No	The timezone in which the data is queried and returned.

Response 200 OK

application/json

[
    {
        "time_15m": "2022-04-13T15:42:05.901Z",
        "atmospheric_pressure": null,
        "relative_humidity": null,
        "air_temperature": null,
        "global_solar_radiation": null,
        "diffuse_solar_radiation": null,
        "direct_solar_radiation": null,
        "horizontal_direct_solar_radiation": null,
        "illuminance": null,
        "total_rainfall": null,
        "wind_direction": null,
        "wind_speed": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/Weather15m"
    },
    "title": "Response Get Data Weather Data Weather Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /data/centrali_frigo

Get central cooling plants aggregated data

Description

Get data for Polito central cooling plants (CF1, CF2, CF3, Castello, Cittadella, Nodo1, Energy Center, CARS) in a given time range.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key
`aggregation`	query	None	15 m	No	Aggregation type (only 15 min supported)
`data_format`	query	None	raw	No	Format of the data output: raw JSON, CSV, or TXT
`end_datetime`	query	string	2025-11-10 15:00:00	No	End of the time range in the selected timezone
`start_datetime`	query	string	2025-11-09 15:00:00	No	Start of the time range in the selected timezone
`tz`	query	None	Europe/Rome	No

Response 200 OK

application/json

[
    {
        "time_15m": "2022-04-13T15:42:05.901Z",
        "cf1_tot": null,
        "cf1_gf3": null,
        "cf2_gf3": null,
        "cf2_gf2": null,
        "cf2_gf1": null,
        "cf2_aux1": null,
        "cf2_aux2": null,
        "cf2_tot": null,
        "cf3_tot": null,
        "cf3_gf3": null,
        "cf3_gf2": null,
        "cf3_gf1": null,
        "castello_nuovo": null,
        "cittadella_gf5": null,
        "cittadella_gf3": null,
        "cittadella_gf4": null,
        "cittadella_gf1": null,
        "cittadella_gf2": null,
        "nodo1_gf3": null,
        "nodo1_tot": null,
        "energy_center": null,
        "cars": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/CentraliFrigo15m"
    },
    "title": "Response Get Data Centrali Frigo 15M Data Centrali Frigo Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Metadata

GET /metadata/meters/

Get all meters

Description

Get all meters available in the monitoring infrastructure.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key

Response 200 OK

application/json

[
    {
        "id": 0,
        "description": "string",
        "notes": null,
        "date_from": null,
        "date_to": null,
        "datalogger_id": "string",
        "type_id": null,
        "unit_id": null,
        "quantity_id": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "items": {
        "$ref": "#/components/schemas/Meter"
    },
    "type": "array",
    "title": "Response Get Metadata Meters All Metadata Meters  Get"
}

Response 404 Not Found

GET /metadata/meters/last

Get last meter installed by id

Description

Get the last meter installed by id

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key

Response 200 OK

application/json

{
    "id": 0,
    "description": "string",
    "notes": null,
    "date_from": null,
    "date_to": null,
    "datalogger_id": "string",
    "type_id": null,
    "unit_id": null,
    "quantity_id": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "integer",
            "title": "id",
            "description": "The meter unique identifier"
        },
        "description": {
            "type": "string",
            "title": "Description of the meter",
            "description": "Description of the meter as it is on the datalogger with convention \"ID>] DESC\""
        },
        "notes": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Notes",
            "description": "Optional notes and comments about the meter"
        },
        "date_from": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Date from",
            "description": "The installation date"
        },
        "date_to": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Date to",
            "description": "The dismissal date"
        },
        "datalogger_id": {
            "type": "string",
            "title": "Datalogger ID",
            "description": "The datalogger ID to which the meter is connected"
        },
        "type_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Type ID",
            "description": "The type ID of the meter represented as BRICK class"
        },
        "unit_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Unit ID",
            "description": "The unit ID of the meter represented as QUDT unit"
        },
        "quantity_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Quantity ID",
            "description": "The quantity ID of the meter represented as QUDT quantityKind"
        }
    },
    "type": "object",
    "required": [
        "id",
        "description",
        "notes",
        "date_from",
        "date_to",
        "datalogger_id",
        "type_id",
        "unit_id",
        "quantity_id"
    ],
    "title": "Meter",
    "description": "Response model for meter entity",
    "examples": [
        {
            "datalogger_id": "M5-100275-20240320",
            "date_from": "2014-01-02",
            "description": "860] Attiva GME",
            "id": 860,
            "notes": "A Attiva GME - Utilizzatore",
            "quantity_id": "ElectricPower",
            "type_id": "Active_Power_Sensor",
            "unit_id": "KiloW"
        }
    ]
}

Response 404 Not Found

GET /metadata/meters/next

Get next meter id available to be installed

Description

Get the next meter id available to be installed

Response 200 OK

application/json

{
    "id": 0,
    "description": "string",
    "notes": null,
    "date_from": null,
    "date_to": null,
    "datalogger_id": "string",
    "type_id": null,
    "unit_id": null,
    "quantity_id": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "integer",
            "title": "id",
            "description": "The meter unique identifier"
        },
        "description": {
            "type": "string",
            "title": "Description of the meter",
            "description": "Description of the meter as it is on the datalogger with convention \"ID>] DESC\""
        },
        "notes": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Notes",
            "description": "Optional notes and comments about the meter"
        },
        "date_from": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Date from",
            "description": "The installation date"
        },
        "date_to": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Date to",
            "description": "The dismissal date"
        },
        "datalogger_id": {
            "type": "string",
            "title": "Datalogger ID",
            "description": "The datalogger ID to which the meter is connected"
        },
        "type_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Type ID",
            "description": "The type ID of the meter represented as BRICK class"
        },
        "unit_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Unit ID",
            "description": "The unit ID of the meter represented as QUDT unit"
        },
        "quantity_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Quantity ID",
            "description": "The quantity ID of the meter represented as QUDT quantityKind"
        }
    },
    "type": "object",
    "required": [
        "id",
        "description",
        "notes",
        "date_from",
        "date_to",
        "datalogger_id",
        "type_id",
        "unit_id",
        "quantity_id"
    ],
    "title": "Meter",
    "description": "Response model for meter entity",
    "examples": [
        {
            "datalogger_id": "M5-100275-20240320",
            "date_from": "2014-01-02",
            "description": "860] Attiva GME",
            "id": 860,
            "notes": "A Attiva GME - Utilizzatore",
            "quantity_id": "ElectricPower",
            "type_id": "Active_Power_Sensor",
            "unit_id": "KiloW"
        }
    ]
}

Response 404 Not Found

GET /metadata/meters/{uuid}

Get last meter installed by id

Description

Get the last meter installed by id

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key
`uuid`	path	string		No	The unique identifier of the meter

Response 200 OK

application/json

{
    "id": 0,
    "description": "string",
    "notes": null,
    "date_from": null,
    "date_to": null,
    "datalogger_id": "string",
    "type_id": null,
    "unit_id": null,
    "quantity_id": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "integer",
            "title": "id",
            "description": "The meter unique identifier"
        },
        "description": {
            "type": "string",
            "title": "Description of the meter",
            "description": "Description of the meter as it is on the datalogger with convention \"ID>] DESC\""
        },
        "notes": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Notes",
            "description": "Optional notes and comments about the meter"
        },
        "date_from": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Date from",
            "description": "The installation date"
        },
        "date_to": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Date to",
            "description": "The dismissal date"
        },
        "datalogger_id": {
            "type": "string",
            "title": "Datalogger ID",
            "description": "The datalogger ID to which the meter is connected"
        },
        "type_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Type ID",
            "description": "The type ID of the meter represented as BRICK class"
        },
        "unit_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Unit ID",
            "description": "The unit ID of the meter represented as QUDT unit"
        },
        "quantity_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Quantity ID",
            "description": "The quantity ID of the meter represented as QUDT quantityKind"
        }
    },
    "type": "object",
    "required": [
        "id",
        "description",
        "notes",
        "date_from",
        "date_to",
        "datalogger_id",
        "type_id",
        "unit_id",
        "quantity_id"
    ],
    "title": "Meter",
    "description": "Response model for meter entity",
    "examples": [
        {
            "datalogger_id": "M5-100275-20240320",
            "date_from": "2014-01-02",
            "description": "860] Attiva GME",
            "id": 860,
            "notes": "A Attiva GME - Utilizzatore",
            "quantity_id": "ElectricPower",
            "type_id": "Active_Power_Sensor",
            "unit_id": "KiloW"
        }
    ]
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /metadata/dataloggers/

Get all dataloggers

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key

Response 200 OK

application/json

[
    {
        "id": "string",
        "description": null,
        "notes": null,
        "serial": "string",
        "date_from": null,
        "date_to": null,
        "ip": "string"
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "items": {
        "$ref": "#/components/schemas/Datalogger"
    },
    "type": "array",
    "title": "Response Get Metadata Dataloggers All Metadata Dataloggers  Get"
}

Response 404 Not Found

GET /metadata/dataloggers/{uuid}

Get datalogger by id

Description

Get the last datalogger installed by id

Input parameters

Parameter	In	Type	Default	Nullable	Description
`APIKeyHeader`	header	string	N/A	No	API key
`uuid`	path	string		No	The unique identifier of the datalogger

Response 200 OK

application/json

{
    "id": "string",
    "description": null,
    "notes": null,
    "serial": "string",
    "date_from": null,
    "date_to": null,
    "ip": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "title": "id",
            "description": "The datalogger unique identifier"
        },
        "description": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Description of the datalogger",
            "description": "Description of the datalogger as it is on the datalogger"
        },
        "notes": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Notes",
            "description": "Optional notes and comments about the datalogger"
        },
        "serial": {
            "type": "string",
            "title": "Serial number of the datalogger",
            "description": "Serial number of the datalogger"
        },
        "date_from": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "The installation date",
            "description": "The date from which the datalogger was installed"
        },
        "date_to": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "The dismissal date",
            "description": "The date to which the datalogger was dis-installed"
        },
        "ip": {
            "type": "string",
            "title": "IP",
            "description": "The IP address of the datalogger"
        }
    },
    "type": "object",
    "required": [
        "id",
        "description",
        "notes",
        "serial",
        "date_from",
        "date_to",
        "ip"
    ],
    "title": "Datalogger",
    "description": "Response model for datalogger entity",
    "examples": [
        {
            "date_from": "2024-03-20",
            "description": "Castello Cabina",
            "id": "M5-100378-20240320",
            "ip": "172.30.102.124",
            "notes": "M501",
            "serial": "M5-100378"
        },
        {
            "date_from": "2024-03-20",
            "description": "Lingotto Cav Est 4P",
            "id": "M5-100282-20240320",
            "ip": "172.30.100.114",
            "serial": "M5-100282"
        }
    ]
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Chart

GET /chart/fotovoltaico

Return static data for photovoltaic weekly chart

Description

Return the Highcharts configuration for the photovoltaic chart. This chart shows the production in kW divided by plant during the last 7 days with a 15 min detail. The plot is a stacked area chart with interactive tooltip and legend.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`lang`	query	None	it	No	What is the graph language?

Response 200 OK

application/json

Schema of the response body

{
    "title": "Response Get Chart Config Fotovoltaico Chart Fotovoltaico Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /chart/bilancio

Return static weekly data for energy balance chart

Description

Return the Highcharts configuration for the energy balance chart. This chart shows the photovoltaic production and the electrical energy withdraw from the grid in kW divided during the last 7 days with a 15 min detail. The plot is a stacked area chart with interactive tooltip and legend.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`lang`	query	None	it	No	Graph language?

Response 200 OK

application/json

Schema of the response body

{
    "title": "Response Get Chart Config Bilancio Chart Bilancio Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /chart/acqua

Return static weekly data for water usage

Description

Return the Highcharts configuration for water usage chart. This chart shows the daily water usage in the last 30 days. The plot is a column chart with interactive tooltip and legend.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`lang`	query	None	it	No	Graph language?

Response 200 OK

application/json

Schema of the response body

{
    "title": "Response Get Chart Config Acqua Chart Acqua Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /chart/fontanelle

Return static weekly data for water usage

Description

Return the Highcharts configuration for the energy balance chart. This chart shows the photovoltaic production and the electrical energy withdraw from the grid in kW divided during the last 7 days with a 15 min detail. The plot is a stacked area chart with interactive tooltip and legend.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`lang`	query	None	it	No	Graph language?

Response 200 OK

application/json

Schema of the response body

{
    "title": "Response Get Chart Config Fontanelle Chart Fontanelle Get"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Report

GET /report/meter

Report Meter

Description

Report that contains info related to a meter id.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`end_datetime`	query	string	2025-11-10 15:00:00	No	Last timestamp of the query in the timezone provided
`start_datetime`	query	string	2024-11-10 15:00:00	No	First timestamp of the query in the timezone provided
`uuid`	query	integer		No	Meter ID to analyze

Response 200 OK

text/html

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /report/water

Report Water

Description

Report that summarizes information for water meters.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`end_datetime`	query	string	2025-11-10 15:00:00	No	Last timestamp of the query in the timezone provided
`start_datetime`	query	string	2015-01-01T00:00:00	No	First timestamp of the query in the timezone provided

Response 200 OK

text/html

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /report/palinsesti

Report Palinsesti

Description

Report that contains info related to "Palinsesti" project static information

Input parameters

Parameter	In	Type	Default	Nullable	Description
`year`	query	integer	2025	No	Year to analyze

Response 200 OK

text/html

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /report/pv

Report Fotovoltaico

Description

Report fotovoltaico che riepiloga la produzione e il bilancio energetico degli impianti PV.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`end_datetime`	query	string	2025-11-10 15:00:00	No	End of the analysis period
`start_datetime`	query	string	2024-11-10 15:00:00	No	Start of the analysis period

Response 200 OK

text/html

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string"
}

Response 404 Not Found

Response 422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Schemas

Aggregation

Type: string

CentraliFrigo15m

Name	Type
`cars`
`castello_nuovo`
`cf1_gf3`
`cf1_tot`
`cf2_aux1`
`cf2_aux2`
`cf2_gf1`
`cf2_gf2`
`cf2_gf3`
`cf2_tot`
`cf3_gf1`
`cf3_gf2`
`cf3_gf3`
`cf3_tot`
`cittadella_gf1`
`cittadella_gf2`
`cittadella_gf3`
`cittadella_gf4`
`cittadella_gf5`
`energy_center`
`nodo1_gf3`
`nodo1_tot`
`time_15m`	string(date-time)

Data15m

Name	Type
`avg_value`
`count_value`
`max_value`
`meter_id`
`min_value`
`sum_value`
`tag`	string
`time_15m`	string(date-time)

Datacenter15m

Name	Type
`time_15m`	string(date-time)
`tot_dc`
`tot_dc_aux`
`tot_dc_gf`
`tot_dc_i1`
`tot_dc_i1_cabina`
`tot_dc_i1_it`
`tot_dc_i1_vent`
`tot_dc_i2`
`tot_dc_i2_it`
`tot_dc_i2_vent`
`tot_dc_i3`
`tot_dc_i3_it`
`tot_dc_i3_vent`
`tot_dc_it`
`tot_dc_vent`

DataFormat

Type: string

Datalogger

Name	Type
`date_from`
`date_to`
`description`
`id`	string
`ip`	string
`notes`
`serial`	string

HealthCheck

Name	Type
`status`	string

HTTPValidationError

Name	Type
`detail`	Array<ValidationError>

Language

Type: string

Meter

Name	Type
`datalogger_id`	string
`date_from`
`date_to`
`description`	string
`id`	integer
`notes`
`quantity_id`
`type_id`
`unit_id`

Pv15m

Name	Type
`time_15m`	string(date-time)
`tot_pv`
`tot_pv_aule_p`
`tot_pv_aule_p_i1`
`tot_pv_aule_p_i2`
`tot_pv_aule_r`
`tot_pv_castelfidardo`
`tot_pv_cit`
`tot_pv_ec`
`tot_pv_ec_inv1`
`tot_pv_ec_inv2`
`tot_pv_ec_inv3`
`tot_pv_ec_inv4`
`tot_pv_i3p`
`tot_pv_i3p_est`
`tot_pv_i3p_ovest`

Tag

Type: string

Timezone

Type: string

ValidationError

Name	Type
`loc`	Array<>
`msg`	string
`type`	string

Water15m

Name	Type
`time_15m`	string(date-time)
`tot_font_aula_magna`
`tot_font_aule_p`
`tot_font_corr_denerg`
`tot_font_corr_nord`
`tot_font_corr_sud`
`tot_sede_centrale`

Weather15m

Name	Type
`air_temperature`
`atmospheric_pressure`
`diffuse_solar_radiation`
`direct_solar_radiation`
`global_solar_radiation`
`horizontal_direct_solar_radiation`
`illuminance`
`relative_humidity`
`time_15m`	string(date-time)
`total_rainfall`
`wind_direction`
`wind_speed`

Security schemes

Name	Type	Scheme	Description
APIKeyHeader	apiKey

Name	Description
Metadata	Gets metadata of monitoring infrastructure.
Data	Gets data values from installed metering points.
Report	Internal reports.
Chart	Return chart config for POLITO website.
Developers	A list of api calls to perform development tests.

API Reference

Base URL

POLITO Data API 1.0.3

Developers

GET /health/live

GET /health/ready

GET /auth/protected

GET /auth/public

GET /auth/apikey/endpoints

Data

GET /data/meters

GET /data/datacenter_1

GET /data/pv

GET /data/water

GET /data/weather

GET /data/centrali_frigo

Metadata

GET /metadata/meters/

GET /metadata/meters/last

GET /metadata/meters/next

GET /metadata/meters/{uuid}

GET /metadata/dataloggers/

GET /metadata/dataloggers/{uuid}

Chart

GET /chart/fotovoltaico

GET /chart/bilancio

GET /chart/acqua

GET /chart/fontanelle

Report

GET /report/meter

GET /report/water

GET /report/palinsesti

GET /report/pv

Schemas

Aggregation

CentraliFrigo15m

Data15m

Datacenter15m

DataFormat

Datalogger

HealthCheck

HTTPValidationError

Language

Meter

Pv15m

Tag

Timezone

ValidationError

Water15m

Weather15m

Security schemes

Tags