Mapping Luxembourg’s Libraries How to programmatically use the BnL’s Open Data

This project locates Luxembourg’s Libraries on a map. The goal of the project is twofold: provide a visual representation of the location of Luxembourg’s libraries on a map which could be used to help patrons find a library near them; and introduce how to use one of the application programming interfaces (API) made available by the National Library of Luxembourg (BnL) through the data.bnl.lu website in a simple project.

In the future, further projects will expand on this first one to access the BnL’s digital collections.

The BnL provides the data as a list of libraries and their addresses. We will use the addresses as well as their GPS coordinates in order to map them.

The project consists of 4 steps:

1. Retrieving the list of libraries;
2. Getting the address details of each library;
3. Getting the GPS coordinates of each library;
4. Mapping the coordinates and displaying the map.

We use Jupyter Labs to encapsulate all the information regarding the project in a single notebook and Python is used as the programming language. If you want to follow along, the Jupyter notebook is available on GitHub.

Retrieving the List of Libraries

The list of libraries is available from the Open Data website of the BnL. Full information on this API is available here: https://data.bnl.lu/apis/infobib/.

In Python, it is a simple call to the API that provides us with the list of libraries and another command to convert it into a readable format:

The result is a list of libraries and their internal code that looks like this:

You can try this yourself directly in your browser with this link: https://infobib.bibnet.lu/bibnet-libraries.json.

Getting the Address Details of each Library

Getting the address details is a bit more involved. First, we build the URL we need by inserting the code for the library and then, we run the query.

We check if there is an address within the data returned, and if that is the case, we retrieve the street, city and post code which is used to build the search string needed to retrieve the GPS coordinates.

Getting the GPS Coordinates of each Library

Why do we need the GPS Coordinates? In order to produce a map using OpenStreetMap (OSM), we have chosen to use Folium which provides a simple interface to OSM.  Folium’s API requires GPS coordinates to be able to place a point on a map. Nominatim, a service of OSM, is used to retrieve the GPS coordinates of each library based on its address.

One specificity of Nominatim’s search engine is that if we keep “L-” in front of the post code, it doesn’t find the address. Therefore, we have remove the first two characters in the post code string in order to supply Nominatim with only the numbers of the post code. Example:

https://nominatim.openstreetmap.org/search.php?­format=jsonv2&street=66+Grand+Rue&­city=Vianden&country=Luxembourg&postalcode=9410

Thus, we launch the query to retrieve the GPS coordinates for the specified address and convert the response into a readable format. If the address was found, we now have the GPS coordinates.

The address and coordinates are saved linked to the library’s name. We then wait 1 second as per the Nominatim’s usage policy before we make the next request.

Mapping the Coordinates and Displaying the Map

The map is created by providing a set of GPS coordinates. In this case, we have used the city of Colmar-Berg as it is a central point in the country.

It is a simple job now to loop through the list of libraries and add a marker to the map. The library name and its address are added to the pop-up so that they can be easily copied by the user if desired.

Displaying the map is as simple as asking Python to “print” the variable called “map”.