Paginação e coleta de grandes conjuntos de dados
Tratamento de paginação, padrões next_cursor, limitação de taxa com time.sleep e barras de progresso.
Paginação e coleta de grandes conjuntos de dados é uma aula grátis de Learn AI with Python no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Learn AI with Python, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Learn AI with Python inclui 4 aulas no total.
Por que a paginação existe
As APIs raramente retornam milhões de registros em uma única resposta. Elas dividem os resultados em páginas para que cada resposta permaneça pequena e rápida.
Para coletar um conjunto de dados completo, você precisa percorrer todas as páginas e combinar os resultados. Esta lição aborda os estilos comuns de paginação, além da limitação de requisições e do acompanhamento do progresso.
Paginação por número de página
O esquema mais simples usa um parâmetro page. Você o incrementa até que a API retorne uma página vazia.
import requests
all_items = []
page = 1
while True:
resp = requests.get(url, params={"page": page, "per_page": 100}, timeout=10)
resp.raise_for_status()
items = resp.json()
if not items:
break
all_items.extend(items)
page += 1
print(len(all_items), "items collected")Paginação por cursor ou URL seguinte
Muitas APIs modernas retornam uma URL seguinte ou um token de cursor que aponta para a página seguinte. Você repete o processo enquanto existir um link seguinte.
Isso é robusto porque o servidor controla onde a próxima página começa.
all_items = []
next_url = "https://api.example.com/items?limit=100"
while next_url:
resp = requests.get(next_url, timeout=10)
resp.raise_for_status()
data = resp.json()
all_items.extend(data["results"])
next_url = data.get("next") # None when no more pages
print(len(all_items))Respeitando limites de requisições com time.sleep
As APIs limitam quantas solicitações você pode enviar por segundo ou por minuto. Enviar solicitações excessivas retorna 429 Too Many Requests ou faz com que você seja bloqueado.
Insira um pequeno time.sleep entre as solicitações para agir de forma adequada e permanecer abaixo do limite.
import time
while next_url:
resp = requests.get(next_url, timeout=10)
resp.raise_for_status()
data = resp.json()
all_items.extend(data["results"])
next_url = data.get("next")
time.sleep(0.5) # 2 requests per secondLendo cabeçalhos de limite de requisições
APIs bem projetadas informam sua cota restante em cabeçalhos como X-RateLimit-Remaining e X-RateLimit-Reset.
Você pode lê-los para diminuir o ritmo apenas quando estiver próximo do limite, em vez de sempre fazer uma pausa.
remaining = int(resp.headers.get("X-RateLimit-Remaining", 1))
if remaining < 5:
reset = int(resp.headers.get("X-RateLimit-Reset", 1))
print("Near limit, sleeping", reset, "s")
time.sleep(reset)Tratando 429 com espera progressiva
Se você receber um 429, a resposta geralmente inclui um cabeçalho Retry-After informando quanto tempo esperar. Respeite esse intervalo antes de tentar novamente.
resp = requests.get(url, timeout=10)
if resp.status_code == 429:
wait = int(resp.headers.get("Retry-After", 5))
time.sleep(wait)
resp = requests.get(url, timeout=10) # retry onceBarras de progresso com tqdm
Tarefas longas de coleta parecem travadas quando não há retorno visual. O tqdm envolve qualquer iterável e exibe uma barra de progresso atualizada, com a taxa e a ETA.
from tqdm import tqdm
for page in tqdm(range(1, 101), desc="Fetching"):
resp = requests.get(url, params={"page": page}, timeout=10)
all_items.extend(resp.json())
time.sleep(0.2)tqdm com totais desconhecidos
Na paginação por cursor, você não sabe antecipadamente a quantidade total. Use tqdm como um contador manual e chame update() a cada iteração.
from tqdm import tqdm
pbar = tqdm(desc="Pages")
while next_url:
resp = requests.get(next_url, timeout=10)
data = resp.json()
all_items.extend(data["results"])
next_url = data.get("next")
pbar.update(1)
pbar.close()Coleta incremental
Para conjuntos de dados enormes, não mantenha tudo na memória. A coleta incremental grava cada página no disco assim que ela chega, portanto uma falha não elimina todo o progresso.
import json
with open("items.jsonl", "w") as f:
while next_url:
resp = requests.get(next_url, timeout=10)
data = resp.json()
for item in data["results"]:
f.write(json.dumps(item) + "\n")
next_url = data.get("next")Coleta retomável
Salve o último cursor ou número de página para que uma nova execução possa retomar o processo, em vez de começar novamente. Isso torna as tarefas longas tolerantes a falhas.
import os
start_page = 1
if os.path.exists("checkpoint.txt"):
start_page = int(open("checkpoint.txt").read()) + 1
for page in range(start_page, 1000):
# ... fetch and store ...
open("checkpoint.txt", "w").write(str(page))Juntando tudo
Um laço de coleta para produção combina todas as partes: paginar, aguardar por causa dos limites de requisições, exibir o progresso, gravar incrementalmente e criar pontos de verificação.
from tqdm import tqdm
import time, json
with open("out.jsonl", "a") as f:
next_url = "https://api.example.com/items?limit=100"
pbar = tqdm(desc="Pages")
while next_url:
r = requests.get(next_url, timeout=10)
r.raise_for_status()
d = r.json()
for it in d["results"]:
f.write(json.dumps(it) + "\n")
next_url = d.get("next")
pbar.update(1)
time.sleep(0.3)Verificação rápida: paginação por cursor
Uma API retorna um campo "next" que contém uma URL, ou None na última página.
Recapitulação: coletando conjuntos de dados grandes
Agora você consegue reunir conjuntos de dados que abrangem muitas páginas:
- Paginação por número de página e por cursor (
while next_url) time.sleepe cabeçalhos de limite de requisições para evitar respostas 429- Espera progressiva com
Retry-Afterquando houver limitação - Barras de progresso
tqdmpara tarefas longas - Gravação incremental e retomável para tolerância a falhas
A seguir: armazenando os dados coletados com eficiência.
Perguntas Frequentes
A aula “Paginação e coleta de grandes conjuntos de dados” é grátis?
Sim — o texto completo de “Paginação e coleta de grandes conjuntos de dados” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Learn AI with Python, atualize para CoddyKit PRO. O curso de Learn AI with Python inclui 4 aulas no total.
O que vou aprender em “Paginação e coleta de grandes conjuntos de dados”?
Tratamento de paginação, padrões next_cursor, limitação de taxa com time.sleep e barras de progresso. Você pratica Learn AI with Python com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Learn AI with Python?
Nenhuma experiência prévia é necessária. Learn AI with Python no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.
Quanto tempo leva a aula “Paginação e coleta de grandes conjuntos de dados”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Learn AI with Python?
Sim. Cada aula de Learn AI with Python inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Fundamentos de APIs REST para coleta de dados
- Paginação e coleta de grandes conjuntos de dados
- Armazenando dados coletados com eficiência
- Trabalhando com APIs de dados públicos