3. Historical Data

This section illustrates how to retrieve historical data for different instruments.

First, the API connection.

In [1]:
import fxcmpy
import pandas as pd
import datetime as dt
con = fxcmpy.fxcmpy(config_file='fxcm.cfg')

3.1. Available Instruments

A list of instruments for which historical data is available is returned by con. get_instruments_for_candles().

In [2]:
instruments = con.get_instruments_for_candles()
for i in range(int(len(instruments)/4)):
    print(instruments[i*4:(i+1)*4])
print(instruments[(i+1)*4:])
['EUR/USD', 'USD/JPY', 'GBP/USD', 'USD/CHF']
['EUR/CHF', 'AUD/USD', 'USD/CAD', 'NZD/USD']
['EUR/GBP', 'EUR/JPY', 'GBP/JPY', 'AUD/JPY']
['GBP/AUD', 'USD/CNH', 'FRA40', 'GER30']
['UK100', 'US30', 'USDOLLAR', 'XAU/USD']
['XAG/USD']

3.2. Fetching the Data

In a simple case, the con.get_candles() method returns the most recent data points available for a specified instrument and period value.

In [3]:
con.get_candles('USD/JPY', period='D1')  # daily data
Out[3]:
bidopen bidclose bidhigh bidlow askopen askclose askhigh asklow tickqty
date
2018-05-24 21:00:00 110.069 109.228 110.085 108.945 110.096 109.275 110.132 108.965 454210
2018-05-25 21:00:00 109.228 109.352 109.734 109.112 109.275 109.419 109.755 109.131 394943
2018-05-27 21:00:00 109.504 109.736 109.806 109.500 109.563 109.796 109.848 109.563 733
2018-05-28 21:00:00 109.736 109.394 109.820 109.222 109.796 109.442 109.847 109.245 301699
2018-05-29 21:00:00 109.394 108.744 109.459 108.102 109.442 108.790 109.481 108.123 574325
2018-05-30 21:00:00 108.744 108.895 109.065 108.341 108.790 108.921 109.086 108.363 498453
2018-05-31 21:00:00 108.895 108.793 108.995 108.376 108.921 108.846 109.015 108.397 452231
2018-06-01 21:00:00 108.793 109.478 109.723 108.712 108.846 109.545 109.752 108.733 368094
2018-06-04 21:00:00 109.552 109.803 109.845 109.548 109.572 109.827 109.865 109.569 57968
2018-06-05 21:00:00 109.803 109.761 109.995 109.462 109.827 109.814 110.016 109.484 374545

