Venecodollar

English

Spanish

Venecodollar is a TypeScript library that provides some asynchronous functions to obtain a JSON object with the different values that the dollar and euro has assumed in bolivars. This library is useful for TypeScript or TypeScript projects that need to obtain updated information about the exchange rate of the dollar or euro in Venezuelan bolivars.

The data is obtained from ExchangeMonitor

Installation

To install the library, you can use the different package managers:

NPM

For the case of NPM:

npm install venecodollar

Yarn

On the other hand, with Yarn it would be as follows:

yarn add venecodollar

Usage

Regarding the use of the library, it is first necessary to import the functions that allow to obtain the values.

This can be done in two ways:

import * as Venecodollar from "venecodollar"

Or

const {
  getDollarPrices,
  getDollarPricesWithAverage,
  calculateBsToDollar,
  calculateDollarToBs,
  getEuroPrices,
  getEuroPricesWithAverage,
  calculateBsToEuro,
  calculateEuroToBs
} = require("venecodollar")

That said, it is necessary to emphasize that both functions are asynchronous, so it is necessary to work them in async/await functions or as promises. Some examples of this can be:

async/await

async function getDollar() {
  try {
    const response = await getDollarPrices()
    return response
  } catch (error) {
    console.log(error)
  }
}

Promises

const getAverage = () => {
  getEuroPricesWithAverage()
    .then(res => {
      return res
    })
    .catch(err => {
      console.log(err)
      return null
    })
}

Functions

The package has at its disposal eight (8) functions, four (4) to dollar values and four (4) to euro values:

Dollar functions:

getDollarPrices()
getDollarPricesWithAverage()
calculateBsToDollar(bs: number)
calculateDollarToBs(dollar: number)

Euro functions:

getEuroPrices()
getEuroPricesWithAverage()
calculateBsToEuro(bs: number)
calculateEuroToBs(euro: number)

Dollar functions

getDollarPrices()

This function returns two possible values. In the case of not having been able to connect to the services that provide the values, it will return null. However, if it succeeds in connecting, it will return an array with the entities in charge of monitoring the dollar value.

Each element of the array will consist of the title of the entity, the dollar value, the date of its last update and some values more. An example of this is the following:

[
  {
    "title": "Dólar EM",
    "dollar": 33.49,
    "updatedDate": "11:42:16 A. M. del sábado 9 de septiembre, 2023",
    "image": "https://exchangemonitor.net/img/ve/exchangemonitor.webp",
    "difference": 0.01,
    "differencePercentage": "0.03%",
    "tendency": "Downtrend",
    "tendencyColor": "red"
  },
  {
    "title": "Monitor Dolar Vzla",
    "dollar": 31.88,
    "updatedDate": "Jueves 31 de agosto, 2023",
    "image": "https://exchangemonitor.net/img/ve/monitor-dolar-vzla.webp",
    "difference": 0,
    "differencePercentage": "0.00%",
    "tendency": "Unchanged",
    "tendencyColor": "gray"
  },
  {
    "title": "BCV",
    "dollar": 33.34,
    "updatedDate": "7:59:16 P. M. del viernes 8 de septiembre, 2023",
    "image": "https://exchangemonitor.net/img/ve/nacional/bcv.webp",
    "difference": 0.12,
    "differencePercentage": "0.36%",
    "tendency": "Uptrend",
    "tendencyColor": "green"
  }
]

getDollarPricesWithAverage()

Similarly to getDollarPrices(), this function returns two possible values. In case of not connecting to the services, it will return the null value. On the other hand, if it does connect, it will return an object which will have the date on which the service was consulted, the average of all the entities whose dollar value is greater than zero (0) and an array with all the entities whose information is consulted. An example of this is the following:

