Skip to content
dukascopy-node

Date formats and time zones

Format dukascopy-node timestamps as readable dates or ISO strings, and convert them to any time zone, from the CLI and from Node.js.

By default every timestamp is a Unix epoch time in milliseconds, in UTC, for example 1707782400000 for 2024-02-13 00:00 UTC. Numbers are compact and unambiguous, but the CLI can also write readable dates.

Formatting dates in the CLI

Section titled “Formatting dates in the CLI”

Pass a Day.js format string with --date-format (-df):

Terminal window
npx dukascopy-node -i eurusd -from 2024-02-13 -to 2024-02-15 -t m1 -f csv \
  --date-format "YYYY-MM-DD HH:mm:ss"
Output
timestamp,open,high,low,close
2024-02-13 00:00:00,1.07718,1.07725,1.07718,1.07723
2024-02-13 00:01:00,1.07724,1.07726,1.07723,1.07726
2024-02-13 00:02:00,1.07727,1.07727,1.07722,1.07722

Some useful formats:

Format Example
YYYY-MM-DD 2024-02-13
YYYY-MM-DD HH:mm 2024-02-13 00:00
YYYY-MM-DD HH:mm:ss 2024-02-13 00:00:00
YYYY-MM-DD HH:mm:ss.SSS 2024-02-13 00:00:00.000
YYYY-MM-DD HH:mm:ss.SSSZ 2024-02-13 00:00:00.000+00:00
DD/MM/YYYY HH:mm 13/02/2024 00:00

ISO 8601

Section titled “ISO 8601”

Use iso for ISO 8601 timestamps in UTC:

Terminal window
npx dukascopy-node -i eurusd -from 2024-02-13 -to 2024-02-15 -t m1 -f csv --date-format iso
Output
timestamp,open,high,low,close
2024-02-13T00:00:00.000Z,1.07718,1.07725,1.07718,1.07723
2024-02-13T00:01:00.000Z,1.07724,1.07726,1.07723,1.07726

Converting to a time zone in the CLI

Section titled “Converting to a time zone in the CLI”

Add --time-zone (-tz) with an IANA time zone name to write dates in that zone. It works together with --date-format:

Terminal window
npx dukascopy-node -i eurusd -from 2024-02-13 -to 2024-02-15 -t m1 -f csv \
  --date-format "YYYY-MM-DD HH:mm" --time-zone Europe/Kyiv
Output
timestamp,open,high,low,close
2024-02-13 02:00,1.07718,1.07725,1.07718,1.07723
2024-02-13 02:01,1.07724,1.07726,1.07723,1.07726

Daylight saving time is applied automatically. To list every time zone your Node.js version knows:

Terminal window
node -p "Intl.supportedValuesOf('timeZone').join('\n')"

In Node.js

Section titled “In Node.js”

getHistoricalRates always returns numeric UTC timestamps, so you can format them however you like. With the built-in Intl API:

import { getHistoricalRates } from 'dukascopy-node';


const candles = await getHistoricalRates({
  instrument: 'eurusd',
  dates: { from: '2024-02-13', to: '2024-02-15' },
  timeframe: 'm1',
  format: 'json'
});


const kyiv = new Intl.DateTimeFormat('sv-SE', {
  timeZone: 'Europe/Kyiv',
  dateStyle: 'short',
  timeStyle: 'short'
});


const rows = candles.map(candle => ({
  ...candle,
  iso: new Date(candle.timestamp).toISOString(), // 2024-02-13T00:00:00.000Z
  local: kyiv.format(candle.timestamp) // 2024-02-13 02:00
}));

Time zones and the date range

Section titled “Time zones and the date range”

Dates you pass in are interpreted the usual JavaScript way: date-only strings such as 2024-02-13 are UTC midnight, while date-times without an offset, such as 2024-02-13T09:00, are in your machine’s local time. Add Z or an offset (2024-02-13T09:00Z, 2024-02-13T09:00+02:00) to be explicit.

The utcOffset option (-utc) shifts both ends of the requested range by a number of minutes. It does not change the timestamps in the output, which are always UTC.