Query Data

Query Dataset

get

Path parameters

dataset_idstringRequired

ID of the dataset to query

Query parameters

api_keyany ofOptional

API key for authentication (query)

stringOptional

or

nullOptional

orderany ofOptional

The order to order results by

Default: asc

string · enumOptionalPossible values:

or

nullOptional

filter_columnany ofOptional

The column to filter results by

stringOptional

or

nullOptional

filter_valueany ofOptional

The value to filter results by

integerOptional

or

numberOptional

or

stringOptional

or

nullOptional

filter_operatorany ofOptionalDefault: =

string · enumOptionalPossible values:

or

nullOptional

limitany ofOptional

The maximum number of rows to return across all pages

integerOptional

or

nullOptional

pageintegerOptional

The page number of results to return

Default: 1

page_sizeany ofOptional

The maximum number of rows to return in a single page

integerOptional

or

nullOptional

columnsany ofOptional

Comma separated list of columns to return. Defaults to all columns.

string[]Optional

or

stringOptional

or

nullOptional

cursorany ofOptional

stringOptional

or

nullOptional

timezoneany ofOptional

The timezone to use when interpreting timezone naive timestamps, resampling to frequencies one day or more, and returning results. A value of marketcan be provided to return results in the timezone of the source ISO for the dataset. If market is specified and the dataset does not have a source ISO, the timezone will default to UTC for the query. When provided, columns in the timezone will be suffixed with _local.

Default: UTC

stringOptional

or

nullOptional

timeany ofOptional

The time to filter results. Cannot be used with start_time or end_time.

Possible values:

• 'latest': Fetches the most recently reported data point.

• A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.

stringOptional

or

string · date-timeOptional

or

nullOptional

time_comparisonany ofOptional

The comparison operator to use when filtering by time.

Possible values:

• '=': Fetches the data at the exact time.

• '>': Fetches the earliest data after the provided time.

• '>=': Fetches the earliest data on or after the provided time.

• '<': Fetches the latest data before the provided time.

• '<=': Fetches the latest data on or before the provided time.

Default: =

string · enumOptionalPossible values:

or

nullOptional

start_timeany ofOptional

The start time to filter results using the dataset's time_index_column. Data on or after this time will be returned. Only applies to datasets with a time_index_column

stringOptional

or

string · date-timeOptional

or

nullOptional

end_timeany ofOptional

The end time to filter results using the dataset's time_index_column. Data before this time will be returned. Only applies to datasets with a time_index_column

stringOptional

or

string · date-timeOptional

or

nullOptional

publish_timeany ofOptional

Controls the filtering based on the dataset's publish time.

Cannot be combined with publish_time_start or publish_time_end.Note: a dataset must have a time index column to use 'latest' or 'latest_before:' options.

Possible values:

• 'latest_report': Returns records only from the most recently published report.

• 'latest': For any given timestamp, fetches the most recently reported data point associated with it.

• A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.

• 'latest_before:': Return the most recent forecast for each operating time where publish_time <= operating_time + offset (e.g., 'latest_before:-6 hours').

• 'latest_before': shorthand for 'latest_before:-0 hours'. Used to get the most recent forecast prior to each operating time. This is useful because some forecasts are published after the operating time they are forecasting for.

• 'latest_before:@HH:MM:SS': Return the latest forecast published before the specified time on the offset day (e.g., 'latest_before:-1 day@10:00:00').

• 'window':: Returns all forecasts for each operating time published between the specified offset from the operating time and the operating time. In other words, where operating_time + offset <= publish_time <= operating_time. (e.g., 'window:-6 hours').

• 'window:@HH:MM:SS': Returns all forecasts for each operating time published between the specified time on the offset day from the operating time and the operating time (e.g., 'window:-1 day@10:00:00').

• None: No filtering based on publish time.

stringOptional

or

string · date-timeOptional

or

nullOptional

publish_time_startany ofOptional

The start time to filter results using the dataset's publish_time_column. Data on or after this time will be returned up to the publish_time_end if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time.

stringOptional

or

string · date-timeOptional

or

nullOptional

publish_time_endany ofOptional

