Rates


Use the Rates endpoint to get the quotes for one or more currency pairs. If applicable, the number of quotes returned is charged against the quote limit for your plan.

You may request quotes for a single date, or as an average over a date range. If your plan has a quote limit, each response will include the X-Rate-Limit-Remaining header containing the number of remaining quotes available for the current billing period.

GET /v1/rates/:base_currency.:output_format

:base_currency: The base currency for all currency pairs in the request

  • format: (string) An upper case 3 letter currency code as defined in the Currencies endpoint
  • REQUIRED
  • example: USD, EUR, CAD

:output_format – The serialization format of the output

  • format: (string) One of json, xml, or csv
  • REQUIRED
  • See API Endpoints

Input Query Parameters

All query parameters are optional and the default for each is noted

quote – A quote currency to cross with the :base_currency

  • format: (string) An upper case 3 letter currency code as defined by the Currencies endpoint
  • default: All available currencies (less the :base_currency) as defined by the Currencies endpoint
  • Can be specified multiple times
    • e.g. /v1/rates/USD.json?quote=EUR&quote=CHF&quote=GBP
  • This parameter controls the number of quotes that are charged against your quote limit. Each quote currency returned by the API counts against your quote limit
    • Note that if you do not specify a quote parameter (i.e. the default option), multiple quotes are returned and counted against your quote limit. You may assume that no more than about 200 quotes will be returned per API call.
  • example: To request the latest USD/EUR and USD/CAD exchange rates curl -X GET "https://web-services.oanda.com/rates/api/v1/rates/USD.json?quote=EUR&quote=CAD"

fields – A list of quote values to return

  • format: (string) – Any of averages, midpoint, highs, lows or all
    • Can be specified multiple times
    • fields=all is the equivalent of fields=averages&fields=midpoint&fields=highs&fields=lows
    • averages: The average (mean) bid and ask quotes for the period (bid and ask)
      • If the period is one day, these are the average (mean) daily bid and ask quotes on that day
      • If the period is a date range, these are the average (mean) bid and ask quotes over that date range. The date range average is calculated using the average daily bid and ask quotes
    • midpoint: The midpoint of the bid and ask quotes (midpoint)
      • In a date range request, this is the midpoint between the date range average bid and ask quotes.
      • NOTE: The midpoint is always rounded to the same level of precision as the bid and ask quotes. Thus, an ask of 1.7533 and a bid of 1.7522 would have a midpoint of 1.7528 and not 1.75275
    • highs: The high bid and ask for the period (high_bid and high_ask)
      • In a date range request, these are the highest (maximum) high_bid and high_ask over that range
    • lows: The low bid and ask quotes for the period (low_bid and low_ask)
      • In a date range request, these are the lowest (minimum) low_bid and low_ask quotes over that range
  • default: averages
  • example: request the latest averages and midpoint for EUR/USD curl -X GET "https://web-services.oanda.com/rates/api/v1/rates/EUR.json?quote=USD&fields=averages&fields=midpoint"

data_set – Which dataset to query

  • format: (string) – OANDA or one of the supported central bank codes (see API Endpoints for complete list)
  • default: OANDA
  • NOTE: The Central Bank exchange rates consist of a single spot rate. As such, the fields parameter will be ignored when data_set is set to any of central bank codes
  • example: Request the latest EUR/USD European Central Bank exchange rate curl -X GET "https://web-services.oanda.com/rates/api/v1/rates/EUR.json?quote=USD&data_set=EUCB"

decimal_places – Number of decimal places to return in the quote output

  • format: ( integer | string ) an integer from 1 to 15 or all
    • Some currency pairs have fewer stored decimal places than is requested in this parameter. For those currency pairs, the quotes returned are padded with zeroes to match the number of decimal places requested.
    • You may request the maximum number of stored decimal places for a currency pair by specifying all. If multiple quote currencies are requested, the precision for each pair may vary.
  • default: 5
  • example: Request the latest EUR/USD quote rounded to 4 decimal places curl -X GET "https://web-services.oanda.com/rates/api/v1/rates/USD.json?quote=EUR&decimal_places=4"

date – A specific quote date

  • format: (string) In the format YYYY-MM-DD
    • Dates are interpreted in UTC time zone
    • Date specified must be less than or equivalent to today’s date
  • default: The current day (UTC time zone)
  • NOTE: Omitting this paramter or specifying today’s date returns the latest quotes available. If today’s quotes exist, they are returned, otherwise the API returns the latest quotes available.
  • The date parameter is ignored if start and end are used to request a date range
  • example: request EUR/USD for January 1, 2014 curl -X GET "https://web-services.oanda.com/rates/api/v1/rates/EUR.json?quote=USD&date=2014-01-01"

