API do Portal de Dados Abertos: consumo automatizado de dados

Sabe o que é uma API?

As interfaces de programação de aplicações (API) são um dos serviços mais comuns de intercâmbio de informações e de acesso a dados atualmente disponíveis.

Complementam a disponibilidade de dados em ficheiros descarregáveis e oferecem uma série de vantagens que a tornam um meio essencial de acesso e consumo de dados em qualquer iniciativa de dados abertos.

Além disso, é o mecanismo de acesso mais adequado para a publicação de dados com uma elevada frequência de atualização, tais como dados em tempo real (API meteorológica) ou dados de transportes públicos, considerados de elevado valor (Regulamento de Execução (UE) 2023/138 da Comissão, de 21 de dezembro de 2022, que estabelece uma lista de conjuntos de dados específicos de elevado valor e modalidades de publicação e reutilização).

As API são particularmente úteis para consumir automaticamente todos os tipos de dados e podem adaptar o descarregamento aos dados pretendidos.

Quais são as vantagens de utilizar a API de dados do Portal de Dados Abertos?

Uma vantagem das API em relação ao descarregamento de ficheiros é que permitem aplicar diferentes operações durante o acesso e a recuperação dos dados. Ao consumir dados através de APIs, é comum filtrar dados e selecionar categorias ou formatos.

Neste artigo, veremos em pormenor o seu funcionamento e a possibilidade de reutilizar o conteúdo do portal de dados abertos do Cabildo de Tenerife graças à sua utilização.

Como utilizar a API datos.tenerife.es?

A documentação sobre a API do portal de Dados Abertosdo Cabildo de Tenerife encontra-se no bloco Dados , na parte superior da página do portal. Quando aceder à secção API, verá o seguinte ecrã:

Nas APIs, a comunicação entre o servidor e os clientes na Web é realizada através do intercâmbio de mensagens HTTP num contexto seguro de interação.

Existem dois tipos de mensagens: os pedidos, que são enviados pelo cliente ao servidor para solicitar o início de alguma ação de interação com os recursos de informação, e as respostas, que constituem a materialização da ação solicitada.

Cada pedido, como veremos adiante, contém toda a informação necessária para executar a ação solicitada. No portal de Dados Abertos do Cabildo, as operações ou acções que podem ser realizadas utilizam o método "GET" sobre diferentes tipos de objectos:

• Conjuntos de dados
• Recursos
• Categorias
• Organismos
• Etiquetas

Operações de conjuntos de dados

A API permite obter a lista dos conjuntos de dados publicados no portal; o fluxo de atividade de todos os que foram adicionados ou modificados recentemente - no último dia; a informação dos conjuntos de dados que pertencem a uma categoria; os conjuntos de dados que respondem a um critério de pesquisa específico ou a relação de metadados de um conjunto de dados e dos seus recursos.

Para obter uma resposta concreta, seria necessário, em primeiro lugar, estabelecer os parâmetros desejados. Neste caso, começaríamos pela primeira operação estabelecida, que corresponde à lista de conjuntos de dados existentes no catálogo do portal.

Depois de clicar em GET ou na seta à direita, será necessário lançar as acções "Try it out" e "Execute", para executar o conteúdo do pedido. Desta forma, o pedido a ser executado será apresentado em primeiro lugar.

Em seguida, é apresentada a resposta, onde se obtém uma lista de todos os conjuntos de dados, que também podem ser descarregados.

O URL do pedido fornecerá uma lista dos conjuntos de dados disponíveis no portal de dados abertos - em formato JSON -, sem ter de aceder ao portal. Com este mesmo URL, pode disponibilizar os dados de forma actualizada, colando-os no seu próprio navegador.

Como posso definir parâmetros para obter resultados específicos?

Para segmentar especificamente os conjuntos de dados obtidos, pode escolher um dos parâmetros existentes em cada operação, para obter aqueles que pertencem a uma categoria específica, que respondem a um critério de pesquisa específico ou que incluem metadados específicos.

