Python requests: instalación y tu primer GET

Requests es la librería más usada de Python para hacer peticiones HTTP. En esta primera parte la instalas y haces tu primera petición GET.

Qué es requests y cuándo conviene usarlo

Requests es un cliente HTTP para Python que se encarga de los detalles incómodos del protocolo: codificar parámetros, abrir y cerrar conexiones, descomprimir respuestas, gestionar cookies y verificar certificados TLS.

Python ya incluye urllib en su biblioteca estándar, pero hacer con él una petición con cabeceras, JSON y control de errores exige bastante más código y es fácil equivocarse. Por eso requests se ha convertido en la opción por defecto para consumir APIs, automatizar tareas y descargar datos.

Es la herramienta adecuada cuando tu programa es síncrono, es decir, hace una petición y espera la respuesta antes de continuar. Si necesitas lanzar cientos de peticiones concurrentes con async/await, te conviene mirar httpx o aiohttp; lo comentamos en las preguntas frecuentes de la Parte 5.

Paso 1: Instala requests en un entorno virtual

Instala requests dentro de un entorno virtual para no mezclar dependencias entre proyectos; la versión estable actual es la 2.34.x y exige Python 3.10 o superior.

# 1. Crea y activa el entorno virtual
python -m venv venv
source venv/bin/activate      # En Windows: venv\Scripts\activate

# 2. Instala requests
pip install requests

# 3. Comprueba la versión
python -c "import requests; print(requests.__version__)"

Si ves un número de versión, ya puedes empezar. Guarda la dependencia en tu proyecto con pip freeze > requirements.txt.

A lo largo de la guía usamos httpbin.org, un servicio público que devuelve lo que le envías, ideal para practicar sin crear cuentas ni claves.

Paso 2: Tu primer GET y cómo leer la respuesta

requests.get() devuelve un objeto Response con todo lo que necesitas: el código de estado, las cabeceras y el cuerpo.

import requests

respuesta = requests.get("https://httpbin.org/get", timeout=10)

print(respuesta.status_code)              # 200
print(respuesta.headers["Content-Type"])  # application/json
print(respuesta.text)                     # cuerpo como texto
print(respuesta.json())                   # cuerpo convertido a dict

Los atributos que más vas a usar:

Atributo	Qué devuelve	Cuándo usarlo
status_code	Entero con el código HTTP (200, 404, 500…)	Comprobar si la petición funcionó
ok	True si el código es menor que 400	Condiciones rápidas
text	Cuerpo decodificado como str	HTML o texto plano
json()	Cuerpo convertido a dict o list	APIs que responden JSON
content	Cuerpo en bytes	Imágenes, PDFs, archivos
headers	Cabeceras de la respuesta (sin distinguir mayúsculas)	Leer Content-Type, límites de uso
url	URL final, tras redirecciones	Verificar a dónde llegaste
elapsed	Tiempo que tardó la petición	Medir rendimiento

Ojo: json() lanza una excepción si el cuerpo no es JSON válido. Cuando no estés seguro, revisa Content-Type o captura el error (lo vemos en la Parte 3).

Los códigos de estado más importantes

Cada respuesta HTTP trae un código de tres cifras que resume qué pasó. Basta con recordar la familia a la que pertenece:

• 2xx (éxito): la petición funcionó. El más común es 200; también verás 201 (recurso creado) y 204 (todo bien, pero sin cuerpo).
• 3xx (redirección): el recurso se movió. Requests sigue las redirecciones de GET automáticamente y guarda el recorrido en respuesta.history. Si quieres verlas sin seguirlas, usa allow_redirects=False.
• 4xx (error del cliente): tú hiciste algo mal. 400 es una petición mal formada, 401 falta autenticación, 403 no tienes permiso, 404 no existe y 429 significa que hiciste demasiadas peticiones.
• 5xx (error del servidor): falló el otro lado. Suelen ser temporales, y por eso más adelante configuraremos reintentos.

Errores comunes al empezar

Antes de pasar a la siguiente parte, revisa estos tropiezos que aparecen una y otra vez:

1. ModuleNotFoundError: No module named 'requests'. Instalaste la librería en un Python y ejecutas el script con otro. Activa el entorno virtual y comprueba con pip --version que apunta a la carpeta venv.
2. Llamar a tu archivo requests.py. Python importaría tu propio archivo en lugar de la librería y verás errores extraños como module 'requests' has no attribute 'get'. Renombra el archivo y borra la carpeta __pycache__.
3. Confundir text con content. text es una cadena ya decodificada; content son bytes. Para imágenes, PDFs o cualquier archivo binario usa siempre content.
4. Olvidar el timeout. Lo repetimos porque importa: sin él, un servidor lento puede dejar tu programa esperando indefinidamente.
5. Suponer que un 404 lanza una excepción. No lo hace; lo resolveremos en la Parte 3 con raise_for_status().

Siguiente parte

En la Parte 2 enviarás parámetros de URL, cabeceras y datos con POST.