Help

HTTP API Specification

In this section we present the specification of API which includes: the description of all response data properties, list of all available methods in three formats with example requests and responses and list of possible error messages.

Data preview and properties

The response data from API can contain various properties. In general there are two structures of responses: the first one is for methods that obtain actual exchange rates and the second for the methods that enables you getting data from the past. Here we give the description for all the properties of response data.

Example response for actual exchange rates looks like this:

{
    "ask": "1.38488",
    "bid": "1.38477",
    "name": "EURUSD",
    "time": "1398420924.000"
}

Data contains the following fields:

  • name - name of a currency pair
  • ask - ask price of a related currency pair
  • bid - bid price of a related currency pair
  • time - a UNIX timestamp, which indicates the time when the related ask and bid values were calculated

Methods for data from the past (historical data, chart data) will have the following structure:

{
    "1396267200": [
        1.3775,
        1.38071,
        1.37837,
        1.37989,
        1.37738,
        1.38055,
        1.37827,
        1.37976
    ],
    "1396274400": [
        1.37716,
        1.38071,
        1.37789,
        1.37758,
        1.37706,
        1.38059,
        1.37777,
        1.37747
    ]
}

This data contains is a dictionary of lists; each key in dictionary is a timestamp, which indicates the beginning of a single period for which the values were collected. The difference between timestamps is called the resolution of data. The interpretation of values in each list is following:

  • minimal ask price - minimal ask price in the related period
  • maximal ask price - maximal ask price in the related period
  • open ask price - ask price at the beginning of the related period
  • close ask price - ask price at the end of the related period
  • minimal bid price - minimal bid price in the related period
  • maximal bid price - maximal bid price in the related period
  • open bid price - bid price at the beginning of the related period
  • close bid price - bid price at the end of the related period

Accessing the API

The API is accessible via RESTful interface. For your needs and convenience, the currencies data is available in three formats: JSON, XML and CSV. In this part we describe the available endpoints for each format.

JSON

All methods for JSON are available as GET and POST methods. In both cases names and types of parameters are identical. Because JSON is the default format, you can also use the below presented methods without the /json part in each URL (for example, /currencies/all is a shorthand for /json/currencies/all). This is kept for consistency with other formats. When requesting data in this format, set the Content-Type header to application/json.

Exchange rates for single currency pair

In order to get the current exchange rate for a single currency pair, use the following method:

{your_api_url}/json/currencies/<pair>

Parameters:

  • pair - single currency pair, for example EURUSD

Example GET request:

{your_api_url}/json/currencies/EURUSD

Example response:

{
    "ask": "1.38488",
    "bid": "1.38477",
    "name": "EURUSD",
    "time": "1398420924.000"
}
Exchange rates for many currency pairs

To get many currency pairs at once, use:

{your_api_url}/json/currencies?pairs=["<pair>", "<pair>"]

Parameters:

  • pairs - list of currency pairs, each pair should be surrounded by quotation marks, for example ["EURUSD", "USDJPY"].

Example GET request:

{your_api_url}/json/currencies?pairs=["EURUSD", "USDJPY"]

Example POST request:

{your_api_url}/json/currencies

Request body:

{
    "pairs": ["EURUSD", "USDJPY"]
}

Example response:

[
    {
        "ask": "1.38488",
        "bid": "1.38477",
        "name": "EURUSD",
        "time": "1398420924.000"
    },
    {
        "ask": "102.20050",
        "bid": "102.18450",
        "name": "USDJPY",
        "time": "1398420923.000"
    }
]
Exchange rates for all available currency pairs

To get the exchange rates for all currency pairs which are provided by xChangeApi.com, use:

{your_api_url}/json/currencies/all

Example response:

[
    {
        "ask": "1.96093",
        "bid": "1.96002",
        "name": "GBPNZD",
        "time": "1398420919.000"
    },
    {
        "ask": "0.81715",
        "bid": "0.81682",
        "name": "AUDCHF",
        "time": "1398420923.000"
    },
    {
        "ask": "309.76700",
        "bid": "309.52900",
        "name": "EURHUF",
        "time": "1398420919.000"
    }

]
Historical data

You can access historical exchange rates with the specified resolution by using the following method.

{your_api_url}/json/history/<pair>?starttime=<starttime>&endtime=<endtime>&resolution=<resolution>

