Servicio Web

La clase ServicioWeb se define en el módulo gee que documenta en esta página.

La forma típica de utilizar esta clase es

>>> from bccr import SW
>>> SW.buscar("nombre de algún indicador")
>>> datos = SW(indic1 = codigo1, indic2=codigo2)

donde codigo1 y codigo2 son los códigos de los indicadorees (posiblemente encontrados con SW.buscar), y indic1 e indic2 los nombres que se le quiere asignar a estos indicadores.

En la documentación que sigue a continuación aparecen más ejemplos.



gee: Un módulo para definir la clase ServicioWeb

Este módulo defile la clase ServicioWeb y crea una instancia de la misma, SW. Esta clase permite descargar datos del ServicioWeb del Banco Central de Costa Rica (https://www.bccr.fi.cr/indicadores-economicos/servicio-web) .

La forma usual de utilizar esta clase es

>>> from bccr import SW

  • para buscar el código de algún indicador de interés, utilice

>>> SW.buscar("nombre de un indicador")

  • para saber más detalles del indicador 3541 (por ejemplo)

>>> SW.quien(3541)

  • para buscar las subcuentas de un indicador, digamos el 779

>>> SW.subcuentas(779)

  • para descargar datos de indicadors 3, 4 y 22 (por ejemplo), hay varias formas de hacerlo

>>> SW(indicA=4, indicB=7, indicC=231) # pasando los códigos como valores de parámetros, en
        cuyo caso los indicadores son renombrados como 'indicA', 'indicB' y 'indicC', respectivamente.
>>> SW(3, 4, 22)   # pasando los códigos directamente (no recomendado)
bccr.gee.FUNCS = {'first': <function <lambda>>, 'last': <function <lambda>>, 'mean': <function <lambda>>, 'nanfirst': <function <lambda>>, 'nanlast': <function <lambda>>, 'nanmean': <function nanmean>, 'nansum': <function nansum>, 'sum': <function <lambda>>}

Diccionario que mapea nombres de funciones a objetos de función. Se utilizan para cambiar de frecuencia los datos

Type

dict of functions

bccr.gee.SW = Clase ServicioWeb: permite buscar y descargar datos de indicadores del servicio web del Banco Central de Costa Rica.

Este es un objeto de clase ServicioWeb con parámetros de inicialización predeterminados. Puede importarse en una sesión simplemente con from bccr import SW.

Type

bccr.ServicioWeb

class bccr.gee.ServicioWeb(nombre: str, correo: str, token: str, indicadores: pandas.core.frame.DataFrame)

Una clase para descargar datos del servicio web del Banco Central de Costa Rica

nombre

El nombre del usuario registrado en el servicio web del BCCR

Type

str

correo

El correo electrónico registrado por el usuario en el servicio web.

Type

str

token

El token recibido por el usuario de parte del BCCR para tener acceso al servicio web.

Type

str

indicadores

una table con la descripción de los indicadores disponibles en el servicio web.

Type

pd.DataFrame

Ejemplos

Asumiendo que Ratón Pérez se registró en el servicio web del BCCR:

>>> from bccr import ServicioWeb
>>> consulta = ServicioWeb('Ratón Pérez', 'raton.perez@correo.com', '4SDLJUHKEZ')

Si Ratón Pérez no se ha registrado en el servicio web del BCCR, entonces simplemente puede usar una instancia predeterminada de ServicioWeb, llamada SW, que utiliza las credenciales del paquete:

>>> from bccr import SW
buscar(todos=None, *, frase=None, algunos=None, frecuencia=None, Unidad=None, Medida=None, periodo=None, subcuentas=False)

buscar códigos de indicadores según su descripción

Parámetros

  • frase (str) – texto que debe aparecer en la descripción del indicador. Sólo una de estos tres parámetros debe utilizarse a la vez. “frase” busca una coincidencia exacta, “todos” que todas las palabras aparezcan (en cualquier orden), “algunos” que al menos una de las palabras aparezca. La búsqueda no es sensible a mayúscula/minúscula. Si no se indica un parámetro [por ejemplo, SW.buscar(“precios consumidor”)], se asume que SW.buscar(todos=”precio consumidor”)

  • todos (str) – texto que debe aparecer en la descripción del indicador. Sólo una de estos tres parámetros debe utilizarse a la vez. “frase” busca una coincidencia exacta, “todos” que todas las palabras aparezcan (en cualquier orden), “algunos” que al menos una de las palabras aparezca. La búsqueda no es sensible a mayúscula/minúscula. Si no se indica un parámetro [por ejemplo, SW.buscar(“precios consumidor”)], se asume que SW.buscar(todos=”precio consumidor”)

  • algunos (str) – texto que debe aparecer en la descripción del indicador. Sólo una de estos tres parámetros debe utilizarse a la vez. “frase” busca una coincidencia exacta, “todos” que todas las palabras aparezcan (en cualquier orden), “algunos” que al menos una de las palabras aparezca. La búsqueda no es sensible a mayúscula/minúscula. Si no se indica un parámetro [por ejemplo, SW.buscar(“precios consumidor”)], se asume que SW.buscar(todos=”precio consumidor”)

  • frecuencia (str, optional. uno de ('A','6M','Q','M','W','D')) – mostrar solo indicadores que tengan la frecuencia indicada.

  • Unidad (str, optional) – mostrar solo indicadores que tengan la unidad indicada

  • Medida (str, optional) – mostrar solo indicadores que tengan la medida indicada

  • periodo (str, optional) – mostrar solo indicadores que tengan la periodicidad indicada

  • subcuentas (bool, optional (False)) – incluir subcuentas de cuentas que ya aparecen en los resultados

Devuelve

Tipo del valor devuelto

pd.DataFrame

Ejemplos

Para buscar un indicador que tenga todas las palabras «IMAE», «tendencia», «ciclo» (en cualquier orden)

>>> from bccr import SW
>>> SW.buscar("IMAE tendencia ciclo")

Para incluir subcuentas de «IMAE tendencia ciclo» en los resultados

>>> SW.buscar("IMAE tendencia ciclo", subcuentas=True)

Para buscar un indicador que tenga la frase exacta «Índice de Precios al Consumidor»

>>> SW.buscar(frase="Índice de Precios al Consumidor")

Para buscar un indicador que tenga al menos una de las palabras «exportaciones» e «importaciones»

>>> SW.buscar(algunos="exportaciones importaciones")

Para buscar los términos «precios transables», y filtrar que muestre solo resultados con medida «Variación interanual»

>>> SW.buscar('precios transables', Medida='Variación interanual')

Para mostrar un breve mensaje de ayuda

>>> SW.buscar()

Notas

El parámetro “frecuencia” será discontinuado en algún momento. Se recomienda usar el parámetro “periodo” para cumplir la misma funcionalidad.

datos(*codigos, FechaInicio=None, FechaFinal=None, func=None, freq=None, fillna=None, **indicadores)
Parámetros

  • codigos (sucesión de enteros o strings) – Los códigos numéricos (como int o str) de los indicadores que se desean descargar (ver parámetro indicadores). En el resultado, el indicador se identifica con el nombre que tiene en el catálogo de cuentas; en caso de querer indicar un nombre distinto, solicitar el indicador usando el parámetro indicadores.

  • FechaInicio (str or int, optional) – fecha de la primera observación a descargar. Ver nota 6 abajo para más detalles.

  • FechaFinal (str or int, optional) – fecha de la última observación a descargar. Ver nota 6 abajo para más detalles.

  • func (str) – Una opción de [“mean”, “sum”, “last”, “first”, “nanmean”, “nansum”, “nanlast”, “nanfirst”]. función que se desea utilizar para transformar la frecuencia de los datos (predeterminado: None). Si se especifica una sola función, se usa la misma para todas las series que lo requiera. Para usar funciones distintas puede pasar un diccionario {nombre-de-la-serie: funcion-a-usar,…}

  • freq (str, optional) – frecuencia a la que se quiere convertir los datos. Si este parámetro no se indica y se requieren series de distintas frecuencias, el resultado será un Data.Frame con la menor periodicidad de las series solicitadas.

  • fillna (str, one of ('backfill', 'bfill', 'pad', 'ffill')) –

    Si hay datos faltantes (por ejemplo, fines de semana), cómo rellenar esos valores. “backfill” y “bfill” usan

    el siguiente valor disponible (llena hacia atrás) mientras que “pad” y “ffill” usan el último valor disponible (llena hacia adelante).

  • indicadores (pares de nombre=codigo, de las series requeridas) – Este es el método preferible para indicar las series requeridas (en vez del parámetro códigos). Las series se enumeran como pares de nombre=codigo, donde nombre es el nombre que tendrá el indicador en el DataFrame resultante, y codigo es un número entero que identifica la serie en el servicio web del BCCR.

Devuelve

una tabla con los datos solicitados, filas indexadas por tiempo, cada columna es un indicador.

Tipo del valor devuelto

pd.DataFrame

Notas

1. Esta función construye una consulta por método GET a partir de los parámetros proporcionados, para cada uno de los Indicadores solicitados. Descarga los datos, los transforma en una tabla de datos de Pandas.

  1. Si hay indicadores de distintas frecuecias, los transforma a la misma frecuencia según el método indicado.

3. A excepción de codigos, todos los parámetros deben usar palabra clave, aunque es preferible usar indicadores en vez de codigos. (Ver los ejemplos)

4. Hay varias maneras de indicar los Indicadores: (a) simplemente enumerándolos, (b) en una lista o tupla, y (c) en un diccionario (método obsoleto, es mejor usar el parámetro indicadores). En caso de tratarse de diccionario, los códigos se indican como las llaves del diccionario, mientras que los valores del diccionario se usan para renombrar las columnas resultantes.

5. Las instancias de la clase ServicioWeb son ejecutables: si se llaman como una función, simplemente ejecutan la función datos()

  1. El formato de fechas es muy flexible. Por ejemplo, todas estas expresiones son válidas:

  • Para indicar el año 2015: se puede emplear tanto un int como un str

>>>   FechaInicio = 2015 # se interpreta como  1 de enero de 2015
>>>   FechaFinal = "2015"  # se interpreta como 31 de diciembre de 2015

  • Para indicar el mes marzo de 2017: cualquiera de estas expresiones es válida

>>> "2017-03"
>>> "2017/03"
>>> "2017m3"
>>> "03/2017"
>>> "03-2017"

En FechaInicio= resulta en 1 de marzo de 2017, en FechaFinal= resulta en 31 de marzo de 2017.

  • Para indicar el 12 de agosto de 2018:

>>> "2017/8/12"
>>> "2017-08-12"
>>> "12/8/2017"

Observe que para separar los componentes de una fecha se puede usar cualquier caracter no numérico (usualmente / o -).

Ejemplos

La forma preferible de solicitar los indicadores es como pares de nombre=código, de manera que nombre se utilice como encabezado de columna en la tabla de datos resultante:

>>> from bccr import SW
>>> SW(IMAE=35449, Inflación=25485)

Para hacer consultas rápidas, puede simplemente pasarse únicamente los códigos

>>> SW(35449, 25485)

Observe que si se «ejecuta» la instancia SW, simplemente se está ejecutando la función datos. Por ello, no es necesario escribir datos en los ejemplos anteriores

>>> SW.datos(35449, 25485) # resultado idéntico al anterior, pero digitando más.

Si se desea, los códigos pueden escribirse como de tipo str:

>>> SW('35449', '25485')

Puede también pasarse los códigos en un diccionario. Advertencia Esta forma se considera obsoleta, pero se mantiene aún en el paquete para darle soporte a código escrito con versiones anteriores de bccr. Nótese que en esta forma, las llaves del diccionario son los códigos, y los valores se usan como encabezado de columna:

>>> cuentas = {33439:'PIB', 33448:'Consumo', 33451:'Gasto', 33457:'Inversión'}
>>> SW(cuentas)    # esta forma es obsoleta, será eliminada en una versión futura

Si desea usar diccionarios, la forma preferible de hacer la consulta anterior es (observe cambio de orden en diccionario y que debe desempacarlo con dos asteriscos ** ):

>>> cuentas = {'PIB': 33439, 'Consumo': 33448, 'Gasto': 33451, 'Inversión':33457}
>>> SW(**cuentas)    # es necesario usar ** delante del nombre del diccionario
>>> SW(PIB=33439, Consumo=33448, Gasto=33451, Inversión=33457)  # equivalente a las dos líneas anteriores

Es posible restringir el rango de los datos, usando los parámetros FechaInicio= y FechaFinal=:

>>> SW(IMAE=35449, Inflación=25485, FechaInicio='2000/01/01')

En caso de solo señalar el año, se sobrentiende «1 de enero» en el caso de FechaInicio= y «31 de diciembre» en FechaFinal=

>>> SW(IMAE=35449, Inflación=25485, FechaInicio=2000, FechaFinal=2015)

Si se solicitan indicadores que tienen distinta periodicidad, el resultado tendrá la periodicidad del indicador menos frecuente. Para ello, se puede indicar la función para convertir los datos de mayor a menor frecuencia, y si de seben rellenar datos faltantes (por ejemplo, valores faltantes en los fines de semana se pueden intrapolar con el dato del lunes siguiente o del viernes anterior)

>>> SW(IMAE=35449, Inflación=25485, TPM=3541, func='mean', fillna='ffill') # IMAE e Inflación son series mensuales,
>>> # miestras que TPM es diaria. TPM se convierte en mensual calculando el promedio, habiendo sustituido los
>>> # valores faltantes con el último dato disponible
quien(codigo)

Imprime información acerca de un indicador

Parámetros

codigo (str or int) – código numérico del indicador que se desea describir.

Devuelve

El resultado se imprime a pantalla

Tipo del valor devuelto

None

Ejemplos

>>> from bccr import SW
>>> SW.quien(33438)
subcuentas(codigo, *, maxlevel=9, arbol=True)

Subcuentas de un indicador

Algunos indicadores pueden desagregarse (por ejemplo, el IMAE total se puede desagregar por actividad económica). Esta función ayuda a encontrar los códigos de esas subcuentas.

Parámetros

  • codigo (str or int) – código numérico del indicador del que se desea conocer sus subcuentas.

  • maxlevel (int (=9, opcional)) – profundidad del árbol. 1= solo ramas directas («hijos»), 2=incluir «nietos», 3=…

  • arbol (bool, (=True, opcional)) – Imprime árbol de subcuentas si True.

Devuelve

Los códigos de las subcuentas. Además, el resultado se imprime a pantalla como un árbol de cuentas (si arbol=True).

Tipo del valor devuelto

list

Ejemplos

>>> from bccr import SW
>>> SW.subcuentas(33439)