Esta es una entrada que quería escribir hace algún tiempo y que había prometido en otro post similar hace algunas semanas.

Cuando uno comienza a realizar análisis macroeconómicos -tanto para análisis como para presentaciones- el flujo de trabajo usual implica ir a la fuente de información -usualmente algún organismo internacional que agrega la información-, descargarse el conjunto de datos y luego importarlo en la herramienta de preferencia para proceder con el análisis.

Este flujo de trabajo, sin embargo, tiene bastantes inconvenientes. En primer lugar, no es replicable: existen varios pasos manuales que no quedan estrictamente documentados. Además, no es escalable, ya que si hubiese alguna nueva variable necesaria para el análisis y no tomada en cuenta en la primera extracción de datos el proceso debe repetirse nuevamente desde el inicio.

Por tanto, para el analista aplicado, se hace imprescindible automatizar el proceso de extracción de datos, de tal manera que la mayor parte del trabajo esté centrada en el análisis y menos en la plomería para contar con la información necesaria.

En este sentido, lo óptimo es contar con una API (del inglés, application programming interfase) que permita encontrar, entender y extraer la información rápidamente, de tal manera que el análisis sea totalmente reproducible y escalable. Por ejemplo, en entradas anteriores mostré cómo, de manera simplificada, acceder a la API de la CEPAL y a la del World Economic Outlook que publica el Fondo Monetario Internacional (FMI) para automatizar el flujo.

En esta entrada, sin embargo, quiero expandir las fuentes de información y ofrecer, al menos conceptualmente, un método general que permita acceder a información de organismos internacionales de forma sistemática. Esto es posible gracias a un modelo de información o protocolo estandarizado denominado SDMX y que permite acceder a los datos de forma más o menos homogénea.

En lo que sigue de esta entrada se revisará conceptualmente el modelo SDMX, se mostrará un flujo relativamente simplificado para extraer información y se mostrarán algunos ejemplos aplicados. Finalmente, para el caso del FMI, se ha creado una librería denominda imfapi que facilita la extracción de datos en base a la API SDMX que tiene actualmente el FMI y que se explora a continuación.

Qué es SDMX

Como se indica en su página web oficial:

SDMX, que significa Statistical Data and Metadata eXchange (Intercambio de Datos y Metadatos Estadísticos), es un estándar ISO diseñado para describir datos y metadatos estadísticos, normalizar su intercambio y mejorar su distribución eficiente entre organizaciones estadísticas y similares.

SDMX está patrocinado por ocho organizaciones internacionales:

1. Banco de Pagos Internacionales (BIS),
2. Banco Central Europeo (BCE),
3. Oficina Estadística de la Unión Europea (Eurostat),
4. Organización Internacional del Trabajo (OIT),
5. Fondo Monetario Internacional (FMI),
6. Organización para la Cooperación y el Desarrollo Económicos (OCDE),
7. División de Estadística de las Naciones Unidas (UNSD) y
8. Banco Mundial (WB)

Cada una de estas organizaciones ha implementado SDMX en sus sistemas de información estadística y provee APIs con esta estructura para su consulta. Esto se puede ver en la tabla a continuación:

Así, el analista puede acceder a una amplia gama de datos macroeconómicos y sociales de diversas fuentes internacionales utilizando un enfoque estandarizado.

Flujo de trabajo general para extraer datos SDMX

Aunque cada API puede tener sus particularidades y el modelo SDMX es bastante amplio, el flujo de trabajo general para extraer datos utilizando APIs SDMX puede resumirse en cuatro pasos. Cada uno corresponde a un concepto clave dentro de la arquitectura SDMX y permite entender cómo están organizados y expuestos los datos por los organismos estadísticos.

1. Identificación del dataflow. El primer paso consiste en identificar el dataflow. Un dataflow es, conceptualmente, el contenedor de un conjunto de datos temático. Funciona como la “base de datos” o el dominio estadístico que publica una institución (por ejemplo, estadísticas monetarias, balances bancarios, tipos de cambio o indicadores macroeconómicos). Identificar el dataflow adecuado implica revisar la lista de dataflows disponibles en la API y seleccionar aquel que contiene la información relevante para el análisis que se desea realizar. Sin este paso, no es posible avanzar hacia una consulta válida, ya que todo dataset SDMX parte de un dataflow específico.
2. Obtención de la estructura de datos. Una vez seleccionado el dataflow, el siguiente paso es obtener la estructura de datos asociada, conocida como Data Structure Definition (DSD). Conceptualmente, la DSD es el esquema lógico del conjunto de datos: describe cómo están organizadas las observaciones y qué elementos intervienen en su identificación. La DSD especifica las dimensiones (como país, indicador, frecuencia o moneda), que son variables clave que clasifican los datos y determinan cómo se combinan para formar series u observaciones. También define la medida principal, que es el valor numérico del dato (por ejemplo, el índice de precios o un saldo monetario), así como los atributos adicionales que proporcionan información contextual (como la unidad, el método de ajuste estacional o el estatus de la observación). Entender esta estructura es esencial para saber qué filtros se pueden aplicar y cómo debe construirse la consulta. 3.Consulta del codelist. El tercer paso consiste en consultar las codelists. Cada dimensión definida en la DSD tiene asociada un codelist, que es el conjunto autorizado de valores posibles para esa dimensión. Las codelists funcionan como un diccionario estándar de códigos que permiten garantizar la interoperabilidad entre instituciones y sistemas. Por ejemplo, una codelist puede contener todos los códigos de países, los tipos de frecuencia temporal (anual, trimestral, mensual), o los distintos indicadores dentro de un dominio estadístico. Consultarlas es fundamental para saber qué valores se pueden usar al filtrar una consulta y cómo deben codificarse correctamente dentro de la URL o del cuerpo de la petición. Como se verá más adelante, muchas veces los codelists muestran lo posible pero no lo que es válido para un dataflow determinado. Por tanto, se tendrá que investigar si el DSD contiene restricciones en los valores y, si no, se obtendrán por fuerza bruta descargando una muestra de los datos y extrayendo los valores únicos. En cualquier caso, lo importante es que el usuario esté familiarizado con los datos.
3. Extracción de datos. Finalmente, el cuarto paso es extraer los datos. Una vez que se conoce el dataflow, su estructura y los códigos permitidos para cada dimensión, es posible construir una consulta válida a la API SDMX. Esto implica seleccionar las combinaciones de códigos relevantes (por ejemplo, país, indicador y frecuencia) y aplicar filtros temporales o de detalle según lo permita la API. La respuesta suele recibirse en un formato estandarizado, como SDMX-JSON o SDMX-XML, que posteriormente puede procesarse en herramientas como R o Python para análisis, visualización o integración en un pipeline reproducible. Este paso materializa todo el trabajo previo, ya que convierte la comprensión conceptual de la estructura SDMX en una solicitud concreta de datos.