Parameters:

  • pair - single currency pair, for example EURUSD
  • starttime - UNIX timestamp indicating the date of the beginning of requested period, for example 1388530800 for 1st of January 2014.
  • endtime - as above, but it is the date of the end of requested period.
  • resolution - resolution of data, possible values are: 1, 5, 10, 60, 1800.

Example GET request:

{your_api_url}/json/history/EURUSD?starttime=1397080800&endtime=1397253600&resolution=1800

Example POST request:

{your_api_url}/json/history/EURUSD

Request body:

{
    "starttime": 1397080800,
    "endtime": 1397253600,
    "resolution": 1800
}

Example response:

{
    "1397113200": [
        1.38489,
        1.3859,
        1.38493,
        1.38566,
        1.38477,
        1.38577,
        1.38481,
        1.38553
    ],
    "1397115000": [
        1.38551,
        1.38625,
        1.38566,
        1.38596,
        1.38538,
        1.38612,
        1.38552,
        1.3858
    ],
    "1397116800": [
        1.38592,
        1.38681,
        1.38597,
        1.38653,
        1.38577,
        1.38669,
        1.3858,
        1.38638
    ]

}
Getting chart peaks for selected period of time

Chart data is similar to historical data. The only difference is, that in this case the resolution is calculated automatically. With the following method, you can access data for one of the specified periods of time:

{your_api_url}/json/chart/<pair>/<period>

Parameters:

  • pair - single currency pair, for example EURUSD.
  • period - one of predefined time periods. Possible values are:
    • 30m - last 30 minutes
    • 1h - last hour
    • 6h - last 6 hours
    • 12h - last 12 hours
    • 1d - last day
    • 2d - last 2 days
    • 7d - last 7 days
    • 1M - last month
    • 3M - last 3 months
    • 6M - last 6 months
    • 1Y - last year

Example GET request:

{your_api_url}/json/chart/EURUSD/1M

Example response:

{
    "1396267200": [
        1.3775,
        1.38071,
        1.37837,
        1.37989,
        1.37738,
        1.38055,
        1.37827,
        1.37976
    ],
    "1396274400": [
        1.37716,
        1.38071,
        1.37789,
        1.37758,
        1.37706,
        1.38059,
        1.37777,
        1.37747
    ],
    "1396281600": [
        1.37638,
        1.37868,
        1.37765,
        1.37731,
        1.37621,
        1.37857,
        1.37753,
        1.37718
    ]
}
Getting chart peaks for specified date range

To get the chart data for some specific period of time, use the following method:

{your_api_url}/json/chart/<pair>?starttime=<starttime>&endtime=<endtime>

Parameters:

  • pair - single currency pair, for example EURUSD.
  • starttime - UNIX timestamp indicating the date of the beginning of requested period, for example 1388530800 for 1st of January 2014.
  • endtime - as above, but it is the date of the end of requested period.

Example GET request:

{your_api_url}/json/chart/EURUSD?starttime=1397080800&endtime=1397253600

Example POST request:

{your_api_url}/json/chart/EURUSD

Request body:

{
    "starttime": 1397080800,
    "endtime": 1397253600
}

Example response:

{
    "1397113440": [
        1.38489,
        1.38588,
        1.3856,
        1.3852,
        1.38477,
        1.38574,
        1.38546,
        1.38506
    ],
    "1397113920": [
        1.38547,
        1.3859,
        1.38583,
        1.38565,
        1.38533,
        1.38577,
        1.3857,
        1.38553
    ],
    "1397114400": [
        1.38534,
        1.38571,
        1.3856,
        1.3854,
        1.3852,
        1.38558,
        1.38547,
        1.38526
    ]
}

XML

Methods for XML format are available as POST methods and requires XML-formatted request body. Names of methods and parameters are identical to those in JSON format. When requesting data in XML format, set the Content-Type header to application/xml or text/xml. Here we present the example requests and responses specific to XML format; the details of each method and its parameters can be found in JSON section.

Request body structure:

<data>
    <param1>value</param1>
    <param2>value</param2>
</data>

Response structure for actual exchange rates:

<result>
    <currency>
        <ask></ask>
        <bid></bid>
        <name></name>
        <time></time>
    </currency>
</result>

Response structure for historical data as well as chart data:

