Rates Endpoints

Endpoints to access rates are in the format:

https://www.oanda.com/rates/api/v2/rates/:endpoint.:output_format?base=:base_currency[&parameter=value…]

URL Components

endpoint

Five endpoints are allowed for querying real-time, historical or forward exchange rates:

Real-time or historical exchange rates
  • spot – Retrieves the current exchange rate, or the rate at a specified point in time
    • Required parameters: base
    • Optional parameters: quote, date_time, data_set
  • candle – Retrieves one daily candle for each specified currency pair
    • Required parameters: base
    • Optional parameters: quote, date_time, fields, data_set
  • candles – Retrieves all daily candles in the specified time range
    • Required parameters: base, start_time, end_time
    • Optional parameters: quote, fields, data_set
  • aggregated – Retrieves one aggregated candle over the given time range for each specified currency pair
    • Required parameters: base, start_time, end_time
    • Optional parameters: quote, fields, data_set

NOTE: Access to the spot, aggregated endpoints may require an account upgrade. Contact our Customer Experience Team at fxdata@oanda.com to confirm your subscription details.

Forward exchange rates
  • forward – Retrieves one forward curve over the given tenor set for the specified currency pair
    • Required parameters: base, quote
    • Optional parameters: tenor, data_set

NOTE: Access to forward endpoints may require an account upgrade. Contact our Customer Experience Team at fxdata@oanda.com to confirm your subscription details.

The examples page has basic examples of each of these endpoints.

Real-time rates and forward rates are only available for OANDA rates. Therefore, for spot and forward endpoints, any value other than “OANDA” will be rejected for data_set parameter.

All endpoints require at least one base currency to be specified, and may require additional parameters as described below. forward endpoint requires exactly one base currency and one quote currency.

All rates prior to January 16th, 2018 reflect Midnight UTC-aligned daily averages. Requested daily average or period average rates after January 16th, 2018 can be adjusted to 15 minute intervals, provided you have Real-time Rates in your Advanced subscription.

output_format

The :output_format URL part determines how information is returned. It can be one of the following values:

  • json – Javascript Object Notation
    • All real numbers in JSON responses are returned as strings to prevent JSON parsers from damaging the precision of the quotes.
  • xml – Well-formed XML document
  • csv – Comma Separated Values
    • Can be imported into most spreadsheet and financial applications
    • Note that CSV format provides standard Unix-like line endings (Unix, Linux, *BSD, MacOS > 9 among others) via an LF character (hex: 0x0A; dec: 10)
    • Due to the limitations of this format, only quotes will be returned, and metadata will be excluded from the output

Parameters

base

At least one base currency is required for all endpoints. Multiple base currencies can be specified by repeating this parameter for spot, candle, candles and aggregated endpoints, and the relation of each base currency will be computed against all specified quote currencies.

The forward endpoint requires exactly one base currency.

All currencies are specified by their three-letter currency code as defined in the currencies endpoint.

quote

For spot, candle, candles and aggregated endpoints, the quote parameter is optional. Multiple quote currencies can be specified by repeating this parameter. If the quote parameter is not found, all available quote currencies will be used, excluding the specified base currency if only one base currency is specified.

The forward endpoint requires exactly one quote currency.

All currencies are specified by their three-letter currency code as defined in the currencies endpoint.

tenor

For forward endpoint, the tenor parameter is optional. Multiple tenors can be specified by repeating this parameter. If the tenor parameter is not found, all supported tenors for the currency pair in the request as defined in supported forwards endpoint will be used.

It is not allowed for spot, candle, candles or aggregated endpoints.

All tenors specified must be supported for the currency pair as defined in the supported forwards endpoint.

start_time / end_time

The start_time and end_time parameters are required for the candles and aggregated endpoints. For the candles endpoint all candles between the start_time and end_time are returned, while the aggregated endpoint will return one aggregated candle per currency pair with rates collected between the start_time and end_time.

All date-time parameters should be in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDThh:mm:ss±hh:mm) and before the current time.

The start_time and end_time must be on a 15-minute boundary, and both must be on the same hour and minute boundary.

There is a limit of 10,000 on the combination of days between start_time and end_time and currency pairs per request. For example, if a request specifies 2 base currencies and 5 quote currencies, its start_time and end_time may not span over 1,000 days. In other words, the product of number of base currencies, number of quote currencies and number of days between start_time and end_time may not exceed 10,000.

NOTE: Access to rates with start_time and end_time not at midnight UTC may require an account upgrade. Contact our Customer Experience Team at fxdata@oanda.com to confirm your subscription details.

date_time

The date_time parameter is optional for the spot and candle endpoints. It is not allowed for the candles and aggregated endpoints. For the spot endpoint the rate at the given date-time will be returned; when this field is not present the real-time spot rate will be returned. For the candle endpoint a candle will be returned that begins at the specified date-time; when this field is not present the most recent candle will be returned.

All date-time parameters should be in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDThh:mm:ss±hh:mm) and before the current time.

If specified, the date_time must be on a 15-minute boundary.