Algunos ejemplos

En esta sección se realizará un ejemplo con las APIs del FMI y, posteriormente, con las APIs del Banco Central Europeo (BCE). Aunque se explicará paso a paso, se debe tener en mente que lo que vamos a hacer es:

1. Identificar los dataflows disponibles (“base de datos”)
2. Obtener la estructura de datos del dataflow de interés (“las variables”)
3. Consultar las codelists asociadas a las dimensiones de interés (“los códigos válidos”)
4. Extraer los datos (“la consulta final”)

SDMX en el FMI

El FMI tiene una colección de APIs SDMX 3.0 bastante completa que permite acceder a una amplia gama de datos macroeconómicos. Estas pueden encontrarse, luego de registrarse, aquí:

Las APIs SDMX del FMI —y en realidad cualquier API SDMX 3.0— están diseñadas siguiendo una estructura jerárquica, donde la URL funciona como un camino que va de lo más general a lo más específico. Esto permite que un usuario explore de forma progresiva el sistema estadístico, empezando por los catálogos completos y avanzando hacia un dataset concreto o incluso una sola serie temporal.

La idea fundamental es que cada segmento de la ruta añade una restricción, un filtro, o un nivel de precisión. Así, una llamada puede significar “mostrar todo”, o “dame exactamente esta estructura de datos”, dependiendo de cuántos parámetros se incluyan. Vamos a verlo por partes.

Datos disponibles: el dataflow

En primer lugar, el punto de partida es la URL base que, en este caso, es https://api.imf.org/external/sdmx/3.0. A partir de este punto podemos decir que la API del FMI se divide en dos grandes familias: una de estructura y otra de datos. La primera permite explorar los catálogos y estructuras, mientras que la segunda permite extraer datos concretos.

Por ejemplo, si a la URL base le añadimos /structure/dataflow, obtenemos el catálogo completo de dataflows disponibles en la API, es decir, estamos pidiendo “dame todos los dataflows que tiene el FMI”. Si, por otro lado, añadimos /structure/datastructure básicamente le estamos pidiendo “dame todas las DSD que tiene el FMI”. Este nivel es más bien bastante general, pues no aplica ningún filtro a la extracción, lo que es útil cuando no sabemos qué es lo que necesitamos.

Para ilustrar esto vamos a realizar el primer paso del flujo de trabajo: obtener todos los dataflows disponibles en la API del FMI y localizar el dataflow correspondiente al World Economic Outlook (WEO). Esto se puede hacer con el siguiente código en R:

# 1. Base URL SDMX 3.0 del FMI
base_url <- "https://api.imf.org/external/sdmx/3.0"


# 2. Obtener todos los dataflows
flows_resp <- httr2::request(paste0(base_url, "/structure/dataflow")) |>
  httr2::req_perform()

flows_json <- flows_resp |>
  httr2::resp_body_string() |>
  jsonlite::fromJSON(flatten = TRUE)

flows <- flows_json$data$dataflows

# Tabla de dataflows en formato tibble
df_flows <- tibble::tibble(
  id      = flows$id,
  name    = flows$names.en,
  version = flows$version,
  agency  = flows$agencyID,
  dsd_urn = flows$structure
)

df_flows |> 
  dplyr::select(id, name, version, agency) |>
  dplyr::arrange(id) |> 
  kableExtra::kable() 

En la tabla anterior podemos ver todos los dataflows disponibles en la API del FMI. Cada dataflow tiene un identificador único (id), un nombre descriptivo (name), una versión (version), una agencia responsable (agency) y un URN (del inglés, Uniform Resource Name) que no se reproduce por motivos de espacio pero que apunta a su estructura de datos asociada (dsd_urn).

En nuestro caso nos interesa el dataflow WEO. Podemos filtrar el dataflow de interés de la siguiente manera:

# Nos quedamos con el dataflow WEO
weo <- df_flows |> 
  dplyr::filter(id == "WEO")

weo |> 
  kableExtra::kable()

