It handles the information related to the pollution dispersion of a specific area.
Pollution dispersion is represented by a heatmap in GeoTIFF format.
Important: This endpoint is available only if the Optima dispersions API module has been installed.
A GeoTIFF image takes as input a compressed file (.zip) from an http data stream.
The archive contains one or more .txt files. Every file represents a pollutant and contains data in the form of a ARC/INFO ASCII GRID (or Esri Grid) that are converted into a raster band representing the heatmap in GeoTIFF format.
All files must refer to the same area (for example, same starting corner, same width, same height, etc.).
Naming rules
The compressed archive must have the following naming convention:
pollution_dispersions_yyyyMMdd_HHmmss.zip
yyyyMMdd_HHmmss is the suffixed timestamp automatically added at creation time.
Inside the archive, every txt file must have its name associated to its respective pollutant.
Valid pollutant identifiers are:
-
co (carbon monoxide)
-
no2 (nitrogen dioxide)
-
so2 (sulfur dioxide)
-
o3 (ozone)
-
pm10 (particulate matter 10μm)
-
pm2.5 (particulate matter 2.5μm)
Example:
Before using the endpoint, you must run the authentication phase (→ Login).
After the authentication, a session opens and a valid session token persists until:
- The end of the session time-out, that is set through the parameter sessionTimeout (→ OptimaWSI configuration > OptimaAuth section).
- An explicit Logout call (→ Logout).
Response
Response status
| HTTP status | Description |
|---|---|
|
201 Created |
GeoTIFF image successfully generated. |
|
400 Bad Request |
Several conditions can be classified under this code. Main examples:
|
|
500 Internal Server Error |
Internal server error. |
Response content-type
Application/JSON
Response output
The output is composed of:
-
The path of the new GeoTIFF file
-
The list of the archived GeoTIFF files
-
The list of the deleted and expired GeoTIFF files
Response example: GeoTIFF created succesfully
Request
https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/dispersions
Response status
| HTTP status | Description |
|---|---|
|
201 |
GeoTIFF image successfully generated. |
Response output
{
"newGeoTiffPath": "/rasters/pollution_dispersions_20241025_153522.tif",
"archivedGeoTiffPath": ["/rasters/historical/pollution_dispersions_20241024_153045.tif"],
"deletedExpiredFiles":["/rasters/historical/pollution_dispersions_20241122_173412.tif","/rasters/historical/pollution_dispersions_20241121_112615.tif"]
}
Response example: Invalid output directory
Request
https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/dispersions
Response status
| HTTP status | Description |
|---|---|
|
400 |
Invalid output directory |
Response output
{
"details": "Error id 27ae418d-3db9-432c-b024-04152a9cf1fe-1, org.jboss.resteasy.spi.UnhandledException: java.io.FileNotFoundException: Directory '/rasters/output' does not exist.",
"stack": "org.jboss.resteasy.spi.UnhandledException: java.io.FileNotFoundException: Directory '/rasters/output' does not exist.\r\n\tat org.jboss.resteasy.core.ExceptionHandler.handleApplicationException(ExceptionHandler.java:107)\r\n\tat org.jboss. 15 more"
}