NOTE: Access to rates with date_time not specified or not at midnight UTC may require an account upgrade. Contact our Customer Experience Team at fxdata@oanda.com to confirm your subscription details.

fields

The fields parameter is optional for the candle, candles and aggregated endpoints. For the spot endpoint, the quote fields returned will always be the bid, ask and midpoint, so this parameter is not allowed.

Allowed values are open, close, averages, highs, lows or all, and multiple values can be specified.

NOTE: Access to open and close rates may require an account upgrade. Contact our Customer Experience Team at fxdata@oanda.com to confirm your subscription details.

data_set

The data_set parameter is optional for all endpoints, and determines which data set to query. It can take one of the following values depending on your plan:

  • OANDA – Rates obtained and aggregated by OANDA Corporation
  • EUCB – European Central Bank rates
  • ALCB – Bank of Albania rates
  • ANCB – Central Bank of Curacao and Sint Maarten rates
  • AUCB – Reserve Bank of Australia rates
  • BGCB – Bulgarian National Bank rates
  • BRCB – Banco Central do Brasil rates
  • CACB – Bank of Canada rates
  • CZCB – Czech National Bank rates
  • DKCB – Danmarks Nationalbank rates
  • GHCB – Bank of Ghana rates
  • GYCB – Bank Of Guyana rates
  • HKCB – Treasury Market Association, Hong Kong rates
  • HRCB – Croatian National Bank rates
  • HUCB – Hungarian National Bank rates
  • IDCB – Bank of Indonesia rates
  • INCB – Reserve Bank of India rates
  • ISCB – Central Bank of Iceland rates
  • MXCB – Banco de Mexico rates
  • MYCB – Bank Negara Malaysia rates
  • NOCB – Norges Bank rates
  • PKCB – State Bank of Pakistan rates
  • PLCB – Narodowy Bank Polski rates
  • RSCB – National Bank of Serbia rates
  • VECB-DICOM – The Banco Central de Venezuela rates
  • VNCB – The State Bank of Vietnam rates

If the data_set parameter is not found, OANDA rates will be returned.

When a Central Bank is specified as the data_set:

  • The spot and forward endpoints are not allowed.
  • For candle, candles and aggregated endpoints, date-time fields should be midnight aligned.

NOTE: Access to Central Bank rates may require an account upgrade. Contact our Customer Experience Team at fxdata@oanda.com to confirm your subscription details.

Response Fields

Some response information differs between the endpoints. See the examples page for more information.

Meta Data

Meta data for the request is only returned when json or xml are specified for the output format. it is returned as the field ‘meta’, which contains a structure with the following fields:

effective_params

The effective_params field contains information on how the API interpreted the parameters in the request. Parameters may or may not be present depending on the allowed parameters for an endpoint.

endpoint

The endpoint that the server interpreted based on the specification above.

request_time

The timestamp that the server processed the request.

skipped_currency_pairs

A list of currency pairs that had no data for the request to spot, candle, candles and aggregated endpoints. This is dependent on both the date-time and the fields specified in the request, because some currency pairs do not have data for all fields at all date-times.

skipped_tenors

A list of tenors that had no data for the forward rates request. This will be present in the forward endpoint to include any specified tenor for which there are no data.

Quotes

The quotes field contains a list of all the data objects returned for the request.

For spot, candle, candles and aggregated endpoints, quotes are ordered by the base_currency, quote_currency alphabetically, both of which are present in all quotes, and finally any applicable date-time fields.

For forward endpoints, quotes are ordered by tenor on their duration. Fields present in each quote are dependent on the endpoint and request type, and are described below.

Real-time Spot Rates

When the spot endpoint is requested without a date_time parameter, real-time spot rates are returned. These quotes contain bid, ask, and midpoint fields, but no other information.

Historical Spot Rates

When the spot endpoint is requested with a date_time parameter, the derived date_time is included in each quote.

Candles

For both the candle and candles endpoints, a list of candles will be returned. All candles have the following date-time fields:

  • start_time – For the candle endpoint this will be the same as the requested date_time while for the candles endpoint this will either be the same as the requested start_time or some days later.
  • open_time – The recorded open that the data was collected
  • close_time – The recorded close that the data was collected

NOTE: The open_time and close_time of the candle may be earlier than the start_time and end_time requested because the data may have been collected at an earlier date and applied to later candles.

Other fields in each candle are dependent on the requested fields parameter.

Aggregated Candles

For the aggregated endpoint, a list of candles will be returned with slightly different date-time fields:

  • start_time – The effective start of the candle
  • end_time – The effective end of the candle

These values may be different than the requested start_time and end_time based on the data available.

All returned date-times are formatted using ISO 8601 and in the UTC timezone. All returned rates are rounded to six significant digits.

Forward Rates

For the forward endpoints, a list of forward rates will be returned containing the following fields:

  • tenor – The tenor code of the forward rates
  • spot_bid – The bid price of the spot rates
  • spot_ask – The ask price of the spot rates
  • spot_midpoint – The midpoint price of the spot rates
  • forward_points_bid – The forward points on the bid price
  • forward_points_ask – The forward points on the ask price