Como consumir APIs com Python e requests

O que é consumir uma API?

Uma API (Application Programming Interface) é uma forma de dois sistemas conversarem. Quando você consulta a previsão do tempo no celular, o app está consumindo uma API. Com Python, você pode fazer o mesmo em poucas linhas.

pip install requests

Sua primeira requisição

import requests

resposta = requests.get("https://api.github.com")
print(resposta.status_code)  # 200
print(resposta.json())       # dicionario com dados

requests.get() faz uma requisição GET — o tipo mais comum, usado para buscar dados.

Entendendo a resposta

import requests

r = requests.get("https://api.github.com/users/python")

print(r.status_code)      # 200 = sucesso
print(r.headers)           # cabecalhos da resposta
print(r.text)              # corpo como string
print(r.json())            # corpo como dicionario Python

dados = r.json()
print(dados["name"])       # Python
print(dados["public_repos"])

Códigos de status mais comuns

Passando parâmetros na URL

Em vez de montar a URL na mão, use o parâmetro params:

import requests

params = {
    "q": "python",
    "sort": "stars",
    "order": "desc"
}

r = requests.get("https://api.github.com/search/repositories", params=params)
dados = r.json()

for repo in dados["items"][:5]:
    print(f"{repo['name']} - {repo['stargazers_count']} estrelas")

O requests monta a URL automaticamente: ?q=python&sort=stars&order=desc.

Enviando dados com POST

import requests

dados = {
    "title": "Meu post",
    "body": "Conteudo do post",
    "userId": 1
}

r = requests.post("https://jsonplaceholder.typicode.com/posts", json=dados)

print(r.status_code)  # 201
print(r.json())       # post criado com id

Use json= para enviar JSON (o mais comum em APIs modernas) ou data= para form-encoded.

Headers e autenticação

Headers personalizados

import requests

headers = {
    "Accept": "application/json",
    "User-Agent": "MeuApp/1.0"
}

r = requests.get("https://api.github.com", headers=headers)

Autenticação com token

import os
import requests

token = os.environ["API_TOKEN"]

headers = {
    "Authorization": f"Bearer {token}"
}

r = requests.get("https://api.exemplo.com/dados", headers=headers)

Autenticação básica

import requests

r = requests.get(
    "https://api.exemplo.com/dados",
    auth=("usuario", "senha")
)

Tratando erros

import requests

def buscar_usuario(username):
    try:
        r = requests.get(
            f"https://api.github.com/users/{username}",
            timeout=10
        )
        r.raise_for_status()  # levanta erro se status >= 400
        return r.json()
    except requests.Timeout:
        print("A requisicao demorou demais")
    except requests.HTTPError as e:
        print(f"Erro HTTP: {e}")
    except requests.RequestException as e:
        print(f"Erro na requisicao: {e}")
    return None

usuario = buscar_usuario("python")
if usuario:
    print(usuario["name"])

Sempre use timeout para evitar que seu script trave esperando uma resposta que nunca chega.

Exemplo prático: consulta de CEP

import requests

def buscar_cep(cep):
    cep = cep.replace("-", "")
    r = requests.get(f"https://viacep.com.br/ws/{cep}/json/", timeout=10)
    r.raise_for_status()
    dados = r.json()

    if "erro" in dados:
        return None
    return dados

endereco = buscar_cep("01001-000")
if endereco:
    print(f"{endereco['logradouro']}, {endereco['bairro']}")
    print(f"{endereco['localidade']} - {endereco['uf']}")

Exemplo prático: previsão do tempo

import requests

def previsao(cidade):
    url = "https://wttr.in"
    params = {"format": "j1"}

    r = requests.get(f"{url}/{cidade}", params=params, timeout=10)
    r.raise_for_status()
    dados = r.json()

    atual = dados["current_condition"][0]
    temp = atual["temp_C"]
    desc = atual["lang_pt"][0]["value"]
    umidade = atual["humidity"]

    print(f"Cidade: {cidade}")
    print(f"Temperatura: {temp} C")
    print(f"Condicao: {desc}")
    print(f"Umidade: {umidade}%")

previsao("Sao Paulo")

Paginação

Muitas APIs retornam dados em páginas. Você precisa iterar:

import requests

def buscar_todos_repos(usuario):
    repos = []
    page = 1

    while True:
        r = requests.get(
            f"https://api.github.com/users/{usuario}/repos",
            params={"page": page, "per_page": 100},
            timeout=10
        )
        r.raise_for_status()
        dados = r.json()

        if not dados:
            break

        repos.extend(dados)
        page += 1

    return repos

repos = buscar_todos_repos("python")
print(f"Total: {len(repos)} repositorios")

Sessions: reutilizando conexões

Se você vai fazer várias requisições para a mesma API, use Session:

import requests

session = requests.Session()
session.headers.update({
    "Authorization": "Bearer meu_token",
    "Accept": "application/json"
})

# Todas as requisicoes usam os mesmos headers
r1 = session.get("https://api.exemplo.com/users")
r2 = session.get("https://api.exemplo.com/posts")

É mais eficiente porque reutiliza a conexão TCP.

Resumo

Consumir APIs é uma das habilidades mais valorizadas no mercado. Com requests, qualquer API vira uma fonte de dados para seus projetos Python.