<result>
    <item>
        <time></time>
        <min_ask></min_ask>
        <max_ask></max_ask>
        <open_ask></open_ask>
        <close_ask></close_ask>
        <min_bid></min_bid>
        <max_bid></max_bid>
        <open_bid></open_bid>
        <close_bid></close_bid>
    </item>
    <item>
        ...
    </item>
</result>
Exchange rates for single currency pair
{your_api_url}/xml/currencies/<pair>

Example POST request:

{your_api_url}/xml/currencies/EURUSD

Example response:

<result>
    <currency>
        <ask>1.38488</ask>
        <bid>1.38477</bid>
        <name>EURUSD</name>
        <time>1398420924.000</time>
    </currency>
</result>
Exchange rates for many currency pairs
{your_api_url}/xml/currencies

Example POST request:

<data>
  <pair>EURUSD</pair>
  <pair>USDJPY</pair>
</data>

Example response:

<result>
    <currency>
        <ask>1.38488</ask>
        <bid>1.38477</bid>
        <name>EURUSD</name>
        <time>1398420924.000</time>
    </currency>
    <currency>
        <ask>102.20050</ask>
        <bid>102.18450</bid>
        <name>USDJPY</name>
        <time>1398420923.000</time>
    </currency>
</result>
Exchange rates for all available currency pairs

POST request:

{your_api_url}/xml/currencies/all
Historical data
{your_api_url}/xml/history/

Example POST request:

{your_api_url}/xml/history/EURUSD

Request body:

<data>
    <starttime>1397080800</starttime>
    <endtime>1397253600</endtime>
    <resolution>1800</resolution>
</data>

Example response:

<result>
    <item>
        <time>1397113200</time>
        <min_ask>1.38489</min_ask>
        <max_ask>1.3859</max_ask>
        <open_ask>1.38493</open_ask>
        <close_ask>1.38566</close_ask>
        <min_bid>1.38477</min_bid>
        <max_bid>1.38577</max_bid>
        <open_bid>1.38481</open_bid>
        <close_bid>1.38553</close_bid>
    </item>
    <item>
        <time>1397115000</time>
        <min_ask>1.38551</min_ask>
        <max_ask>1.38625</max_ask>
        <open_ask>1.38566</open_ask>
        <close_ask>1.38596</close_ask>
        <min_bid>1.38538</min_bid>
        <max_bid>1.38612</max_bid>
        <open_bid>1.38552</open_bid>
        <close_bid>1.3858</close_bid>
    </item>
</result>
Getting chart peaks for selected period of time
{your_api_url}/xml/chart/<pair>/<period>

Example POST request:

{your_api_url}/xml/chart/EURUSD/1M

Example response:

<result>
    <item>
        <time>1396850400</time>
        <min_ask>1.37139</min_ask>
        <max_ask>1.37187</max_ask>
        <open_ask>1.37146</open_ask>
        <close_ask>1.3718</close_ask>
        <min_bid>1.37128</min_bid>
        <max_bid>1.37176</max_bid>
        <open_bid>1.37133</open_bid>
        <close_bid>1.37169</close_bid>
    </item>
    <item>
        <time>1396857600</time>
        <min_ask>1.37118</min_ask>
        <max_ask>1.3719</max_ask>
        <open_ask>1.3716</open_ask>
        <close_ask>1.37161</close_ask>
        <min_bid>1.37107</min_bid>
        <max_bid>1.37181</max_bid>
        <open_bid>1.37148</open_bid>
        <close_bid>1.37151</close_bid>
    </item>
</result>
Getting chart peaks for specified date range
{your_api_url}/xml/chart/<pair>

Example POST request:

{your_api_url}/xml/chart/EURUSD

Request body:

<data>
    <starttime>1397080800</starttime>
    <endtime>1397253600</endtime>
</data>

Example response:

<result>
    <item>
        <time>1397113440</time>
        <min_ask>1.38489</min_ask>
        <max_ask>1.38588</max_ask>
        <open_ask>1.3856</open_ask>
        <close_ask>1.3852</close_ask>
        <min_bid>1.38477</min_bid>
        <max_bid>1.38574</max_bid>
        <open_bid>1.38546</open_bid>
        <close_bid>1.38506</close_bid>
    </item>
    <item>
        <time>1397113920</time>
        <min_ask>1.38547</min_ask>
        <max_ask>1.3859</max_ask>
        <open_ask>1.38583</open_ask>
        <close_ask>1.38565</close_ask>
        <min_bid>1.38533</min_bid>
        <max_bid>1.38577</max_bid>
        <open_bid>1.3857</open_bid>
        <close_bid>1.38553</close_bid>
    </item>
