Do you know what an API is?
Application Programming Interfaces (APIs) are one of the most common information exchange and data access services nowadays.
They complement the availability of data in downloadable files and provide a series of advantages that make them an essential means of accessing and consuming data in any Open Data Initiative.
Moreover, it is the most suitable access mechanism for publishing data with a high update frequency, such as real-time data (weather API) or public transport data, considered of high value (Commission Implementing Regulation (EU) 2023/138 of 21 December 2022 establishing a list of specific high-value datasets and modalities for publication and re-use).
APIs are particularly useful for consuming all types of data automatically and can tailor the download to the desired data.
What are the advantages of using the Open Data Portal data API?
One advantage of APIs over downloading files is that they allow different operations to be applied during data access and retrieval. When consuming data via APIs, it is common to filter data and select categories or formats.
In this article, we will take a closer look at how they work and the possibility of reusing the content of the Cabildo de Tenerife's Open Data portal thanks to their use.
How to use the API datos.tenerife.es?
The documentation on the API of the Cabildo de Tenerife's Open Data portal can be found in the Data block at the top of the portal page. When you access the API section you will see the following screen:
In the APIs, communication between server and clients on the Web is carried out by means of the exchange of HTTP messages in a secure context of interaction.
There are two types of messages: requests, which are sent by the client to the server to request the initiation of some action to interact with the information resources, and responses, which constitute the materialisation of the requested action.
Each request, as we will see below, contains all the information necessary to execute the requested action. In the Cabildo's Open Data portal, the operations or actions that can be carried out use the ‘GET’ method on different types of objects:
- Datasets
- Resources
- Categories
- Organisations
- Tags
Operations on datasets
The API makes it possible to obtain the list of datasets published on the portal; the activity flow of all those that have been added or modified recently - in the last day; the information of those datasets that belong to a category; the datasets that respond to a specific search criterion or the metadata relation of a dataset and its resources.
In order to obtain a concrete answer, it would first be necessary to establish the desired parameters. In this case, we would start with the first operation established, which corresponds to the list of existing datasets in the portal catalogue.
After clicking on GET or on the arrow on the far right, it will be necessary to launch the actions ‘Try it out’ and ‘Execute’, in order to execute the content of the request. In this way, the request to be executed will be displayed first.
And then the response is shown, where we will obtain a list of all the datasets, which can also be downloaded.
The URL of the request will provide a list of the datasets available on the Open Data portal -in JSON format-, without having to access the portal. With this same URL you can make the data available in an updated form by pasting it into your own browser.
How can parameters be set to obtain specific results?
In order to specifically segment the datasets obtained, you can choose one of the existing parameters in each operation, to obtain those that belong to a specific category, that respond to a specific search criterion or that include specific metadata.
In the case of datasets belonging to a category (/action/group_package_show) it is mandatory to indicate an id.
This ‘id’ corresponds to the different categories included in the portal, also called ‘groups’. To identify which one is closest to your search, you can consult the categories listed on the portal's home page. But, without leaving the current page, they can also be obtained using the operations on ‘Categories’ (/action/group_list), which returns all those that the portal has (whether or not they contain datasets).
First click on ‘Try it out’ and then on ‘Execute’ to obtain the corresponding list. This image shows the list of the ‘id’ of the different existing categories.
After obtaining the corresponding ‘ids’, select the one that comes closest to the answer you wish to obtain and write it in the corresponding box, as indicated above.
In this way, the results would show all the datasets related to that category. In the following example, we will indicate ‘trade’ to visualise the results that would be obtained.
In the ‘limit’ box, you can indicate the maximum number of datasets you want to obtain per category (10 by default).
This operation makes it possible to obtain the list of specific and updated datasets, which can facilitate their reuse.
In the following operation (/action/package_search) a search for a dataset that satisfies a given search criterion could be performed. In this case, different parameters are displayed.
In the ‘q’ field, data can be queried using the Solr search syntax. For this, codes such as ‘tags’, ‘groups’ or ‘organisation’ would be used, followed by a colon and the corresponding word. Simple searches can also be performed in this field, using the word directly, without using codes.
As an example, entering ‘tags:restaurants’ will return the datasets in which this word is included as a tag.
In the same way, it is also possible to narrow the search by organisation (‘organisation’) or by category (‘groups’), as in the example ‘organisation:transports-interurbans-de-tenerife-titsa’.
How to get metadata of a dataset and its resources?
Another of the possibilities offered by the API is to obtain the metadata of a specific dataset and its resources (/action/package_show). First of all, it is necessary to know the ‘id’ or ‘name’ of the dataset to be queried, for which we can use any of the previous operations in whose results we can find the name and/or identifier of the resulting datasets.
From the previous example, from the operation /action/package_search we can select the corresponding ‘id’ or ‘name’ of the dataset from which we want to obtain its metadata specifically (for the previous example of ‘restaurants’):
So in this case using its ‘id’ (4912b6d8-89f3-48d7-9dd1-bdefb18dbb17) or ‘name’ (establecimientos-de-hosteleria-y-restauracion-de-tenerife) we would obtain the metadata of the dataset and its resources.
In this way, the corresponding list would be obtained, with the URL that could be used to have the updated data, as in the examples explained above.
If we continue advancing in the API documentation, we will see other operations or actions, indicated as follows:
/action/tag_list
/action/tag_show
/action/organisation_show
/action/resource_show
In these cases, they could be executed in the same way as those indicated above.
And so much for a brief explanation in which we show some of the possibilities of the catalogue API of the Cabildo de Tenerife's Open Data portal. It is clear that APIs are essential tools for accessing and sharing data efficiently and programmatically in the digital world.
So it only remains for you to discover more in our own portal datos.tenerife.es