{"_id":"566b7c8a03870a0d008ee7a2","version":{"_id":"55312174c68f493900aebb42","project":"55312174c68f493900aebb3f","__v":10,"createdAt":"2015-04-17T15:06:28.598Z","releaseDate":"2015-04-17T15:06:28.598Z","categories":["55312175c68f493900aebb43","566b431d03b4b20d00d02c3a","566b58f212bc0517005d3068","566b59110506f40d0034f148","566b7cc94d1a4d0d00801c00","566b82d130cdb417008d217d","566b855b4d1a4d0d00801c04","566b856f03870a0d008ee7a7","566c42d2f0a5dc0d009acbab","566c443d85dc790d0062c134"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.7.0","version":"0.7"},"editedParams":true,"user":"5531215e29603d2300011341","__v":2,"category":{"_id":"566b431d03b4b20d00d02c3a","version":"55312174c68f493900aebb42","__v":8,"pages":["566b438f1766bf0d00e73981","566b51a3f46dc90d009de82a","566b57f068eba90d009cac72","566b6564461c970d0038bfd9","566b6f17bc5adc0d0096760c","566b7c8a03870a0d008ee7a2","566b81db30cdb417008d217b","56a48d9521d3d60d000341f4"],"project":"55312174c68f493900aebb3f","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-12-11T21:41:49.917Z","from_sync":false,"order":1,"slug":"basic-requests","title":"API Endpoints"},"editedParams2":true,"project":"55312174c68f493900aebb3f","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-12T01:46:50.982Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"get","results":{"codes":[{"status":200,"language":"json","code":"{\n    \"disclaimer\": \"https://openexchangerates.org/terms/\",\n    \"license\": \"https://openexchangerates.org/license/\",\n    \"start_date\": \"2013-01-01\",\n    \"end_date\": \"2013-01-31\",\n    \"base\": \"AUD\",\n    \"rates\": {\n        \"2013-01-01\": {\n            \"BTC\": 0.0778595876,\n            \"EUR\": 0.785518,\n            \"HKD\": 8.04136\n        },\n        \"2013-01-02\": {\n            \"BTC\": 0.0789400739,\n            \"EUR\": 0.795034,\n            \"HKD\": 8.138096\n        },\n        \"2013-01-03\": {\n            \"BTC\": 0.0785299961,\n            \"EUR\": 0.80092,\n            \"HKD\": 8.116954\n        },\n        /* ... */\n    }\n}","name":""},{"status":400,"name":"Bad Request (not_available)","code":"{\n    \"error\": true,\n    \"status\": 400,\n    \"message\": \"not_available\",\n    \"description\": \"Historical rates for one or more of your requested dates are not available - please try a different date-range, or contact support:::at:::openexchangerates.org.\"\n}","language":"json"},{"code":"{\n    \"error\": true,\n    \"status\": 400,\n    \"message\": \"invalid_date_range\",\n    \"description\": \"Invalid date range: `start` and `end` dates must be valid days, in the format 'YYYY-MM-DD'.\"\n}","language":"json","status":400,"name":"Bad Request (invalid_date_range)"}]},"settings":"","examples":{"codes":[{"name":null,"language":"http","code":"https://openexchangerates.org/api/time-series.json\n    ?app_id=YOUR_APP_ID\n    &start=2012-01-01\n    &end=2012-01-31\n    &base=AUD\n    &symbols=BTC,EUR,HKD\n    &prettyprint=1"},{"language":"javascript","name":"jQuery","code":"var query_vars = {\n    app_id: 'YOUR_APP_ID',\n    start: '2012-01-01',\n    end: '2012-01-31',\n    base: 'AUD',\n    symbols: 'BTC,EUR,HKD',\n    prettyprint: 1\n}\n\n$.get('https://openexchangerates.org/api/time-series.json', query_vars, function(data) {\n    console.log(data);\n});"}]},"auth":"required","params":[{"_id":"566b47ff85fbc81700f89547","ref":"","in":"query","required":false,"desc":"Your unique App ID","default":"Required","type":"string","name":"app_id"},{"_id":"566b6564461c970d0038bfda","ref":"","in":"query","required":false,"desc":"The time series start date in YYYY-MM-DD format","default":"Required","type":"yyyy-mm-dd","name":"start"},{"_id":"566b7c8a03870a0d008ee7a4","ref":"","in":"query","required":false,"desc":"The time series end date in YYYY-MM-DD format (see notes)","default":"Required","type":"yyyy-mm-dd","name":"end"},{"_id":"566b438f1766bf0d00e73982","ref":"","in":"query","required":false,"desc":"Limit results to specific currencies (comma-separated list of 3-letter codes)","default":"Recommended","type":"string","name":"symbols"},{"_id":"566b438f1766bf0d00e73983","ref":"","in":"query","required":false,"desc":"Change base currency (3-letter code, default: USD)","default":"Optional","type":"string","name":"base"},{"_id":"598889c1c8e7270025fd3c86","ref":"","in":"query","required":false,"desc":"Extend returned values with alternative, black market and digital currency rates","default":"(Optional)","type":"boolean","name":"show_alternative"},{"_id":"566b7c8a03870a0d008ee7a3","ref":"","in":"query","required":false,"desc":"Human-readable response for debugging (response size will be much larger)","default":"Optional","type":"boolean","name":"prettyprint"}],"url":"/time-series.json"},"isReference":true,"order":3,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The maximum query period currently allowed is one month. If you need more than one month’s data, please request months sequentially (details below).\\n\\nWith a full list of currencies for each requested day, Time-Series API responses can be very large in size. For better performance, use the `symbols` parameter to cut down response weight.\",\n  \"title\": \"Important\"\n}\n[/block]\nThe Time Series response format is different from the standard API response as in **latest.json**. Please familiarise yourself with the standard API response format before using this endpoint.\n\nThe `start_date` is the first day of the time series, and the `end_date` is the final day (**both inclusive**). \n\nThe `base` property provides the 3-letter currency code to which all the delivered exchange rates are relative. This base currency is also given in the rates object by default (e.g. `\"USD\": 1`).\n\nThe `rates` property is an object of dates, each an object containing the conversion or exchange rates for the specified date, labeled by their international-standard 3-letter currency codes. All the values are relative to 1 unit of the requested `base` currency.\n\n**There is no `timestamp` property in this response.**\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Important notes about Time-Series queries\"\n}\n[/block]\n1. Please note that each day requested counts as one API request (so requesting a full month of data will count as up to 31 ‘hits’).\n2. Where the requested `end` date is not a valid calendar date, it will be corrected backwards automatically to the nearest valid day. For example, `2012-02-31` will be corrected to `2012-02-29`. \n3. To request multiple months sequentially, you can simply request the **1st to the 31st** of each month, regardless of month length.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Errors\"\n}\n[/block]\nPlease see [API Error Messages](doc:errors) for a list of possible errors not specified above.","excerpt":"Get historical exchange rates for a given time period, where available, using the time series / bulk download  API endpoint. Please read all the details before integrating.\n\nTime Series requests are currently available for clients on the Enterprise and Unlimited plans.","slug":"time-series-json","type":"endpoint","title":"/time-series.json"}

get/time-series.json

Get historical exchange rates for a given time period, where available, using the time series / bulk download API endpoint. Please read all the details before integrating. Time Series requests are currently available for clients on the Enterprise and Unlimited plans.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

app_id:
stringRequired
Your unique App ID
start:
yyyy-mm-ddRequired
The time series start date in YYYY-MM-DD format
end:
yyyy-mm-ddRequired
The time series end date in YYYY-MM-DD format (see notes)
symbols:
stringRecommended
Limit results to specific currencies (comma-separated list of 3-letter codes)
base:
stringOptional
Change base currency (3-letter code, default: USD)
show_alternative:
boolean(Optional)
Extend returned values with alternative, black market and digital currency rates
prettyprint:
booleanOptional
Human-readable response for debugging (response size will be much larger)

Examples


Result Format


Documentation

[block:callout] { "type": "warning", "body": "The maximum query period currently allowed is one month. If you need more than one month’s data, please request months sequentially (details below).\n\nWith a full list of currencies for each requested day, Time-Series API responses can be very large in size. For better performance, use the `symbols` parameter to cut down response weight.", "title": "Important" } [/block] The Time Series response format is different from the standard API response as in **latest.json**. Please familiarise yourself with the standard API response format before using this endpoint. The `start_date` is the first day of the time series, and the `end_date` is the final day (**both inclusive**). The `base` property provides the 3-letter currency code to which all the delivered exchange rates are relative. This base currency is also given in the rates object by default (e.g. `"USD": 1`). The `rates` property is an object of dates, each an object containing the conversion or exchange rates for the specified date, labeled by their international-standard 3-letter currency codes. All the values are relative to 1 unit of the requested `base` currency. **There is no `timestamp` property in this response.** [block:api-header] { "type": "basic", "title": "Important notes about Time-Series queries" } [/block] 1. Please note that each day requested counts as one API request (so requesting a full month of data will count as up to 31 ‘hits’). 2. Where the requested `end` date is not a valid calendar date, it will be corrected backwards automatically to the nearest valid day. For example, `2012-02-31` will be corrected to `2012-02-29`. 3. To request multiple months sequentially, you can simply request the **1st to the 31st** of each month, regardless of month length. [block:api-header] { "type": "basic", "title": "Errors" } [/block] Please see [API Error Messages](doc:errors) for a list of possible errors not specified above.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}