{
  "date": "2023-09-09T12:56:14.087Z",
  "average": 32.80,
  "entities": [
    {
      "entity": "Dólar EM",
      "info": {
        "title": "Dólar EM",
        "dollar": 33.49,
        "updatedDate": "11:42:16 A. M. del sábado 9 de septiembre, 2023",
        "image": "https://exchangemonitor.net/img/ve/exchangemonitor.webp",
        "difference": 0.01,
        "differencePercentage": "0.03%",
        "tendency": "Downtrend",
        "tendencyColor": "red"
      }
    },
    {
      "entity": "Monitor Dolar Vzla",
      "info": {
        "title": "Monitor Dolar Vzla",
        "dollar": 31.88,
        "updatedDate": "Jueves 31 de agosto, 2023",
        "image": "https://exchangemonitor.net/img/ve/monitor-dolar-vzla.webp",
        "difference": 0,
        "differencePercentage": "0.00%",
        "tendency": "Unchanged",
        "tendencyColor": "gray"
      }
    },
    {
      "entity": "BCV",
      "info": {
        "title": "BCV",
        "dollar": 33.34,
        "updatedDate": "7:59:16 P. M. del viernes 8 de septiembre, 2023",
        "image": "https://exchangemonitor.net/img/ve/nacional/bcv.webp",
        "difference": 0.12,
        "differencePercentage": "0.36%",
        "tendency": "Uptrend",
        "tendencyColor": "green"
      }
    }
  ]
}

calculateBsToDollar(bs: number)

The response returned by this function is very similar to getDollarPrices(), however, it has a notorious particularity and, is that each entity belonging to the array will be formed by three very notorious elements: entity, being the name of the entity, info that contains the title of the entity, its dollar value and the date on which it updated the value and, finally, bsCalculated, which would represent the calculation performed to know the value of the dollar amount, passed as a parameter in terms of bolivars.

calculateDollarToBs(dollar: number)

This function would represent the calculation similar to the calculateBsToDollar function but, instead of calculating the value of the amount expressed in bolivars in dollars, this function would show the entities with the calculation made for each of them in dollar terms.

Euro functions

getEuroPrices()

This function returns two possible values. In the case of not having been able to connect to the services that provide the values, it will return null. However, if it succeeds in connecting, it will return an array with the entities in charge of monitoring the euro value.

Each element of the array will consist of the title of the entity, the euro value, the date of its last update and some values more. An example of this is the following:

[
  {
    "title": "Dólar EM",
    "euro": 37.62,
    "updatedDate": "11:41:41 A. M. del sábado 9 de septiembre, 2023",
    "image": "https://exchangemonitor.net/img/ve/exchangemonitor.webp",
    "difference": 0.01,
    "differencePercentage": "0.02%",
    "tendency": "Uptrend",
    "tendencyColor": "green"
  },
  {
    "title": "Monitor Dolar Vzla",
    "dollar": 37.42,
    "updatedDate": "11:41:41 A. M. del sábado 9 de septiembre, 2023",
    "image": "https://exchangemonitor.net/img/ve/monitor-dolar-vzla.webp",
    "difference": 0,
    "differencePercentage": "0.01%",
    "tendency": "Downtrend",
    "tendencyColor": "red"
  },
  {
    "title": "BCV",
    "dollar": 37.45,
    "updatedDate": "8:07:41 P. M. del viernes 8 de septiembre, 2023",
    "image": "https://exchangemonitor.net/img/ve/nacional/bcv.webp",
    "difference": 0.15,
    "differencePercentage": "0.41%",
    "tendency": "Uptrend",
    "tendencyColor": "green"
  }
]

getEuroPricesWithAverage()

Similarly to getEuroPrices(), this function returns two possible values. In case of not connecting to the services, it will return the null value. On the other hand, if it does connect, it will return an object which will have the date on which the service was consulted, the average of all the entities whose dollar value is greater than zero (0) and an array with all the entities whose information is consulted. An example of this is the following:

