Api Calibsun (0.1.0)

Welcome to CalibSun API

API Quickstart

In this section, you'll find a short guide to quickly start using the CalibSun API.

Authentication

Client credential flow

To access the endpoints of the CalibSun API, you need to authenticate your requests using a bearer token.

client_id and client_secret credentials can be generated in the user space UI https://calibsun.com/login in My Account>My API credentials toggle

Note: You can regenerate new API credentials directly in the UI at any moment.

Get a token

Token URL: https://api.calibsun.com/api/v2/open/token Token india URL: https://api-india.calibsun.com/api/v2/open/token

export CLIENT_ID="my_client_id"
export CLIENT_SECRET="my_client_secret"

curl --location 'https://api.calibsun.com/api/v2/open/token' \
 --header 'Content-Type: application/json' \
 --header "x-api-key: $CLIENT_SECRET" \
 --data "{\"client_id\": \"${CLIENT_ID}\"}"
 
# Response
{
  "access_token":"MY_ACCESS_TOKEN",
  "expires_in":3600,
  "token_type":"Bearer"
}
  
# Use API
curl --location 'https://api.calibsun.com/api/v2/public/latestforecastdemo/gti' \
--header 'Authorization: Bearer MY_ACCESS_TOKEN'

HTTP Response codes

HTTP Status Code Description
200 Successful request
204 Successful request with empty content
400 Logic error
401 Authentication error
403 Forbidden
404 Not found
422 Validation error
500 Internal server error

Useful response message, including error details, are included in the details field of the response.

{"details":"Useful response message"}

Rate limitation

The CalibSun API has a rate limiting of 100 requests per second.

If the rate limit is exceeded the request is rejected with a 429 HTTP error.

Usage examples

Retrieve your forecast

Python
import requests
import os
import json

client_id = os.environ.get('CLIENT_ID')
client_secret = os.environ.get('CLIENT_SECRET')

token_url = 'https://api.calibsun.com/api/v2/open/token'
india_token_url = 'https://api-india.calibsun.com/api/v2/open/token'

# Requesting token
headers = {
    'Content-Type': 'application/json',
    'x-api-key': client_secret
}

data = {
    'client_id': client_id
}
json_data = json.dumps(data)

response = requests.post(token_url, headers=headers, data=json_data)
access_token = response.json().get('access_token')

# Using the API
if access_token:
    api_url = 'https://api.calibsun.com/api/v2/public/latestforecastdemo/gti'
    api_headers = {
        'Authorization': f'Bearer {access_token}'
    }
    api_response = requests.get(api_url, headers=api_headers)
    print(api_response.json())
else:
    print('Failed to retrieve access token')
CURL
export CLIENT_ID="my_client_id"
export CLIENT_SECRET="my_client_secret"

# Requesting token
response=$(curl --silent --location 'https://api.calibsun.com/api/v2/open/token' \
 --header 'Content-Type: application/json' \
 --header "x-api-key: $CLIENT_SECRET" \
 --data "{\"client_id\": \"$CLIENT_ID\"}")

ACCESS_TOKEN=$(echo "$response" | jq -r '.access_token')
export ACCESS_TOKEN

# Using the API
if [ -n "$ACCESS_TOKEN" ]; then
    api_response=$(curl --silent --location 'https://api.calibsun.com/api/v2/public/latestforecastdemo/gti' \
    --header "Authorization: Bearer $ACCESS_TOKEN")

    echo "$api_response"
else
    echo 'Failed to retrieve access token'
fi
Powershell
$CLIENT_ID = "my_client_id"
$CLIENT_SECRET = "my_client_secret"

# Requesting token
$headers = @{
    "Content-Type" = "application/json"
    "x-api-key" = $CLIENT_SECRET
}
$body = @{
    "client_id" = $CLIENT_ID
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "https://api.calibsun.com/api/v2/open/token" -Method Post -Headers $headers -Body $body
$access_token = $response.access_token

# Using the API
if ($access_token) {
    $api_headers = @{
        "Authorization" = "Bearer $access_token"
    }
    $api_response = Invoke-RestMethod -Uri "https://api.calibsun.com/api/v2/public/latestforecastdemo/gti" -Headers $api_headers
    $api_response
} else {
    Write-Host "Failed to retrieve access token"
}
JavaScript
const CLIENT_ID = "my_client_id";
const CLIENT_SECRET = "my_client_secret";

// Requesting token
fetch('https://api.calibsun.com/api/v2/open/token', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': CLIENT_SECRET
    },
    body: JSON.stringify({ client_id: CLIENT_ID })
})
    .then(response => response.json())
    .then(data => {
        const access_token = data.access_token;

        // Using the API
        if (access_token) {
            fetch('https://api.calibsun.com/api/v2/public/latestforecastdemo/gti', {
                headers: {
                    'Authorization': `Bearer ${access_token}`
                }
            })
                .then(apiResponse => apiResponse.json())
                .then(apiData => {
                    console.log(apiData);
                })
                .catch(error => {
                    console.error('Error fetching API data:', error);
                });
        } else {
            console.log('Failed to retrieve access token');
        }
    })
    .catch(error => {
        console.error('Error fetching access token:', error);
    });
