Market Data - REST API
RESTful endpoint provides the widest range of data, based on HTTP protocol which works in Request-Reply scheme.
Implemented Standards:
Endpoints
Enviroment | Encryption | Value |
---|---|---|
Production | Yes | https://rest.coinapi.io/ |
Production | No | http://rest.coinapi.io/ |
Sandbox | Yes | https://rest-sandbox.coinapi.io/ |
Sandbox | No | http://rest-sandbox.coinapi.io/ |
Sandbox
The sandbox environment is provided for development and non-production use-cases, it has few differences in comparison to the production one:
- You still need active API Key to access the sandbox; it can be a free one.
- We do not provide any support or SLA for this environment.
- Real-time and historical data is limited to specific data sources: COINBASE, GEMINI, testnets, UAT environments and ECB (European Central Bank).
- Data could be invalid/fake or delayed.
- API changes could be visible faster on the sandbox than in the production environment.
General
Authorization
To use resources that require authorized access, you will need to provide an API key to us when making HTTP requests.
There are 2 methods for passing the API key to us, you only need to use one:
- Custom authorization header named
X-CoinAPI-Key
- Query string parameter named
apikey
Custom authorization header
You can authorize by providing additional custom header named X-CoinAPI-Key
and API key as its value.
Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY
, then the authorization header you should send to us will look like:
X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY
Query string authorization parameter
You can authorize by providing an additional parameter named apikey
with a value equal to your API key in the query string of your HTTP request.
Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY
and that you want to request all exchange rates from BTC
asset, then your query string should look like this: GET /v1/exchangerate/BTC?apikey=73034021-THIS-IS-SAMPLE-KEY
HTTP Requests
Each HTTP request must contain the header Accept: application/json
as all our responses are in JSON format.
We encourage you to use the HTTP request header Accept-Encoding: deflate, gzip
for all requests.
This will indicate to us that we can deliver compressed data to you which on your side should be decompressed transparently.
HTTP Success
Successful HTTP responses have the status code 200
and the body in a format according to documentation of the requested resource.
HTTP Errors
Error message is returned in JSON structured like this:
{
"message": "Invalid API key"
}
All HTTP requests with response status codes different to 200
must be considered as failed
and you should expect additional JSON inside the body of the response with the error message encapsulated inside it as shown in the example.
We use the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- There is something wrong with your request |
401 | Unauthorized -- Your API key is wrong |
403 | Forbidden -- Your API key doesnt't have enough privileges to access this resource |
429 | Too many requests -- You have exceeded your API key rate limits |
550 | No data -- You requested specific single item that we don't have at this moment. |
Limits
Any authenticated endpoint is providing (in HTTP response headers) information about the current state of the limits associated with API Key. In this section we will describe each limit.
Request limit / APIKey
X-RateLimit-Limit: 1000000
X-RateLimit-Remaining: 999989
X-RateLimit-Request-Cost: 1
X-RateLimit-Reset: 2018-01-22T15:25:15.1234567Z
The request limit define number of maximum requests that could be executed in the 24 hours period (sliding/rollowing window - always last 24 hours from specific moment) for your subscription.
We define request as data request credits and this is not always equal to the number of API calls executed against the API. A request is deemed to be a single one if the limit query parameter on the endpoint isn’t available, isn’t used or it's stated otherwise in the API documentation. Otherwise — if the limit query parameter is available and is used — then each of the 100 data points returned in the response is counted as one request.
For example at the 2019-08-22 13:00 UTC value of the requests remaining (X-RateLimit-Remaining) will be equal to the allocated quota (X-RateLimit-Limit) decreased by the sum of the request costs (SUM(X-RateLimit-Request-Cost)) executed in the period 2019-08-21 13:00 UTC - 2019-08-22 13:00 UTC (last 24 hours).
HTTP Header | Type | Description |
---|---|---|
X-RateLimit-Used | int | Request limit used (in the last 24-hours period). |
X-RateLimit-Limit | int | Request limit allocated (in the last 24-hours period). |
X-RateLimit-Remaining | int | The number of requests left at the moment based on the last 24-hour usage. |
X-RateLimit-Request-Cost | int | The number of requests used to generate current HTTP response. |
X-RateLimit-Reset | timestring | The time when all provisioned requests are available to execute again if no more requests will be executed. |
X-RateLimit-Overage | string | Status of the overage mode. Allowed values: ENABLED or DISABLED . |
Concurrency limit / APIKey
X-ConcurrencyLimit-Limit: 10
X-ConcurrencyLimit-Remaining: 5
The concurrency limit defines the number of maximum concurrent API calls/requests that the API could process for your subscription at the current moment. Every API call/request increases the Concurrency limit against quota, and when it finishes, decreases it.
HTTP Header | Type | Description |
---|---|---|
X-ConcurrencyLimit-Limit | int | Concurrency limit allocated for your API key. |
X-ConcurrencyLimit-Remaining | int | The number of concurrent API calls/requests available to be executed in this moment for your API key. |
Output data format
By default we are using JSON output data format for all of our endpoints, you can control format of data by using output_format
variable in query string parameters.
URL Parameters
Parameter | Type | Description |
---|---|---|
output_format | string | Output data format (optional, default value is json , possible values are json , xml or csv ) |
csv_include_header | bool | Ignore header line in CSV output? (optional, default value is true , true to include CSV header line, false otherwise) |
csv_include_quotes | bool | Encapsulate strings with quotes in CSV output? (optional, default value is false , true to encapsulate all strings with " , false to leave them unquoted) |
csv_exclude_col | string | Comma delimited list of column names to ignore in CSV output (optional, by default all columns are included) |
csv_set_delimiter | string | Character that will be used as column delimiter in CSV output (optional, default value is ; ) |
csv_set_dec_mark | string | Character that will be used as decimal separator in CSV output (optional, default value is . ) |
csv_set_timeformat | string | Format for datetime type in CSV output or unix for unix timestamp (optional, default value is yyyy-MM-ddTHH:mm:ss.fffffffZ ) |
csv_set_newline | string | New line type (optional, default value is unix , possible values win , mac , unix ) |
Excel / G-Sheets
There are several ways to use data from our REST API inside the Excel, Google Sheets, or similar calculation sheet application. This section will do as best as possible to keep all information up to date on how you could load the data into these applications. Feel free to contact support if we are missing an option.
CSV download, import:
- Open the data in the CSV format from the browser eg.
https://rest.coinapi.io/v1/exchangerate/USD?apikey=YOUR_API_KEY&invert=true&output_format=csv
- Save the data to the file with the .csv extension.
- Use the file saved and import it into the software.
- When configuring import, refer to the parameters like delimiter from the Output data format
The platform-independent way described above is based on CSV but could also be used in other formats like JSON and XML as long as the software support it, but the import procedure needs to be adjusted accordingly.
Microsoft Excel
- Use PowerQuery (opens in a new tab) to load the URL directly into the CSV import without saving the file locally.
- Use the =WEBSERVICE (opens in a new tab) function to load the API response directly into the sheet, but this will not parse the data; additional processing is required.
Google Sheets
- Use =IMPORT (opens in a new tab) function to load the REST API endpoint and automatically parse the CSV format data into the cells. eg.
=IMPORTDATA("https://rest.coinapi.io/v1/exchangerate/USD?apikey=YOUR_API_KEY&invert=true&output_format=csv
OpenOffice Calc
- Select the menu Insert -> Sheet From File, 2. In the Insert dialog, put the URL eg.
https://rest.coinapi.io/v1/exchangerate/USD?apikey=YOUR_API_KEY&invert=true&output_format=csv
in the File Name box at the bottom. Set the drop-down list next to that to Web Page Query and click Open. The Text Import dialog opens where you can change the defaults if needed.