Estructura de datos: las dimensiones

Ahora que tenemos el dataflow de interés, el siguiente paso es entender qué varialbles (dimensions) están disponibles en su estructura de datos. Para ello, el API que debemos consultar tiene la forma de: /structure/datastructure/{agency}/{dsd_id}/{version}, donde {agency}, {dsd_id} y {version} son los componentes que debemos extraer del URN del dataflow WEO. Nótese que, en el caso de no indicar estos tres campos se corre el riesgo de obtener información desactualizada.

¿Cómo obtenemos esta información? Lo bueno es que, al momento de consultar el dataflow esta información se provee en el URN asociada:

# Parsear el URN del datastructure de WEO
urn <- weo$dsd_urn
urn

## [1] "urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=IMF.RES:DSD_WEO(9.0+.0)"

Nótese que aquí tenemos las 3 piezas esenciales:

1. La agencia responsable del DSD: IMF.RES
2. El identificador del DSD: DSD_WEO
3. La versión del DSD: 9.0+.0

Para extraer estas piezas de forma sistemática podemos usar expresiones regulares en R de la siguiente manera:

m     <- base::regexec("DataStructure=([^:]+):([^()]+)\\(([^)]+)\\)", urn)
parts <- base::regmatches(urn, m)[[1]]

agency_dsd  <- parts[2]   # p.ej. "IMF.RES"
dsd_id      <- parts[3]   # p.ej. "DSD_WEO"
version_dsd <- parts[4]   # p.ej. "9.0+.0"


# Descargar el datastructure de WEO y ver dimensiones

dsd_url <- paste0(
  base_url,
  "/structure/datastructure/",
  agency_dsd, "/", dsd_id, "/", version_dsd
)
dsd_url

## [1] "https://api.imf.org/external/sdmx/3.0/structure/datastructure/IMF.RES/DSD_WEO/9.0+.0"

Ahora que tenemos la URL del datastructure de WEO, podemos descargarlo y ver las dimensiones disponibles:

dsd_resp <- httr2::request(dsd_url) |>
  httr2::req_perform()

dsd_json <- dsd_resp |>
  httr2::resp_body_string() |>
  jsonlite::fromJSON(flatten = TRUE)

# Dimensiones "normales": COUNTRY, INDICATOR, FREQUENCY
dims_main <- dsd_json$data$dataStructures$dataStructureComponents.dimensionList.dimensions[[1]] |>
  tibble::as_tibble() |>
  dplyr::select(position, id, type)

# Dimensión de tiempo: TIME_PERIOD
time_dim <- dsd_json$data$dataStructures$dataStructureComponents.dimensionList.timeDimensions[[1]] |>
  tibble::as_tibble() |>
  dplyr::select(position, id, type)

# Orden completo de dimensiones
dims_clean <- dplyr::bind_rows(dims_main, time_dim) |>
  dplyr::arrange(position)

dims_clean |> 
  kableExtra::kable()

En la tabla anterior podemos ver las dimensiones disponibles en el dataflow WEO (COUNTRY, INDICATOR, FREQUENCY y TIME_PERIOD). Estas dimensiones son esenciales para entender cómo se organizan los datos y qué filtros podemos aplicar al momento de extraer información específica.

Nótese también que, aunque la consulta se ha obtenido sin errores, previamente se exploró dsd_json para entender dónde y cómo estaba almacenando la información.

Codelists: los códigos válidos

Como tercer paso, y antes de extraer los datos, es importante conocer los códigos válidos para cada dimensión del dataset. Esto es fundamental porque, al construir la consulta final, debemos asegurarnos de usar los valores exactos que la API reconoce. Caso contrario nos devolverá un error. Por ejemplo, si queremos obtener el crecimiento del PIB real para un país específico, necesitamos saber cómo codifica el FMI el país, el indicador y la frecuencia. No basta con escribir “Bolivia” o “Real GDP growth”: hay que usar los códigos oficiales definidos por la estructura del dataset.

Cada una de las dimensiones del WEO —COUNTRY, INDICATOR, FREQUENCY y TIME_PERIOD— tiene un conjunto autorizado de valores posibles: el codelist. Por ejemplo, los códigos de país pueden ser BOL, ARG o USA; los indicadores pueden ser NGDP_RPCH, LUR u otros; y las frecuencias válidas suelen ser A (anual), Q (trimestral), etc. Un detalle importante es que cada dataset puede tener codelists distintos, aun para conceptos relativamente similares. El FMI podría usar una lista de países para WEO, otra para BOP (Balance of Payments), y otra para estadísticas monetarias. Esto significa que no necesariamente los códigos que funcionan para un dataflow van a funcionar para otro.

Por eso, si queremos consultar datos del WEO, no podemos inventarnos los códigos ni confiar en listas antiguas: se debe consultar directamente al FMI las codelists oficiales asociadas. La única manera segura de hacerlo es comenzar por el dataflow, obtener su estructura (la DSD) y, desde allí, recuperar las listas de códigos correctas para cada dimensión. Este procedimiento asegura que la consulta sea reproducible, exacta y totalmente compatible con la definición que el FMI usa internamente.

Para obtener estas codelists asociadas al dataflow WEO, utilizamos una URL específica de la API SDMX del FMI. El patrón general es: /structure/dataflow/{agency}/{dataflow_id}/+, donde {agency} y {dataflow_id} provienen del propio dataflow (en nuestro caso, IMF.RES y WEO, respectivamente). El símbolo + indica que queremos la versión más reciente disponible. Pero lo realmente importante son los parámetros que añadimos al final: ?detail=full&references=descendants¹.

