Welcome to WTDpy’s documentation!

WTDpy is a python package for making basic calls to the GitHub World Trading Data API.

Welcome to WTDpy documentation! Please check the contents below for information on installation, getting started and example code. If you want to dive straight into the code you can check out the GitHub page or the working examples presented in Jupyter Notebooks.

Installation

Stable release

To install WTDpy, run this command in your terminal:

# Use pip to install wtdpy
pip install wtdpy

This is the preferred method to install WTDpy, as it will always install the most recent stable release.

If you do not have pip installed, this Python installation guide can guide you through the process.

From sources

The sources for WTDpy can be downloaded from the Github repo.

You can either clone the public repository:

# Use git to clone WTDpy
git clone https://github.com/uijl/wtdpy/

Or download the tarball:

# Use curl to obtain the tarball
curl  -OL https://github.com/uijl/wtdpy/tarball/master

Once you have a copy of the source, you can install it with:

# Use python to install
python setup.py install

Examples

This small example guide will cover the basic start-up and the functions now available in WTDpy:

• Import package and set-up a class.
• Make a call to the World Trading Data API.

Start-Up

The first part is importing the package and setting up the class with your own API key.

# Import wtdpy
from wtdpy import WTDpy

If you do not yet have your own API key of the World Trading Data API you can create a free account. With this free account you can request up to 250 historical time series per day. As soon as you log on to your dashboard it shows large on the screen “Your API Token”. Copy this random string and assign it to a variable.

# Set your own api_key
api_key = "your_unique_api_key"

# Create the class
wtd = WTDpy(api_token = api_key)

Make a call to the API

Once you have initialised your WTDpy class you can make a call to the World Trading data API. If you are not sure about the symbol you want to look up you can check if the symbol you want is returned by the API with the following code.

# Check for correct response
# Returns True if the returned symbol is equal to the request
symbol = ["^AEX"]
wtd.search_available_data(symbol = symbol)

If you have selected the correct symbol, or list of symbols, you can use the code below to request all the available historical data.

# Request historical time series of two indices
symbol = ["^AEX", "^DAX"]
wtd.get_historical_data(symbol = symbol)

WTDpy

This page lists all functions and classes available of WTDpy.

Submodules

There is only one submodule with one class: WTDpy. Please check the information below on how the code reads.

wtdpy.wtdpy module

class wtdpy.wtdpy.WTDpy(api_token: str)

Python wrapper for the World Trading Data API.

Parameters

api_token : str

Your personal API token from https://www.worldtradingdata.com/.

Attributes

api_token : str

Your personal API token from https://www.worldtradingdata.com/.

url : str

The base url for requesting the API.

Notes

Create an account on https://www.worldtradingdata.com/ to obtain your API key. It will show on the top of your personal dashboard. You can make 250 API calls per day with the free tier.

Currently supporting:

• Historical data;
• Checking if a symbol excists.

get_historical_data(symbol: Union[str, Sequence[str]], date_from: Union[datetime.datetime, str] = None, date_to: Union[datetime.datetime, str] = None, sort: str = 'asc', output: str = 'dict') → Union[dict, pandas.core.frame.DataFrame]

Get the historical data for the given symbol.

Parameters

symbol : str or list of str

A string or list of strings such as “^AEX”, or [“^AEX”, “^DAX”]. The symbols should match the format as shown on the World Trading Data site. You can check https://www.worldtradingdata.com/search to see what data is available at World Trading Data.

date_from : str or datetime

A string representing a date in isoformat (yyyy-mm-dd), a datetime object or None. If no data is provided the earliest date will be requested.

date_to: str or datetime

A string representing a date in isoformat (yyyy-mm-dd), a datetime object or None. If no data is provided the latest date will be requested.

sort: str

A string representing the sorting of the requested data. Either ascending “asc” or descending “desc”.

output: str

A string representing the desired output. Either dict for a python dict or “df” for a pandas DataFrame.

Raises

ValueError

• If provided symbol is not available.

TypeError

• If date_from is not a correct string or datetime object
• If date_to is not a correct string or datetime object
• If sort is not a correct string
• If output is not a correct string

Returns

to_return : dict or pd.DataFrame

A dictionary or a pandas DataFrame. If symbol is a list then a dictionary of pandas DataFrames will be returned.

search(query: Union[str, Sequence[str]], number_of_hits: int = 5) → Union[dict, Sequence[dict]]

Search the query in the World Trading Data database.

Parameters

query : str or list of str

A string or list of strings such as “Apple computers” or [“Apple computers”, “Microsoft”]. This is similar to manually checking https://www.worldtradingdata.com/search to see what data is available at World Trading Data.

number_of_hits : int

The number of hits that will be returned.

Returns

response : dict or list

A dict, or a list of dicts, with the listed hits based on your search query.

search_available_data(symbol: Union[str, Sequence[str]], list_alternatives: bool = False, number_of_alternatives: int = 1) → Union[bool, Sequence[dict]]

Check if the requested data is available.

Parameters

symbol : str or list of str

A string or list of strings such as “^AEX”, or [“^AEX”, “^DAX”]. The symbols should match the format as shown on the World Trading Data site. You can check https://www.worldtradingdata.com/search to see what data is available at World Trading Data.

list_alternatives : bool

If True a list of likely matches is presented

number_of_alternatives : int

The number of alternatives, besides the top hit, that are checked whether or not they match the provided symbol.

Returns

response : bool or list

A boolean to check whether data is avaible. If list_alternatives is True and a symbol is not found a list with possible alternatives will be returned.

Indices and tables

• Index
• Module Index
• Search Page