A biblioteca Requests é a ferramenta mais popular do Python para trabalhar com protocolos HTTP. Se você precisa consumir APIs, fazer web scraping, baixar arquivos ou integrar sistemas, o Requests é a escolha ideal pela sua simplicidade e poder.

Neste guia completo, você vai aprender desde a instalação até técnicas avançadas como autenticação, sessões persistentes e tratamento de erros. Ao final, terá domínio completo para trabalhar com qualquer tipo de requisição HTTP em Python.

📦 Instalação e Configuração

O Requests não vem incluso na biblioteca padrão do Python, então você precisa instalá-lo via pip. A instalação é extremamente simples:

# Instalando via pip
pip install requests
Ou usando pip3 em sistemas Linux/Mac
pip3 install requests

Para verificar se a instalação foi bem-sucedida, você pode importar o módulo e verificar sua versão:

import requests
print(requests.version)

A biblioteca é mantida pela comunidade Python e possui excelente documentação oficial. Você pode consultar a documentação completa em requests.readthedocs.io.

🌐 Fazendo sua Primeira Requisição GET

A requisição GET é o método mais básico e comum para retrieving dados de um servidor. Com o Requests, fazer uma requisição GET é incrivelmente simples:

import requests
Requisição GET simples
response = requests.get("https://api.github.com")
Verificando o status da resposta
print(f"Status Code: {response.status_code}")
print(f"Reason: {response.reason}")
Visualizando o conteúdo (texto)
print(response.text[:500])

O objeto response contém diversas informações sobre a resposta do servidor:

• status_code: Código HTTP de status (200 = OK, 404 = Not Found, etc)
• reason: Frase descritiva do status ("OK", "Not Found", etc)
• text: Conteúdo da resposta em formato texto
• json(): Conteúdo parsed como JSON
• headers: Cabeçalhos da resposta
• cookies: Cookies recebidos

Verificando Status de FormaSeguro

É uma boa prática verificar se a requisição foi bem-sucedida antes de processar os dados. O Requests facilita isso com o atributo ok:

import requests
response = requests.get("https://api.github.com")
if response.ok:
print("Requisição bem-sucedida!")
data = response.json()
print(data)
else:
print(f"Erro: {response.status_code} - {response.reason}")

📋 Trabalhando com Parâmetros de Query

Muitas APIs utilizam parâmetros de query string para filtrar ou paginar resultados. O Requests permite passar esses parâmetros de forma organizada:

import requests
Parâmetros de query passados como dicionário
params = {
"page": 1,
"per_page": 10,
"sort": "created",
"direction": "desc"
}
response = requests.get(
"https://api.github.com/repos/python/cpython/releases",
params=params
)
print(f"URL gerada: {response.url}")
print(f"Status: {response.status_code}")
Vendo os dados JSON retornados
releases = response.json()
for release in releases[:3]:
print(f"- {release['tag_name']}: {release['name']}")

Esta abordagem é muito mais limpa do que concatenar strings manualmente, pois o Requests trata automaticamente da codificação URL.

📤 Enviando Dados com POST

O método POST é utilizado para enviar dados ao servidor, seja para criar novos recursos, submeter formulários ou enviar payloads JSON:

import requests
Dados para enviar (dicionário Python)
data = {
"username": "usuario_teste",
"email": "[email protected]",
"password": "senha_segura123"
}
Enviando POST com dados de formulário
response = requests.post(
"https://httpbin.org/post",
data=data
)
print(f"Status: {response.status_code}")
print(response.json())

Enviando JSON no Corpo da Requisição

Muitas APIs modernas esperam receber dados no formato JSON. Você pode usar o parâmetro json para isso:

import requests
Payload JSON
payload = {
"title": "Novo Post",
"body": "Conteúdo do post aqui",
"userId": 1
}
response = requests.post(
"https://jsonplaceholder.typicode.com/posts",
json=payload
)
A resposta já vem em JSON automaticamente
result = response.json()
print(f"ID criado: {result['id']}")
print(f"Título: {result['title']}")