Para nuestro caso, la URL completa para obtener las codelists del WEO es la siguiente:

weo_struct_url <- paste0(
  base_url,
  "/structure/dataflow/",
  weo$agency, "/", weo$id, "/+",
  "?detail=full&references=descendants"
)
weo_struct_url

## [1] "https://api.imf.org/external/sdmx/3.0/structure/dataflow/IMF.RES/WEO/+?detail=full&references=descendants"

Al realizar la petición a esta URL, obtenemos una respuesta que incluye todas las codelists asociadas al dataflow WEO. Podemos procesar esta respuesta para extraer las codelists específicas que necesitamos para cada dimensión:

weo_struct_resp <- httr2::request(weo_struct_url) |>
  httr2::req_perform()

weo_struct_json <- weo_struct_resp |>
  httr2::resp_body_string() |>
  jsonlite::fromJSON(flatten = TRUE)

# Tabla de codelists
codelists_tbl <- weo_struct_json$data$codelists

codelists_tbl |> 
  dplyr::select(id, name, version, agencyID) |> 
  head() |> 
  kableExtra::kable()

Nótese que en la tabla anterior se ha extraído bastante información sobre las codelists disponibles para el dataflow WEO. En el código a continuación vamos a resumir un poco lo extraído:

# Vista resumida de las codelists
weo_codelists_overview <- tibble::tibble(
  cl_id   = codelists_tbl$id,
  cl_name = ifelse(is.na(codelists_tbl$names.en), 
                   yes = codelists_tbl$name,
                   no = codelists_tbl$names.en
                   ),
  n_codes = sapply(codelists_tbl$codes, nrow)
)

weo_codelists_overview |> 
  dplyr::arrange(desc(cl_id)) |> 
  kableExtra::kable()

En la tabla anterior podemos ver un resumen de las codelists disponibles para el dataflow WEO. Cada codelist tiene un identificador (cl_id), un nombre descriptivo (cl_name) y el número de códigos que contiene (n_codes). En nuestro caso, nos interesan particularmente las codelists asociadas a las dimensiones COUNTRY, INDICATOR y FREQUENCY: CL_WEO_COUNTRY, CL_WEO_INDICATOR y CL_FREQUENCY.

Por ejemplo, en el caso de CL_WEO_COUNTRY:

weo_country_codes <- codelists_tbl$codes[[which(codelists_tbl$id == "CL_WEO_COUNTRY")]] |>
  tibble::as_tibble() |>
  dplyr::transmute(
    code    = id,
    name_en = names.en  # en CL_WEO_COUNTRY viene como names.en1
  )
weo_country_codes |>
  head(20) |> 
  kableExtra::kable()

En la tabla anterior podemos ver los códigos de país válidos para el dataflow WEO. Cada país tiene un código (code) y un nombre descriptivo en inglés (name_en). Estos códigos son esenciales para construir consultas precisas al API del FMI.

Ahora, procedemos a buscar los INDICATOR disponibles en el WEO:

weo_indicator_codes <- codelists_tbl$codes[[which(codelists_tbl$id == "CL_WEO_INDICATOR")]] |>
  tibble::as_tibble() |>
  dplyr::transmute(
    code    = id,
    name_en = names.en
  )

weo_indicator_codes |>
  kableExtra::kable()

Finalmente, para la frecuencia:

weo_frequency_codes <- codelists_tbl$codes[[which(codelists_tbl$id =="CL_FREQ")]] |>
  tibble::as_tibble() |>
  dplyr::transmute(
    code    = id,
    name_en = names.en
  )
weo_frequency_codes |>
  kableExtra::kable()

Una vez que tenemos los códigos válidos para las dimensiones de interés, estamos listos para proceder a la extracción de datos específicos del dataflow WEO. Este es el último paso del flujo de trabajo SDMX y nos permitirá obtener las series temporales que necesitamos para nuestro análisis macroeconómico.

Extracción de datos: la consulta final

Con los códigos válidos para las dimensiones COUNTRY, INDICATOR y FREQUENCY en mano, ya estamos en condiciones de construir la consulta final para extraer datos específicos del dataflow WEO. Desde el punto de vista de la API del FMI, el endpoint general de datos tiene la forma:

/data/{context}/{agencyID}/{resourceID}/{version}/{key}[?c]

En nuestro caso, {context} será dataflow, {agencyID} será IMF.RES, {resourceID} será WEO y {version} la última versión estable (+). Es decir, todo lo que está antes de {key} ya lo conocemos a partir de los pasos anteriores. Lo que nos falta definir es precisamente el key y, opcionalmente, el parámetro de filtro c.

El parámetro key es la pieza central de la consulta: representa la combinación de valores de dimensiones que identifica una serie o un subconjunto del “cubo” de datos. La API lo define como “the combination of dimension values identifying series or slices of the cube”. En la práctica, esto se traduce en una cadena donde los valores de las dimensiones se concatenan siguiendo el orden definido en la DSD.

En el caso del WEO, vimos que el orden es COUNTRY.INDICATOR.FREQUENCY, así que un key como BOL.NGDP_RPCH.A significa: país Bolivia (BOL), indicador “Real GDP, percent change” (NGDP_RPCH) y frecuencia anual (A). La API permite también trabajar con comodines (*), por ejemplo BOL.*.A (todas las series anuales de Bolivia) o *.NGDP_RPCH.A (la variación del PIB real anual, para todos los países). Esto hace del key una forma muy compacta de expresar qué combinaciones de dimensiones queremos.