start and end – Start and end dates for calculating average quotes over a date range

  • format: (string) In the format YYYY-MM-DD
    • Dates are interpreted in UTC time zone
    • Must be less than or equivalent to today’s date
    • If start is specified but not end, then end is assumed to be the current day
    • If end is specified but not start or if start comes after end, an error is generated
    • Identical start and end values are equivalent to a single date parameter value
  • default: None; the absence of start and end or a date values returns the latest quotes available
  • example: Request the average bid and ask for EUR/USD for the month of January, 2014 curl -X GET "https://web-services.oanda.com/rates/api/v1/rates/EUR.json?quote=USD&start=2014-01-01&end=2014-01-31"
  • See the Date Ranges section for information on how the quotes returned differ from a regular date request
  • See the Specifications & Caveats section for information on restriction at the date range determined by start and end.

Responses

If your plan has a quote limit, all responses from the Rates endpoint will also include the X-Rate-Limit-Remaining HTTP header. The header’s value is the number of quotes remaining for the current billing period. This value is also available from the Remaing Quotes endpoint.

The following examples show the output for a request of all fields for USD/EUR and USD/GBP for January 1, 2014.

JSON

Request:

GET /v1/rates/USD.json?quote=EUR&quote=GBP&date=2014-01-01&fields=all

Response headers & body:

1
2
3
HTTP/1.1 200 OK
Content-Type: application/json
X-Rate-Limit-Remaining: 100000
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
   "base_currency" : "USD",
   "meta" : {
      "effective_params" : {
         "data_set": "OANDA",
         "date" : "2014-01-01",
         "decimal_places" : "5",
         "fields" : [
            "averages",
            "highs",
            "lows",
            "midpoint"
         ],
         "quote_currencies" : [
            "EUR",
            "GBP"
         ],
      },
      "request_time" : "2017-06-02T20:08:29+0000",
      "skipped_currencies" : []
   },
   "quotes" : {
      "EUR" : {
         "ask" : "0.72533",
         "bid" : "0.72522",
         "date" : "2014-01-01T21:00:00+0000",
         "high_ask" : "0.72533",
         "high_bid" : "0.72522",
         "low_ask" : "0.72533",
         "low_bid" : "0.72522",
         "midpoint" : "0.72528"
      },
      "GBP" : {
         "ask" : "0.60369",
         "bid" : "0.60360",
         "date" : "2014-01-01T21:00:00+0000",
         "high_ask" : "0.60369",
         "high_bid" : "0.60360",
         "low_ask" : "0.60369",
         "low_bid" : "0.60360",
         "midpoint" : "0.60364"
      }
   }
}

XML

Request:

GET /v1/rates/USD.xml?quote=EUR&quote=GBP&date=2014-01-01&fields=all

Response headers & body:

1
2
3
HTTP/1.1 200 OK
Content-Type: application/xml
X-Rate-Limit-Remaining: 100000
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
<response>
  <base_currency>USD</base_currency>
  <meta>
    <effective_params>
      <data_set>OANDA</data_set>
      <date>2014-01-01</date>
      <decimal_places>5</decimal_places>
      <fields>
        <field>averages</field>
        <field>highs</field>
        <field>lows</field>
        <field>midpoint</field>
      </fields>
      <quote_currencies>
        <currency>EUR</currency>
        <currency>GBP</currency>
      </quote_currencies>
    </effective_params>
    <skipped_currencies>
      <currency>...</currency>
    </skipped_currencies>
    <request_time>2017-06-02T20:12:43+0000</request_time>
  </meta>
  <quotes>
    <quote>
      <ask>0.60369</ask>
      <bid>0.60360</bid>
      <currency>GBP</currency>
      <date>2014-01-01T21:00:00+0000</date>
      <high_ask>0.60369</high_ask>
      <high_bid>0.60360</high_bid>
      <low_ask>0.60369</low_ask>
      <low_bid>0.60360</low_bid>
      <midpoint>0.60364</midpoint>
    </quote>
    <quote>
      <ask>0.72533</ask>
      <bid>0.72522</bid>
      <currency>EUR</currency>
      <date>2014-01-01T21:00:00+0000</date>
      <high_ask>0.72533</high_ask>
      <high_bid>0.72522</high_bid>
      <low_ask>0.72533</low_ask>
      <low_bid>0.72522</low_bid>
      <midpoint>0.72528</midpoint>
    </quote>
  </quotes>
</response>

CSV

Request:

