Começar rapidamente
Experimente um pedido simples. Cole este URL no browser ou numa aplicação:
Ao abrir este link, obtêm-se dados de uma série específica em formato estruturado.
Como funciona
A API organiza os dados da seguinte forma:
Quais os passos para obter os dados?
Quais os passos para obter os dados?
Os dados são devolvidos em formato JSON-stat, adequado a utilização em código e integração em sistemas.
Não é necessário conhecer em detalhe este formato para começar a utilizar a API, mas é útil saber como os dados são organizados.
Na prática, isto significa que:
- os dados não vêm como uma tabela simples
- estão organizados por dimensões (por exemplo: periodicidade, setor de atividade)
- cada valor corresponde a uma combinação dessas dimensões
Nota: não é possível extrair todos os dados de um domínio com um único pedido.
É necessário consultar os datasets e efetuar pedidos específicos para cada um. Depois de perceber esta estrutura, o passo seguinte é construir o pedido à API.
Construir um pedido
Os pedidos são feitos através de um URL e seguem uma estrutura simples.
Um pedido à API é composto por vários elementos.
| Elemento | Corresponde a |
|---|---|
domain_id | domínio |
dataset_id | dataset |
series_ids | série(s) |
lang | idioma |
Estes identificadores são obtidos ao explorar os dados disponíveis através da API, nomeadamente os domínios, datasets e séries.
O dataset_id é gerado automaticamente e pode ser obtido via API ou no próprio BPstat.
Se ainda não souber que domínio, dataset ou série utilizar, consulte na secção seguinte os endpoints disponíveis.
Exemplo prático
Suponha que pretende obter uma série de taxas de câmbio.
Cada observação corresponde a uma combinação única dessas dimensões. Esta estrutura permite organizar e analisar os dados de forma flexível.
Como apresentado no exemplo prático, no URL, 29 corresponde ao domínio, 23e0cdd56bddb4ad3016a9c3ad63a539 é o identificador do dataset correspondente ao conjunto de dados selecionado, e 12531971 identifica a série.
O URL reflete diretamente as escolhas feitas para obter os dados.
Resultado:
- dados organizados por período
- valores numéricos da série
- estrutura pronta para análise automática
O mesmo pedido pode ser reutilizado em scripts, dashboards ou aplicações.
Este é o mesmo princípio utilizado nos restantes pedidos à API: identificar a série pretendida e construir o URL com os parâmetros necessários.
Os dados são obtidos através de um URL, sem necessidade de navegação manual no portal.
A resposta é devolvida num formato adequado a análise programática e integração.
Aplicável em consultas pontuais, automatizações simples ou sistemas mais complexos.
Endpoints disponíveis
A API disponibiliza vários endpoints para explorar dados e metadados.
Esta secção ajuda a descobrir que dados existem antes de construir um pedido.
Como usar os endpoints?
Comece por listar os domínios disponíveis.
Depois, consulte os datasets do domínio selecionado.
| Passo 3 – Estrutura | |
|---|---|
| Explore dimensões, categorias e séries antes de pedir os dados (observações). | |
| dimensões | https://bpstat.bportugal.pt/data/v1/domains/{domain_id}/dimensions/ |
| categorias | https://bpstat.bportugal.pt/data/v1/domains/{domain_id}/dimensions/{dimension_id} |
| séries | https://bpstat.bportugal.pt/data/v1/series/ |
| dados | https://bpstat.bportugal.pt/data/v1/domains/{domain_id}/datasets/{dataset_id} |
Formas de acesso
Dependendo da utilização pretendida, existem duas formas principais de aceder aos dados.
Use API para integração e automatização. Use Excel ou CSV para análise manual.
Formato JSON-stat, estrutura multidimensional.
Adequado para integração, automatização e análise programática.
Formatos prontos a usar.
Download rápido, utilização prática em Excel e automatização simples.
Como gerar links no BPstat?
Se preferir, pode gerar os links de pedidos diretamente no BPstat. Para isso basta:
- navegar num domínio estatístico
- consultar a lista de séries
- filtrar pelas dimensões disponíveis
- clicar em "atualizar"
- escolher as séries
- aceder a "ver séries na lista de seleção"
Depois, pode obter o link permanente ou descarregar os dados. Os links do download incluem automaticamente os series_ids.
Utilização
A API pode ser utilizada em diferentes contextos.
Permite atualizar dados sem necessidade de tarefas manuais repetitivas.
Utilizar dados em aplicações internas ou outros sistemas.
Recolher regularmente a informação. Exemplo: atualização de taxas de câmbio.
Boas práticas
- Evitar pedidos desnecessários
- Utilizar apenas os dados necessários
- Aplicar filtros, sempre que possível
Usar a API em Python, R e outras ferramentas
Exemplo de utilização da API em diferentes linguagens.
import requests
import pandas as pd
url = "https://bpstat.bportugal.pt/data/v1/domains/29/datasets/23e0cdd56bddb4ad3016a9c3ad63a539?lang=PT&series_ids=12531971"
data = requests.get(url).json()
df = pd.DataFrame(data['value'], columns=["valor"])
print(df.head())
library(httr)
library(jsonlite)
url <- "https://bpstat.bportugal.pt/data/v1/domains/29/datasets/23e0cdd56bddb4ad3016a9c3ad63a539?lang=PT&series_ids=12531971"
data <- fromJSON(content(GET(url), "text"))
head(data$value)
Perguntas frequentes
Posso obter todos os dados de um domínio num único pedido?
Não. É necessário consultar os datasets individualmente.
Posso filtrar os dados?
Depende do dataset. Recomenda-se verificar a estrutura antes.
Os dados são atualizados automaticamente?
Sim. Ficam disponíveis na API após atualização no BPstat.