Documentação da API

Esta página descreve o comportamento da API do dados.gov.

Para que seja possível executar as operações de escrita, precisa primeiro de se autenticar/registar e obter uma chave de API nas configurações do seu perfil.

Esta chave deve ser fornecida em cada chamada à API no cabeçalho HTTP X-API-KEY.

As chamadas à API estão sujeitas às mesmas permissões que a interface web (frontend).

Por exemplo, é necessário pertencer a uma organização para modificar os seus conjuntos de dados.

Alguns métodos são paginados e seguem sempre o mesmo padrão. A lista de objetos é encapsulada num objeto Page.

Não é necessário calcular as páginas anterior e seguinte porque as URLs estão disponíveis na resposta sob os atributos previous_page e next_page. Estes serão definidos como null se não existir nenhuma página anterior ou seguinte.

Exemplo:

{
    "data": [{...}, {...}],
    "page": 1,
    "page_size": 20,
    "total": 43,
    "next_page": "https://dados.gov.pt/api/endpoint/?page=2",
    "previous_page": null
}

Todos os exemplos utilizam httpie e jq utilitários para fins de legibilidade. Não é necessário utilizar essas ferramentas no seu código, porém, são apenas formas de compreender melhor a API.

Verificar que o httpie está a funcionar

Quando o httpie estiver instalado, pode verificar que ele funciona conforme o esperado, digitando este comando na shell:

$ http 'https://dados.gov.pt/api/1/organizations/?page_size=1'

Deve retornar algo deste género:

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
... LOTS OF HEADERS ...

{
    "data": [
        {

            ... LOTS OF DATA ...

            "name": "Organization Name",
            "page": "https://dados.gov.pt/organizations/organization-name/",
            "slug": "organization-name",
            "uri": "https://dados.gov.pt/api/1/organizations/organization-name/",
            "url": null
        }
    ],
    "next_page": "https://dados.gov.pt/api/1/organizations/?page=2&page_size=1",
    "page": 1,
    "page_size": 1,
    "previous_page": null,
    "total": 529
}

Este resultado é muito detalhado e não precisamos de tanta informação ainda. É por isso que utilizamos o jq.

Verificando que o jq está a funcionar

Assim que o jq estiver instalado, podemos verificar que ele funciona como esperado, inserindo este comando na shell:

$ http 'https://dados.gov.pt/api/1/organizations/?page_size=1' | jq '.data[].name'

Deve retornar algo deste género:

"Organization Name"

Bem melhor. Agora que temos a certeza de que ele funciona conforme o esperado, vamos encurtar um pouco a linha de comando:

$ export API="https://dados.gov.pt/api/1/"

O comando é equivalente ao anterior e é também mais legível (não se esqueça das aspas):

$ http $API'organizations/?page_size=1' | jq '.data[].name'

Vamos agora explorar a própria API. Se ainda não se apercebeu, acabou de recolher a primeira organização através da API.

Navegando e recolhendo dados

Você pode selecionar uma lista de organizações (filtrada ou não) ou uma única organização. Quando alcança um "endpoint", o tamanho da página padrão é 20. Vamos recolher as 20 primeiras organizações a partir da API:

$ http $API'organizations/' | jq '.data[].name'

"Organization name 1"
"Organization name 2"
"Organization name 3"
"Organization name 4"
"Organization name 5"
"Organization name 6"
"Organization name 7"
"Organization name 8"
"Organization name 9"
"Organization name 10"
...
"Organization name X"

Este é um bom exemplo de uma listagem, mas e se quisermos percorrer as organizações retornadas? Vamos recolher apenas as 5 primeiras URIs de organizações:

$ http $API'organizations/?page_size=5' | jq '.data[].uri'

"https://dados.gov.pt/api/1/organizations/organization-uri-1/"
"https://dados.gov.pt/api/1/organizations/organization-uri-2/"
"https://dados.gov.pt/api/1/organizations/organization-uri-3/"
"https://dados.gov.pt/api/1/organizations/organization-uri-4/"
"https://dados.gov.pt/api/1/organizations/organization-uri-5/"

Agora vamos conseguir recolher uma única organização graças ao URI retornado:

$ http $API'organizations/organization-uri-x/' | jq '.'

É uma grande quantidade de dados para calcular. Vamos refinar estes dados, se apenas necessitarmos de métricas:

$ http $API'organizations/organization-uri-x/' | jq '.metrics'

{
  "dataset_views": 16345,
  "datasets": 178,
  "followers": 79,
  "members": 16,
  "nb_hits": 0,
  "nb_uniq_visitors": 0,
  "nb_visits": 0,
  "permitted_reuses": 82,
  "resource_downloads": 4316,
  "reuse_views": 257,
  "reuses": 3,
  "views": 699
}

Ou talvez apenas o nome dos membros dessa organização:

$ http $API'organizations/organization-uri-x/' | jq '.members[].user.last_name'

"Martin"
"Lee"
"Zhang"
"Wang"
"Nguyen"
"Garcia"
"Fernandes"
...
"Tales"
"Gonzalez"
"Hernandez"
"Smith"
"Smirnov"
"Müller"
"Santos"
"Bernard"

Depende de si a obtenção de dados que interessem ao seu projeto. Não hesite em percorrer o tutorial do jq e o manual se quiser navegar pela API através da linha de comandos em profundidade.

Modificar e apagar dados

Atenção: a modificação ou eliminação de dados com a API é definitiva e não é disponibilizado nenhum ambiente de testes (por enquanto). Esteja ciente destas responsabilidades antes de utilizar os seus grandes poderes.

Se tentar modificar um recurso sem um token de autenticação, será devolvido um erro 401:

$ http PUT $API'organizations/organization-uri-x/'

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Unauthorized",
    "status": 401
}

É necessário a especificar a sua chave de API (veja acima) e utilizar o cabeçalho HTTP X-API-KEY. Se tentar modificar um recurso sem permissão, será devolvido um erro 400:

$ http PUT $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Invalid API Key",
    "status": 401
}

Esta é a mensagem que receberá se especificou uma chave de API errada. Existe outra mensagem de erro que também poderá encontrar:

HTTP/1.1 403 FORBIDDEN
... LOTS OF HEADERS ...

{
    "message": "You do not have the permission to modify that object.",
    "status": 403
}

Esta mensagem ocorre se tentar aceder a um recurso que não pode editar com as suas credenciais. Se a sua chave for válida, deverá receber algo parecido com isto:

HTTP/1.1 200 OK
... LOTS OF HEADERS ...

{
    ...
}

Mas não alterou nada! É perfeitamente normal, não especificámos os dados corretos a enviar para o servidor.

$ http PUT $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here name="Lorem ipsum" description="The quick brown fox jumps over the lazy dog." | jq '{name: .name, description: .description}'

{
  "name": "Lorem ipsum",
  "description": "The quick brown fox jumps over the lazy dog."
}

O recurso foi modificado com sucesso. Finalmente, pode apagar um recurso com o pedido HTTP apropriado (atenção que não é possível reverter algo feito através da API neste momento):

$ http DELETE $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here

HTTP/1.0 204 NO CONTENT
... LOTS OF HEADERS ...

Uma vez efectuado, pode verificar que funciona emitindo um pedido GET contra o URI anterior:

$ http GET $API'organizations/organization-uri-x/'

HTTP/1.0 410 GONE
... LOTS OF HEADERS ...

{
    "message": "Organization has been deleted",
    "status": 410
}

Por favor, consulte a documentação de referência abaixo para mais interações com a API ou contacte-nos para questões relacionadas!