El parámetro c, por su parte, permite filtrar por componentes adicionales mediante una sintaxis de tipo c[DIM]=valor. La documentación lo presenta como “Filter data by component value (e.g. c[FREQ]=A)” y, además, permite añadir operadores lógicos. En nuestro ejemplo sencillo, no usamos c porque ya restringimos país, indicador y frecuencia directamente en el key, y dejamos que la API devuelva toda la historia disponible de la serie. Sin embargo, c es muy útil cuando se quieren aplicar filtros adicionales (por ejemplo, acotar el rango de tiempo, seleccionar solo ciertas monedas, métodos o estados de observación) sin tener que complicar el key o cuando se trabaja con estructuras más ricas en dimensiones.

Supongamos que queremos obtener el crecimiento del PIB real (percent change) para Bolivia con frecuencia anual.

# Código de Bolivia (según la codelist WEO)
bol_code <- "BOL"

# Código del indicador "Real GDP, percent change"
rgdp_code <- "NGDP_RPCH"

# Frecuencia anual (A) según la dimensión FREQUENCY
freq_code <- "A"

# Clave SDMX para WEO: COUNTRY.INDICATOR.FREQUENCY
weo_key <- paste(bol_code, rgdp_code, freq_code, sep = ".")
weo_key

## [1] "BOL.NGDP_RPCH.A"

Ahora que tenemos el key procedemos a realizar la consulta:

# URL de extracción de datos SDMX 3.0 (data query correcta)
weo_data_url <- paste0(
  base_url,
  "/data/dataflow/",
  weo$agency, "/", weo$id, "/+/",
  weo_key
)


weo_data_resp <- httr2::request(weo_data_url) |>
  httr2::req_url_query(
    dimensionAtObservation = "TIME_PERIOD",
    attributes             = "dsd",
    measures               = "all",
    includeHistory         = "false"
  ) |>
  httr2::req_perform()

weo_data_json <- weo_data_resp |>
  httr2::resp_body_string() |>
  jsonlite::fromJSON(flatten = FALSE)

En weo_data_json tenemos la respuesta completa de la API con los datos solicitados. La estructura de este objeto es más bien compleja, pues es una lista de listas con varios y distintos niveles de profundidad.

str(weo_data_json, max.level = 4)

## List of 2
##  $ meta: Named list()
##  $ data:List of 2
##   ..$ dataSets  :'data.frame':	1 obs. of  4 variables:
##   .. ..$ structure               : int 0
##   .. ..$ action                  : chr "Replace"
##   .. ..$ series                  :'data.frame':	1 obs. of  1 variable:
##   .. .. ..$ 0:0:0:'data.frame':	1 obs. of  2 variables:
##   .. ..$ dimensionGroupAttributes:'data.frame':	1 obs. of  1 variable:
##   .. .. ..$ :0:::List of 1
##   ..$ structures:'data.frame':	1 obs. of  6 variables:
##   .. ..$ dataSets   :List of 1
##   .. .. ..$ : int 0
##   .. ..$ links      :List of 1
##   .. .. ..$ :'data.frame':	2 obs. of  2 variables:
##   .. ..$ dimensions :'data.frame':	1 obs. of  2 variables:
##   .. .. ..$ series     :List of 1
##   .. .. ..$ observation:List of 1
##   .. ..$ measures   :'data.frame':	1 obs. of  1 variable:
##   .. .. ..$ observation:List of 1
##   .. ..$ attributes :'data.frame':	1 obs. of  3 variables:
##   .. .. ..$ dimensionGroup:List of 1
##   .. .. ..$ series        :List of 1
##   .. .. ..$ observation   :List of 1
##   .. ..$ annotations:List of 1
##   .. .. ..$ : list()

El siguiente paso, por tanto, es transformar esta respuesta en un formato más manejable, como un tibble en R, que contenga las observaciones de tiempo y sus valores correspondientes. En primer lugar vamos a extraer el objeto de la lista anterior denominado dataSets y todo lo que contiene:

# Serie 0:0:0 (la única que pedimos en el WEO)
obs_df <- weo_data_json$data$dataSets$series$`0:0:0`$observations

obs_values <- obs_df[1, ] |>
  unlist(use.names = FALSE) |>
  as.numeric()

# TIME_PERIOD desde la estructura
time_dim    <- weo_data_json$data$structures$dimensions$observation[[1]]$values |> 
  unlist(use.names = FALSE)

# Tibble final (año, valor)
weo_bol_rgdp <- tibble::tibble(
  time  = as.integer(time_dim),
  value = obs_values
) |>
  dplyr::arrange(time)

weo_bol_rgdp |> 
  kableExtra::kable()

Finalmente, podemos también hacer la consulta más rica. Por ejemplo, extraemos el crecimiento anual del PIB real y el déficit primario como porcentaje del PIB para Bolivia, España y Estados Unidos entre el 2015 y 2025:

# 1. Parámetros de consulta

countries  <- c("BOL", "ESP", "USA")
indicators <- c("NGDP_RPCH", "GGXONLB_NGDP")  # Real GDP % y déficit % PIB
freq_code  <- "A"                             # Frecuencia anual

