Node.js API reference — getHistoricalRates config

import { getHistoricalRates } from 'dukascopy-node';

const data = await getHistoricalRates({
  instrument: 'eurusd',
  dates: { from: '2024-01-01', to: '2024-02-01' },
  timeframe: 'h1',
  format: 'json'
});

Functions

getHistoricalRates(config)

Downloads historical data and resolves with the whole result. The return type depends on format and timeframe: an array of candles or ticks, or a CSV string. It rejects if the config is invalid or a request fails after all retries.

getRealTimeRates(config)

Fetches the most recent ticks or candles, including the period still in progress. Takes instrument, timeframe, format, priceType, volumes, and either last or dates. See real-time data.

Data

`instrument`

Required InstrumentType

Instrument id, for example eurusd, btcusd or aaplususd. Find ids on the instruments page.

CLI: -i, --instrument <value>

`dates.from`

Required Date | string | number

Start of the range (inclusive): a Date, a date string such as 2021-03-04 or 2021-03-04T10:30:00Z, or a Unix timestamp in milliseconds. Dates before the instrument’s earliest available data are moved forward to it.

CLI: -from, --date-from <value>

`dates.to`

Required Date | string | number

End of the range (exclusive), in the same formats as dates.from. Future dates are clamped to the current time.

CLI: -to, --date-to <value>

`timeframe`

TimeframeType

Aggregation of the data: tick, s1, m1, m5, m15, m30, h1, h4, d1 or mn1. See timeframes.

Default: 'd1'
CLI: -t, --timeframe <value>

`priceType`

'bid' | 'ask'

Side of the market used for candles: bid or ask. Ignored for tick, which always includes both.

Default: 'bid'
CLI: -p, --price-type <value>

`utcOffset`

number

Shifts both ends of the requested range by this many minutes. Output timestamps stay in UTC; to convert them, see time zones.

Default: 0
CLI: -utc, --utc-offset <value>

Output

`format`

'array' | 'json' | 'csv'

Output format: array, json or csv. See output formats.

Default: 'array'
CLI: -f, --format <value>

`volumes`

boolean

Include volume columns in the output.

Default: true
CLI: -v, --volumes

`volumeUnits`

'millions' | 'thousands' | 'units'

Unit of volume values: millions, thousands or units.

Default: 'millions'
CLI: -vu, --volume-units <value>

`ignoreFlats`

boolean

Skip candles with zero volume (flats), typically weekends and market holidays.

Default: true
CLI: -fl, --flats

Batching and rate limits

`batchSize`

number

Number of requests sent concurrently in one batch.

Default: 10
CLI: -bs, --batch-size <value>

`pauseBetweenBatchesMs`

number

Pause between batches, in milliseconds. Skipped when a whole batch is served from the cache.

Default: 1000
CLI: -bp, --batch-pause <value>

`requestIntervalMs`

number

Minimum time between individual requests, in milliseconds. 0 keeps the requests of a batch concurrent.

Default: 0
CLI: --request-interval <ms>

`rateLimitRetryCount`

number

Retries after HTTP 429 (Too Many Requests), separate from regular retries. Waits back off exponentially and honour Retry-After.

Default: 3
CLI: --rate-limit-retries <count>

Retries

`retryCount`

number

Number of retries for a failed request. 0 disables retries. Refused requests (HTTP 403) are never retried.

Default: 0
CLI: -r, --retries <value>

`pauseBetweenRetriesMs`

number

Pause between retries, in milliseconds.

Default: 500
CLI: -rp, --retry-pause <value>

`retryOnEmpty`

boolean

Treat successful responses with an empty dataset as failed attempts, so they are retried.

Default: false
CLI: -re, --retry-on-empty

`failAfterRetryCount`

boolean

Throw when a request still fails after all attempts. Set to false to skip the failed period and continue, also when retryCount is 0.

Default: true
CLI: -fr, --no-fail-after-retries

Cache

`useCache`

boolean

Store completed periods on disk and read them from there on later runs. Periods that are still changing, such as the current hour or day, are always fetched.

Default: false
CLI: -ch, --cache

`cacheFolderPath`

string

Folder for cached data, relative to the working directory.

Default: '.dukascopy-cache'
CLI: -chpath, --cache-path <value>

Full example

The options above with their default values, except instrument and dates:

const data = await getHistoricalRates({
  instrument: 'btcusd',
  dates: { from: '2024-01-01', to: '2024-02-01' },
  timeframe: 'd1',
  priceType: 'bid',
  utcOffset: 0,
  format: 'array',
  volumes: true,
  volumeUnits: 'millions',
  ignoreFlats: true,
  batchSize: 10,
  pauseBetweenBatchesMs: 1000,
  requestIntervalMs: 0,
  rateLimitRetryCount: 3,
  retryCount: 0,
  pauseBetweenRetriesMs: 500,
  retryOnEmpty: false,
  failAfterRetryCount: true,
  useCache: false,
  cacheFolderPath: '' // '' means ./.dukascopy-cache
});

Other exports

Export	Description
`RateLimitError`, `DukascopyAccessDeniedError`	Error classes for rate limits and refused access. See errors.
`instrumentMetaData`	Name, description and earliest data of every instrument.
`Instrument`, `Timeframe`, `Format`, `Price`	String enums of allowed values.
`defaultConfig`	The default value of every option.
`getHistoricRates`, `getCurrentRates`	Aliases of `getHistoricalRates` (deprecated) and `getRealTimeRates`.