GET /v1/rates/USD.csv?quote=EUR&quote=GBP&date=2014-01-01&fields=all

Response headers & body:

1
2
3
HTTP/1.1 200 OK
Content-Type: text/plain
X-Rate-Limit-Remaining: 100000
1
2
3
base_currency,currency,date,bid,ask,midpoint,high_bid,high_ask,low_bid,low_ask
USD,EUR,2014-01-01T21:00:00+0000,0.72522,0.72533,0.72528,0.72522,0.72533,0.72522,0.72533
USD,GBP,2014-01-01T21:00:00+0000,0.60360,0.60369,0.60364,0.60360,0.60369,0.60360,0.60369

Response Fields

Note: The meta section is not returned as part of CSV responses.

meta – (JSON | XML) Metadata on the original request

  • effective_params – (JSON | XML) A list of the effective query parameters made after normalizing the input and applying defaults
  • request_time – (JSON | XML) The UTC date and time that this request was made
    • This is helpful when reporting problems to OANDA on the availability of data
  • skipped_currencies – (JSON | XML) A list of currencies that were skipped due to the abscence of data for the requested date or date range

base_currency – (ALL) The three character base currency code requested

quotes – (JSON | XML) The container for all quotes returned by a request

  • currency – (XML | CSV) The three character quote currency for a quote in the quotes container
    • (JSON) The currency is the key to the object containing the quote
  • date – (ALL) The UTC date and time when this quote was generated
    • NOTE: Certain currency pairs, especially those containing exotic or emerging currencies, do not update daily. For requests containing those currency pairs, the API returns the most recent quote. This may result in the same quote being returned over several consecutive days.
  • bid and ask – (ALL) The average (mean) bid and ask quotes on the requested date
  • spot – (ALL) The spot rate when using Central Bank dataset
  • midpoint – (ALL) The midpoint between the bid and ask quotes
  • high_bid and high_ask – (ALL) The highest bid and ask quotes for the requested date
  • low_bid and low_ask – (ALL) The lowest bid and ask quotes for the requested date

Date Ranges

When a date range is specified using start and end the returned quotes are slightly different:

  • bid and ask – The average (mean) bid and ask quotes over the date range. The date range average is calculated using the average daily bid and ask quotes over the entire date range, including the start and end dates
  • spot – For Central Bank exchange rates only. The average (mean) spot rate over the date range. This is calculated just as bid and ask are.
  • midpoint – The midpoint between the date range average bid and ask quotes. It is NOT the average of all midpoints
  • high_bid and high_ask – The highest (maximum) high_bid and high_ask values in the range
  • low_ask and low_bid – The lowest (minimum) low_bid and low_ask values in the range

Specifications & Caveats

This section discusses some of the API specifications and how the API handles a number of special cases:

  • Rates are updated and posted daily at 22:00 ET.
  • All requested and returned dates and times are UTC.
  • Rates are rounded half to even when requesting less number of decimal places than we have.
  • The Central Bank exchange rates consist solely of a spot price. As such, the fields option will be ignored when requesting Central Bank exchange rates.
  • Quotes availability on certain date of certain currency pair varies on data set. You may check the Currencies endpoint to see what is available for certain data set.
    • When quotes are absent for one or more currencies on specified date or date range, the API will return quotes for only the currency pairs that have data available. For example, if you pass a date that is before January 1, 1999, the API will not return any EUR currency pairs.
    • Please note that quotes that are not returned by the API are not counted against your quote limit.
    • If you do not see the rates you are looking for, please contact us at fxdata@oanda.com.
  • If your API request specifies the highs and lows fields (i.e.high_bid, high_ask, low_bid, low_ask):
    • These fields are only available for instruments that trade on OANDA’s fxTrade platform
    • If these fields are requested and are not available, they are omitted from the results. If the output format is JSON or XML the fields are not included in the quote. If the output format is CSV, the columns corresponding to these fields are left empty
    • If only highs and/or lows are requested, and there are no quotes for a particular quote currency, the quote is omitted from the response. If this results in all quotes being omitted, an error will be thrown
  • date is omitted from a quote response when a date range is requested as the quotes returned are calculated on-the-fly and not stored by the API
  • Not all currency pairs are updated daily. For those currency pairs, requesting a particular date’s quote returns the most recent quote prior or equal to that day.
  • If you specify a date range, there is a limit of 10,000 on the number of days in the range combining with the number of quote currencies per request. For example, if a request specifies 10 quote currencies, its start and end date may not span over 1,000 days. In other words, the product of number of quote currencies and number of days between start and end may not exceed 10,000.