{"_id":"59627cdb09c31d001557eb6b","project":"55312174c68f493900aebb3f","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"},"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"},"user":"5531215e29603d2300011341","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-07-09T18:58:35.836Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"https://openexchangerates.org/api/ohlc.json\n    ?app_id=YOUR_APP_ID\n    &start_time=2017-07-17T11:00:00Z\n    &period=30m\n    &base=USD\n    &symbols=GBP,EUR,HKD\n    &prettyprint=true","language":"http","name":null},{"code":"var query_vars = {\n    app_id: 'YOUR_APP_ID',\n    start_time: '2017-07-01T14:30:00Z',\n    period: '30m',\n    base: 'USD',\n    symbols: 'GBP,EUR,HKD',\n    prettyprint: false\n}\n\n$.get('https://openexchangerates.org/api/time-series.json', query_vars, function(data) {\n    console.log(data);\n});","name":"jQuery","language":"javascript"}]},"settings":"","results":{"codes":[{"name":"","code":"\n{\n  \"disclaimer\": \"...\",\n  \"license\": \"...\",\n  \"start_time\": \"2017-07-17T11:00:00Z\",\n  \"end_time\": \"2017-07-17T11:29:59Z\",\n  \"base\": \"USD\",\n  \"rates\": {\n    \"EUR\": {\n      \"open\": 0.872674,\n      \"high\": 0.872674,\n      \"low\": 0.87203,\n      \"close\": 0.872251,\n      \"average\": 0.872253\n    },\n    \"GBP\": {\n      \"open\": 0.765284,\n      \"high\": 0.7657,\n      \"low\": 0.7652,\n      \"close\": 0.765541,\n      \"average\": 0.765503\n    },\n    \"HKD\": {\n      \"open\": 7.804003,\n      \"high\": 7.80568,\n      \"low\": 7.80399,\n      \"close\": 7.805248,\n      \"average\": 7.804725\n    }\n  }\n}","language":"json","status":200},{"language":"json","code":"{\n    \"error\": true,\n    \"status\": 400,\n    \"message\": \"invalid_start_time\",\n    \"description\": \"Invalid start: `start_time` must be in ISO 8601 format with 0 seconds and UTC timezone: YYYY-MM-DDTHH:MM:00Z.\"\n}","name":"Bad Request (invalid_start_time)","status":400},{"name":"Bad Request (invalid_period_for_start_time)","status":400,"language":"json","code":"{\n    \"error\": true,\n    \"status\": 400,\n    \"message\": \"invalid_period_for_start_time\",\n    \"description\": \"Invalid period for start time: `start_time` is invalid for the selected `period` in UTC time. Please see the documentation for details related to valid start time and period values.\"\n}"},{"name":"Bad Request (not_available)","status":400,"language":"json","code":"{\n    \"error\": true,\n    \"status\": 400,\n    \"message\": \"not_available\",\n    \"description\": \"The combination of start time and period used resulted in an end time that is in the future.\"\n}"}]},"method":"get","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 start time for the requested OHLC period (ISO-8601 format, UTC only). Restrictions apply (please see below).","default":"Required","type":"datetime","name":"start_time"},{"_id":"566b7c8a03870a0d008ee7a4","ref":"","in":"query","required":false,"desc":"The requested period (starting on the start_time), e.g. \"1m\", \"30m\", \"1d\". Please see below for supported OHLC periods.","default":"Required","type":"string","name":"period"},{"_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":"/ohlc.json"},"isReference":true,"order":5,"body":"[block:api-header]\n{\n  \"title\": \"\"\n}\n[/block]\n**The following parameters are available for OHLC requests:**\n\n**`app_id`** (required)\n\n  * Your Open Exchange Rates App ID\n\n**`start`** (required)\n\n  * A full ISO 8601 formatted timestamp in UTC timezone, with any hour/minute and zero seconds.\n  * Format: \"YYYY-MM-DDThh:mm:00Z\".\n  * Example: `&start=2017-07-17T08:30:00Z`.\n  * There are limitations to the start time, depending on the chosen `period` (see below).\n\n**`period`** (required)\n\n  * The requested time period for the OHLC data.\n  * Allowed periods are: `1m`, `5m`, `15m`, `30m`, `1h`, `12h`, `1d`, `1w`, and `1mo`.\n  * Example: `&period=30m`.\n  * There are limitations to the period, depending on the chosen 'start' time (see below).\n\n**`base`** (optional)\n\n  * Choose base currency for OHLC prices (default USD).\n  * Example: `&base=GBP`\n\n**`symbols`** (optional)\n  * Limit the number of currencies returned. Recommended to reduce file size.\n  * Example: `&symbols=XAU,XAG,XPD,XPT`\n\n**`show_alternative`** (optional)\n\n  * Include alternative, digital and black currency prices\n  * Example: `&show_alternative=true`\n\n**`prettyprint`** (optional)\n\n  * Get a human-readable (whitespace formatted) response. Not recommended for production use.\n  * Example: `&prettyprint=true`\n\n[block:api-header]\n{\n  \"title\": \"Limitations\"\n}\n[/block]\nThe following restrictions apply to the combination of `start_time` and `period`:\n\n- `start_time` must always have zero seconds (i.e. \"hh:mm**:00**\") and must be on/after December 19th 2016.\n- The format for `start_time` must be ISO-8601 and limited to UTC (timezones are not currently supported) – i.e: \"YYYY-MM-DD**T**hh:mm:00**Z**\".\n- Periods of `1m` must not start more than 60 minutes ago (i.e. `start_time` should be within the past hour).\n- Periods of `5m` must not start more than 24 hours ago, and must be aligned to a whole 5 minute period (e.g. 00, 05, 10, 15 etc.)\n- Periods of `15m` must not start more than 24 hours ago, and must be aligned to a whole 15 minute period (i.e. 00, 15, 30, 45)\n- Periods of `30m` or `60m`/`1h` must not start more than 32 days ago, and must be aligned to a whole 30 minute period (i.e. 00 or 30)\n- Periods of `12h` or `24h`/`1d` must be aligned to whole 30 minute period (i.e. 00, 30)\n- Periods of `7d`/`1w` must be aligned to the start of a whole calendar day (i.e. YYYY-MM-DDT**00**:00:00Z)\n- Periods of `1mo` must be aligned to the start of a whole calendar month (i.e. YYYY-MM-**01**T00:00:00Z)\n- The requested combination of `start_time` and `period` must not produce an `end_time` that is in the future (i.e. an incomplete period).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"With a full list of currencies, OHLC responses can be very large in size. For better performance, use the `symbols` parameter to cut down response weight, and set `prettyprint=false` to remove whitespace.\",\n  \"title\": \"Important\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"API Response Format\"\n}\n[/block]\nThe OHLC endpoint response format is similar to the standard API response in **latest.json**. Please familiarise yourself with the standard API response format before using this endpoint.\n\nThe `start_time` is the ISO-8601 formatted timestamp (UTC) of the start of period, corresponding to the 'open' rate.\n\nThe `end_time` is the ISO-8601 formatted timestamp (UTC) of the end of period (inclusive), corresponding to the 'close' rate. (For example, a period of `60m` would begin on `hh:00:00` and end on `hh:59:59`).\n\nThe `base` property provides the 3-letter currency code to which all the delivered exchange rates are relative.\n\nThe `rates` object contains an object for each currency in the result set, labelled by its international-standard 3-letter currency code. Each object contains five values:\n\n- `open` – The midpoint rate recorded at `start_time`\n- `high` – The highest midpoint rate recorded at any time during the period\n- `low` – The lowest midpoint rate recorded at any time during the period\n- `close` – The midpoint rate recorded at `end_time`\n- `average` – The time-weighted average midpoint exchange rate for the entire period\n\nAll the values are relative to 1 unit of the requested `base` currency.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"\"\n}\n[/block]\n\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 Open, High Low, Close (OHLC) and Average exchange rates for a given time period, ranging from 1 month to 1 minute, where available. Please read all the details before starting integration.\n\nValues for 'high', 'low' and 'average' are based on all recorded prices we published (up to every 1 second).\n\nOHLC requests are currently available for clients of our VIP Platinum tier.","slug":"ohlc-json","type":"endpoint","title":"/ohlc.json"}

