oanda-exchange-rates

OANDA Exchange Rates API client module for NodeJS

This module provides a simple wrapper around the OANDA Exchange Rates API using NodeJS. Go to the API documentation page for a full reference of all the methods. This service requires you to sign up for a trial or paying subscription to obtain an API key.

Installation
Usage
- Class: OANDAExchangeRates
Tests
Author
Copyright and License
Release History

Installation

npm install oanda-exchange-rates --save

Usage

var api = require('oanda-exchange-rates');
 
var client = new api({
    api_key: 'my_api_key'
});
 
client.getCurrencies('oanda', function(response) {
    if (response.success) {
        console.log('USD=', response.data['USD']);
    } else {
        console.log('error(', response.errorCode, ')', response.errorMessage);
    }
});
 
client.getRates('USD', function(response) {
    if (response.success) {
        console.log('daily average USD/GBP:', response.data.quotes.GBP.midpoint);
    } else {
        console.log('error(', response.errorCode, ')', response.errorMessage);
    }
});
 
client.getRates({ base: 'EUR', quote: 'CAD', date: '2014-01-01' }, function(response) {
    if (response.success) {
        console.log('daily average EUR/CAD on Jan 1st 2014:', response.data.quotes.CAD.midpoint);
    } else {
        console.log('error(', response.errorCode, ')', response.errorMessage);
    }
});
 
client.getRemainingQuotes(function(response) {
    if (response.success) {
        console.log('Can call getRates()', response.data.remaining_quotes, 'time(s)');
    } else {
        console.log('error(', response.errorCode, ')', response.errorMessage);
    }
});

If successful, will output:

USD=US Dollar
Daily average USD/GBP: 0.60365
Daily average EUR/CAD on Jan 1st 2014: 1.46537
Can call getRates() 100000 time(s)

If not, for example:

error(8) Malformed Authorization header or invalid access token

Class: OANDAExchangeRates

All API methods return a Response object that provides access to the state of the response and has deserialized the JSON data into a native Javascript object.

new OANDAExchangeRates(options)

The constructor for the API wrapper. Other than api_key all other parameters are optional.

options:
- api_key
  
  required: the API key provided by the service
- proxy
```
  proxy: 'http://your.proxy.com:8080/'
```
  If you access the service behind a proxy, you can provide it. This sets the proxy for the underlying HTTP client. Similarly, if the http_proxy environment variable is set with the proxy, it will be use automatically.

client.getCurencies([data_set], [callback])

Returns the /v1/currencies.json endpoint; a hash of valid currency codes.

Note: the endpoint usually returns an array of hashes which contain code and description keys but getCurrencies() massages them into a hash with the code as a key and description has the value.

The Javascript object returned by response.data will look something like this:

{
    CAD: 'Canadian Dollar',
    EUR: 'Euro',
    USD: 'US Dollar',
    ...
}

data_set:

Indicates which of the OANDA currency list or the European Central Bank currency list to query. Valid values are 'oanda' or 'ecb'

**DEFAULT:** 'oanda'

client.getRates(options, [callback])

Returns the /v1/rates/XXX.json endpoint; a list of quotes for a specific base currency.

This is the core of the API and provides daily averages, highs, lows and idpoints for a each cross of currencies.

The Javascript object returned by response.data will look something like this --- Please see the OANDA Exchange Rates API Docs for a detailed breakdown:

