Documentation

Introduction

Line Rating Forecast API Documentation

This guide explains how to use the Line Rating Forecast API to retrieve forecasted line ratings and weather data.

The documentation is designed to provide useful examples for a user who is familiar with Python and who wants to create a simple integration to explore the API, for professional use, we recommend to generate integration from the Open API spec (details at the end of the guide)

Overview

Lines: List all power lines, optionally filtered by status.
Line Rating Forecasts: Get forecasted ratings for a specific power line up to 10 days ahead.
Weather Sites: List all available sites with their details.
Weather Forecasts: Retrieve weather forecasts for specific sites.

You’ll need an ID Token for authentication. Contact GridRaven to obtain one.

Base URLs

Test: https://dev-claw.gridraven.com/api/public
Production: https://claw.gridraven.com/api/public

Authentication

Uses Google json auth key. Example in Python:

1from google.oauth2 import service_account
2from google.auth.transport.requests import AuthorizedSession
3
4# Key from variable
5creds = service_account.IDTokenCredentials.from_service_account_info(
6						AUTH_KEY, target_audience=CLAW_URL)
7
8# or Key from file
9creds = service_account.IDTokenCredentials.from_service_account_file(
10            AUTH_KEY_FULL_PATH, target_audience=CLAW_URL)
11
12# Create an authorized session that automatically handles token refresh
13# This object should be re-used
14session = AuthorizedSession(creds)

Endpoints

1. Get All Lines

Endpoint: /lines

Method: GET

Description: Lists all lines, optionally filtered by status.

Parameters:

status (optional, query): Filter by line status (active, inactive, draft).

Example Request:

1url = "https://claw.gridraven.com/api/public/lines?status=active"
2
3response = session.get(url)
4
5if response.status_code == 200:
6    print(response.json())
7else:
8    print(f"Error: {response.json()['message']}")

Example Response:

1{
2  "status_code": 200,
3  "lines": [
4    {
5      "id": "eb8647ac-0aec-42c5-b1f5-0fc39fc864a9",
6      "external_id": "L007",
7      "name": "Line from A to B",
8      "status": "active"
9    }
10  ]
11}

Error Handling

Errors return a JSON object with:

status_code: HTTP status (e.g., 400, 404).
code: Machine-readable error code (e.g., "NOT_FOUND").
message: Human-readable error message.

Example Error:

1{
2  "status_code": 404,
3  "code": "NOT_FOUND",
4  "message": "Line '12345ABC' not found"
5}

2. Get Line Rating Forecast

Endpoint: /lines/{line_id}/rating-forecasts

Method: GET

Description: Retrieves the latest forecast for a specific power line, including dynamic line ratings (DLR), ambient adjusted ratings (AAR), and seasonal ratings (SR).

Parameters:

line_id (required, in path): The ID of the line (e.g., "eb8647ac-0aec-42c5-b1f5-0fc39fc864a9").

Example Request:

1line_id = "eb8647ac-0aec-42c5-b1f5-0fc39fc864a9"
2url = f"https://claw.gridraven.com/api/public/lines/{line_id}/rating-forecasts"
3
4
5response = session.get(url)
6
7if response.status_code == 200:
8    print(response.json())
9else:
10    print(f"Error: {response.json()['message']}")

Example Response:

1{
2  "status_code": 200,
3  "line_id": "eb8647ac-0aec-42c5-b1f5-0fc39fc864a9",
4  "line_name": "Main Transmission Line",
5  "created_at": "2023-10-23T13:43:21Z",
6  "reference_time": "2023-10-23T13:00:00Z",
7  "scheme": "V1",
8  "results": [
9    {
10      "valid_start": "2023-10-23T13:00:00Z",
11      "valid_end": "2023-10-23T14:00:00Z",
12      "step": 0,
13      "duration": "PT1H",
14      "ratings": {
15        "mean_dlr": 150.1,
16        "dlr": {"50": 150.1, "75": 200.2, "90": 250.2},
17        "aar": 140.2,
18        "sr": 100.1
19      }
20    }
21  ]
22}

Errors:

404: Line not found.