get/ohlc.json

Get historical Open, High Low, Close (OHLC) and Average exchange rates for a given time period, ranging from 1 month to 1 minute, where available. Please read all the details before starting integration. Values for 'high', 'low' and 'average' are based on all recorded prices we published (up to every 1 second). OHLC requests are currently available for clients of our VIP Platinum tier.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

app_id:
stringRequired
Your unique App ID.
start_time:
datetimeRequired
The start time for the requested OHLC period (ISO-8601 format, UTC only). Restrictions apply (please see below).
period:
stringRequired
The requested period (starting on the start_time), e.g. "1m", "30m", "1d". Please see below for supported OHLC periods.
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:api-header] { "title": "" } [/block] **The following parameters are available for OHLC requests:** **`app_id`** (required) * Your Open Exchange Rates App ID **`start`** (required) * A full ISO 8601 formatted timestamp in UTC timezone, with any hour/minute and zero seconds. * Format: "YYYY-MM-DDThh:mm:00Z". * Example: `&start=2017-07-17T08:30:00Z`. * There are limitations to the start time, depending on the chosen `period` (see below). **`period`** (required) * The requested time period for the OHLC data. * Allowed periods are: `1m`, `5m`, `15m`, `30m`, `1h`, `12h`, `1d`, `1w`, and `1mo`. * Example: `&period=30m`. * There are limitations to the period, depending on the chosen 'start' time (see below). **`base`** (optional) * Choose base currency for OHLC prices (default USD). * Example: `&base=GBP` **`symbols`** (optional) * Limit the number of currencies returned. Recommended to reduce file size. * Example: `&symbols=XAU,XAG,XPD,XPT` **`show_alternative`** (optional) * Include alternative, digital and black currency prices * Example: `&show_alternative=true` **`prettyprint`** (optional) * Get a human-readable (whitespace formatted) response. Not recommended for production use. * Example: `&prettyprint=true` [block:api-header] { "title": "Limitations" } [/block] The following restrictions apply to the combination of `start_time` and `period`: - `start_time` must always have zero seconds (i.e. "hh:mm**:00**") and must be on/after December 19th 2016. - The format for `start_time` must be ISO-8601 and limited to UTC (timezones are not currently supported) – i.e: "YYYY-MM-DD**T**hh:mm:00**Z**". - Periods of `1m` must not start more than 60 minutes ago (i.e. `start_time` should be within the past hour). - Periods of `5m` must not start more than 24 hours ago, and must be aligned to a whole 5 minute period (e.g. 00, 05, 10, 15 etc.) - Periods of `15m` must not start more than 24 hours ago, and must be aligned to a whole 15 minute period (i.e. 00, 15, 30, 45) - Periods of `30m` or `60m`/`1h` must not start more than 32 days ago, and must be aligned to a whole 30 minute period (i.e. 00 or 30) - Periods of `12h` or `24h`/`1d` must be aligned to whole 30 minute period (i.e. 00, 30) - Periods of `7d`/`1w` must be aligned to the start of a whole calendar day (i.e. YYYY-MM-DDT**00**:00:00Z) - Periods of `1mo` must be aligned to the start of a whole calendar month (i.e. YYYY-MM-**01**T00:00:00Z) - The requested combination of `start_time` and `period` must not produce an `end_time` that is in the future (i.e. an incomplete period). [block:callout] { "type": "warning", "body": "With a full list of currencies, OHLC responses can be very large in size. For better performance, use the `symbols` parameter to cut down response weight, and set `prettyprint=false` to remove whitespace.", "title": "Important" } [/block] [block:api-header] { "title": "API Response Format" } [/block] The OHLC endpoint response format is similar to the standard API response in **latest.json**. Please familiarise yourself with the standard API response format before using this endpoint. The `start_time` is the ISO-8601 formatted timestamp (UTC) of the start of period, corresponding to the 'open' rate. The `end_time` is the ISO-8601 formatted timestamp (UTC) of the end of period (inclusive), corresponding to the 'close' rate. (For example, a period of `60m` would begin on `hh:00:00` and end on `hh:59:59`). The `base` property provides the 3-letter currency code to which all the delivered exchange rates are relative. The `rates` object contains an object for each currency in the result set, labelled by its international-standard 3-letter currency code. Each object contains five values: - `open` – The midpoint rate recorded at `start_time` - `high` – The highest midpoint rate recorded at any time during the period - `low` – The lowest midpoint rate recorded at any time during the period - `close` – The midpoint rate recorded at `end_time` - `average` – The time-weighted average midpoint exchange rate for the entire period All the values are relative to 1 unit of the requested `base` currency. [block:api-header] { "type": "basic", "title": "" } [/block] [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 }}