Exercise 1 - Your first dataset
In this section you are going to publish a vector dataset.
For this exercise, we will use a CSV dataset of free Wifi locations in Florence, kindly provided by opendata.comune.fi.it.
You can find this dataset in
This exercise consists of two key steps:
- adapt the
pygeoapi.config.ymlto define this dataset as an OGC API - Features collection
- ensure that pygeoapi can find and connec to the data file
We will use the
docker-compose.yml file provided.
Verify the existing Docker Compose config
Before making any changes, we will make sure that the initial Docker Compose setup provided to you is actually working. Two files are relevant:
Test the workshop configuration
- In a terminal shell navigate to the workshop folder and type:
http://localhost:5000in your browser, verify some collections 1. Close by typing
You may also run the Docker container in the background (detached) as follows:
docker-compose up -d docker ls # verify that the pygeoapi container is running # visit http://localhost:5000 in your browser, verify some collections docker logs --follow pygeoapi # view logs docker-compose stop
Publish first dataset
You are now ready to publish your first dataset.
Setting up the pygeoapi config file
- Open the file
workshop/exercises/pygeoapi/pygeoapi.config.ymlin your text editor
- Look for the commented config section starting with
# START - EXERCISE 1 - Your First Collection
- Uncomment all lines until
# END - EXERCISE 1 - Your First Collection
Make sure that the indentation aligns (hint: directly under
# START ...)
The config section reads:
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
The most relevant part is the
providers section. Here, we define a
pointing the file path to the
/data directory we will mount (see next) from the local
directory into the Docker container above. Because a CSV is not a spatial file, we explicitly
configure pygeoapi so that the longitude and latitude (x and y) is mapped from the columns
lat in the CSV file.
To learn more about the pygeoapi configuration syntax and conventions see the relevant chapter in the documentation.
pygeoapi includes numerous data providers which enable access to a variety of data formats. Via the OGR/GDAL plugin the number of supported formats is almost limitless. Consult the data provider page how you can set up a connection to your dataset of choice. You can always copy a relevant example configuration and place it in the datasets section of the pygeoapi configuration file for your future project.
Making data available in the Docker container
As the Docker container (named
pygeoapi) cannot directly access files on your
local host system, we will use Docker volume mounts. This can be defined
docker-compose.yml file as follows:
Configure access to the data
- Open the file
- Look for the commented section
# Exercise 1 -
- Uncomment that line
The relevant lines read:
43 44 45
./pygeoapi/pygeoapi.config.yml file was already mounted. Now
we have also mounted (made available) the entire local directory
Start with updated configuration
- Start by typing
- Observe logging output
- If no errors: open http://localhost:5000
- Look for the Free Wifi Collection
- Browse through the collection
Debugging configuration errors
Incidentally you may run into errors, briefly discussed here:
- A file cannot be found, a typo in the configuration
- The format or structure of the spatial file is not fully supported
- The port (5000) is already taken. Is a previous pygeoapi still running? If you change the port, consider that you also have to update the pygeoapi config file
There are two parameters in the configuration file which help to address these issues.
Set the logging level to
DEBUG and indicate a path to a log file.
On Docker, set the path of the logfile to the mounted folder, so you can easily access it from your host system. You can also view the console logs from your Docker container as follows:
docker logs --follow pygeoapi
Errors related to file paths typically happen on initial setup. However, they may also happen at unexpected moments, resulting in a broken service. Products such as GeoHealthCheck aim to monitor, detect and notify service health and availability. The OGC APi - Features tests in GeoHealthCheck poll the availability of the service at intervals. Consult the GeoHealthCheck documentation for more information.