Cómo convertir el JSON de una API en un DataFrame pandas

Las APIs de datos casi siempre devuelven JSON con una estructura anidada, es decir, diccionarios dentro de diccionarios. Ese formato es ideal para transportar datos, pero malo para analizar: para filtrar, agrupar o crear gráficos necesitas una tabla plana. Convertir el JSON de una API en un DataFrame pandas es justamente ese paso, y la función pandas.json_normalize lo resuelve en pocas líneas. A continuación verás cómo, usando una API pública real como ejemplo.

Requisitos previos

• Python 3.9 o superior instalado.
• Las librerías pandas y requests (instálalas con pip install pandas requests).
• Conocimientos básicos de Python: variables, listas y diccionarios.
• Conexión a internet para llamar a la API pública de ejemplo.

Paso 1: Obtener los datos de la API

Como ejemplo usamos una API pública y gratuita que devuelve una lista de usuarios, cada uno con campos anidados de dirección y de empresa. Hacemos la petición con requests, comprobamos que salió bien con raise_for_status() y convertimos la respuesta en objetos Python con .json().

import requests
import pandas as pd

url = "https://jsonplaceholder.typicode.com/users"
resposta = requests.get(url, timeout=10)
resposta.raise_for_status()  # lança um erro se o pedido falhar
dados = resposta.json()

print(type(dados), len(dados))
print(dados[0])

La variable dados es una lista de diccionarios. Fíjate en que campos como address y company contienen, a su vez, más diccionarios: esa es la estructura anidada que vamos a aplanar en el siguiente paso.

Paso 2: Convertir el JSON en un DataFrame

La función pandas.json_normalize recorre cada registro y crea una columna para todos los campos, incluidos los anidados. Por defecto une los niveles con un punto; por ejemplo, el campo city dentro de address pasa a llamarse address.city.

df = pd.json_normalize(dados)

print(df.shape)
print(df.columns.tolist())

El resultado tiene columnas como id, name, address.city, address.geo.lat y company.name. En un solo paso, el JSON anidado se convirtió en una tabla plana con una fila por usuario.

Consejo: json_normalize aplana automáticamente todos los niveles de diccionarios, por muy profundos que estén. No necesitas recorrer el JSON a mano.

Paso 3: Nombres de columnas más limpios

El punto en los nombres funciona, pero puede dar error cuando escribes código como df.address.city. Con el parámetro sep eliges otro separador, como el guion bajo, y después te quedas solo con las columnas que interesan para tu análisis.

df = pd.json_normalize(dados, sep="_")

colunas = ["id", "name", "email", "address_city", "company_name"]
print(df[colunas].head())

Ahora las columnas se llaman address_city o company_name, mucho más fáciles de usar en el resto del trabajo.

Paso 4: Aplanar una lista dentro del JSON

Muchas APIs no devuelven una lista simple: devuelven un objeto con algunos metadatos y la lista de registros dentro. En esos casos, indica la ruta hasta la lista con record_path y los campos de nivel superior que quieres mantener en cada fila con meta.

resposta_api = {
    "empresa": "bConcepts",
    "pais": "PT",
    "clientes": [
        {"id": 1, "nome": "Ana", "cidade": "Porto"},
        {"id": 2, "nome": "Bruno", "cidade": "Lisboa"},
    ],
}

df_clientes = pd.json_normalize(
    resposta_api,
    record_path="clientes",
    meta=["empresa", "pais"],
)
print(df_clientes)

El resultado tiene una fila por cliente y las columnas empresa y pais se repiten en cada fila. Así es como combinas los registros detallados con la información de contexto que venía al principio de la respuesta.

Verificar el resultado

Para confirmar que la conversión salió bien, revisa la forma de la tabla, echa un vistazo a las primeras filas y asegúrate de que no quedó ningún diccionario por aplanar:

print(df.shape)   # (linhas, colunas)
print(df.head())

# Procurar colunas que ainda contenham dicionarios:
aninhadas = [c for c in df.columns if df[c].apply(lambda v: isinstance(v, dict)).any()]
print("Colunas ainda aninhadas:", aninhadas)

Si la lista aninhadas aparece vacía, todos los campos se aplanaron y el DataFrame está listo para el análisis.

Conclusión

En pocas líneas convertiste el JSON de una API en una tabla lista para usar: obtuviste los datos, aplanaste los campos anidados con json_normalize y ordenaste los nombres de las columnas. A partir de aquí puedes guardar el resultado con df.to_csv("dados.csv", index=False), cargarlo en una base de datos o combinarlo con la paginación para traer todas las páginas de una vez. ¿Cuál será la próxima API que necesites convertir en un DataFrame?