{
  "date": "2023-09-09T12:56:14.087Z",
  "average": 37.03,
  "entities": [
    {
      "entity": "Dólar EM",
      "info": {
        "title": "Dólar EM",
        "euro": 37.62,
        "updatedDate": "11:41:41 A. M. del sábado 9 de septiembre, 2023",
        "image": "https://exchangemonitor.net/img/ve/exchangemonitor.webp",
        "difference": 0.01,
        "differencePercentage": "0.02%",
        "tendency": "Uptrend",
        "tendencyColor": "green"
      }
    },
    {
      "entity": "Monitor Dolar Vzla",
      "info": {
        "title": "Monitor Dolar Vzla",
        "dollar": 37.42,
        "updatedDate": "11:41:41 A. M. del sábado 9 de septiembre, 2023",
        "image": "https://exchangemonitor.net/img/ve/monitor-dolar-vzla.webp",
        "difference": 0,
        "differencePercentage": "0.01%",
        "tendency": "Downtrend",
        "tendencyColor": "red"
      }
    },
    {
      "entity": "BCV",
      "info": {
        "title": "BCV",
        "dollar": 37.45,
        "updatedDate": "8:07:41 P. M. del viernes 8 de septiembre, 2023",
        "image": "https://exchangemonitor.net/img/ve/nacional/bcv.webp",
        "difference": 0.15,
        "differencePercentage": "0.41%",
        "tendency": "Uptrend",
        "tendencyColor": "green"
      }
    }
  ]
}

calculateBsToEuro(bs: number)

The response returned by this function is very similar to getEuroPrices(), however, it has a notorious particularity and, is that each entity belonging to the array will be formed by three very notorious elements: entity, being the name of the entity, info that contains the title of the entity, its dollar value and the date on which it updated the value and, finally, bsCalculated, which would represent the calculation performed to know the value of the bolivars amount, passed as a parameter in terms of euros.

calculateEuroToBs(euro: number)

This function would represent the calculation similar to the calculateBsToEuro function but, instead of calculating the value of the amount expressed in bolivars in euros, this function would show the entities with the calculation made for each of them in euro terms.

Types

Likewise, the package was designed using TypeScript, so it is possible to make use of function typing. To do so, it is necessary to import the data types directly from your folder:

import { TDollar, TDollarEntity, TDollarAverage, TDollarCalculated, TBsCalculated, TDollarCalculatedAverage, TBsCalculatedAverage } from 'venecodollar/src/types/DollarType'

Or

const { TEuro, TEuroEntity, TEuroAverage, TEuroCalculated, TBsCalculated, TEuroCalculatedAverage, TBsCalculatedAverage } = require('venecodollar/src/types/DollarType')

As can be seen, there are fourteen (14) data types, of which we can highlight TDollar, TDollarEntity, TDollarAverage, TDollarCalculated, TBsCalculated, TDollarCalculatedAverage, TBsCalculatedAverage, TEuro, TEuroEntity, TEuroAverage, TEuroCalculated, TBsCalculated, TEuroCalculatedAverage and TBsCalculatedAverage.

TDollar

type TDollar = {
  title: string;
  dollar: number;
  updatedDate: string;
  image?: string;
  difference?: number;
  differencePercentage?: string;
  tendency?: string;
  tendencyColor?: string;
}

TDollarEntity

type TEntity = {
  entity: string
  info: TDollar
}

TDollarAverage

type TDollarAverage = {
  date: Date;
  average: number;
  entities: TDollarEntity[];
}

TDollarCalculated

type TDollarCalculated = {
  entity: string,
  info: TDollar,
  dollarCalculated: number
}

TBsCalculated

type TBsCalculated = {
  entity: string,
  info: TDollar,
  bolivarCalculated: number
}

TDollarCalculatedAverage

type TDollarCalculatedAverage = {
  date: Date,
  average: number,
  entities: TDollarCalculated[]
}

TBsCalculatedAverage

type TBsCalculatedAverage = {
  date: Date,
  average: number,
  entities: TBsCalculated[]
}

