https://github.com/futurestudio/fixer-node
Node.js library to access the fixer.io API for currency conversion and exchange rates
https://github.com/futurestudio/fixer-node
currency-conversion exchange-rate fixer fixer-node future-studio-university request-exchange-rates
Last synced: 10 months ago
JSON representation
Node.js library to access the fixer.io API for currency conversion and exchange rates
- Host: GitHub
- URL: https://github.com/futurestudio/fixer-node
- Owner: futurestudio
- License: mit
- Created: 2018-05-04T09:13:08.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-08-09T09:43:14.000Z (over 1 year ago)
- Last Synced: 2024-08-11T12:17:04.146Z (over 1 year ago)
- Topics: currency-conversion, exchange-rate, fixer, fixer-node, future-studio-university, request-exchange-rates
- Language: JavaScript
- Homepage:
- Size: 168 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# fixer-node
A Node.js SDK to interact with the [fixer.io](https://fixer.io) API for currency conversion and exchange rates.
For release notes, see the [CHANGELOG](https://github.com/futurestudio/fixer-node/blob/master/CHANGELOG.md).
------
The Future Studio University supports development of this Node.js library 🚀
Join the Future Studio University and Skyrocket in Node.js
------
## Requirements
> **Node.js v8 (or newer)**
`fixer-node` uses async/await which requires **Node.js v8 or newer**.
## Installation
Add `fixer-node` as a dependency to your project:
```bash
# NPM v5 users, this way is yours
npm i fixer-node
# you’re using NPM v4:
npm i -S fixer-node
```
## Usage
Initialize an instance of `fixer-node` and pass your fixer.io access key as an argument:
```js
const Fixer = require('fixer-node')
const fixer = new Fixer('access-key')
```
### Options
The constructor of `fixer-node` requires an access key as the first argument.
The second argument is an `options` object allowing the following properties:
- `https:` (boolean) set the fixer.io API base URL to either `https` or `http`; default: `http`
```js
const Fixer = require('fixer-node')
const fixer = new Fixer('access-key', {
https: true
})
```
## Error Handling
`fixer-node` throws a custom error instance: [FixerError](https://github.com/futurestudio/fixer-node/blob/master/lib/fixer-error.js).
The `FixerError` contains the fixer.io API related error properties for `info`, `code`, and `type`.
The error message is derived from the `info` property.
```js
const Fixer = require('node-fixer')
const fixer = new Fixer('access-key')
try {
const data = fixer.base({ base: 'USD' })
} catch (err) {
// err.info is the same as err.message,
// e.g. "Your monthly API request volume has been reached. Please upgrade your plan"
const info = err.info
// err.code the fixer.io API code,
// e.g. "201" which represents "An invalid base currency has been entered."
const code = err.code
}
```
Find more details on errors in the [fixer.io API docs](https://fixer.io/documentation#errors).
## API
> aka “how to use this library”
`fixer-node` supports all fixer.io API endpoints. Here’s an overview on how to use the methods.
### Symbols
Request a list of currency symbols.
This is a mapping between the currency shortcut (EUR) and full name (Euro).
```js
const data = await fixer.symbols()
```
### Latest
Request the latest exchange rates.
The `.latest()` method accepts two parameters:
1. `symbols`: (string) a list of symbols you want the exchange rates for (this reduces the response payload)
2. `base`: (string) the base currency
```js
// get the latest rates for all currencies
const latest = await fixer.latest()
// get the latest rates for selected currencies
const latest = await fixer.latest({ symbols: 'EUR, USD, AUD' })
// get the latest rates for selected currencies and base
const latest = await fixer.latest({ symbols: 'EUR, USD', base: 'AUD' })
```
### Base
Request exchange rates for a given base.
```js
// get all rates for a selected base
const base = await fixer.base({ base: 'AUD' })
// get specific rates for a selected base
const base = await fixer.base({ base: 'AUD', symbols: 'USD, EUR' })
```
### Historic
Request historic exchange rates for a given day.
```js
// get exchange rates for May 9th, 2018
const date = await fixer.forDate({ date: '2018-05-09' })
// with symbols
const date = await fixer.forDate({ date: '2018-05-09', symbols: 'USD, EUR, AUD' })
// with symbols and base
const date = await fixer.forDate({ date: '2018-05-09', symbols: 'EUR, AUD', base: 'USD' })
```
### Convert
Convert an amount from one currency to another.
The `.convert()` method is aliased as `fromTo()`.
Use both, `.convert()` and `.fromTo()`, for the same operation.
```js
// 25 from GBP to JPY
const convert = await fixer.convert({ from: 'GBP', to: 'JPY', amount: 25 })
// 25 from GBP to JPY on 2018-05-08
const convert = await fixer.fromTo({ from: 'GBP', to: 'JPY', amount: 25, date: '2018-05-08' })
```
### Time-Series
Historical exchange rates between two dates.
The `.timeseries()` method is aliased as `between()`.
Use both, `.timeseries()` and `.between()`, for the same operation.
```js
// start - end
const timeseries = await fixer.timeseries({
start_date: '2018-05-05',
end_date: '2018-05-08'
})
// start - end with base and symbols
const timeseries = await fixer.between({
start_date: '2018-05-05',
end_date: '2018-05-08',
symbols: 'EUR, USD',
base: 'AUD'
})
```
### Fluctuation
Retrieve information about how currencies fluctuate on a day-to-day basis.
```js
// start - end
const fluctuation = await fixer.fluctuation({
start_date: '2018-05-05',
end_date: '2018-05-08'
})
// start - end with base and symbols
const fluctuation = await fixer.fluctuation({
start_date: '2018-05-05',
end_date: '2018-05-08',
symbols: 'EUR, USD',
base: 'AUD'
})
```
## Feature Requests
Do you miss a feature? Please don’t hesitate to
[create an issue](https://github.com/futurestudio/fixer-node/issues) with a short description of your desired addition to this plugin.
## Links & Resources
- [fixer.io](https://fixer.io): exchange rate and currency conversion
## Contributing
We highly appreciate your pull request and any kind of support!
1. Create a fork
2. Create your feature branch: `git checkout -b my-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request 🚀
## License
MIT © [Future Studio](https://futurestud.io)
---
> [futurestud.io](https://futurestud.io) ·
> GitHub [@futurestudio](https://github.com/futurestudio/) ·
> Twitter [@futurestud_io](https://twitter.com/futurestud_io)