GRgridstatus
Query Data

Query Dataset

Changed on

Query a dataset and return matching rows as JSON or CSV.

JSON rows stream directly from a Postgres server-side cursor instead of being buffered in memory first (JSON only; CSV and external datasets always buffer). The result-dependent X-Has-Next-Page and X-rows-in-response headers are omitted from streamed responses -- read pagination from the JSON meta.hasNextPage and meta.cursor fields.

get/datasets/{dataset_id}/query

Request

Path parameters

dataset_idstring required

ID of the dataset to query

Query parameters

api_keystring nullable

API key for authentication (query)

order'asc' | 'desc'

The order to order results by

filter_columnstring nullable

The column to filter results by

integer
OR
number
OR
string
filter_operator'=' | '!=' | '>' | '>=' | '<' | '<=' | 'in'
limitinteger nullable

The maximum number of rows to return across all pages

pageinteger

The page number of results to return

page_sizeinteger nullable

The maximum number of rows to return in a single page

string[]
OR
string
cursorstring nullable
timezonestring nullable

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.

string
OR
string date-time
time_comparison'=' | '>' | '>=' | '<' | '<=' nullable

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.

string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
resample_frequencystring nullable

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
string[]
OR
string
resample_function'mean' | 'sum' | 'min' | 'max' | 'count' | 'stddev' | 'variance'

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

return_format'json' | 'csv'

The return format of the response

downloadboolean

Whether to download the file or not

json_schema'array-of-objects' | 'array-of-arrays'

The json schema of the response

Headers

x-api-keystring nullable

API key for authentication (header)

Response

Successful response

OR

Changes

  • 31ad4f0c6816Revision changes
    • info

      added the optional property // to the response with the status