TEuro

type TEuro = {
  title: string;
  euro: number;
  updatedDate: string;
  image?: string;
  difference?: number;
  differencePercentage?: string;
  tendency?: string;
  tendencyColor?: string;
}

TEuroEntity

type TEntity = {
  entity: string
  info: TEuro
}

TEuroAverage

type TEuroAverage = {
  date: Date;
  average: number;
  entities: TEuroEntity[];
}

TEuroCalculated

type TEuroCalculated = {
  entity: string;
  info: TEuro;
  euroCalculated: number;
}

TBsEuroCalculated

type TBsEuroCalculated = {
  entity: string;
  info: TEuro;
  bolivarCalculated: number;
}

TEuroCalculatedAverage

type TEuroCalculatedAverage = {
  date: Date;
  average: number;
  entities: TEuroCalculated[];
}

TBsEuroCalculatedAverage

type TBsEuroCalculatedAverage = {
  date: Date;
  average: number;
  entities: TBsEuroCalculated[];
}

API Reference

The package is also deployed and works as an API for those users who do not want to or cannot incorporate it into their projects as a dependency.

To access the API they should use the path https://venecodollar.vercel.app/api/v2.

Likewise, you can access the documentation made in swagger for the project located here venecodollar API documentation.

Get all entities with dollar prices

  GET /api/v2/dollar

This endpoint allows obtaining all the dollar monitoring entities with their respective name and last update date, as well as an average of all the active entities (i.e., those with a dollar value greater than zero).

Get all entities with euro prices

  GET /api/v2/euro

This endpoint allows obtaining all the euro monitoring entities with their respective name and last update date, as well as an average of all the active entities (i.e., those with a euro value greater than zero).

Get entities by name with dollar prices

  GET /api/v2/dollar/entity?name=${name}

Parameter	Type	Description
`name`	`string`	Required. Name of entitites to fetch

This endpoint allows to obtain all the monitoring entities of the dollar by the name provided in the path parameter. If the name provided matches more than one entity, the endpoint returns an average of the values given by the entities and the information for each of these entities. If the name provided matches only one entity, the endpoint will return the information for that entity only.

Get entities by name with euro prices

  GET /api/v2/euro/entity?name=${name}

Parameter	Type	Description
`name`	`string`	Required. Name of entitites to fetch

This endpoint allows to obtain all the monitoring entities of the euro by the name provided in the path parameter. If the name provided matches more than one entity, the endpoint returns an average of the values given by the entities and the information for each of these entities. If the name provided matches only one entity, the endpoint will return the information for that entity only.

Calculate Bs with dollar param

  GET /api/v2/dollar/toBs?dollar=${dollar}&entity={entity}

Parameter	Type	Description
`dollar`	`number`	Required. Amount in dollars to be calculated in bolivars.
`entity`	`string`	Name of entities to fetch

This endpoint allows obtaining all the dollar monitoring entities while calculating the value of the dollar passed as a parameter in the path in terms of bolivars. If the name of an entity to be filtered by is passed as a parameter in the path, the endpoint will return only the dollar monitoring entities that match the parameter passed.

Calculate Bs with euro param

  GET /api/v2/euro/toBs?euro=${euro}&entity={entity}

Parameter	Type	Description
`euro`	`number`	Required. Amount in euros to be calculated in bolivars.
`entity`	`string`	Name of entities to fetch

This endpoint allows obtaining all the euro monitoring entities while calculating the value of the euro passed as a parameter in the path in terms of bolivars. If the name of an entity to be filtered by is passed as a parameter in the path, the endpoint will return only the dollar monitoring entities that match the parameter passed.

Calculate Dollar with bolivars param

  GET /api/v2/dollar/toDollar?bs=${bs}&entity={entity}

Parameter	Type	Description
`bs`	`number`	Required. Amount in bolivars to be calculated in dollars.
`entity`	`string`	Name of entities to fetch