Requests en Python: guía completa para principiantes

La biblioteca Requests en Python simplifica la comunicación con sitios web y APIs. Con unas pocas líneas puedes consultar recursos, enviar formularios o JSON, descargar archivos y trabajar con autenticación. Su interfaz es más directa que las herramientas HTTP de bajo nivel de la biblioteca estándar, por lo que resulta adecuada para automatizaciones, integraciones y proyectos de aprendizaje.

En esta guía aprenderás a instalar Requests, realizar peticiones GET y POST, enviar parámetros y cabeceras, leer JSON, configurar timeouts, reutilizar conexiones con sesiones y manejar errores de red. Para aislar correctamente la dependencia, conviene comenzar con la guía de entornos virtuales en Python.

Instalar Requests

python -m pip install requests

Después de la instalación, verifica que el paquete se importe desde el mismo intérprete utilizado para ejecutar el proyecto:

import requests

print(requests.__version__)

La documentación oficial de Requests reúne la guía de inicio, la referencia de la API y las opciones avanzadas de sesiones, autenticación y streaming.

Realizar una petición GET

GET se utiliza para obtener un recurso. Incluye siempre un timeout para evitar que el programa espere indefinidamente.

import requests

url = "https://jsonplaceholder.typicode.com/posts/1"
respuesta = requests.get(url, timeout=10)
respuesta.raise_for_status()

datos = respuesta.json()
print(datos["title"])

raise_for_status() genera una excepción para respuestas HTTP de error. El método json() convierte un documento JSON válido en estructuras de Python, normalmente diccionarios y listas. La guía de diccionarios en Python ayuda a trabajar con estas respuestas.

Enviar parámetros en la URL

No construyas una query string concatenando texto. Usa params para que Requests codifique los valores correctamente.

parametros = {
    "userId": 1,
    "_limit": 5,
}

respuesta = requests.get(
    "https://jsonplaceholder.typicode.com/posts",
    params=parametros,
    timeout=10,
)

print(respuesta.url)
print(respuesta.json())

Enviar datos con POST

El argumento json serializa un diccionario y añade la cabecera apropiada.

nuevo_post = {
    "title": "Informe semanal",
    "body": "Contenido generado por Python",
    "userId": 1,
}

respuesta = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=nuevo_post,
    timeout=10,
)
respuesta.raise_for_status()
print(respuesta.json())

Para formularios tradicionales utiliza data=.... La visión general de HTTP en MDN explica métodos, cabeceras, respuestas y códigos de estado.

Cabeceras y autenticación

cabeceras = {
    "Accept": "application/json",
    "User-Agent": "mi-aplicacion/1.0",
}

respuesta = requests.get(
    "https://api.example.com/items",
    headers=cabeceras,
    timeout=10,
)

No escribas tokens directamente en el código. Guárdalos en variables de entorno y excluye los archivos locales de secretos del control de versiones. La guía para leer variables de entorno con Python muestra un flujo seguro.

Manejar errores de red

import requests

try:
    respuesta = requests.get(
        "https://api.example.com/datos",
        timeout=(3.05, 15),
    )
    respuesta.raise_for_status()
    datos = respuesta.json()
except requests.Timeout:
    print("La petición superó el tiempo límite")
except requests.ConnectionError:
    print("No fue posible conectar con el servidor")
except requests.HTTPError as error:
    print(f"Respuesta HTTP no válida: {error}")
except requests.JSONDecodeError:
    print("La respuesta no contiene JSON válido")

Captura excepciones específicas y conserva suficiente información para diagnosticar el problema. La guía de try y except en Python explica cómo evitar bloques demasiado amplios.

Reutilizar conexiones con Session

Una sesión conserva cookies, cabeceras y conexiones entre peticiones relacionadas.

import requests

with requests.Session() as sesion:
    sesion.headers.update({
        "Accept": "application/json",
        "User-Agent": "cliente-academify/1.0",
    })

    for identificador in range(1, 4):
        respuesta = sesion.get(
            f"https://jsonplaceholder.typicode.com/posts/{identificador}",
            timeout=10,
        )
        respuesta.raise_for_status()
        print(respuesta.json()["title"])

Descargar archivos por streaming

from pathlib import Path
import requests

url = "https://example.com/archivo-grande.zip"
destino = Path("descargas") / "archivo.zip"
destino.parent.mkdir(exist_ok=True)

with requests.get(url, stream=True, timeout=30) as respuesta:
    respuesta.raise_for_status()

    with destino.open("wb") as archivo:
        for bloque in respuesta.iter_content(chunk_size=8192):
            if bloque:
                archivo.write(bloque)

El uso de bloques evita cargar el archivo completo en memoria. Para construir rutas portables, consulta la guía de pathlib en Python.

Buenas prácticas

• Configura siempre un timeout.
• Usa raise_for_status() antes de confiar en la respuesta.
• No registres tokens, contraseñas ni cabeceras sensibles.
• Valida el tipo y la estructura del JSON recibido.
• Reutiliza una sesión para grupos de peticiones relacionadas.
• Respeta límites de uso, términos del servicio y políticas de cada API.
• Implementa reintentos solamente para errores temporales e idempotentes.

Requests y web scraping

Requests descarga el HTML, pero no interpreta la estructura del documento. Para extraer elementos necesitas un parser como BeautifulSoup. La guía de web scraping con BeautifulSoup y Requests combina ambas herramientas y explica límites éticos y técnicos.

Conclusión

Requests en Python permite construir clientes HTTP legibles con parámetros, cabeceras, JSON, sesiones, streaming y manejo de errores. La base de un cliente fiable es sencilla: timeout explícito, comprobación del estado, validación de la respuesta y protección de credenciales. Comienza con una petición GET pequeña y añade autenticación, sesiones o descargas solamente cuando el proyecto lo necesite.