oandapyV20.contrib.factories.InstrumentsCandlesFactory(instrument, params=None)

InstrumentsCandlesFactory - generate InstrumentCandles requests.

InstrumentsCandlesFactory is used to retrieve historical data by automatically generating consecutive requests when the OANDA limit of count records is exceeded.

This is known by calculating the number of candles between from and to. If to is not specified to will be equal to now.

The count parameter is only used to control the number of records to retrieve in a single request.

The includeFirst parameter is forced to make sure that results do no have a 1-record gap between consecutive requests.

  • instrument (string (required)) – the instrument to create the order for
  • params (params (optional)) – the parameters to specify the historical range, see the REST-V20 docs regarding ‘instrument’ at If no params are specified, just a single InstrumentsCandles request will be generated acting the same as if you had just created it directly.


The oandapyV20.API client processes requests as objects. So, downloading large historical batches simply comes down to:

>>> import json
>>> from oandapyV20 import API
>>> from oandapyV20.contrib.factories import InstrumentsCandlesFactory
>>> client = API(access_token=...)
>>> instrument, granularity = "EUR_USD", "M15"
>>> _from = "2017-01-01T00:00:00Z"
>>> params = {
...    "from": _from,
...    "granularity": granularity,
...    "count": 2500,
... }
>>> with open("/tmp/{}.{}".format(instrument, granularity), "w") as OUT:
>>>     # The factory returns a generator generating consecutive
>>>     # requests to retrieve full history from date 'from' till 'to'
>>>     for r in InstrumentsCandlesFactory(instrument=instrument,
...                                        params=params)
>>>         client.request(r)
>>>         OUT.write(json.dumps(r.response.get('candles'), indent=2))


Normally you can’t combine from, to and count. When count specified, it is used to calculate the gap between to and from. The params passed to the generated request itself does contain the count parameter.