The end time to filter results using the dataset's publish_index_column. Data before this time will be returned down the publish_time_start if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time.

stringOptional

or

string · date-timeOptional

or

nullOptional

resample_frequencyany ofOptional

The frequency to resample the data to. Must be one of:

• "1 minute"
• "5 minutes"
• "10 minutes"
• "15 minutes"
• "1 hour"
• "1 day"
• "1 week"
• "1 month"
• "1 year"

When resampling_frequency is specified, start_time and end_time values must also be provided. The only exception to this is when querying datasets that have a publish time and the publish time is specified as a specific timestamp or 'latest_report'.

Additionally, the number of days of data that can be queried is limited based on the resample frequency. The maximum number of days of data that can be queried for each resample frequency is listed below. There is no limit on days for resample frequencies not listed below.

• 1 minute: 31 days
• 5 minutes: 100 days
• 10 minutes: 120 days
• 15 minutes: 180 days
• 1 hour: 365 days
• 1 day: 1825 days

stringOptional

or

nullOptional

resample_byany ofOptional

A comma separated list of columns to group by before resampling.

• When resampling, the data is always grouped by the time index column of the dataset.

• If a value is provided for resample_by, the data will be grouped by the provided columns in addition to the time index column.

• If the dataset has a subseries index and no value is provided for resample_by, the data will also be grouped by the subseries index column.

• If the dataset has a publish time column and the publish_time parameter is not 'latest', the data will also be grouped by the publish time column.

string[]Optional

or

stringOptional

or

nullOptional

resample_functionany ofOptional

The function to use when resampling. Defaults to "mean". Possible values are "mean", "sum", "min", "max", "stddev", "count". If resample is None, this is ignored.

Default: mean

string · enumOptionalPossible values:

or

nullOptional

return_formatstring · enumOptional

The return format of the response

Default: jsonPossible values:

downloadbooleanOptional

Whether to download the file or not

Default: false

json_schemastring · enumOptional

The json schema of the response

Default: array-of-objectsPossible values:

Header parameters

x-api-keyany ofOptional

API key for authentication (header)

stringOptional

or

nullOptional

Responses

200

Successful response

application/json

or

422

Validation Error

application/json

get

/datasets/{dataset_id}/query

HTTPcURLJavaScriptPython