R
library(httr)

CLIENT_ID <- "my_client_id"
CLIENT_SECRET <- "my_client_secret"

# Requesting token
token_url <- "https://api.calibsun.com/api/v2/open/token"
token_body <- list(client_id = CLIENT_ID)
token_headers <- c(
  "Content-Type" = "application/json",
  "x-api-key" = CLIENT_SECRET
)

token_response <- POST(token_url, body = token_body, encode = "json", add_headers(.headers = token_headers))
token_data <- content(token_response, "parsed")

access_token <- token_data$access_token

# Using the API
if (!is.null(access_token)) {
  api_url <- "https://api.calibsun.com/api/v2/public/latestforecastdemo/gti"
  api_headers <- c(
    "Authorization" = paste("Bearer", access_token)
  )
  
  api_response <- GET(api_url, add_headers(.headers = api_headers))
  api_data <- content(api_response, "parsed")
  
  print(api_data)
} else {
  print("Failed to retrieve access token")
}

Push measurements

Python
import requests
import os
import json

client_id = os.environ.get('CLIENT_ID')
client_secret = os.environ.get('CLIENT_SECRET')

token_url = 'https://api.calibsun.com/api/v2/open/token'

# Requesting token
headers = {
    'Content-Type': 'application/json',
    'x-api-key': client_secret
}

data = {
    'client_id': client_id
}
json_data = json.dumps(data)

response = requests.post(token_url, headers=headers, data=json_data)
access_token = response.json().get('access_token')

# List plants
if access_token:
    api_url = 'https://api.calibsun.com/api/v2/public/listplant'
    api_headers = {
        'Authorization': f'Bearer {access_token}'
    }
    api_response = requests.get(api_url, headers=api_headers)
    plants = api_response.json()

# Iterate over your plants
    for plant_id, plant in plants.items():
        format = "csv"
        api_url = f"https://api.calibsun.com/api/v2/public/uploadmeasurements/{plant_id}/{format}"
        api_response = requests.get(api_url, headers=api_headers)
        presigned_payload = api_response.json()
        
        # If sending a file
        filepath = "example.json"
        with open(filepath, "r") as file:
            resp = requests.post(
                url=presigned_payload["url"], files={"file": (filepath, file)}, data=presigned_payload["fields"]
            )

        # If sending in memory data 
        data = [
        {
            "PROD": 100,
            "GTI": 200,
            "measure_date": "2023-10-01T12:00:00Z",
        }
    ]
        filelike = BytesIO()
        filelike.write(json.dumps(data).encode("utf-8"))
        # Reset the file pointer to the beginning so it can be read when posting
        filelike.seek(0)

        resp = requests.post(
            url=presigned_payload["url"],
            files={"file": filelike},
            data=presigned_payload["fields"],
        )

else:
    print('Failed to retrieve access token')

Get Bearer Token

Request Body schema: application/json
required
client_id
required
string (Client Id)

Responses

Request samples

Content type
application/json
{
  • "client_id": "string"
}

Response samples

Content type
application/json
null

v2.0

Get all plants

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Latest forecast

path Parameters
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"
query Parameters
run_tag
string (Run Tag)

Optional run tag given by Calibsun Team to identify a specific forecast type

Responses

Response samples

Content type
application/json
{
  • "target": "ghi",
  • "site_id": "DEMO-01",
  • "date_forecast": "2024-05-01T14:15:22Z",
  • "resolution": 30,
  • "data": {
    }
}

Timed forecast

path Parameters
time
required
string (format HHMM)
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"
query Parameters
run_tag
string (Run Tag)

Optional run tag given by Calibsun Team to identify a specific forecast type

Responses

Response samples

Content type
application/json
{
  • "target": "ghi",
  • "site_id": "DEMO-01",
  • "date_forecast": "2024-05-01T14:15:22Z",
  • "resolution": 30,
  • "data": {
    }
}

Retrieve specific historical forecast

path Parameters
datetime
required
string <date-time> (Datetime in ISO 8601 format)
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"
query Parameters
run_tag
string (Run Tag)

Optional run tag given by Calibsun Team to identify a specific forecast type

Responses

Response samples

Content type
application/json
{
  • "target": "ghi",
  • "site_id": "DEMO-01",
  • "date_forecast": "2024-05-01T14:15:22Z",
  • "resolution": 30,
  • "data": {
    }
}

Retrieve specific historical forecast

path Parameters
datetime
required
string <date-time> (Datetime in ISO 8601 format)
siteid
required
string (Siteid)
mode
required
string (Mode)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"
query Parameters
run_tag
string (Run Tag)

Optional run tag given by Calibsun Team to identify a specific forecast type

Responses

Response samples

