Usar el API v2 de estadística desde Python y R

En el post anterior hablamos de las mejoras que trae el API V2 de las estadísticas del sistema financiero dominicano. Hoy vamos a hablar sobre cómo integrar estas mejoras en dos lenguajes muy utilizados en la ciencia de datos.

Contenido

· Introducción
· Consumir el API V2 desde Python.
· Consumir el API V2 desde R.
· Conclusiones

Introducción

Antes de iniciar, debemos entender el concepto central de esta mejora, el cual consiste en la paginación.

Un API paginado devuelve la información en pequeñas partes o páginas en lugar de entregar toda la información en una sola respuesta (como ocurre en el API que tenemos actualmente). El usuario debe especificar el número de página y el tamaño de página que desea recuperar, y se devuelve la página solicitada con información adicional sobre el número total de elementos y páginas disponibles. Esto es beneficioso para manejar grandes conjuntos de datos de manera eficiente y manejable en pequeñas partes.

Según la definición anterior, ahora en cada petición recibiremos unos metadatos que nos guiarán a través del proceso para obtener la información. Estos metadatos serán parte del encabezado (header) de la respuesta. A continuación, enumeramos estos metadatos:

HTTP response API V2

x-pagination: [JSON] Es el nombre del atributo del encabezado (header) que contiene los metadatos.

CurrentPage: [Entero] Es el atributo que nos informa en que página nos encontramos.

RequestRecords: [Entero] Nos informa del número de páginas que hemos especificado en la consulta.

RecordsResponse: [Entero] Nos indica el número de página que ha traído la petición.

HasPrevious: [Booleano] Nos indica si hay paginas anteriores a la que estamos consultando.

HasNext: [Booleano] Nos indica si hay páginas posteriores a la que estamos consultando.

TotalRecords: [Entero] Nos indica el total de registro en la consulta.

TotalPages: [Entero] Nos indica el total de páginas en la consulta.

Ahora que comprendemos los cambios en el API V2, vamos a mostrar un ejemplo de cómo consultarlo utilizando estos dos lenguajes.

Consumir el API V2 desde Python.

#Librerías necesarias para seguir el  ejercicio. 
import json
import requests
import pandas as pd

#Variable para saber si hay más página 
next_page = True
#Página inicial
pagina = 1
#Registros que queremos por petición.
#Seleccionar un número que se adapte a sus necesidades menor a 100k.
registro = 50_000

#Rango de fecha a consultar
periodo_inicial = '2021-07'
periodo_final = '2021-08'

#Endpoint que se consultará
end_point = 'captaciones/detalle'

#Colopar API KEY personal en la variable headers

headers={
          'Ocp-Apim-Subscription-Key': 'TU_API_KEY' ,   
          'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36',
}

#Listas que almacenará los datos
registros_list = []

#El ciclo funcionará hasta que se llegue a la última página de la petición
while next_page:
    
    #Concatenamos las variables para formar la url de la consulta
    url = f'https://apis.sb.gob.do/estadisticas/v2/{ end_point }?periodoInicial={ periodo_inicial }&periodoFinal={ periodo_final }&tipoEntidad=BM&paginas={ pagina }&registros={ registro }'

    try:
        #Hacemos la petición
        response  = requests.get(url, headers=headers) 
        #Validamos el estatus de la petición según el protocolo http.
        response.raise_for_status()
        
        #Parseamos la respuesta con los datos a Json
        datos = response.json()
        
        #Agregamos los datos a una lista conformada por dataframes de pandas
        registros_list.append(pd.DataFrame(datos))
    
        #Obtenemos los metadatos que necesitamos, los cuales decribimos más arriba en el artículo.    
        #Parseamos
        metadatos = json.loads(response.headers['x-pagination'])
        
        #Obtebemos los metadatos necesarios
        next_page = metadatos['HasNext']
        total_pages =  metadatos['TotalPages']
        total_record = metadatos["TotalRecords"]
        
        #Imprimimos la página actual y el total de página
        print('Pagina:',pagina,'/',total_pages)
        
        #Incrementamos 1 para ir a la siguiente página
        pagina +=1
        
    except requests.exceptions.HTTPError as errh:
        print("Error HTTP:", errh)
        raise errh
    except requests.exceptions.ConnectionError as errc:
        print("Error de conexión:", errc)
        raise errc
    except requests.exceptions.Timeout as errt:
        print("Error Timeout:", errt)
        raise errt
    except requests.exceptions.RequestException as err:
        print("Algo salío mal:", err)
        raise err
        
#Concatenamos la lista de dataframes en uno solo       
registros = pd.concat(registros_list, ignore_index=True)

#Vemos los primeros cinco regístros del dataframe
registros.head()

Impresión del dataframe por pantalla

Consumir el API V2 desde R.

#Librerías necesarias para seguir el  ejercicio. 
library(httr) 
library(jsonlite) 
library(dplyr) 

#Variable para saber si hay más página 
next_page <- TRUE
#Página inicial
pagina <- 1

#Registros que queremos por petición. 
#Seleccionar un número que se adapte a sus necesidades menor a 100k.
registro <- 50000

#Rango de fecha a consultar
periodo_inicial <- '2021-07'
periodo_final <- '2021-07'

#Endpoint que se consultará
end_point <- 'captaciones/detalle'

#Colopar API KEY personal en la variable headrers
headers <- c('Ocp-Apim-Subscription-Key' = 'TU_API_KEY') 

#Listas que almacenará los datos
registros_list <- list() 

#El ciclo funcionará hasta que se llegue a la última página de la petición
while (next_page) {
  
  #Concaternamos las variables para formar la url de la consulta
  url <- paste0("https://apis.sb.gob.do/estadisticas/v2/", end_point, 
                "?periodoInicial=", periodo_inicial, 
                "&periodoFinal=", periodo_final, 
                "&tipoEntidad=BM&paginas=", pagina, 
                "&registros=",registro
                ) 
  
  tryCatch({ 
    #Hacemos la petición
    response <- GET(url, add_headers(headers)) 
    
    #Validamos el estatus de la petición según el protocolo http.
    stop_for_status(response) 
    
    ##Parseamos la respuesta con los datos a Json
    datos <- content(response, as = "text") %>% 
             fromJSON(simplifyDataFrame = TRUE) 
    
    #Agregamos los datos a una lista conformadas por dataframe
    registros_list[[pagina]] <- as.data.frame(datos) 
    
    #Obtenemos los metadatos que necesitamos, los cuales decribimos más arriba en el artículo.    
    #Parseamos
    metadatos <- fromJSON(response$headers$`x-pagination`) 
    
    #Obtenemos los metadatos necesarios
    next_page <- metadatos[['HasNext']] 
    total_pages <- metadatos[['TotalPages']] 
    total_record <- metadatos[["TotalRecords"]] 
    
    #Imprimimos la página actual y el total de página
    cat('Pagina:',pagina,'/',total_pages, "\n") 
    
    #Incrementamos 1 para ir a la siguiente página
    pagina <- pagina + 1 
    
    }, 
    error = function(e){ 
      stop(e$message) 
    }) } 

#Concatenamos la lista de dataframe en uno solo  
registros <- do.call(rbind, registros_list)

Mostrando datos por pantalla

Conclusiones

El código expuesto anteriormente es informativo y puede ser modificado, optimizado y compartido.

Para tener un mayor entendimiento de los códigos HTTP recomendamos la siguiente lectura: HTTP response status codes — HTTP | MDN (mozilla.org).