By default, the method returns a pandas DataFrame object which simplifies the majority of typical analytics and visualizations tasks significantly (see http://pandas.pydata.org).

3.3. Data Frequency

The parameter period defines the frequency of the data to be retrieved. Below is a list of all currently available frequencies.

  • minutes: m1, m5, m15 and m30,
  • hours: H1, H2, H3, H4, H6 and H8,
  • one day: D1,
  • one week: W1,
  • one month: M1.

By default, con.get_candles() returns data for the last 10 available periods, depending on the parameter value for period.

In [4]:
con.get_candles('EUR/USD', period='M1')  # monthly data
Out[4]:
bidopen bidclose bidhigh bidlow askopen askclose askhigh asklow tickqty
date
2017-07-31 21:00:00 1.18403 1.19081 1.20693 1.16610 1.18428 1.19110 1.20716 1.16634 6893224
2017-08-31 21:00:00 1.19081 1.18108 1.20913 1.17160 1.19110 1.18197 1.20937 1.17181 6183348
2017-09-30 21:00:00 1.18108 1.16450 1.18792 1.15731 1.18197 1.16476 1.18810 1.15750 4598301
2017-10-31 21:00:00 1.16450 1.19026 1.19601 1.15528 1.16476 1.19051 1.19624 1.15549 4392023
2017-11-30 22:00:00 1.19026 1.20038 1.20244 1.17165 1.19051 1.20103 1.20267 1.17187 3678417
2017-12-31 22:00:00 1.20038 1.24122 1.25369 1.19144 1.20103 1.24148 1.25392 1.19166 6771090
2018-01-31 22:00:00 1.24122 1.21922 1.25547 1.21867 1.24148 1.21962 1.25566 1.21890 6552190
2018-04-01 20:00:00 1.23228 1.23191 1.23290 1.23191 1.23306 1.23252 1.23330 1.23252 39
2018-05-01 20:00:00 1.21214 1.19907 1.21377 1.19801 1.21291 1.19948 1.21400 1.19822 477918
2018-06-01 20:00:00 1.16534 1.16561 1.17273 1.15091 1.16596 1.16624 1.17297 1.15112 1806820

A number different from 10 can also be defined via the number parameter.

In [5]:
con.get_candles('EUR/USD', period='m1', number=5)  # five one-minute bars
Out[5]:
bidopen bidclose bidhigh bidlow askopen askclose askhigh asklow tickqty
date
2018-06-06 08:52:00 1.17460 1.17442 1.17461 1.17429 1.17484 1.17464 1.17484 1.17453 213
2018-06-06 08:53:00 1.17442 1.17430 1.17442 1.17420 1.17465 1.17453 1.17466 1.17445 241
2018-06-06 08:54:00 1.17429 1.17436 1.17440 1.17425 1.17453 1.17460 1.17463 1.17449 223
2018-06-06 08:55:00 1.17437 1.17448 1.17457 1.17437 1.17460 1.17470 1.17480 1.17460 351
2018-06-06 08:56:00 1.17448 1.17479 1.17487 1.17448 1.17470 1.17502 1.17510 1.17469 292

3.4. Time Windows

Alternatively, one can specifiy start and stop values to specifiy the time window for data retrieval.

In [6]:
start = dt.datetime(2018, 5, 15)
end = dt.datetime(2018, 6, 1)
con.get_candles('EUR/USD', period='D1',
                start=start, end=end)
Out[6]:
bidopen bidclose bidhigh bidlow askopen askclose askhigh asklow tickqty
date
2018-05-16 21:00:00 1.18366 1.18052 1.18530 1.17620 1.18389 1.18092 1.18553 1.17644 398818
2018-05-17 21:00:00 1.18052 1.17920 1.18363 1.17752 1.18092 1.17964 1.18388 1.17776 308010
2018-05-18 21:00:00 1.17920 1.17673 1.18209 1.17486 1.17964 1.17754 1.18233 1.17508 212112
2018-05-20 21:00:00 1.17630 1.17667 1.17785 1.17623 1.17698 1.17745 1.17810 1.17698 168
2018-05-21 21:00:00 1.17667 1.17900 1.17945 1.17155 1.17745 1.17930 1.17968 1.17179 194031
2018-05-22 21:00:00 1.17900 1.17765 1.18287 1.17553 1.17930 1.17810 1.18310 1.17578 276164
2018-05-23 21:00:00 1.17765 1.16944 1.17886 1.16747 1.17810 1.16980 1.17909 1.16770 381970
2018-05-24 21:00:00 1.16944 1.17182 1.17494 1.16897 1.16979 1.17212 1.17515 1.16921 320736
2018-05-25 21:00:00 1.17182 1.16469 1.17325 1.16447 1.17212 1.16529 1.17349 1.16473 317164
2018-05-27 21:00:00 1.16534 1.16849 1.16868 1.16534 1.16596 1.16885 1.16907 1.16596 947
2018-05-28 21:00:00 1.16849 1.16231 1.17273 1.16063 1.16885 1.16260 1.17297 1.16084 244898
2018-05-29 21:00:00 1.16231 1.15382 1.16385 1.15091 1.16260 1.15407 1.16409 1.15112 421212
2018-05-30 21:00:00 1.15383 1.16599 1.16753 1.15176 1.15408 1.16673 1.16774 1.15199 441679
2018-05-31 21:00:00 1.16599 1.16890 1.17233 1.16400 1.16673 1.16963 1.17254 1.16423 384090
2018-06-01 21:00:00 1.16890 1.16561 1.17168 1.16158 1.16962 1.16624 1.17193 1.16180 314941

3.5. Data Visualization

The Python ecosystem provides a number of alternatives to visualize financial time series data. The standard plotting library is matplotlib (see http://matplotlib.org) which is tighly integrated with pandas DataFrame objects, allowing for efficient visualizations.

In [7]:
from pylab import plt
plt.style.use('seaborn')
%matplotlib inline

Using the columns parameter, one can specifiy which data columns are returned. Here, just one column is specified.

In [8]:
data = con.get_candles('EUR/USD', period='m1',
                       columns=['askopen'], number=500)

The following code visualizes the only financial time series in the DataFrame object.

In [9]:
data.plot(figsize=(10, 6), lw=0.8);
_images/02_historical_data_25_0.png

Specifying the columns parameter to be asks (bids) returns all columns related to ask (bid) prices.

In [10]:
data = con.get_candles('EUR/USD', period='m1',
                       columns=['asks'], number=50)
In [11]:
data.plot(figsize=(10, 6), lw=0.8);
_images/02_historical_data_28_0.png
In [12]:
con.close()