Skip to content

DATA API DETAILS

What is an API

An API is an application programming interface. In other words, it is a set of general-purpose functions and procedures used in software development for integration between applications. The acronym API stands for application programming interface.

Open Data Bizkaia provides two types of APIs:

  • Catalogue management API: API used to query and manage catalogue information, resources, datasets, tags, themes, etc.
  • CSV resource query API: API that allows querying and filtering the information contained in a CSV of a resource.

Both the CSV resource query APIs and the catalogue management APIs are provided as REST Web Services in JSON format.

Most of the methods can also be invoked directly via the URL, adding any necessary parameters. The callback parameter can be included in the call to these methods so that the response is returned in JSONP format for later use with Javascript.

Catalogue management API

This is the API offered by the CKAN application to manage the dataset catalogue. We can access this API through the URL as indicated in the "API access point" section, adding the name of the method we wish to Access.

Reusers can, through this API, access the same information on resources, datasets, tags, topics, etc. published on the Open Data Bizkaia portal itself.

Some of the methods that can be used with this API are as follows:

  • current_package_list_with_resources: returns a list of all current datasets with their resources
  • package_search: search for a given dataset within the catalogue
  • resource_search: search for a particular resource within the catalogue
  • package_show: returns the metadata of a dataset
  • resource_show: returns the metadata of a resource
  • group_list: list of portal themes

CSV resource query API

This API allows you to act on a specific CSV resource in the portal. When a CSV is uploaded to the application, a table is created internally in the datastore database for this resource. The API for querying CSV resources is precisely the datastore API, which allows queries to be made directly on these tables.

The Open Data Bizkaia portal provides an endpoint for all the platform's CSVs, which allows you to search for information within a resource by defining a series of search criteria that are added as parameters to the call.

This endpoint is the following (datastore_search): (datastore_search):
https://www.opendatabizkaia.eus/es/api/3/action/datastore_search

Note that the parameter /es/ refers to the Spanish language, and /eu/ can be used for Basque and /en/ for English, as long as the resource is available in each of these languages.

When querying a specific resource, the idenftifier (ID) of the resource to be queried must be defined as a parameter.

What is the identifier of a resource

To obtain the identifier (ID) of a resource you must take into account that the URLs of the resources in the portal are of the type:
https://www.opendatabizkaia.eus/en/catalogue/name-dataset/resource/identifier

Where identifier is the idenftifier (ID) of the resource in question. So by simply browsing the portal resources you can get the resource identifiers to query the API with that idenftifier (ID).

For example, for the resource "Real estate (2019 - 2022)", right-clicking on the "Download CSV" section and choosing the option "Copy link address" will give the following URL which includes the resource identifier: https://www.opendatabizkaia.eus/en/dump/58f8c26e-996a-42e3-a49e-ef1e8e754ce6/bienes-inmuebles-2019-2022?format=csv

How to get the names of the fields of a resource

To obtain the names of the fields of a resource and to be able to make queries with the API, we only need to access the preview of the CSV resource.

For example, if we access the resource "Real estate (2019-2022)" and we look at the data explorer view, we can see that the resource has some headers which in this case in question are: SOZIETATEA_EU/SOCIEDAD_EU, SOZIETATEA_CAS/SOCIEDAD_CAS, EKITALDIA/EJERCICIO, etc.

How to get the names of the fields of a resource

With the resource idenftifier (ID) and these fields, we can make queries, as explained in the section "How the API is used to make queries".

How the API is used to make queries

The endpoint for queries is as follows:
https://www.opendatabizkaia.eus/es/api/3/action/datastore_search

The parameters that can be used with this endpoint are:

  • resource_id (string - mandatory) - idenftifier (ID) of the CSV resource to be searched for.
  • filters (dictionary) - conditions to be met. Example: {" SOZIETATEA_EU/SOCIEDAD_EU ": "%BFA%"}
  • q (string or dictionary) - full text search. You can specify a string to search in all fields or a dictionary to search in specific fields, e.g. {"key1": "a", "key2": "b"}.
  • distinct (boolean) - returns only different rows.
  • plain (boolean) - treats the query as if it were plain text.
  • language (string) - query language in full text.
  • limit (int) - maximum number of results. By default it returns 100 results.
  • offset (int) - number of results to skip. Useful for paging results.
  • fields (string) - list of fields to be included in the response. By default it returns all fields in the same order as in the CSV.
  • sort (string) - name of the fields to be sorted separated by commas: " SOZIETATEA_EU/SOCIEDAD_EU, SOZIETATEA_CAS/SOCIEDAD_CAS "
  • include_total (boolean) - Returns the total count of matching records (optional, default: true).

How to obtain the updated data of a resource

To obtain the most recent data for an entry for a resource in a dataset, the last updated resource in the dataset must be selected. The "last_modified" metadata provides such information within the response to the request and allows the selection of the one closest to the current date.

Thus, the reuser can implement in the application being developed a function that goes through all the resources in a given dataset and selects the most up-to-date one.

Finally, once you have the last updated resource, you must make a query to the datastore API with the idenftifier (ID) of the resource in question retrieved in the processing described above. And if you wish, in this last request to the datastore API you can pass parameters as filters.