# Como consumir API de CPF em Jupyter Notebook para análise exploratória

> Aprenda a consumir a API de CPF da CPFHub.io em Jupyter Notebook para enriquecer datasets e realizar análise exploratória de dados cadastrais.

**Publicado:** 27/06/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-jupyter-notebook-para-analise-exploratoria

---


Para consumir a API de CPF da CPFHub.io em um [Jupyter Notebook](https://jupyter.org/documentation), basta fazer uma requisição GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key` e processar o JSON retornado diretamente em um DataFrame pandas. A natureza interativa do Jupyter permite executar célula por célula, visualizar resultados imediatamente e iterar sobre datasets completos com barras de progresso visuais via `tqdm`. Quando o dataset contém CPFs e é necessário enriquecer esses dados com informações cadastrais — como nome, gênero e data de nascimento — a integração com a API da CPFHub.io se torna uma etapa direta no pipeline de análise.

---

## 1. Pré-requisitos

* **Python 3.9+** com Jupyter instalado: `pip install jupyter`.

* Pacotes adicionais: `pip install requests pandas matplotlib seaborn tqdm`.

* Uma conta gratuita na [**CPFHub.io**](https://www.cpfhub.io/)

---

## 2. Configure o notebook

Na primeira célula do notebook, importe as bibliotecas e configure as credenciais:

```python
# Célula 1: Importações e configuração
import requests
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
import re
import time
import os
from tqdm.notebook import tqdm

# Configuração da API
API_KEY = os.getenv("CPFHUB_API_KEY", "SUA_CHAVE_DE_API")
BASE_URL = "https://api.cpfhub.io"
TIMEOUT = 5 # segundos

# Configuração visual
sns.set_theme(style="whitegrid")
pd.set_option("display.max_columns", None)

print("Ambiente configurado com sucesso.")
```

---

## 3. Crie a função de consulta

Defina uma função reutilizável para consultar CPFs:

```python
# Célula 2: Função de consulta
def consultar_cpf(cpf: str) -> dict:
 """
 Consulta dados de um CPF na API da CPFHub.io.
 Retorna dict com dados ou dict com erro.
 """
 cpf_limpo = re.sub(r"\D", "", str(cpf))

 if len(cpf_limpo) != 11:
 return {"error": "CPF inválido", "cpf": cpf_limpo}

 url = f"{BASE_URL}/cpf/{cpf_limpo}"
 headers = {
 "x-api-key": API_KEY,
 "Accept": "application/json",
 }

 try:
 response = requests.get(url, headers=headers, timeout=TIMEOUT)

 if response.status_code == 200:
 data = response.json()
 if data.get("success"):
 return {**data["data"], "error": None}

 error_messages = {
 400: "Formato inválido",
 401: "API key inválida",
 404: "Não encontrado",
 }
 return {
 "error": error_messages.get(response.status_code, f"HTTP {response.status_code}"),
 "cpf": cpf_limpo,
 }

 except requests.exceptions.Timeout:
 return {"error": "Timeout", "cpf": cpf_limpo}
 except requests.exceptions.RequestException as e:
 return {"error": str(e), "cpf": cpf_limpo}

# Teste rápido
resultado = consultar_cpf("12345678900")
print(resultado)
```

---

## 4. Consulte um único CPF

```python
# Célula 3: Consulta individual
cpf_teste = "12345678900"
dados = consultar_cpf(cpf_teste)

if dados.get("error") is None:
 print(f"Nome: {dados['name']}")
 print(f"CPF: {dados['cpf']}")
 print(f"Gênero: {dados['gender']}")
 print(f"Nascimento: {dados['birthDate']}")
else:
 print(f"Erro: {dados['error']}")
```

---

## 5. Enriqueça um DataFrame com dados de CPF

Para análise exploratória, carregue um dataset e enriqueça-o com dados da API:

```python
# Célula 4: Carregar dataset de exemplo
df = pd.DataFrame({
 "cpf": ["12345678900", "98765432100", "11122233344"],
 "valor_compra": [150.00, 320.50, 89.90],
 "data_compra": ["2026-01-15", "2026-02-20", "2026-03-10"],
})

print(f"Dataset original: {len(df)} registros")
df.head()
```

```python
# Célula 5: Enriquecer dataset com dados da CPFHub
resultados = []

for idx, row in tqdm(df.iterrows(), total=len(df), desc="Consultando CPFs"):
 dados = consultar_cpf(row["cpf"])
 resultados.append(dados)
 time.sleep(0.5) # Respeitar rate limit

df_enriquecido = df.copy()
df_api = pd.DataFrame(resultados)

# Mesclar dados
if "name" in df_api.columns:
 df_enriquecido["nome"] = df_api["name"]
 df_enriquecido["genero"] = df_api["gender"]
 df_enriquecido["nascimento"] = df_api["birthDate"]
 df_enriquecido["ano_nasc"] = df_api["year"]
 df_enriquecido["erro_api"] = df_api["error"]

print(f"Dataset enriquecido: {len(df_enriquecido)} registros")
df_enriquecido.head()
```

---

## 6. Análise exploratória dos dados enriquecidos

Com os dados enriquecidos, realize análises visuais:

```python
# Célula 6: Análise de gênero
if "genero" in df_enriquecido.columns:
 fig, axes = plt.subplots(1, 2, figsize=(12, 5))

 # Distribuição de gênero
 genero_counts = df_enriquecido["genero"].value_counts()
 axes[0].bar(genero_counts.index, genero_counts.values, color=["#3498db", "#e74c3c"])
 axes[0].set_title("Distribuicao por Genero")
 axes[0].set_xlabel("Genero")
 axes[0].set_ylabel("Quantidade")

 # Valor médio por gênero
 media_genero = df_enriquecido.groupby("genero")["valor_compra"].mean()
 axes[1].bar(media_genero.index, media_genero.values, color=["#3498db", "#e74c3c"])
 axes[1].set_title("Valor Medio de Compra por Genero")
 axes[1].set_xlabel("Genero")
 axes[1].set_ylabel("Valor Medio (R$)")

 plt.tight_layout()
 plt.show()
```

```python
# Célula 7: Análise por faixa etária
if "ano_nasc" in df_enriquecido.columns:
 df_enriquecido["idade"] = 2026 - df_enriquecido["ano_nasc"]

 bins = [0, 25, 35, 45, 55, 65, 100]
 labels = ["18-25", "26-35", "36-45", "46-55", "56-65", "65+"]
 df_enriquecido["faixa_etaria"] = pd.cut(
 df_enriquecido["idade"], bins=bins, labels=labels
 )

 fig, ax = plt.subplots(figsize=(10, 5))
 faixa_counts = df_enriquecido["faixa_etaria"].value_counts().sort_index()
 faixa_counts.plot(kind="bar", ax=ax, color="#2ecc71")
 ax.set_title("Distribuicao por Faixa Etaria")
 ax.set_xlabel("Faixa Etaria")
 ax.set_ylabel("Quantidade")
 plt.xticks(rotation=45)
 plt.tight_layout()
 plt.show()
```

---

## 7. Métricas de qualidade dos dados

Avalie a taxa de sucesso das consultas:

```python
# Célula 8: Métricas de qualidade
total = len(df_enriquecido)
sucesso = df_enriquecido["erro_api"].isna().sum()
falha = total - sucesso

print(f"Total de CPFs: {total}")
print(f"Consultas com sucesso: {sucesso} ({sucesso/total*100:.1f}%)")
print(f"Consultas com erro: {falha} ({falha/total*100:.1f}%)")

if falha > 0:
 print("\nDetalhamento dos erros:")
 print(df_enriquecido[df_enriquecido["erro_api"].notna()]["erro_api"].value_counts())
```

---

## 8. Exporte os resultados

Salve o dataset enriquecido para uso posterior:

```python
# Célula 9: Exportar resultado
output_path = "dataset_enriquecido.csv"
df_enriquecido.to_csv(output_path, index=False, encoding="utf-8-sig")
print(f"Dataset exportado para: {output_path}")

# Também pode exportar para Excel
df_enriquecido.to_excel("dataset_enriquecido.xlsx", index=False)
print("Exportado também para Excel.")
```

---

## 9. Boas práticas para Jupyter

* **Variáveis de ambiente** -- Use `os.getenv()` para a chave de API. Nunca deixe credenciais no notebook que será compartilhado ou versionado.

* **Consultas em lote** -- Adicione `time.sleep()` entre consultas sequenciais. O plano gratuito oferece 50 consultas/mês; ao ultrapassar o limite, a API cobra R$0,15 por consulta extra — ela não bloqueia.

* **Cache local** -- Para evitar consultas repetidas durante a exploração, salve os resultados em um DataFrame intermediário ou arquivo CSV.

* **Timeout** -- O timeout de 5 segundos garante que o notebook não trave em caso de problemas de rede. A latência típica da API é de ~900ms.

* **tqdm** -- Use `tqdm.notebook` para barras de progresso visuais em consultas em lote.

* **LGPD** -- A API da CPFHub.io é 100% compatível com a LGPD. Ao compartilhar notebooks, certifique-se de anonimizar dados pessoais.

---

## Perguntas frequentes

### Como configurar a autenticação da API CPFHub.io em um Jupyter Notebook?

A autenticação usa o header `x-api-key` em cada requisição. No Jupyter, armazene a chave em uma variável de ambiente com `os.getenv("CPFHUB_API_KEY")` e nunca a inclua diretamente no código do notebook, especialmente se ele for compartilhado via Git ou publicado. Use um arquivo `.env` com `python-dotenv` para carregar as credenciais localmente.

### A API CPFHub.io bloqueia requisições quando o limite do plano gratuito é atingido?

Não. Ao atingir o limite de 50 consultas/mês do plano gratuito, a API não retorna erro nem bloqueia — ela cobra R$0,15 por consulta adicional. Para análises exploratórias com datasets maiores, considere o plano Pro (R$149/mês, 1.000 consultas incluídas) ou implemente um cache local para evitar reconsultar o mesmo CPF.

### Qual é a latência da API ao consultar CPFs em lote no Jupyter?

A API da CPFHub.io tem latência média de ~900ms por consulta. Para um dataset de 100 CPFs com `time.sleep(0.5)` entre requisições, espere cerca de 2,5 minutos de processamento total. Use a barra de progresso do `tqdm.notebook` para acompanhar o andamento e estime o tempo antes de executar consultas em lote maiores.

### Como evitar reconsultar CPFs já enriquecidos durante a exploração?

Salve o DataFrame intermediário em CSV após cada bloco de consultas com `df_enriquecido.to_csv("cache_cpfs.csv")`. Nas execuções seguintes, carregue o arquivo e filtre apenas os CPFs ainda sem dados com `df[df["erro_api"].isna() & df["nome"].isna()]`. Essa abordagem respeita a [ANPD](https://www.gov.br/anpd) ao minimizar o volume de dados pessoais processados desnecessariamente.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Como consumir API de CPF em Python com FastAPI](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-python-com-fastapi)
- [Como integrar validação de CPF em Apache Airflow para pipelines de dados](https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-apache-airflow-para-pipelines-de-dados)

---

## Conclusão

Consumir a API da [**CPFHub.io**](https://www.cpfhub.io/)

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)