3. Get All Weather Sites

Endpoint: /sites

Method: GET

Description: Lists all sites with their IDs, latitude, longitude, and status.

Example Request:

1url = "https://claw.gridraven.com/api/public/sites"
2
3response = session.get(url)
4
5if response.status_code == 200:
6    print(response.json())
7else:
8    print(f"Error: {response.json()['message']}")

Example Response:

1{
2  "status_code": 200,
3  "items": [
4    {
5      "id": "-20.12345_-40.12345",
6      "lat": -20.12345,
7      "lon": -40.12345,
8      "status": "active"
9    }
10  ]
11}

4. Get Weather Forecasts

Endpoint: /weather-forecasts

Method: GET

Description: Retrieves weather forecasts for specific sites, including wind speed, direction, temperature, and solar irradiance. Requires at least one query parameter (site_ids or all).

Parameters:

site_ids (optional, query): Comma-separated site IDs (e.g., "-20.12345_-40.12345,-21.12345_-41.12345").
all (optional, query): Set to true to include all sites.
page (optional, query): Page number (default: 1).
page_size (optional, query): Items per page (default: 1000).

Example Request:

1url = "https://claw.gridraven.com/api/public/weather-forecasts?site_ids=-20.12345_-40.12345"
2
3response = session.get(url)
4
5if response.status_code == 200:
6    print(response.json())
7else:
8    print(f"Error: {response.json()['message']}")

Example Response:

1{
2  "status_code": 200,
3  "page": 1,
4  "pageSize": 1000,
5  "totalItems": 1,
6  "totalPages": 1,
7  "items": [
8    {
9      "site_id": "-20.12345_-40.12345",
10      "created_at": "2023-10-23T13:43:21Z",
11      "reference_time": "2023-10-23T13:00:00Z",
12      "scheme": "V1",
13      "results": [
14        {
15          "valid_start": "2023-10-23T13:00:00Z",
16          "valid_end": "2023-10-23T14:00:00Z",
17          "step": 0,
18          "duration": "PT1H",
19          "ratings": {
20            "wind_speed": 4.4,
21            "wind_direction": 180.3,
22            "temperature": 10.3,
23            "solar_irradiance": 22.2,
24            "confidence_intervals": {
25              "50": {
26                "l_wind_speed": 3.3,
27                "u_wind_speed": 9.9,
28                "l_wind_direction": 180.3,
29                "r_wind_direction": 270.6
30              }
31            }
32          }
33        }
34      ]
35    }
36  ]
37}

Errors:

400: Missing required query parameters.

Tips for Beginners

Install Modules: Run pip install google-auth google-auth-oauthlib.
Check Responses: Always check response.status_code to handle errors.
Contact GridRaven: Reach out for your ID Token to authenticate requests.

This API is straightforward to use with Python and provides valuable data for managing power lines and sites. Start with the example code above and explore the endpoints!

Minimal Weather API Example

Full Example

OpenAPI Specification

gridraven-public-api.yaml

The OpenAPI Specifications provide a formal standard for describing HTTP APIs, allowing clients to inspect the endpoints and generate API clients using tools.

Inspecting OpenAPI Endpoints using Swagger

The public api endpoints have an OpenAPI spec which can be used to inspect the endpoints using a Swagger editor: https://editor.swagger.io/

Generating Python client from OpenAPI

Instead of writing your own client code with requests package, you can use openapi-generator-cli to generate the client library. This also creates the response domain objects in Python.

uv is required in order for this script to work.

1#!/bin/bash
2GEN_VERSION=7.10.0
3
4# Generate Python client
5PYTHON_CLIENT_DIR="claw_client"
6rm -rf $PYTHON_CLIENT_DIR
7mkdir -p $PYTHON_CLIENT_DIR
8
9uvx openapi-generator-cli@"$GEN_VERSION" generate \
10  -i ./gridraven-public-api.yaml \
11  -g python \
12  --global-property apis,supportingFiles,models,apiTests=false,modelTests=false \
13  --additional-properties=packageName=claw_client,basePath=/api/public \
14  -o $PYTHON_CLIENT_DIR