openapi: 3.1.0
info:
  title: WattTime Account Emissions Data API
  description: The WattTime Data API v3 provides access to real-time, forecast, and historical marginal emissions data for electric grids worldwide. Key signals include CO2 MOER (Marginal Operating Emissions Rate), health damage estimates, and CO2 AOER (Average Operating Emissions Rate). Coverage spans 342 grid regions in 210 countries and territories, with real-time data updated every five minutes. Authentication uses JWT bearer tokens obtained via the login endpoint using HTTP Basic Auth.
  version: '3.0'
  contact:
    name: WattTime Support
    email: support@watttime.org
    url: https://watttime.org/
  license:
    name: Proprietary
    url: https://watttime.org/data-plans/
  x-generated-from: documentation
servers:
- url: https://api.watttime.org/v3
  description: WattTime API v3 Production
- url: https://api2.watttime.org/v2
  description: WattTime API v2 Legacy
tags:
- name: Emissions Data
  description: Access real-time, historical, and forecast marginal emissions signals for electric grids.
paths:
  /data:
    get:
      operationId: getHistoricalData
      summary: WattTime Get Historical Emissions Data
      description: Retrieve historical emissions data for a specified grid region and signal type within a time window. The maximum query window is 32 days. For longer historical datasets, use the /historical endpoint to download CSV files. Available to ANALYST and PRO subscribers; preview available for CAISO_NORTH.
      tags:
      - Emissions Data
      security:
      - bearerAuth: []
      parameters:
      - name: region
        in: query
        required: true
        description: Grid region identifier (e.g., CAISO_NORTH). Obtain from /region-from-loc or /my-access.
        schema:
          type: string
        example: CAISO_NORTH
      - name: signal_type
        in: query
        required: true
        description: 'The emissions signal type to retrieve. Valid values: co2_moer, co2_aoer, health_damage.'
        schema:
          type: string
          enum:
          - co2_moer
          - co2_aoer
          - health_damage
        example: co2_moer
      - name: start
        in: query
        required: true
        description: Start of the time window in ISO 8601 format (UTC). Maximum window is 32 days.
        schema:
          type: string
          format: date-time
        example: '2026-04-01T00:00:00Z'
      - name: end
        in: query
        required: true
        description: End of the time window in ISO 8601 format (UTC).
        schema:
          type: string
          format: date-time
        example: '2026-04-02T00:00:00Z'
      - name: model
        in: query
        required: false
        description: Model version date to use (e.g., 2026-03-01). Defaults to the latest available model for the region.
        schema:
          type: string
        example: '2026-03-01'
      responses:
        '200':
          description: Historical emissions data points for the requested window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResponse'
              examples:
                GetHistoricalData200Example:
                  summary: Default getHistoricalData 200 response
                  x-microcks-default: true
                  value:
                    meta:
                      region: CAISO_NORTH
                      signal_type: co2_moer
                      model:
                        date: '2026-03-01'
                      units: lbs_co2_per_mwh
                    data:
                    - point_time: '2026-04-01T00:00:00+00:00'
                      value: 412.5
                      version: '2026-03-01'
        '400':
          description: Bad request - invalid parameters or window too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or expired token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - subscription plan does not include this region.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /historical:
    get:
      operationId: downloadHistoricalData
      summary: WattTime Download Historical Emissions CSV
      description: Download multi-year historical emissions data as compressed CSV files. Returns a URL to download the CSV file for the specified grid region, signal type, and date range. Available to ANALYST and PRO subscribers.
      tags:
      - Emissions Data
      security:
      - bearerAuth: []
      parameters:
      - name: region
        in: query
        required: true
        description: Grid region identifier (e.g., CAISO_NORTH).
        schema:
          type: string
        example: CAISO_NORTH
      - name: signal_type
        in: query
        required: true
        description: The emissions signal type.
        schema:
          type: string
          enum:
          - co2_moer
          - co2_aoer
          - health_damage
        example: co2_moer
      - name: start
        in: query
        required: false
        description: Start date for historical data download (YYYY-MM-DD).
        schema:
          type: string
          format: date
        example: '2023-01-01'
      - name: end
        in: query
        required: false
        description: End date for historical data download (YYYY-MM-DD).
        schema:
          type: string
          format: date
        example: '2024-01-01'
      - name: model
        in: query
        required: false
        description: Model version date.
        schema:
          type: string
        example: '2026-03-01'
      responses:
        '200':
          description: Download URL for the historical emissions CSV file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalDownloadResponse'
              examples:
                DownloadHistoricalData200Example:
                  summary: Default downloadHistoricalData 200 response
                  x-microcks-default: true
                  value:
                    region: CAISO_NORTH
                    signal_type: co2_moer
                    model: '2026-03-01'
                    download_url: https://storage.watttime.org/historical/CAISO_NORTH_co2_moer_2023.csv.gz
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - subscription plan does not include historical downloads.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    DataResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/DataMeta'
        data:
          type: array
          description: Array of emissions data points.
          items:
            $ref: '#/components/schemas/DataPoint'
    DataPoint:
      type: object
      properties:
        point_time:
          type: string
          format: date-time
          description: Timestamp for the emissions data point (ISO 8601 UTC).
          example: '2026-04-01T00:00:00+00:00'
        value:
          type: number
          format: double
          description: Emissions value in the units specified by the response meta.
          example: 412.5
        version:
          type: string
          description: Model version used for this data point.
          example: '2026-03-01'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type or code.
          example: unauthorized
        message:
          type: string
          description: Human-readable error message.
          example: Invalid or expired token. Please re-authenticate.
        detail:
          type: string
          description: Additional error detail.
          example: Token has expired. Please call /login to get a new token.
    DataMeta:
      type: object
      properties:
        region:
          type: string
          description: Grid region identifier.
          example: CAISO_NORTH
        signal_type:
          type: string
          description: Signal type of the returned data.
          example: co2_moer
        model:
          type: object
          properties:
            date:
              type: string
              description: Model version date.
              example: '2026-03-01'
        units:
          type: string
          description: Units for the data values.
          example: lbs_co2_per_mwh
    HistoricalDownloadResponse:
      type: object
      properties:
        region:
          type: string
          description: Grid region identifier.
          example: CAISO_NORTH
        signal_type:
          type: string
          description: Signal type.
          example: co2_moer
        model:
          type: string
          description: Model version date used.
          example: '2026-03-01'
        download_url:
          type: string
          format: uri
          description: URL to download the historical CSV file.
          example: https://storage.watttime.org/historical/CAISO_NORTH_co2_moer_2023.csv.gz
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication used only for the /login endpoint. Provide username and password to obtain a bearer token.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT bearer token obtained from the /login endpoint. Token expires after 30 minutes. Include as Authorization: Bearer {token} header.'