{"_id":"566b6564461c970d0038bfd9","user":"5531215e29603d2300011341","editedParams2":true,"project":"55312174c68f493900aebb3f","githubsync":"","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"},"editedParams":true,"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"},"__v":9,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-12T00:08:04.673Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"http","code":"https://openexchangerates.org/api/historical/2012-07-10.json?app_id=YOUR_APP_ID"},{"language":"javascript","name":"jQuery","code":"var date = \"2001-02-16\";\n\n$.get('https://openexchangerates.org/api/historical/' + date + '.json', {app_id: 'YOUR_APP_ID'}, function(data) {\n    console.log(data);\n});"}]},"method":"get","results":{"codes":[{"status":200,"name":"","code":"{\n    disclaimer: \"Usage subject to terms: https://openexchangerates.org/terms\",\n    license: \"https://openexchangerates.org/license\",\n    timestamp: 1341936000,\n    base: \"USD\",\n    rates: {\n        AED: 3.672914,\n        AFN: 48.337601,\n        ALL: 111.863334\n        /* ... */\n    }\n}","language":"json"},{"status":400,"language":"json","code":"{\n    \"error\": true,\n    \"status\": 400,\n    \"message\": \"not_available\",\n    \"description\": \"The date you requested is invalid - please try a different date, or contact support:::at:::openexchangerates.org.\"\n}","name":"Bad Request (invalid_date)"},{"language":"json","code":"{\n    \"error\": true,\n    \"status\": 400,\n    \"message\": \"not_available\",\n    \"description\": \"Historical rates for the requested date are not available - please try a different date, or contact support@openexchangerates.org.\"\n}","name":"Bad Request (not_available)","status":400}]},"settings":"","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":"path","required":false,"desc":"The requested date in YYYY-MM-DD format (required).","default":"Required","type":"yyyy-mm-dd","name":"date"},{"_id":"566b438f1766bf0d00e73983","ref":"","in":"query","required":false,"desc":"Change base currency (3-letter code, default: USD)","default":"Optional","type":"string","name":"base"},{"_id":"566b438f1766bf0d00e73982","ref":"","in":"query","required":false,"desc":"Limit results to specific currencies (comma-separated list of 3-letter codes)","default":"Optional","type":"string","name":"symbols"},{"_id":"5988861352b044000ffb0a2c","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":"59888adb0dd83a000f42bbc2","ref":"","in":"query","required":false,"desc":"Human-readable response for debugging (response size will be much larger)","default":"(Optional)","type":"boolean","name":"prettyprint"}],"url":"/historical/:date.json"},"isReference":true,"order":1,"body":"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`).\n\nThe `rates` property is an object (hash/dictionary/associative array) containing all the conversion or exchange rates for all of the available (or requested) currencies, labeled by their international-standard 3-letter currency codes. All the values are relative to 1 unit of the requested `base` currency.\n\nThe `timestamp` property indicates the time (UNIX) that the rates were published. (If you’re using the timestamp value in JavaScript, remember to multiply it by 1000, because JavaScript uses time in milliseconds instead of seconds.)\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Changing the `base` currency and requesting specific `symbols` are currently available for clients on the Developer, Enterprise and Unlimited plans.\",\n  \"title\": \"Additional Parameters\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"For the sake of consistency, all dates and timestamps in the Open Exchange Rates API refer to the UTC timezone (i.e. GMT+00:00), with no daylight saving applied. \\n\\nIf your server/integration operates in a different timezone (or supports multiple timezones), you should convert your server's local time to the equivalent UTC time before making your request.\",\n  \"title\": \"Historical Timezones & Daylight Saving Time\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Historical requests for the current day's UTC date\",\n  \"body\": \"Historical rates are generally the last values we published on a given UTC day (up to and including 23:59:59 UTC), with the exception of the **current UTC date**. \\n\\nIf you make a request for the current day's historical file, you will receive the **most recent rates** available for your subscription plan at that moment, as the day is not yet complete (therefore in such cases, the values returned would be the same as you would find via our **latest.json** endpoint).\\n\\nThis behaviour was added early on in response to client feedback, because the historical endpoint aims to always provide a value for a *valid* date (even if that date is the same as today's date and therefore no end-of-day values are available).\\n\\nIf you wish to obtain rates for a historical date that is the same as today's date (in UTC), you may prefer to make use of the **latest.json** endpoint instead, in order to prevent unexpected behaviour.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Basic Code Samples\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var date = \\\"2010-10-10\\\";\\n\\n$.get('https://openexchangerates.org/api/historical/' + date + '.json', {app_id: 'YOUR_APP_ID'}, function(data) {\\n    console.log(\\\"On \\\" + date + \\\", 1 US Dollar was worth \\\" + data.rates.GBP + \\\" GBP\\\");\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    },\n    {\n      \"code\": \"More code samples are on their way! Please get in touch if you'd like to submit a new/improved code sample in your languague or framework.\",\n      \"language\": \"text\",\n      \"name\": \"Others...\"\n    }\n  ]\n}\n[/block]\nTo request rates for a different base currency, please see [Changing Base Currency](doc:changing-base-currency).\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 any date available from the Open Exchange Rates API, currently going back to 1st January 1999.\n\nLike latest.json, our /historical/ route provides a standard response object containing all the conversion rates for all available symbols/currencies on your requested date, labeled by their international-standard 3-letter ISO currency codes.\n\nThe historical rates returned are the last values we published for a given UTC day (up to and including 23:59:59 UTC), except for the current UTC date.","slug":"historical-json","type":"endpoint","title":"/historical/*.json"}