Content type
application/json
Example
{
  • "target": "ghi",
  • "site_id": "DEMO-01",
  • "date_forecast": "2024-05-01T14:15:22Z",
  • "resolution": 30,
  • "data": {
    }
}

Retrieve specific historical forecast

path Parameters
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"
query Parameters
Start Date (string) or Start Date (null) (Start Date)

Start date in ISO format. Default is 1 day ago.

End Date (string) or End Date (null) (End Date)

End date in ISO format. Defaults is now.

run_tag
string (Run Tag)

Optional run tag

Responses

Response samples

Content type
application/json
[
  • "2026-07-22T11:39:17.837615+00:00",
  • "..."
]

Latest Probabilistic or Deterministic forecast

path Parameters
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"
mode
required
string (Mode)
query Parameters
run_tag
string (Run Tag)

Optional run tag given by Calibsun Team to identify a specific forecast type

Responses

Response samples

Content type
application/json
Example
{
  • "target": "ghi",
  • "site_id": "DEMO-01",
  • "date_forecast": "2024-05-01T14:15:22Z",
  • "resolution": 30,
  • "data": {
    }
}

Probabilistic or Deterministic forecast for a certain hour

path Parameters
time
required
string (format HHMM)
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"
mode
required
string (Mode)
query Parameters
run_tag
string (Run Tag)

Optional run tag given by Calibsun Team to identify a specific forecast type

Responses

Response samples

Content type
application/json
Example
{
  • "target": "ghi",
  • "site_id": "DEMO-01",
  • "date_forecast": "2024-05-01T14:15:22Z",
  • "resolution": 30,
  • "data": {
    }
}

Latest forecast key

path Parameters
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"

Responses

Response samples

Content type
application/json
{
  • "lastModified": "20240515111500"
}

Latest measurements

Last 5h by default

path Parameters
siteid
required
string (Siteid)

Responses

Response samples

Content type
application/json
{
  • "site_id": "DEMO-01",
  • "data": {
    },
  • "data_qc": { }
}

Latest measurements filtered on target

Last 5h by default

path Parameters
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"

Responses

Response samples

Content type
application/json
{
  • "site_id": "DEMO-01",
  • "data": {
    },
  • "data_qc": { }
}

Latest forecast file

path Parameters
siteid
required
string (Siteid)
target
required
string (Target)
Enum: "ghi" "gti" "prod" "dni" "dhi" "bhi" "dti" "bti" "rti" "unknown"
format
required
string (Format)
query Parameters
run_tag
string (Run Tag)

Optional run tag

Responses

Response samples

Content type
#CALIBSUN SOLAR FORECAST
#
#NEXT service v1
#
#Customer: support@calibsun.com
#Site ID: DEMO-01
#Site name: Demo site
#Latitude: 43.26
#Longitude: 5.87
#Elevation: 441.0
#
#
#Computation date (UTC): 2024-05-27 12:45
#
#Summarization: cumulated (end of interval)
#Forecast period (UTC): 2024-05-27 13:00 - 2024-05-29 00:45
#Target: Power [kW]
#
#Forecast inputs
#Meteorological data: Irradiance, temperature, windspeed and other weather variables from several NWP models (ECMWF, Meteo France, NOAA, NASA…)
#Satellite data: Meteosat MSG, IODC, GOES, HIMAWARI with CalibSun irradiance conversion method
#In-situ measurements data (available in NEXT Advanced only): activated
#
#Forecast parameters
#Meteorological data (1 if used 0 if not): 1
#Satellite data (1 if used 0 if not): 1
#Measurements data (1 if used 0 if not): 1
#Horizon [h]: 48
#Resolution [min]: 5
#Frequency of update [min]: 15
#
#Measurements status info (1 if ok, 0.5 if last measurement data was rejected by quality check but a previous measurement data was used, 0 if no measurement available or if every last usable measurement data points were rejected by quality check
#Status: 1.0
#tout est ok
#
#
#Service provider: CalibSun s.a.s., Eco-Lucioles BAT. A, 955 route des Lucioles, 06560 Sophia Antipolis, France
#SIRET: 97923043000014, VAT Number: FR33979230430, RCS: 979230430
#https://www.calibsun.com, support@calibsun.com
#
#
#Copyright (c) CalibSun s.a.s.
#
#
#Forecast data for target Power [kW]:
horizon,date,p_01,p_05,p_10,p_15,p_20,p_25,p_30,p_35,p_40,p_45,p_50,p_55,p_60,p_65,p_70,p_75,p_80,p_85,p_90,p_95,p_99,clear_sky,deterministic
2024-05-27 19:15:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0
2024-05-27 19:30:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0
2024-05-27 19:45:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0
2024-05-27 20:00:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0
2024-05-27 20:15:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0
<...>
2024-05-28 02:00:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0
2024-05-28 02:15:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0
2024-05-28 02:30:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0
2024-05-28 02:45:00+00:00,2024-05-27 12:45:00+00:00,,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,,0.0,0.0