Overview

Welcome to the Derapi API Reference. Here you will find details about interacting with the API and details for each endpoint.

The API is standard REST + JSON over HTTPS fully documented with OpenAPI 3.1.

We aim to comply with all major RFCs for HTTP(S) and choose the most user-friendly standard when there are competing options for our API.

SDKs

Derapi offers SDKs to more easily integrate with Derapi APIs. Our SDKs are regularly updated.

Available APIs:

• Python derapi-python

If your preferred program language is not list please contact [email protected].

Versioning

The Derapi API maintains versions in the format vYYYY-MM-DD. The current version is v2024-09-01. Version can be specified by setting the header api-version.

Errors

Derapi uses standard HTTP response codes to signal success or failure. In cases of failure, Derapi's response includes a description of the failure in JSON format.

When possible, programmatic details specifying your issues with your request (and any possibly remedy) will be returned.

See our errors page for details.

Pagination

List endpoints are paginated. Query string parameters pageSize and pageToken can be provided to control the pagination behavior; a property nextPageToken will be present in the response when there are more results to view. Responses may also include totalSize where available.

To get all results, in pseudocode:

results, nextPageToken = listOperation(pageSize)
while nextPageToken is not null:
    nextPage, nextPageToken = listOperation(nextPageToken)
    results += nextPage

Interval Data endpoints

Our API defines a number of interval data endpoints. These endpoints are parameterized with start, end, and summaryLevel query parameters. None of them are required, but they can all be used to construct your desired window of returned data.

Start and end are used in a standard, right-open or end-exclusive interval notation -- i.e. [start, end). The minimum value for start is the operationalSince of a site; the maximum value for end is now. Requesting data beyond operationalSince or now is a 422 error. Requesting a window size (end - start) greater than the maximum allowed for the summary level is a 422 error.

Missing Data

Within operationalSince and now, a vendor may not have data for a given interval. In such cases, our API still returns an interval with "missing": true. Our API is explicit about missing data to empower our clients and help them avoid errors in their calculations; however, if so desired, clients can pass missing=drop to omit any known missing intervals from our response. Note that, when there is missing data (particularly in the recent past), later retries may provide the data due to vendor processing latency.

Maximum window sizes

end - start has the following limits per summary level:

Defaulting

If you don't provide any parameters, we default to the last three days of hourly data.

In most cases, summaryLevel will default to hour; if you do not specify summaryLevel but do specify both start and end, we will choose a compatible summaryLevel automatically.

If only one of start or end is provided, the other will be inferred using the following default window sizes for the provided summaryLevel.

Custom formats

Currently, Derapi extends the OpenAPI 3.1 standard with a single custom format.

date-time-tz

Where the API expects or returns date times, they are specified with the custom format date-time-tz. A date-time-tz value must specify a timezone in one of the valid ISO8601 standards.

For example:

• 2021-01-01T00:00:00-7:00
• 2021-01-01T00:00Z
• 2021-01-01T00:00+0:00

Example incorrect values:

• 2021-01-01T00:00