No caso dos datasets pertencentes a uma categoria (/action/group_package_show) é obrigatório indicar um id.

Este "id" corresponde às diferentes categorias incluídas no portal, também designadas por "grupos". Para identificar a que mais se aproxima da sua pesquisa, pode consultar as categorias listadas na página inicial do portal. Mas, sem sair da página atual, podem também ser obtidas através das operações sobre "Categorias" (/action/group_list), que devolve todas as que o portal possui (quer contenham ou não conjuntos de dados) .

Clique primeiro em "Experimentar" e depois em "Executar" para obter a lista correspondente. Nesta imagem, é apresentada a lista dos "id" das diferentes categorias existentes.

Depois de obter os "ids" correspondentes, selecione o que mais se aproxima da resposta que pretende obter e escreva-o na caixa correspondente, como indicado acima.

Desta forma, os resultados mostrarão todos os conjuntos de dados relacionados com essa categoria. No exemplo seguinte, indicaremos "comércio" para visualizar os resultados que seriam obtidos.

Na caixa "limite", pode indicar o número máximo de conjuntos de dados que pretende obter por categoria (10 por defeito).

Esta operação permite obter a lista de conjuntos de dados específicos e actualizados, o que pode facilitar a sua reutilização.

Na operação seguinte (/action/package_search) pode ser efectuada uma pesquisa de um conjunto de dados que satisfaça um determinado critério de pesquisa. Neste caso, são apresentados diferentes parâmetros.

No campo "q", os dados podem ser consultados utilizando a sintaxe de pesquisa Solr. Para o efeito, seriam utilizados códigos como "tags", "groups" ou "organisation", seguidos de dois pontos e da palavra correspondente. Também podem ser efectuadas pesquisas simples neste campo, utilizando diretamente a palavra, sem utilizar códigos.

Por exemplo, se introduzir "tags:restaurantes", obterá os conjuntos de dados em que esta palavra está incluída como tag.

Da mesma forma, pode também restringir a pesquisa por organização ("organisation") ou por categoria ("groups"), como no exemplo "organisation:transport-inter-urban-transport-from-tenerife-titsa".

Como obter metadados de um conjunto de dados e dos seus recursos?

Outra possibilidade oferecida pela API é a de obter os metadados de um conjunto de dados específico e dos seus recursos (/action/package_show). Em primeiro lugar, é necessário saber o "id" ou "nome" do conjunto de dados a consultar, para o que podemos utilizar qualquer uma das operações anteriores em cujos resultados podemos encontrar o nome e/ou identificador dos conjuntos de dados resultantes.

Do exemplo anterior, a partir da operação /action/package_search podemos selecionar o "id" ou "name"correspondente do conjunto de dados do qual queremos obter especificamente os seus metadados (para o exemplo anterior de "restaurants"):

Assim, neste caso, utilizando o seu "id" (4912b6d8-89f3-48d7-9dd1-bdefb18dbb17) ou "name" (establecimientos-de-hosteleria-y-restauracion-de-tenerife), obteríamos os metadados do conjunto de dados e dos seus recursos.

Desta forma, obter-se-ia a lista correspondente, com o URL que poderia ser utilizado para ter os dados actualizados, como nos exemplos explicados anteriormente.

Se continuarmos a avançar na documentação da API, veremos outras operações ou acções, indicadas da seguinte forma:

/action/tag_list

/action/tag_show

/action/organisation_show

/action/resource_show

Nestes casos, podem ser executadas da mesma forma que as indicadas acima.

Até aqui, uma breve explicação em que mostramos algumas das possibilidades da API de catálogo do portal de dados abertos do Cabildo de Tenerife. É evidente que as APIs são ferramentas essenciais para aceder e partilhar dados de forma eficiente e programática no mundo digital.

Por isso, só lhe resta descobrir mais no nosso próprio portal datos.tenerife.es