GET /v1/datasets/{dataset_id}/query HTTP/1.1
Host: api.gridstatus.io
Accept: */*

{
  "status_code": 200,
  "data": [
    {
      "interval_start_local": "2018-04-10T00:00:00-07:00",
      "interval_start_utc": "2018-04-10T07:00:00+00:00",
      "interval_end_local": "2018-04-10T00:05:00-07:00",
      "interval_end_utc": "2018-04-10T07:05:00+00:00",
      "load": 22459
    },
    {
      "interval_start_local": "2018-04-10T00:05:00-07:00",
      "interval_start_utc": "2018-04-10T07:05:00+00:00",
      "interval_end_local": "2018-04-10T00:10:00-07:00",
      "interval_end_utc": "2018-04-10T07:10:00+00:00",
      "load": 22371
    },
    {
      "interval_start_local": "2018-04-10T00:10:00-07:00",
      "interval_start_utc": "2018-04-10T07:10:00+00:00",
      "interval_end_local": "2018-04-10T00:15:00-07:00",
      "interval_end_utc": "2018-04-10T07:15:00+00:00",
      "load": 22330
    }
  ],
  "meta": {
    "page": 1,
    "limit": 1000,
    "page_size": 100000,
    "hasNextPage": false
  },
  "dataset_metadata": {
    "id": "caiso_load",
    "name": "CAISO Load",
    "time_index_column": "interval_start_utc",
    "all_columns": [
      {
        "name": "interval_start_local",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_start_utc",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_end_local",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_end_utc",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "load",
        "type": "INTEGER",
        "is_date": false,
        "is_datetime": false,
        "is_numeric": true
      }
    ]
  }
}

Query Dataset by column value

get

Query a dataset by a column value

This is a shortcut for /datasets/{dataset_id}/query?filter_column={filter_column}&filter_value={filter_value}

Path parameters

dataset_idstringRequired

filter_column_idstringRequired

ID of the column to filter by

filter_value_pathstringRequired

Value to filter by

Query parameters

api_keyany ofOptional

API key for authentication (query)

stringOptional

or

nullOptional

return_formatstring · enumOptional

The return format of the response

Default: jsonPossible values:

downloadbooleanOptional

Whether to download the file or not

Default: false

json_schemastring · enumOptional

The json schema of the response

Default: array-of-objectsPossible values:

orderany ofOptional

The order to order results by

Default: asc

string · enumOptionalPossible values:

or

nullOptional

filter_columnany ofOptional

The column to filter results by

stringOptional

or

nullOptional

filter_valueany ofOptional

The value to filter results by

integerOptional

or

numberOptional

or

stringOptional

or

nullOptional

filter_operatorany ofOptionalDefault: =

string · enumOptionalPossible values:

or

nullOptional

limitany ofOptional

The maximum number of rows to return across all pages

integerOptional

or

nullOptional

pageintegerOptional

The page number of results to return

Default: 1

page_sizeany ofOptional

The maximum number of rows to return in a single page

integerOptional

or

nullOptional

columnsany ofOptional

Comma separated list of columns to return. Defaults to all columns.

string[]Optional

or

stringOptional

or

nullOptional

cursorany ofOptional

stringOptional

or

nullOptional

timezoneany ofOptional

The timezone to use when interpreting timezone naive timestamps, resampling to frequencies one day or more, and returning results. A value of marketcan be provided to return results in the timezone of the source ISO for the dataset. If market is specified and the dataset does not have a source ISO, the timezone will default to UTC for the query. When provided, columns in the timezone will be suffixed with _local.

Default: UTC

stringOptional

or

nullOptional

timeany ofOptional

The time to filter results. Cannot be used with start_time or end_time.

Possible values:

• 'latest': Fetches the most recently reported data point.

• A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.

stringOptional

or

string · date-timeOptional

or

nullOptional

time_comparisonany ofOptional

The comparison operator to use when filtering by time.

Possible values:

• '=': Fetches the data at the exact time.

• '>': Fetches the earliest data after the provided time.

• '>=': Fetches the earliest data on or after the provided time.

• '<': Fetches the latest data before the provided time.

• '<=': Fetches the latest data on or before the provided time.

Default: =

string · enumOptionalPossible values:

or

nullOptional

start_timeany ofOptional

The start time to filter results using the dataset's time_index_column. Data on or after this time will be returned. Only applies to datasets with a time_index_column

stringOptional

or

string · date-timeOptional

or

nullOptional

end_timeany ofOptional

The end time to filter results using the dataset's time_index_column. Data before this time will be returned. Only applies to datasets with a time_index_column

stringOptional

or

string · date-timeOptional

or

nullOptional

publish_timeany ofOptional

Controls the filtering based on the dataset's publish time.

Cannot be combined with publish_time_start or publish_time_end.Note: a dataset must have a time index column to use 'latest' or 'latest_before:' options.

Possible values:

• 'latest_report': Returns records only from the most recently published report.

• 'latest': For any given timestamp, fetches the most recently reported data point associated with it.

• A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.

• 'latest_before:': Return the most recent forecast for each operating time where publish_time <= operating_time + offset (e.g., 'latest_before:-6 hours').

• 'latest_before': shorthand for 'latest_before:-0 hours'. Used to get the most recent forecast prior to each operating time. This is useful because some forecasts are published after the operating time they are forecasting for.

• 'latest_before:@HH:MM:SS': Return the latest forecast published before the specified time on the offset day (e.g., 'latest_before:-1 day@10:00:00').

• 'window':: Returns all forecasts for each operating time published between the specified offset from the operating time and the operating time. In other words, where operating_time + offset <= publish_time <= operating_time. (e.g., 'window:-6 hours').

• 'window:@HH:MM:SS': Returns all forecasts for each operating time published between the specified time on the offset day from the operating time and the operating time (e.g., 'window:-1 day@10:00:00').

• None: No filtering based on publish time.

stringOptional

or

string · date-timeOptional

or

nullOptional

publish_time_startany ofOptional

The start time to filter results using the dataset's publish_time_column. Data on or after this time will be returned up to the publish_time_end if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time.

stringOptional

or

string · date-timeOptional

or

nullOptional

publish_time_endany ofOptional

The end time to filter results using the dataset's publish_index_column. Data before this time will be returned down the publish_time_start if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time.

stringOptional

or

string · date-timeOptional

or

nullOptional

resample_frequencyany ofOptional

The frequency to resample the data to. Must be one of:

• "1 minute"
• "5 minutes"
• "10 minutes"
• "15 minutes"
• "1 hour"
• "1 day"
• "1 week"
• "1 month"
• "1 year"

When resampling_frequency is specified, start_time and end_time values must also be provided. The only exception to this is when querying datasets that have a publish time and the publish time is specified as a specific timestamp or 'latest_report'.

Additionally, the number of days of data that can be queried is limited based on the resample frequency. The maximum number of days of data that can be queried for each resample frequency is listed below. There is no limit on days for resample frequencies not listed below.

• 1 minute: 31 days
• 5 minutes: 100 days
• 10 minutes: 120 days
• 15 minutes: 180 days
• 1 hour: 365 days
• 1 day: 1825 days

stringOptional

or

nullOptional

resample_byany ofOptional

A comma separated list of columns to group by before resampling.

• When resampling, the data is always grouped by the time index column of the dataset.

• If a value is provided for resample_by, the data will be grouped by the provided columns in addition to the time index column.

• If the dataset has a subseries index and no value is provided for resample_by, the data will also be grouped by the subseries index column.

• If the dataset has a publish time column and the publish_time parameter is not 'latest', the data will also be grouped by the publish time column.

string[]Optional

or

stringOptional

or

nullOptional

resample_functionany ofOptional

The function to use when resampling. Defaults to "mean". Possible values are "mean", "sum", "min", "max", "stddev", "count". If resample is None, this is ignored.

Default: mean

string · enumOptionalPossible values:

or

nullOptional

Header parameters

x-api-keyany ofOptional

API key for authentication (header)

stringOptional

or

nullOptional

Responses

200

Successful response

application/json

or

422

Validation Error

application/json

get

/datasets/{dataset_id}/query/{filter_column_id}/{filter_value_path}

HTTPcURLJavaScriptPython

GET /v1/datasets/{dataset_id}/query/{filter_column_id}/{filter_value_path} HTTP/1.1
Host: api.gridstatus.io
Accept: */*

