Gridraven 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.

Base URLs

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

Authentication

API Key is used in Bearer token for authentication.

Key can be obtained from https://claw.gridraven.com/claw-api after logging in.

1import http.client
2
3conn = http.client.HTTPSConnection("claw.gridraven.com")
4
5headers = { 'Authorization': "Bearer YOUR_SECRET_TOKEN" }
6
7conn.request("GET", "/api/public/xxx", headers=headers)

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:

1requests.get(
2    "https://claw.gridraven.com/api/public/lines",
3    headers={
4      "Authorization": "Bearer YOUR_SECRET_TOKEN"
5    },
6    params={
7      "status": "active"
8    }
9)

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      "id": "019cddd3-a4e9-79eb-a18c-1123d27c4a9e",
12      "external_id": "L008",
13      "name": "Line from C to D",
14      "status": "active"
15    }
16  ]
17}

Errors:

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 the latest 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).

The length of forecast depends on the forecast configuration and available data.

Parameters:

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

Example Request:

1requests.get(
2    "https://claw.gridraven.com/api/public/lines/{line_id}/rating-forecasts",
3    headers={
4      "Authorization": "Bearer YOUR_SECRET_TOKEN"
5    }
6)

Example Response:

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

Errors:

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

3. Get past line rating forecast series

Returns past line rating forecast results within the specified valid time and adjusted step. Valid results are available for the time period the line was active.

How step adjustment works: The from and to parameters specify the valid time range (when the forecast prediction applies). The system finds forecasts whose reference time plus the step falls within this range. For example, with step=24 and valid time range 2025-02-15 to 2025-02-16, the system retrieves forecasts made on 2025-02-14 to 2025-02-15 (24 hours earlier), because those forecasts predicted the requested valid time range.

JSON format is limited to 7 days of data. Parquet format is limited to 60 days.

Path Parameters:

line_id string required

Query Parameters:

from Type:string Format:date-time required
to Type:string Format:date-time required
format
step Type:integer min: 0 max: 240 required

Example Request:

1requests.get(
2    "https://claw.gridraven.com/api/public/lines/{line_id}/rating-forecast-series",
3    headers={
4      "Authorization": "Bearer YOUR_SECRET_TOKEN"
5    },
6    params={
7      "from": "",
8      "to": "",
9      "format": "json",
10      "step": "0"
11    }
12)

Example Responses

200 List of Rating Forecasts

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

400, 404 Error for client statuses 4xx

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

4. Get seasonal rating for a line over a time period

Returns seasonal rating values for the given line over the specified time period. Time period can be up to multiple years. Results are returned as unique rating segments where consecutive periods with the same rating value are merged.

Path Parameters:

line_id string required

Query Parameters:

start Type:string, Format:date-time required
end Type:string, Format:date-time required

Example Request:

1requests.get(
2    "https://claw.gridraven.com/api/public/lines/{line_id}/rating-seasonal",
3    headers={
4      "Authorization": "Bearer YOUR_SECRET_TOKEN"
5    },
6    params={
7      "start": "",
8      "end": ""
9    }
10)

Example Responses

200 Seasonal ratings retrieved successfully

1{
2  "status_code": 200,
3  "line_id": "eb8647ac-0aec-42c5-b1f5-0fc39fc864a9",
4  "line_external_id": "12345ABC",
5  "line_name": "Main Transmission Line",
6  "created_at": "2025-11-11T10:30: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": "PT1H",
13      "duration": "PT1H",
14      "ratings": {
15        "sr": 100.1,
16        "mean_dlr": 150.1,
17        "dlr": {
18          "50": 150.1,
19          "75": 200.2,
20          "90": 250.2
21        },
22        "aar": 140.2
23      }
24    }
25  ]
26}

400, 404 Error for client statuses 4xx

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

5. Get all available sites

Endpoint: /sites

Method: GET

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

Query Parameters

type array SiteType[]

Example Request:

1requests.get(
2    "https://claw.gridraven.com/api/public/sites",
3    headers={
4      "Authorization": "Bearer YOUR_SECRET_TOKEN"
5    },
6    params={
7      "type": "line"
8    }
9)

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}

6. Get weather stations

Endpoint: /weather-stations

Method: GET

Description: Returns a paginated list of weather stations for the organization. Usually, EPSG:4326 (WGS84) is used for crs.

Query Parameters:

page Type:integer, min:1, default:1
page_size Type:integer, min:1, default: 1000

Example Request:

1requests.get(
2    "https://claw.gridraven.com/api/public/weather-stations",
3    headers={
4      "Authorization": "Bearer YOUR_SECRET_TOKEN"
5    },
6    params={
7      "page": "1",
8      "page_size": "1000"
9    }
10)

Example Response:

1{
2  "status_code": 200,
3  "page": 1,
4  "pageSize": 50,
5  "totalItems": 157,
6  "totalPages": 3,
7  "items": [
8    {
9      "id": "019401f9-5c4e-71a3-86c9-aef1d95f12a3",
10      "external_id": "WS-001",
11      "name": "Main Weather Station",
12      "site_id": "55.04979_-24.15618",
13      "lat": 55.04979,
14      "lon": -24.15618,
15      "crs": "EPSG:4326",
16      "status": "active"
17    }
18  ]
19}

7. Get the latest weather forecast for sites

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:

1requests.get(
2    "https://claw.gridraven.com/api/public/weather-forecasts",
3    headers={
4      "Authorization": "Bearer YOUR_SECRET_TOKEN"
5    },
6    params={
7      "page": "1",
8      "page_size": "1000",
9      "site_ids": "",
10      "all": "true"
11    }
12)

Example Response:

1{
2  "status_code": 200,
3  "page": 1,
4  "pageSize": 50,
5  "totalItems": 157,
6  "totalPages": 3,
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": "PT1H",
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              "75": {
32                "l_wind_speed": 3.3,
33                "u_wind_speed": 9.9,
34                "l_wind_direction": 180.3,
35                "r_wind_direction": 270.6
36              },
37              "90": {
38                "l_wind_speed": 3.3,
39                "u_wind_speed": 9.9,
40                "l_wind_direction": 180.3,
41                "r_wind_direction": 270.6
42              },
43              "95": {
44                "l_wind_speed": 3.3,
45                "u_wind_speed": 9.9,
46                "l_wind_direction": 180.3,
47                "r_wind_direction": 270.6
48              },
49              "98": {
50                "l_wind_speed": 3.3,
51                "u_wind_speed": 9.9,
52                "l_wind_direction": 180.3,
53                "r_wind_direction": 270.6
54              },
55              "99": {
56                "l_wind_speed": 3.3,
57                "u_wind_speed": 9.9,
58                "l_wind_direction": 180.3,
59                "r_wind_direction": 270.6
60              }
61            }
62          }
63        }
64      ]
65    }
66  ]
67}

Errors:

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

Tips for Beginners

Check Responses: Always check response.status_code to handle errors.

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