country_key   <- paste(countries,  collapse = "+")
indicator_key <- paste(indicators, collapse = "+")
weo_key_multi <- paste(country_key, indicator_key, freq_code, sep = ".")

# URL de datos SDMX 3.0 (IMF WEO)
weo_data_url_multi <- paste0(
  base_url,
  "/data/dataflow/",
  weo$agency, "/", weo$id, "/+/",
  weo_key_multi
)


# 2. Llamada a la API (1980–2030)

weo_data_resp_multi <- httr2::request(weo_data_url_multi) |>
  httr2::req_url_query(
    dimensionAtObservation = "TIME_PERIOD",
    attributes             = "dsd",
    measures               = "all",
    includeHistory         = "false",
    startPeriod            = "1980",
    endPeriod              = "2030"
  ) |>
  httr2::req_perform()

weo_data_json_multi <- weo_data_resp_multi |>
  httr2::resp_body_string() |>
  jsonlite::fromJSON(flatten = FALSE)


# 3. Estructuras de dimensiones

series_dims_resp <- weo_data_json_multi$data$structures$dimensions$series[[1]]
obs_dim_resp     <- weo_data_json_multi$data$structures$dimensions$observation[[1]]

time_values <- obs_dim_resp$values |>
  unlist(use.names = FALSE)


# 4. Extraer las series

series_df <- weo_data_json_multi$data$dataSets$series

# Cada columna es un data.frame con $attributes y $observations
series_list <- lapply(series_df, function(col) col$observations)
names(series_list) <- names(series_df)

# Función para desanidar una serie
extract_series_tbl <- function(obs_df, series_name) {
  # Índices de dimensión a partir de "0:0:0"
  idx <- as.integer(strsplit(series_name, ":", fixed = TRUE)[[1]]) + 1L
  
  # Mapear índices a códigos de COUNTRY / INDICATOR / FREQUENCY
  dim_values <- purrr::map2_chr(
    seq_along(series_dims_resp$id),
    idx,
    ~ series_dims_resp$values[[.x]]$id[.y]
  )
  names(dim_values) <- series_dims_resp$id
  
  # Número de observaciones
  n_obs <- ncol(obs_df)
  if (is.null(n_obs) || n_obs == 0) {
    return(tibble::tibble(
      COUNTRY     = character(0),
      INDICATOR   = character(0),
      FREQ        = character(0),
      TIME_PERIOD = integer(0),
      value       = numeric(0)
    ))
  }
  
  # Mapear columnas "0,1,2,...,41,..." a índices de time_values
  pos_idx     <- as.integer(colnames(obs_df)) + 1L
  these_times <- as.integer(time_values[pos_idx])
  
  values_num <- obs_df[1, ] |>
    unlist(use.names = FALSE) |>
    as.numeric()
  
  tibble::tibble(
    COUNTRY     = dim_values[["COUNTRY"]],
    INDICATOR   = dim_values[["INDICATOR"]],
    FREQ        = dim_values[["FREQUENCY"]],
    TIME_PERIOD = these_times,
    value       = values_num
  )
}

# Aplicar a todas las series
weo_multi_tidy_raw <- purrr::imap_dfr(
  series_list,
  extract_series_tbl
)


# 5. Filtrar 2015–2025

weo_multi_tidy <- weo_multi_tidy_raw |>
  dplyr::filter(TIME_PERIOD >= 2015, TIME_PERIOD <= 2025) |>
  dplyr::arrange(COUNTRY, INDICATOR, TIME_PERIOD)

# Versión ancha (una columna por indicador)
weo_multi_wide <- weo_multi_tidy |>
  tidyr::pivot_wider(
    id_cols    = c(COUNTRY, TIME_PERIOD),
    names_from  = INDICATOR,
    values_from = value
  )

weo_multi_wide |> 
  kableExtra::kable()

SDMX en el ECB

El Banco Central Europeo (BCE) también ofrece una API SDMX 3.0 bastante completa para acceder a sus datos estadísticos. Adicionalmente, el BCE tiene información en su web dedicada a explicar cada uno de sus dataflows con lo que la exploración es más sencilla².

El flujo de trabajo para extraer datos del BCE es similar al del FMI, pero con algunas diferencias en la estructura de las URLs y los parámetros específicos. Adicionalmente, la respuesta de las consultas a las APIs vienen en formato .xml y los datos se pueden descargar en formato .csv lo cual se tendrá que tomar en cuenta a la hora de procesar la información.

Datos disponibles: el dataflow

En primer lugar, buscamos los dataflows disponibles en la API del BCE.

# 1. Base URL
base_url_ecb <- "https://data-api.ecb.europa.eu/service/"

# 2. Extraer todos los dataflows
flows_resp_ecb <- httr2::request(
  paste0(base_url_ecb, "dataflow")
) |>
  httr2::req_perform()

xml <- xml2::read_xml(
  httr2::resp_body_string(flows_resp_ecb)
)

# 3. Extraer los nodos del Dataflow
df_nodes <- xml2::xml_find_all(
  xml,
  ".//*[local-name()='Dataflow']"
)

