Conceptualizacion básica de APIs, e implementación de consultas de la base pública de la OCDE
2026-09-18
Simplificación analógica
Simplificación Técnica
Clasificación de las API
Ejemplo de formato de intercambio en las API
Sintasix de la URL API de consulta
La URL que genera el compositor de consultas de la OCDE, sigue los siguientes elementos (OECD, 2024a):
| Sintasix general de consulta mediante ResFul API |
|---|
| {Host URL}/{Agency identifier},{Dataset identifier},{Dataset version}/{Data selection}?{other optional parameters} |
Sintaxis de la URL API de estructura de datos
La URL que genera el compositor de consultas de la OCDE, que contiene la metadata relacionada a la URL de consulta tiene los siguientes elementos (OECD, 2024a):
| Sintaxis general de la estructura de datos relacionada a la consulta |
|---|
| {Host URL}/{Agency identifier},{Dataset identifier},{Dataset version}?Data structure parameters |
Sin embargo, la OCDE pone en disposición la lista completa de datasets, en la siguiente URL:
Acceder al Developer API query builder, y copiar la Data Query generada:
![]()
Pegar la url en nuestro codigo en R.
Generación de la Gráfica
# 9. GENERACIÓN DE LA GRÁFICA
# ========================================================================
# Paso A: Preparar y limpiar los datos en formato largo para tsbox
Graf_GDPppr <- GDPppr_potential_2026_2036 %>%
filter(REF_AREA == "USA", SCENARIO %in% c("BAU1", "BAU2")) %>%
# Renombramos las columnas obligatorias que requiere tsbox
select(time = TIME_PERIOD, id = SCENARIO, value = obsValue) %>%
# Dividimos entre 1000 y redondeamos para mantener consistencia con tu tabla
mutate(
value = as.numeric(value),
value = round(value / 1000, digits = 2),
# Renombramos los códigos técnicos a nombres legibles para la leyenda
id = case_match(id,
"BAU1" ~ "Business as Usual (Medium Damage)",
"BAU2" ~ "Business as Usual (High Damage)")
)
# Paso B: Dibujar la serie de tiempo interactiva
ts_plot(Graf_GDPppr,
title = "USA: PIB Real Potencial Per Cápita (Base 2021)",
subtitle = "Proyecciones 2026-2036 en miles de USD bajo escenarios de daño climático")
API
Preguntas para la clase:
¿Por qué la OCDE adoptó el estándar SDMX para su API en lugar de usar un formato JSON convencional?
¿Cuáles son las ventajas y desventajas de consumir los datos en vivo mediante la API frente a la descarga tradicional de archivos CSV o Excel?
¿Que riesgos potenciales podriamos enfrentar al integrar la API de la OCDE a un entorno de producción o institucional, y como mitigarlos?
¿Cómo podemos aprovechar la API para vincular la consulta del Structure Query con los Data Query?
Acceso por suscripción.
Debido al volumen, consistencia, disponibilidad y usos comerciales de la base de datos, la oficina de UN Comtrade divide a sus usuarios en tres categorias (United Nations Statistics Division, 2026a):
Free Tier (Acceso público y gratuito: Abierto para estudiantes, periodistas y analistas que realizan consultas rápidas y de bajo volumen. Limita el acceso a un máximo de 50k registros por consulta; todo mediante una API validada por una KEY, limitanto tambien a un maximo de 500 llamadas de consulta al día (University of Toronto Libraries, 2026).
Institutional Access: Portal que otorga acceso sin restricciones y sin costos para el docente y el alumno, según los convenios que la universidad suscriba con UN Comtrade (Stanford University Libraries, 2026).
Premium Subscription: Destinado a entidades privadas que lucran con la información, a gobiernos y centros de investigación. Se gestiona mediante licencia (United Nations Shop, 2026), la cual brinda acceso sin restricciones de ancho de banda, sin contador de volumen, e incluye soporte técnico. Esto habilita herramientas de descargas asincronicas por lotes, descargas masivas (Bulk Download Tool), gestion on-deman de la cuenta en Azure, y acceso preferencia al DataLake de la ONU (United Nations Shop, 2026). Se separa en acceso individual (un solo usuario) y Premium Institutional (red de usuarios)
1. Uso de la libreria comtradr
#carga de datos de las Exportaciones de los paises centroamericanos hacia el resto del mundo
datos_export_ca <- comtradr::ct_get_data(
reporter = c("BLZ", "GTM", "SLV","HND", "NIC", "CRI"),
partner = "World",
flow_direction = "export",
frequency = "A",
start_date = 2018,
end_date = 2025,
commodity_code = "TOTAL")
exportaciones_ca <- datos_export_ca |> as_tibble()
head (exportaciones_ca)# A tibble: 6 × 47
type_code freq_code ref_period_id ref_year ref_month period reporter_code
<chr> <chr> <int> <int> <int> <chr> <int>
1 C A 20180101 2018 52 2018 84
2 C A 20180101 2018 52 2018 188
3 C A 20180101 2018 52 2018 222
4 C A 20180101 2018 52 2018 320
5 C A 20180101 2018 52 2018 340
6 C A 20180101 2018 52 2018 558
# ℹ 40 more variables: reporter_iso <chr>, reporter_desc <chr>,
# flow_code <chr>, flow_desc <chr>, partner_code <int>, partner_iso <chr>,
# partner_desc <chr>, partner2code <int>, partner2iso <chr>,
# partner2desc <chr>, classification_code <chr>,
# classification_search_code <chr>, is_original_classification <lgl>,
# cmd_code <chr>, cmd_desc <chr>, aggr_level <int>, is_leaf <lgl>,
# customs_code <chr>, customs_desc <chr>, mos_code <chr>, mot_code <int>, …# Cargar la librería para graficar
# Crear la gráfica paso a paso
grafica_1 <- ggplot(exportaciones_ca, aes(x = ref_year, y = primary_value/m_m_usd, color = reporter_desc)) +
geom_line() + # 1. Dibuja las líneas
geom_point() + # 2. Dibuja los puntos sobre las líneas
labs(
title = "Gráfica 1: Exportaciones de Centroamérica hacia el resto del mundo",
x = "Año",
y = "Valor en miles de millones de USD",
color = "País",
caption = "Fuente: UN Comtrade utilizando API gratuita validada con Key y la libreria comtradr"
)
grafica_1
2. Uso de comtradr con limitaciones de consulta
#Bloque sugerido si la consulta llegase a exceder los 50k items.
bloques_paises <- list(c("BLZ", "GTM", "SLV"), c("HND", "NIC", "CRI"))
bloques_anios <- list(c(2018, 2021), c(2022, 2025))
lista_datos <- list()
for (paises in bloques_paises) {
for (anios in bloques_anios) {
bloque_descargado <- tryCatch(
{ct_get_data(
reporter = paises,
partner = "World",
flow_direction = "export",
frequency = "A",
start_date = as.character(anios[1]),
end_date = as.character(anios[2]),
commodity_code = "TOTAL")},
error = function(e) { return(NULL) })
lista_datos <- append(lista_datos, list(bloque_descargado))
Sys.sleep(2)}}
exportaciones_ca2 <- bind_rows(lista_datos)
head (exportaciones_ca2) type_code freq_code ref_period_id ref_year ref_month period reporter_code
1 C A 20180101 2018 52 2018 84
2 C A 20180101 2018 52 2018 222
3 C A 20180101 2018 52 2018 320
4 C A 20190101 2019 52 2019 84
5 C A 20190101 2019 52 2019 222
6 C A 20190101 2019 52 2019 320
reporter_iso reporter_desc flow_code flow_desc partner_code partner_iso
1 BLZ Belize X Export 0 W00
2 SLV El Salvador X Export 0 W00
3 GTM Guatemala X Export 0 W00
4 BLZ Belize X Export 0 W00
5 SLV El Salvador X Export 0 W00
6 GTM Guatemala X Export 0 W00
partner_desc partner2code partner2iso partner2desc classification_code
1 World 0 W00 World H5
2 World 0 W00 World H5
3 World 0 W00 World H5
4 World 0 W00 World H5
5 World 0 W00 World H5
6 World 0 W00 World H5
classification_search_code is_original_classification cmd_code
1 HS TRUE TOTAL
2 HS TRUE TOTAL
3 HS TRUE TOTAL
4 HS TRUE TOTAL
5 HS TRUE TOTAL
6 HS TRUE TOTAL
cmd_desc aggr_level is_leaf customs_code customs_desc mos_code
1 All Commodities 0 FALSE C00 TOTAL CPC 0
2 All Commodities 0 FALSE C00 TOTAL CPC 0
3 All Commodities 0 FALSE C00 TOTAL CPC 0
4 All Commodities 0 FALSE C00 TOTAL CPC 0
5 All Commodities 0 FALSE C00 TOTAL CPC 0
6 All Commodities 0 FALSE C00 TOTAL CPC 0
mot_code mot_desc qty_unit_code qty_unit_abbr qty is_qty_estimated
1 0 TOTAL MOT -1 N/A 0 FALSE
2 0 TOTAL MOT -1 N/A 0 FALSE
3 0 TOTAL MOT -1 N/A 0 FALSE
4 0 TOTAL MOT -1 N/A 0 FALSE
5 0 TOTAL MOT -1 N/A 0 FALSE
6 0 TOTAL MOT -1 N/A 0 FALSE
alt_qty_unit_code alt_qty_unit_abbr alt_qty is_alt_qty_estimated net_wgt
1 -1 N/A 0 FALSE 0
2 -1 N/A 0 FALSE 0
3 -1 N/A 0 FALSE 0
4 -1 N/A 0 FALSE 0
5 -1 N/A 0 FALSE 0
6 -1 N/A 0 FALSE 0
is_net_wgt_estimated gross_wgt is_gross_wgt_estimated cifvalue fobvalue
1 TRUE 0 FALSE NA 240911158
2 TRUE 0 FALSE 0 5905411211
3 TRUE 0 FALSE NA 10863483936
4 TRUE 0 FALSE NA 245901227
5 TRUE 0 FALSE 0 5904956424
6 TRUE 0 FALSE NA 11289176124
primary_value legacy_estimation_flag is_reported is_aggregate
1 240911158 4 FALSE TRUE
2 5905411211 4 FALSE TRUE
3 10863483936 4 FALSE TRUE
4 245901227 4 FALSE TRUE
5 5904956424 4 FALSE TRUE
6 11289176124 4 FALSE TRUE# Crear la gráfica
grafica_2 <- ggplot(exportaciones_ca2, aes(x = ref_year, y = primary_value/m_m_usd, color = reporter_desc)) +
geom_line() + # 1. Dibuja las líneas
geom_point() + # 2. Dibuja los puntos sobre las líneas
labs(
title = "Gráfica 2: Exportaciones de Centroamérica hacia el resto del mundo",
x = "Año",
y = "Valor en miles de millones de USD",
color = "País",
caption = "Fuente: UN Comtrade utilizando API gratuita validada con key + la libreria comtradr + ciclo for para no saturar consulta"
)
grafica_2
library (countrycode)
exportaciones_ca3 <- exportaciones_ca3 |>
mutate(
refYear = as.numeric(refYear),
primaryValue = as.numeric(primaryValue),
nombre_pais = countrycode(reporterCode, origin = "un", destination = "country.name.es")
)
# Crear la gráfica
grafica_3 <- ggplot(exportaciones_ca3, aes(x = refYear, y = primaryValue/m_m_usd, color = nombre_pais,group = nombre_pais)) +
geom_line() + # 1. Dibuja las líneas
geom_point() + # 2. Dibuja los puntos sobre las líneas
labs(
title = "Gráfica 3: Exportaciones de Centroamérica hacia el resto del mundo",
x = "Año",
y = "Valor en miles de millones de USD",
color = "País",
caption = "Fuente: UN Comtrade utilizando consulta HTTP validada con Key y la libreria httr"
)
grafica_3
API + key
Preguntas para la clase:
¿Qué es el estandar M49?
¿Qué diferencia hay entre usar el paquete comtradr y construir la URL manualmente con httr2?
¿Por qué la API de UN Comtrade nos exige incluir una “Subscription Key” (clave de API) para darnos los datos?