</result>

CSV

All methods for CSV format are available as both GET and POST methods. The input parameters are taken in JSON format and the method calls are the same as for the JSON format (JSON), in this case, only the output is CSV-formatted. When requesting API for CSV format, the Content-Type header should be set to application/json. In this section we present available methods and example responses in CSV format; the details of each method and its parameters, as well as example requests can be found in JSON section.

For each method, first row in response is a header row with names of each column and the following rows contain the exchange rates data. For the description of fields go to Data preview and properties.

Exchange rates for single currency pair
{your_api_url}/csv/currencies/<pair>

Example response:

ask,bid,name,time
1.38488,1.38477,EURUSD,1398420924.000
Exchange rates for many currency pairs
{your_api_url}/csv/currencies?pairs=["<pair>", "<pair>"]

Example response:

ask,bid,name,time
1.38488,1.38477,EURUSD,1398420924.000
102.20050,102.18450,USDJPY,1398420923.000
Exchange rates for all available currency pairs
{your_api_url}/csv/currencies/all

Example response:

ask,bid,name,time
1.02348,1.02315,AUDCAD,1398420857.000
0.81715,0.81682,AUDCHF,1398420923.000
519.45698,519.04829,AUDCLP,1398420923.000
...
Historical data:
{your_api_url}/csv/history/<pair>?starttime=<starttime>&endtime=<endtime>&resolution=<resolution>

Example response:

time,min_ask,max_ask,open_ask,close_ask,min_bid,max_bid,open_bid,close_bid
1397113200,1.38489,1.3859,1.38493,1.38566,1.38477,1.38577,1.38481,1.38553
1397115000,1.38551,1.38625,1.38567,1.38596,1.38538,1.38612,1.38553,1.3858
1397116800,1.38592,1.38681,1.38597,1.38653,1.38577,1.38669,1.3858,1.38638
...
Getting chart peaks for selected period of time
{your_api_url}/csv/chart/<pair>/<period>

Example response:

time,min_ask,max_ask,open_ask,close_ask,min_bid,max_bid,open_bid,close_bid
1396850400,1.37139,1.37187,1.37146,1.3718,1.37128,1.37176,1.37133,1.37169
1396857600,1.37118,1.3719,1.3716,1.37161,1.37107,1.37181,1.37148,1.37151
1396864800,1.37265,1.37303,1.37281,1.37266,1.37254,1.37292,1.3727,1.37255
...
Getting chart peaks for specified date range
{your_api_url}/csv/chart/<pair>?starttime=<starttime>&endtime=<endtime>

Example response:

time,min_ask,max_ask,open_ask,close_ask,min_bid,max_bid,open_bid,close_bid
1397113440,1.38489,1.38588,1.3856,1.3852,1.38477,1.38574,1.38546,1.38506
1397113920,1.38547,1.3859,1.38583,1.38565,1.38533,1.38577,1.3857,1.38553
1397114400,1.38534,1.38571,1.3856,1.3854,1.3852,1.38558,1.38547,1.38526

API Error Messages

It may happen that something goes wrong and API will return an error message. The structure of error response is dependant of the format you requested data.

For JSON format the error response has the structure:

"Error message"

or, for validation errors:

{
    "param": "Error message"
}

For XML format, the structure will be:

<result>
    <msg>Error message</msg>
</result>

or, for validation errors:

<result>
    <param>Error message</param>
</result>

Below is the description of some specific errors with their HTTP status codes.

Status code Message Description
403 IP not allowed Client is not allowed to access requested resource.
403 Response too large Client requested data which could not be returned, because of its too large size. It may occur when requesting historical or chart data for too long time period or too small resolution.
403 Requests limit exceeded Client used the maximal number of requests for his plan in the current billing period.
403 Data limit exceeded Client transferred the maximal amount of data for his plan in the current billing period.
450 Invalid schema One or more parameters sent by client are missing or have wrong values. In this case response contains a dictionary, where the keys are parameters that caused the error and the values are messages explaining the reason.

Available currencies

List is available here.