# 4. Extraer campos básicos de cada dataflow
flows_tbl <- tibble::tibble(
  id      = purrr::map_chr(df_nodes, ~ xml2::xml_attr(.x, "id")),
  agency  = purrr::map_chr(df_nodes, ~ xml2::xml_attr(.x, "agencyID")),
  version = purrr::map_chr(df_nodes, ~ xml2::xml_attr(.x, "version")),
  
  # extraer la referencia al DSD
  dsd_id = purrr::map_chr(
    df_nodes,
    ~ xml2::xml_attr(
        xml2::xml_find_first(.x, ".//*[local-name()='Structure']/*[local-name()='Ref']"),
        "id"
      )
  ),
  
  dsd_agency = purrr::map_chr(
    df_nodes,
    ~ xml2::xml_attr(
        xml2::xml_find_first(.x, ".//*[local-name()='Structure']/*[local-name()='Ref']"),
        "agencyID"
      )
  ),
  
  dsd_version = purrr::map_chr(
    df_nodes,
    ~ xml2::xml_attr(
        xml2::xml_find_first(.x, ".//*[local-name()='Structure']/*[local-name()='Ref']"),
        "version"
      )
  ),
  
  # Extraer nombre con xpath independiente del namespace
  name    = purrr::map_chr(
    df_nodes,
    ~ xml2::xml_text(
        xml2::xml_find_first(.x, ".//*[local-name()='Name']")
      )
  )
)

# 5. Mostrar tabla ordenada
flows_tbl |>
  dplyr::arrange(id) |>
  dplyr::select(agency, version, dsd_id, name) |>
  kableExtra::kable()

En la tabla anterior podemos ver todos los dataflows disponibles en la API del BCE. Cada dataflow tiene un identificador único (id), una agencia responsable (agency), una versión (version), el dsd_id que se utilizará para identificar el dataflow y un nombre descriptivo (name).

Supongamos que nos interesa el dataflow EST, que muestra el tipo de interés a corto plazo del euro (€STR) y refleja los costos de financiación mayorista, en euros y sin garantía, de los bancos ubicados en la zona del euro para préstamos a un día.

# Nos quedamos con el dataflow CBD2
est <- flows_tbl |> 
  dplyr::filter(id == "EST")

est |> 
  kableExtra::kable()

Estructura de datos: las dimensiones

Como se indicó anteriormente, el siguiente paso es entender qué variables (dimensiones) están disponibles en la estructura de datos del dataflow EST. En este caso particular, el BCE tiene información detallada en su web sobre lo que contiene este dataflow. Sin embargo, vamos a verificar qué dimensiones tiene:

# 1. Definir parámetros del DSD

base_url_ecb <- "https://data-api.ecb.europa.eu/service/"
dsd_id       <- "ECB_EST1"
dsd_agency   <- "ECB"
dsd_version  <- "latest"   # o "1.0" si se quisiera una versión específica


# 2. Descargar el datastructure del dataflow EST

url_dsd <- paste0(
  base_url_ecb,
  "datastructure/", dsd_agency, "/", dsd_id, "/", dsd_version,
  "?references=children"
)

dsd_resp <- httr2::request(url_dsd) |>
  httr2::req_perform()

xml_dsd <- xml2::read_xml(
  httr2::resp_body_string(dsd_resp)
)


# 3. Extraer series de dimensiones

