Grid Status Query Data API

openapi: 3.2.0
info:
  title: Grid Status Query Data API
  description: The Grid Status hosted API provides programmatic access to United States and Canadian electricity grid and power market data across CAISO, ERCOT, IESO, ISONE, MISO, NYISO, PJM, and SPP.
  version: 1.3.0
  contact:
    name: Grid Status
    url: https://www.gridstatus.io
    email: contact@gridstatus.io
servers:
- url: https://api.gridstatus.io/v1
  description: Grid Status hosted API
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: Query Data
  description: Query dataset rows with filters, resampling, and pagination.
paths:
  /datasets/{dataset_id}/query:
    get:
      operationId: queryDataset
      tags:
      - Query Data
      summary: Query a dataset
      description: Query a dataset and return matching rows as JSON or CSV. Example dataset IDs include ercot_spp_day_ahead_hourly (ERCOT day-ahead settlement point prices), ercot_fuel_mix, ercot_as_prices, caiso_load, caiso_lmp_real_time_5_min, and pjm_lmp_real_time_5_min. Pass the X-Stream true request header to stream JSON rows from a server-side cursor instead of buffering the whole result (JSON only); in streaming mode read pagination from the JSON meta.hasNextPage and meta.cursor fields.
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: start_time
        in: query
        description: Start of the time range filter on the dataset's time index column (ISO 8601). Rows on or after this time are returned.
        schema:
          type: string
      - name: end_time
        in: query
        description: End of the time range filter on the dataset's time index column (ISO 8601). Rows before this time are returned.
        schema:
          type: string
      - name: time
        in: query
        description: Point-in-time filter. Accepts 'latest' or an ISO 8601 timestamp. Cannot be combined with start_time or end_time.
        schema:
          type: string
      - name: time_comparison
        in: query
        description: Comparison operator used when filtering by time.
        schema:
          type: string
          enum:
          - '='
          - '>'
          - '>='
          - <
          - <=
      - name: publish_time
        in: query
        description: Filter based on the dataset's publish time column.
        schema:
          type: string
      - name: publish_time_start
        in: query
        description: Start of a publish-time range filter.
        schema:
          type: string
      - name: publish_time_end
        in: query
        description: End of a publish-time range filter.
        schema:
          type: string
      - name: filter_column
        in: query
        description: The column to filter results by (for example location).
        schema:
          type: string
      - name: filter_value
        in: query
        description: The value to filter results by.
        schema:
          type: string
      - name: filter_operator
        in: query
        description: Operator applied between filter_column and filter_value.
        schema:
          type: string
          enum:
          - '='
          - '!='
          - '>'
          - '>='
          - <
          - <=
          - in
          default: '='
      - name: columns
        in: query
        description: Comma separated list of columns to return. Defaults to all columns.
        schema:
          type: string
      - name: order
        in: query
        description: Sort order of results.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: limit
        in: query
        description: Maximum number of rows to return across all pages.
        schema:
          type: integer
      - name: page
        in: query
        description: Page number of results to return.
        schema:
          type: integer
          default: 1
      - name: page_size
        in: query
        description: Maximum number of rows to return in a single page.
        schema:
          type: integer
      - name: cursor
        in: query
        description: Cursor for cursor-based pagination.
        schema:
          type: string
      - name: timezone
        in: query
        description: Timezone used when interpreting timezone-naive timestamps and when resampling to frequencies of one day or longer.
        schema:
          type: string
      - name: resample_frequency
        in: query
        description: Frequency to resample the data to, from '1 minute' through '1 year' (for example '5 minutes', '1 hour', '1 day', '1 month').
        schema:
          type: string
      - name: resample_by
        in: query
        description: Comma separated list of columns to group by before resampling.
        schema:
          type: string
      - name: resample_function
        in: query
        description: Aggregation function used when resampling.
        schema:
          type: string
          enum:
          - mean
          - sum
          - min
          - max
          - count
          - stddev
          - variance
          default: mean
      - $ref: '#/components/parameters/ReturnFormat'
      - name: json_schema
        in: query
        description: Shape of the JSON response.
        schema:
          type: string
          enum:
          - array-of-objects
          - array-of-arrays
          default: array-of-objects
      - name: download
        in: query
        description: Whether to return the result as a file download.
        schema:
          type: boolean
          default: false
      - name: X-Stream
        in: header
        description: Set to true to stream JSON rows from a server-side cursor.
        schema:
          type: boolean
      responses:
        '200':
          description: Matching rows plus pagination and dataset metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryDatasetResponse'
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /datasets/{dataset_id}/query/{filter_column_id}/{filter_value_path}:
    get:
      operationId: queryDatasetByColumnValue
      tags:
      - Query Data
      summary: Query a dataset by column value
      description: Shortcut form of the query endpoint that filters by a single column value in the path (for example a location or settlement point). Accepts the same time-range, resampling, pagination, and format query parameters as the main query endpoint.
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: filter_column_id
        in: path
        required: true
        description: The column to filter by.
        schema:
          type: string
      - name: filter_value_path
        in: path
        required: true
        description: The value to filter the column by.
        schema:
          type: string
      - $ref: '#/components/parameters/ReturnFormat'
      responses:
        '200':
          description: Matching rows plus pagination and dataset metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryDatasetResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    ValidationError:
      description: Validation error on request parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: array
                items:
                  type: object
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Missing API Key.
    TooManyRequests:
      description: Rate limit exceeded for your plan.
  schemas:
    DatasetResponse:
      type: object
      properties:
        id:
          type: string
          example: ercot_spp_day_ahead_hourly
        name:
          type: string
        description:
          type: string
        earliest_available_time_utc:
          type: string
          format: date-time
        latest_available_time_utc:
          type: string
          format: date-time
        source:
          type: string
        source_url:
          type: string
        last_checked_time_utc:
          type: string
          format: date-time
        primary_key_columns:
          type: array
          items:
            type: string
        publish_time_column:
          type:
          - string
          - 'null'
        time_index_column:
          type: string
        subseries_index_column:
          type:
          - string
          - 'null'
        all_columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              description:
                type: string
        number_of_rows_approximate:
          type: integer
        table_type:
          type: string
        data_frequency:
          type: string
        publication_frequency:
          type: string
        is_published:
          type: boolean
        status:
          type: string
        popularity_rank:
          type: integer
    QueryDatasetResponse:
      type: object
      properties:
        status_code:
          type: integer
        data:
          type: array
          description: Matching rows (array of objects by default).
          items:
            type: object
        meta:
          type: object
          properties:
            page:
              type: integer
            pageSize:
              type: integer
            hasNextPage:
              type: boolean
            cursor:
              type:
              - string
              - 'null'
        dataset_metadata:
          $ref: '#/components/schemas/DatasetResponse'
  parameters:
    ReturnFormat:
      name: return_format
      in: query
      description: The return format of the response.
      schema:
        type: string
        enum:
        - json
        - csv
        default: json
    DatasetId:
      name: dataset_id
      in: path
      required: true
      description: ID of the dataset (for example ercot_spp_day_ahead_hourly).
      schema:
        type: string
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key from https://www.gridstatus.io/settings/api.
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as a query parameter (alternative to the header).