User Guide
Introduction
The Open Data portal of the City of Žilina provides access to data through individual datasets. Each dataset contains specific data from a selected area together with the technical information required for its use.
The portal is intended for users who want to display, analyze, or use the data in their own applications and systems.
What a dataset contains
Each dataset includes basic information that helps users understand what data it provides and how it can be accessed. This typically includes:
• the dataset name,
• a brief description of its content,
• the dataset API address,
• the supported method,
• input parameters,
• a request example,
• a response example,
• a description of the fields in the response,
• where applicable, available output formats and additional metadata.
API address and method
Each dataset includes an API address, which is the internet address to which a request is sent in order to obtain the data.
Each dataset also specifies a method, most commonly GET or POST. With the GET method, parameters are usually added directly to the address. With the POST method, they are sent separately in the request body.
To send a request correctly, it is therefore not enough to know only the dataset address. The specified method must always be taken into account as well.
Input parameters
Some datasets also require input parameters when queried. These determine what data should be returned in the response.
Each parameter usually includes its name, data type, information on whether it is required or optional, and a brief description of its meaning. If a parameter is required, it must be entered exactly as described. Otherwise, the dataset may not return the requested data or may return an error.
For example, the cyclists counter dataset uses the classType parameter with the value bike.
How to send a request to a dataset
To obtain data, a request must be sent to the dataset API address in the manner specified for that dataset.
First, it is necessary to check the dataset address, the method used, and any input parameters. With the GET method, parameters are added to the address. With the POST method, they are sent in the request body, most commonly in JSON format.
Requests can be sent using various tools, for example Postman, Curl, Python, or JavaScript.
Output data formats
The Open Data portal of the City of Žilina may provide data in several formats depending on the dataset. The choice of format depends on how the user intends to work with the data further.
JSON
The JSON format is particularly suitable for technical data processing in applications, systems, or scripts. It makes it possible to clearly display the structure of the response, including nested data.
CSV
The CSV format is mainly suitable for opening in spreadsheet applications such as Excel or LibreOffice Calc. However, in more complex datasets, some nested data may be stored as text in a single field.
XML
The XML format is intended mainly for data exchange between systems. It is used especially where the target system specifically expects this format.
GeoJSON
The GeoJSON format is used for datasets containing geographic data and is suitable for displaying objects on a map.
Examples of sending a request in different tools
Below are examples of using the cyclists counter dataset. The examples use the POST method and the classType parameter with the value bike.
Curl
curl -X POST "https://opendata.zilina.sk/api/datasets/v1/city-dashboard/bicycles/list" \
-H "Content-Type: application/json" \
-d '{
"classType": "bike"
}'
To obtain output in CSV or XML format, modify the dataset address by adding the parameter:
• ?outputType=csv
• ?outputType=xml
Example:
• https://opendata.zilina.sk/api/datasets/v1/city-da...
• https://opendata.zilina.sk/api/datasets/v1/city-da...
Python
import requests
url = "https://opendata.zilina.sk/api/datasets/v1/city-dashboard/bicycles/list"
payload = {
"classType": "bike"
}
response = requests.post(url, json=payload)
print(response.json())
To obtain output in CSV or XML format, modify the dataset address by adding ?outputType=csv or ?outputType=xml. At the same time, it is recommended to use response.text instead of response.json(), because the response will be textual.
JavaScript
fetch("https://opendata.zilina.sk/api/datasets/v1/city-dashboard/bicycles/list", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
classType: "bike"
})
})
.then(response => response.json())
.then(data => console.log(data));
To obtain output in CSV or XML format, modify the dataset address by adding ?outputType=csv or ?outputType=xml. At the same time, response.json() must be replaced with response.text().
Postman
When using Postman, it is necessary to:
• select the POST method,
• enter the dataset address,
• in the Body tab, select raw format and JSON type,
• enter the parameter:
{
"classType": "bike"
}
To obtain output in CSV or XML format, modify the dataset address by adding ?outputType=csv or ?outputType=xml.
Typical error states
Error responses may also occur when working with the API. The most common are the following:
400 – Bad Request
The request was not sent in the correct format or a required parameter is missing.
404 – Resource Not Found
The specified dataset address does not exist or is incorrect.
500 – Internal Server Error
A problem occurred on the server side while processing the request.
If the error persists, it is recommended to check the dataset address, the method used, and the entered parameters.
Dataset metadata
Metadata is available directly in the detail of the specific dataset. It contains basic information about the dataset, in particular its name, description, API address, supported method, input parameters, output formats, and a description of the fields in the response.
Metadata helps the user understand what the dataset contains, how it is used, and what the individual data fields mean.
Conclusion
The Open Data portal of the City of Žilina provides data in a standardized way and includes the basic technical information required for using each dataset.
It is therefore recommended to first check the dataset address, method, parameters, and available output formats. The provided request examples can then be used and adjusted to specific needs.