{
  "status_code": 200,
  "data": [
    {
      "interval_start_local": "2018-04-10T00:00:00-07:00",
      "interval_start_utc": "2018-04-10T07:00:00+00:00",
      "interval_end_local": "2018-04-10T00:05:00-07:00",
      "interval_end_utc": "2018-04-10T07:05:00+00:00",
      "load": 22459
    },
    {
      "interval_start_local": "2018-04-10T00:05:00-07:00",
      "interval_start_utc": "2018-04-10T07:05:00+00:00",
      "interval_end_local": "2018-04-10T00:10:00-07:00",
      "interval_end_utc": "2018-04-10T07:10:00+00:00",
      "load": 22371
    },
    {
      "interval_start_local": "2018-04-10T00:10:00-07:00",
      "interval_start_utc": "2018-04-10T07:10:00+00:00",
      "interval_end_local": "2018-04-10T00:15:00-07:00",
      "interval_end_utc": "2018-04-10T07:15:00+00:00",
      "load": 22330
    }
  ],
  "meta": {
    "page": 1,
    "limit": 1000,
    "page_size": 100000,
    "hasNextPage": false
  },
  "dataset_metadata": {
    "id": "caiso_load",
    "name": "CAISO Load",
    "time_index_column": "interval_start_utc",
    "all_columns": [
      {
        "name": "interval_start_local",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_start_utc",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_end_local",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_end_utc",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "load",
        "type": "INTEGER",
        "is_date": false,
        "is_datetime": false,
        "is_numeric": true
      }
    ]
  }
}