{
  "quotes": {
    "GBP": {
      "midpoint": "0.60365",
      "low_bid": "0.60360",
      "low_ask": "0.60369",
      "high_bid": "0.60360",
      "high_ask": "0.60369",
      "date": "2014-01-01T21:00:00+0000",
      "bid": "0.60360",
      "ask": "0.60369"
    },
    "EUR": {
      "midpoint": "0.72527",
      "low_bid": "0.72522",
      "low_ask": "0.72533",
      "high_bid": "0.72522",
      "high_ask": "0.72533",
      "date": "2014-01-01T21:00:00+0000",
      "bid": "0.72522",
      "ask": "0.72533"
    }
  },
  "meta": {
    "skipped_currencies": [],
    "request_time": "2014-05-06T19:23:14+0000",
    "effective_params": {
      "quote_currencies": [
        "EUR",
        "GBP"
      ],
      "fields": [
        "averages",
        "highs",
        "lows",
        "midpoint"
      ],
      "decimal_places": 5,
      "date": "2014-01-01"
    }
  },
  "base_currency": "USD"
}

options can either be an object or a string. If options is a string it will be used as the base currency parameter.

options:
- base
  
  REQUIRED - The base currency that all quotes are crossed against. Must be a valid 3 letter upper case currency code as provided by /v1/currencies.json endpoint.
```
  base: 'USD'
```
- quote
  
  A single currency code, or an array of currency codes to cross against the base currency.
  
  DEFAULT: All other available currencies.
```
  quote: 'EUR'
  quote: [ 'EUR', 'GBP', 'CHF' ]
```
- data_set
  
  Indicates which of the OANDA rate or the European Central Bank rate to query. Valid values are 'oanda' or 'ecb'
  
  DEFAULT: 'oanda'
- decimal_places
  
  The number of decimal places to provide in the quote. May be a positive integer of reasonable size (as of this writing, up to 14) or the string "all". Quotes that are requested with more precision than exist are padded out with zero's.
  
  DEFAULT: 5
```
  decimal_places: 'all'
```
- fields
  
  Which fields to return in the quotes. These can currently be:
  - averages - the bid and ask
  - midpoint - the midpoint between the bid and ask
  - highs - the highest bid and ask
  - lows - the lowest bid and ask
  - all - all of the above
  DEFAULT: averages
- date
  
  The requested date for the quotes. This must be in YYYY-MM-DD format. The 24 hour period of the date is considered to be that period in UTC.
  
  DEFAULT: The most recent quote
```
  date: '2014-02-01'
```
- start, end
  
  This allows you to specify a date range. Also in YYYY-MM-DD format. When requesting a date range, quotes are modified such that:
  - averages (bid and ask) are the average of the daily values over the date range
  - midpoint (midpoint) is the midpoint between those averages
  - highs (high_ask and high_bid) are the highest values over the range
  - lows (low_ask and low_bid) are the lowest values over the range
  Specifying no end will assume today's date as the end point. Date ranges are inclusive (they include all quotes on and between start and end).
  
  DEFAULT: none
```
  start: '2014-01-01',
  end: '2014-01-31'
```

client.getRemainingQuotes([callback])

Returns the /v1/remaining_quotes.json endpoint; the number of quote requests available in the current billing period.

Some plans are limited to a specific number of quotes per billing period. This endpoint can be used to determine how many quotes you have left.

The Javascript object returned by response.data will look something like this:

{
  remaining_quotes: 100000
}

For plans that have no quote limits, remaining_quotes will equal "unlimited".

Class: Response

This object is returned by any API method called in OANDAExchangeRates. It automatically deserializes the data into a native Javascript object and provides information about the response.

Fields:
- data
  
  Contains the deserialized Javascript object of the API
- errorCode
  
  If the request failed due to an API error, contains the error code of the problem (see also List of Errors) If the request failed due to a network error (connection lost, malformed JSON data), it will not be set
- errorMessage
  
  If the request failed, contains a description of the problem
- statusCode
  
  HTTP status code
- raw
  
  Contains the raw serialized JSON data returned by the API
- success
  
  Boolean flag indicating whether the request was successful or not

Tests

npm test

Author

Jerome Lecomte <jerome@oanda.com>

Copyright and License

Release History

0.2.0 - June 27 - Add 'data_set' parameter to getCurrencies() and getRates()
0.1.0 - May 7 - Initial release

oanda-exchange-rates