get/historical/*.json

Get historical exchange rates for any date available from the Open Exchange Rates API, currently going back to 1st January 1999. Like latest.json, our /historical/ route provides a standard response object containing all the conversion rates for all available symbols/currencies on your requested date, labeled by their international-standard 3-letter ISO currency codes. The historical rates returned are the last values we published for a given UTC day (up to and including 23:59:59 UTC), except for the current UTC date.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

date:
yyyy-mm-ddRequired
The requested date in YYYY-MM-DD format (required).

Query Params

app_id:
stringRequired
Your unique App ID (required)
base:
stringOptional
Change base currency (3-letter code, default: USD)
symbols:
stringOptional
Limit results to specific currencies (comma-separated list of 3-letter codes)
show_alternative:
boolean(Optional)
Extend returned values with alternative, black market and digital currency rates
prettyprint:
boolean(Optional)
Human-readable response for debugging (response size will be much larger)

Examples


Result Format


Documentation

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 (hash/dictionary/associative array) containing all the conversion or exchange rates for all of the available (or requested) currencies, labeled by their international-standard 3-letter currency codes. All the values are relative to 1 unit of the requested `base` currency. The `timestamp` property indicates the time (UNIX) that the rates were published. (If you’re using the timestamp value in JavaScript, remember to multiply it by 1000, because JavaScript uses time in milliseconds instead of seconds.) [block:callout] { "type": "info", "body": "Changing the `base` currency and requesting specific `symbols` are currently available for clients on the Developer, Enterprise and Unlimited plans.", "title": "Additional Parameters" } [/block] [block:callout] { "type": "warning", "body": "For the sake of consistency, all dates and timestamps in the Open Exchange Rates API refer to the UTC timezone (i.e. GMT+00:00), with no daylight saving applied. \n\nIf your server/integration operates in a different timezone (or supports multiple timezones), you should convert your server's local time to the equivalent UTC time before making your request.", "title": "Historical Timezones & Daylight Saving Time" } [/block] [block:callout] { "type": "warning", "title": "Historical requests for the current day's UTC date", "body": "Historical rates are generally the last values we published on a given UTC day (up to and including 23:59:59 UTC), with the exception of the **current UTC date**. \n\nIf you make a request for the current day's historical file, you will receive the **most recent rates** available for your subscription plan at that moment, as the day is not yet complete (therefore in such cases, the values returned would be the same as you would find via our **latest.json** endpoint).\n\nThis behaviour was added early on in response to client feedback, because the historical endpoint aims to always provide a value for a *valid* date (even if that date is the same as today's date and therefore no end-of-day values are available).\n\nIf you wish to obtain rates for a historical date that is the same as today's date (in UTC), you may prefer to make use of the **latest.json** endpoint instead, in order to prevent unexpected behaviour." } [/block] [block:api-header] { "type": "basic", "title": "Basic Code Samples" } [/block] [block:code] { "codes": [ { "code": "var date = \"2010-10-10\";\n\n$.get('https://openexchangerates.org/api/historical/' + date + '.json', {app_id: 'YOUR_APP_ID'}, function(data) {\n console.log(\"On \" + date + \", 1 US Dollar was worth \" + data.rates.GBP + \" GBP\");\n});", "language": "javascript", "name": "jQuery" }, { "code": "More code samples are on their way! Please get in touch if you'd like to submit a new/improved code sample in your languague or framework.", "language": "text", "name": "Others..." } ] } [/block] To request rates for a different base currency, please see [Changing Base Currency](doc:changing-base-currency). [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 }}