{"_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":0,"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","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=[[app: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: '[[app: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 (required)","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 (required)","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 (required) – see note below","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":"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\": \"This Enterprise Feature endpoint is currently in stable Beta, during which the maximum query period 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. Although this feature is currently in Beta, the request and response structure **will no longer be changed** and will be legacy-supported indefinitely. Changes and upgrades will be published under our new, versioned API and will be \"opt-in\". Therefore you may feel free to build your integration with this endpoint.\n2. 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’).\n3. 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`. \n4. 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 (required)
start:
yyyy-mm-ddRequired
The time series start date in YYYY-MM-DD format (required)
end:
yyyy-mm-ddRequired
The time series end date in YYYY-MM-DD format (required) – see note below
symbols:
stringRecommended
Limit results to specific currencies (comma-separated list of 3-letter codes)
base:
stringOptional
Change base currency (3-letter code, default: USD)
prettyprint:
booleanOptional
Human-readable response for debugging (response size will be much larger)

Examples


Result Format


Documentation

[block:callout] { "type": "warning", "body": "This Enterprise Feature endpoint is currently in stable Beta, during which the maximum query period 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. Although this feature is currently in Beta, the request and response structure **will no longer be changed** and will be legacy-supported indefinitely. Changes and upgrades will be published under our new, versioned API and will be "opt-in". Therefore you may feel free to build your integration with this endpoint. 2. 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’). 3. 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`. 4. 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 }}