O Requests automaticamente define o header Content-Type como application/json quando você usa o parâmetro json.

🎯 Headers Personalizados

Em algumas situações, você precisa enviar cabeçalhos personalizados na requisição, como tokens de autenticação, identificação de aplicação ou preferências de formato:

import requests
Definindo headers personalizados
headers = {
"Authorization": "Bearer seu_token_aqui",
"Accept": "application/json",
"User-Agent": "MinhaApp/1.0",
"Accept-Language": "pt-BR,pt;q=0.9"
}
response = requests.get(
"https://api.exemplo.com/dados-protegidos",
headers=headers
)
print(f"Status: {response.status_code}")
print(response.json())

🔐 Autenticação com Requests

O Requests suporta diversos métodos de autenticação de forma nativa. Os mais comuns são Basic Auth e Bearer Token:

Basic Authentication

import requests
from requests.auth import HTTPBasicAuth
Autenticação Basic (usuário e senha)
auth = HTTPBasicAuth("usuario", "senha")
response = requests.get(
"https://httpbin.org/basic-auth/usuario/senha",
auth=auth
)
print(f"Status: {response.status_code}")
print(response.text)

Bearer Token (JWT)

import requests
Bearer Token para APIs que usam JWT
headers = {
"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
response = requests.get(
"https://api.exemplo.com/usuario/perfil",
headers=headers
)
print(response.json())

Para autenticação mais complexa, você pode implementar sua própria classe de autenticação herdando de requests.auth.AuthBase. A documentação oficial sobre autenticação está disponível em docs.python-requests.org.

🍪 Trabalhando com Cookies e Sessões

Cookies são fundamentais para manter estado entre requisições, como sessões de usuário. O Requests facilita o trabalho com cookies:

import requests
Verificando cookies da resposta
response = requests.get("https://httpbin.org/cookies")
print("Cookies recebidos:")
print(response.json())
Enviando cookies customizados
cookies = {
"session_id": "abc123xyz",
"user_preference": "dark_mode"
}
response = requests.get(
"https://httpbin.org/cookies",
cookies=cookies
)
print(response.json())

Usando Sessões Persistentes

Quando você precisa fazer múltiplas requisições mantendo os mesmos cookies e configurações, usar uma Session é muito mais eficiente:

import requests
Criar uma sessão
session = requests.Session()
A sessão mantém cookies automaticamente entre requisições
session.headers.update({
"User-Agent": "MeuBot/1.0"
})
Primeira requisição - login
login_data = {"username": "admin", "password": "123456"}
response = session.post("https://exemplo.com/login", data=login_data)
print(f"Login: {response.status_code}")
Segunda requisição - já autenticado
response = session.get("https://exemplo.com/dashboard")
print(f"Dashboard: {response.status_code}")
Terceira requisição - continuar usando a sessão
response = session.get("https://exemplo.com/perfil")
print(f"Perfil: {response.status_code}")

A sessão também permite compartilhar conexões TCP, melhorando a performance em requisições múltiplas. Para mais detalhes sobre sessões, consulte a documentação avançada.

⏱️Timeouts e Tratamento de Erros

Por padrão, o Requests espera indefinidamente por uma resposta. É crucial definir timeouts para evitar que sua aplicação trave:

import requests
from requests.exceptions import Timeout, ConnectionError
Timeout de 5 segundos (connect e read)
try:
response = requests.get(
"https://api.exemplo.com/dados",
timeout=5
)
print(response.json())
except Timeout:
print("Tempo limite excedido!")
except ConnectionError:
print("Erro de conexão!")
except requests.exceptions.RequestException as e:
print(f"Erro geral: {e}")

Exceções Disponíveis

O Requests levanta várias exceções que você pode capturar:

• requests.exceptions.RequestException: Classe base para todas exceções
• requests.exceptions.ConnectionError: Erro de conexão de rede
• requests.exceptions.Timeout: Tempo limite excedido
• requests.exceptions.HTTPError: Resposta HTTP com erro (4xx ou 5xx)
• requests.exceptions.TooManyRedirects: Excesso de redirects

Verificando Errors HTTP Automaticamente

Você também pode configurar o Requests para levantar exceções automaticamente em erros HTTP:

import requests
from requests.exceptions import HTTPError
Definir para levantar exceções em status de erro
response = requests.get("https://httpbin.org/status/404")
response.raise_for_status()  # Levanta HTTPError para 4xx/5xx

📥 Download de Arquivos e Stream de Dados

Para arquivos grandes, você não quer carregar tudo na memória de uma vez. O Requests permite fazer streaming de dados:

import requests
Streaming de download - não baixa tudo na memória
url = "https://example.com/arquivo-grande.zip"
response = requests.get(url, stream=True)
Obter tamanho total (se disponível)
total_size = response.headers.get("content-length")
print(f"Tamanho total: {total_size} bytes")
Baixar em chunks
with open("arquivo.zip", "wb") as f:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
print("Download concluído!")

A técnica de streaming é essencial para arquivos grandes ou para processar dados em tempo real. Para download de imagens ou outros arquivos binários, o Requests automaticamente detecta o tipo de conteúdo.

🔄 Retry e Retry Strategy

Em aplicações de produção, você frequentemente precisa tentar novamente requisições que falharam temporariamente:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
Configurar retry strategy
session = requests.Session()
retry_strategy = Retry(
total=3,
backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET", "POST"]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("http://", adapter)
session.mount("https://", adapter)
Agora as requisições会自动重试
response = session.get("https://api.exemplo.com/dados")
print(f"Status: {response.status_code}")

Esta configuração faz a requisição tentar novamente até 3 vezes, com delay exponencial entre tentativas, apenas para erros de servidor (5xx) ou rate limiting (429).

📊 Timeout Adaptativo com Session

Para aplicações que fazem muitas requisições, você pode configurar timeouts padrão na sessão:

import requests
session = requests.Session()
Configurar timeout padrão para todas as requisições
session.timeout = 10
Timeout específico para uma requisição
response = session.get("https://api.exemplo.com", timeout=30)
print(response.status_code)

🛡️ Verificação de SSL

Por padrão, o Requests verifica certificados SSL. Em ambientes de desenvolvimento, você pode precisar desabilitar essa verificação:

import requests
Desabilitar verificação SSL (NÃO use em produção!)
response = requests.get(
"https://exemplo.com",
verify=False
)
Para ignorar apenas certificados específicos
response = requests.get("https://exemplo.com", verify="/path/to/cert.pem")

Aviso importante: Nunca desabilite a verificação SSL em ambiente de produção, pois isso expõe sua aplicação a ataques man-in-the-middle.

🔗 Integração com Web Scraping

O Requests é frequentemente usado junto com BeautifulSoup para web scraping. Após obter o HTML com Requests, você pode parsear com BeautifulSoup:

import requests
from bs4 import BeautifulSoup
Obter página HTML
response = requests.get("https://exemplo.com/artigos")
response.encoding = "utf-8"
Parsear o HTML
soup = BeautifulSoup(response.text, "html.parser")
Extrair títulos dos artigos
for article in soup.select("article"):
title = article.select_one("h2").text
link = article.select_one("a")["href"]
print(f"{title} -> {link}")

Se você quer aprender mais sobre web scraping, temos um guia completo de web scraping com Python que explora técnicas mais avançadas.

✅ Boas Práticas e Performance

Para usar o Requests de forma eficiente em produção, siga estas práticas:

• Use Session: Reutilize conexões TCP com sessões para melhor performance
• Defina Timeouts: Sempre defina timeouts para evitar travamentos
• Trate Erros: Capture exceções apropriadamente
• Use Retry: Implemente retry com backoff para operações transient failures
• Reuse Connections: Configure connection pooling para muitas requisições
• Log Requests: Adicione logging para debugging em produção