series_dims <- xml2::xml_find_all(
  xml_dsd,
  ".//*[local-name()='DataStructure']
     /*[local-name()='DataStructureComponents']
     /*[local-name()='DimensionList']
     /*[local-name()='Dimension']"
)


# 4. Extraer el ID de la dimensión y el ConceptID ref

dimensions_tbl <- tibble::tibble(
  id = purrr::map_chr(
    series_dims,
    ~ xml2::xml_attr(.x, "id")
  ),
  
  concept_ref = purrr::map_chr(
    series_dims,
    ~ {
      concept_node <- xml2::xml_find_first(
        .x,
        ".//*[local-name()='ConceptIdentity']/*[local-name()='Ref']"
      )
      xml2::xml_attr(concept_node, "id")
    }
  ),
  
  position = seq_along(series_dims)
)

dimensions_tbl |> 
  kableExtra::kable()

Codelists: los códigos válidos

Una vez se conocen las dimensiones del dataflow EST, el siguiente paso es extraer las codelists asociadas a cada dimensión. En algunos casos, la DSD contiene información adicional sobre los codelist como, por ejemplo, restricciones que nos permiten entender qué códigos son válidos. En otros casos, no.

Supongamos que el DSD no mostrase las restricciones de los codelists. En este caso tendríamos que utilizar una aproximación más pragmática y deberíamos extraer una muestra de datos para entender qué valores toman nuestras dimensiones. Esto es relativamente sencillo con el BCE porque la API devuelve datos estructurados en formato .csv. Además, se utilizará el parámetro lastNObservations para controlar el tamaño de la muestra:

est_sample <- httr2::request(
  "https://data-api.ecb.europa.eu/service/data/EST"
) |>
  httr2::req_url_query(
    format = "csvdata",
    lastNObservations = 100
  ) |>
  httr2::req_perform() |>
  httr2::resp_body_string() |>
  readr::read_csv(show_col_types = FALSE)

est_sample |> 
  dplyr::select(KEY, FREQ, BENCHMARK_ITEM, DATA_TYPE_EST, TIME_PERIOD, OBS_VALUE) |>
  head() |> 
  kableExtra::kable()

Para verificar los valores úinicos realizamos la siguiente consulta sobre las dimensiones del dataflow:

est_sample |> 
  dplyr::distinct(FREQ, BENCHMARK_ITEM, DATA_TYPE_EST,TITLE) |> 
  kableExtra::kable()

Extracción de datos: la consulta final

Entonces, supongamos que queremos extraer la tasa de interés compuesta del euro a corto plazo (€STR) con un plazo de 12 meses. Según la muestra anterior, los códigos relevantes son:

est_all <- httr2::request(
  "https://data-api.ecb.europa.eu/service/data/EST/B.EU000A2QQF57.CR"
) |>
  httr2::req_url_query(
    format = "csvdata",
    startPeriod = "2025-01-01",
    endPeriod   = "2025-12-06"
  ) |>
  httr2::req_perform() |>
  httr2::resp_body_string() |>
  readr::read_csv(show_col_types = FALSE)

est_all |> 
  dplyr::select(KEY, FREQ, BENCHMARK_ITEM, DATA_TYPE_EST, TIME_PERIOD, OBS_VALUE) |>
  head() |> 
  kableExtra::kable() 

Graficamos:

library(ggplot2)

est_all |> 
ggplot( aes(x = TIME_PERIOD, y = OBS_VALUE)) +
  geom_line(color = "steelblue", linewidth = 1.2) +
  labs(
    title = "Tasa de interés compuesta del euro a corto plazo (€STR) - 12 meses",
    x = "Fecha",
    y = "Tasa de interés (%)"
  ) +
  theme_bw()

Una nueva librería: imfapi

Hace unos meses alguien de mi red en LinkedIn compartió el post de Christopher Smith donde anunciaba la creación de una nueva librería que “Proporciona funciones fáciles de usar para acceder de forma programática a datos macroeconómicos del ‘SDMX 3.0 IMF Data API’ del Fondo Monetario Internacional.”. La librería en cuestión está disponible en CRAN y funciona establemente. Además, esta librería forma parte del EconDataverse, que recomiendo explorar. A continuación voy a mostrar, de forma simplificada, como acceder a los mismos datos del WEO que vimos anteriormente.

Usando imfapi para extraer datos del WEO

En primer lugar, cargamos la librería:

library(imfapi)

Luego, extraemos los dataflows disponibles en la API del FMI:

dataflows <- imfapi::imf_get_dataflows()

dataflows |> 
  dplyr::glimpse() 

## Rows: 72
## Columns: 6
## $ id           <chr> "GFS_SSUC", "QGFS", "QNEA", "MFS_IR", "WHDREO", "IRFCL", …
## $ name         <chr> "GFS Statement of Sources and Uses of Cash", "Quarterly G…
## $ description  <chr> "The Government Finance Statistics (GFS) includes a cash‐…
## $ version      <chr> "10.0.0", "12.0.0", "7.0.0", "8.0.1", "5.0.0", "11.0.0", …
## $ agency       <chr> "IMF.STA", "IMF.STA", "IMF.STA", "IMF.STA", "IMF.WHD", "I…
## $ last_updated <chr> "2025-06-06T01:50:52.945047Z", "2025-09-03T16:39:57.78654…

Ahora, filtramos el dataflow WEO:

weo_flow <- dataflows |> 
  dplyr::filter(id == "WEO")

weo_flow |> 
  kableExtra::kable()

Y obtenemos las dimensiones del dataflow WEO:

dsd_weo <- imfapi::imf_get_datastructure(dataflow_id = "WEO")
dsd_weo |> 
  kableExtra::kable()

A continuación, extraemos los codelists asociados al dataflow WEO:

dim_list <- list()

for(dim_id in dsd_weo$dimension_id) {
  dim_list[[dim_id]] <- imfapi::imf_get_codelists(dimension_ids = dim_id,
                                                  dataflow_id = "WEO")
}

dim_list |> 
  dplyr::bind_rows() |> 
  dplyr::group_by(dimension_id) |> 
  dplyr::summarise(n_codes = dplyr::n()) |> 
  kableExtra::kable()

En este caso tenemos 338 códigos para la dimensión COUNTRY, 6 códigos para la dimensión FREQUENCY y 145 códigos válidos para INDICATOR.

Finalmente, extraemos los datos del WEO para Bolivia y el crecimiento del PIB real:

data <- imfapi::imf_get(dataflow_id = "WEO",
                        dimensions = list(COUNTRY = "BOL",
                                          INDICATOR = "NGDP_RPCH",
                                          FREQUENCY = "A")
                        )

data |>
  kableExtra::kable()

En la tabla anterior podemos ver los datos extraídos del WEO para Bolivia y el crecimiento del PIB real con frecuencia anual. La librería imfapi simplifica considerablemente el proceso de extracción de datos desde la API del FMI, permitiendo a los usuarios centrarse en el análisis de los datos en lugar de en los detalles técnicos de la API SDMX.

Conclusiones

El objetivo de esta entrada fue mostrar que, para el analista aplicado, trabajar con APIs SDMX no es un fin en sí mismo, sino una forma de construir flujos de trabajo más limpios, reproducibles y escalables. En lugar de depender de descargas manuales y pasos poco documentados, SDMX permite encontrar, entender y extraer datos macroeconómicos de distintos organismos bajo una lógica común.

A través del FMI y el BCE vimos que el proceso general —identificar el dataflow, revisar su estructura, consultar las codelists y finalmente extraer los datos— se repite de manera consistente, lo que facilita automatizarlo y aplicarlo a otras bases. Además, herramientas como imfapi demuestran cómo este enfoque puede simplificarse aún más, haciendo que la carga técnica sea mínima y que la mayor parte del esfuerzo se concentre en el análisis.