Technical Reference

This part of the API documentation provides general setup details, and technical information about the API’s requirements, data formats, and limitations. See the separate sections for information about data queries or data and schemas available to you.

Authentication

Authentication with the Metamarkets API is performed via an “Authorization” header. Retrieve your token from the API token page and present it as follows:

  Authorization: Bearer <token>

Important security note: Carefully protect your API key. It grants the same data access as your regular Metamarkets username and password, so treat it as if you would your password. Do not add your API key to a code repository or share it in a screenshot.

If you think your key may have been shared accidentally, visit the API token page and revoke your token. This will eliminate all access via that token, and allow you to generate a fresh token.

Interval specification

All data queries require specification of a time window of interest. Data will be only included when it was timestamped within this interval. This is how you specify data ‘from the previous month’ or ‘from March 8 this year’. The interval parameter is specified in ISO 8601 format.

While there are other reference sources that give information about the ISO 8601 format,
note that:

  • Dates are in YYYY-MM-DD format. You may use a hyphen or a minus sign to separate the components of the date.
  • Separate the date, and an optional time, with a T.
  • Times are in HH:MM:SS format. You can freely omit minutes or seconds, and the time will be treated as ending with 00:00.
  • You can specify an optional time zone by appending a Z to the time for UTC, or an offset such as -07 (UTC – 7 hours) or +13 (UTC + 13 hours). An omitted time zone will be interpreted as UTC.
  • Use 00 as the hours to specify midnight at the beginning of a day, and 24 to specify midnight at the end of a day.
  • Durations can be specified as P3W (three weeks), P4D (four days), or PT5H (5 hours). Note the extra T for time durations.

There are four ways you may express a time interval:

  • By start and end, eg:

2016-03-08T00Z/2016-03-08T24Z

  • By start and duration, eg:

2016-03-08T00Z/P7D
2016-03-08T00Z/PT12H

  • By duration and end, eg:

P7D/2016-03-15T24

  • By duration only. Here, intervals will be interpreted as ending at the present time:

P1D
PT1H

Example time intervals

Some example intervals are:

Interval Value Meaning
2016-03-08/2016-03-09 Two days of data, including all of the 8th and the 9th
2016-03-08T00/2016-03-09T24 48 full hours of data, same as above, including all of the 8th and the 9th
2016-03-08/P7D 7 full days of data, including all of the 8th and all of the 14th
2016-03-08/PT12H The first half of the 8th, from 12am at the beginning of the day to 12pm (noon)
P7D/2016-03-08T24 7 full days of data, ending at the end of the 8th, and including the 2nd but not the 1st
P7D/2016-03-08 Same as above, 7 full days of data, including all of the 8th and none of the 1st
P1D The most recent day of data
PT1H The most recent hour of data
2016-03-08T00Z/2016-03-09T24-07 Exactly the same as the above, just with an optional timezone added
2016-03-08T00-07/2016-03-09T24-07 48 full hours of data, with the 8th and 9th in pacific daylight time

Rate limits

Rate limits apply to all users of the API. These vary with the pricing plan you choose. We limit both the number of in-flight queries per key as well as the total number of calls per key per day. We include the following headers in all responses to explain these limits:

  X-RateLimit-Limit: <the number of requests permitted per window>
  X-RateLimit-Remaining: <the number of requests remaining in the current window>
  X-RateLimit-Reset: <the time, in epoch seconds, when the limit window next resets>

Versioning

We use Semantic Versioning 2.0.0 (see semver.org) to support changes in our API. You may specify the version you wish to use in a header. If you do not specify a version, the API will use the latest available version. Following semver.org, we use MAJOR.MINOR.PATCH to version our API, where MAJOR is incremented when we make incompatible API changes, MINOR is incremented with the addition of backwards-compatible functionality, and PATCH is incremented with backwards-compatible bug fixes.

Indicate the version you would like using an ‘Accept-Version’ header, for example:

Accept-Version: ~1     // for the latest minor and patch of major version 1
Accept-Version: <2.2.0 // for anything before 2.2.0
Accept-Version: *      // for the latest version (or just omit the header)

We do not expect most users to have to specify an API version.

Error Codes

We use HTTP response codes and status messages to provide rich, relevant information about failed queries. You may see the following error codes:

Codes Type Description
200 OK For successful queries
204 No content When a query is valid but the response contains no data
400 Bad request When there is a generic error in the request and we do not have a more specific error message
401 Unauthorized When no key is supplied
403 Forbidden When a key or data view is supplied but is incorrect
404 Not found When an invalid endpoint is requested
405 Method not allowed When the wrong method is used on a valid endpoint
429 Too many requests When we are rate-limiting queries
500 Internal server error When we have an internal error
503 Service unavailable When our API is down or overloaded
504 Bad gateway An alternative that may occur when our service is unhealthy or down

All errors with a 4xx or 5xx response code will include a JSON error message response of
the form:

  { "message": "Incorrect key" }