Introduction

API Reference

The Frogcast API provides an easy way to integrate your weather forecast data with any external system.

The API is organised around REST semantics, uses JSON to encode objects, and relies on standard HTTP codes to signal operation outcomes.

The Frogcast API doesn't support bulk updates. You can work on only one object per request.

we release new versions and tailor functionality. Log in to see docs customized to your version of the API, with your key and data.

If you find any features missing or have any suggestions, please contact us.

Free Usage and Paid Subscription

Registration is free and access is immediate.
New users are granted a single location, regardless of their geographic area.
Once these free requirements are exhausted, users will be offered a paid subscription and can upgrade their locations.
See our pricing and plans page for more details.

Authentification

Frogcast uses a simple token-based authentication.
All API requirements must be authenticated and made via HTTPS.

Your token is automatically generated when you register on the app.frogcast.
Once you sign in, you can access it here https://app.frogcast.com/fr/api/
The token must be added in the header.

Key

Value

Authorization

Token {your token}

Your API token has the same privileges as your user account, so be sure to keep them secret!
Do not share your secret API keys in publicly accessible areas.
API requests without authentication will fail.

Errors

Frogast uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

Codes in the 2-- range indicate success.
Codes in the 4-- range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
Codes in the 5-- range indicate an error with Frogcast's servers.

HTTP Status Summary

StatusCode

Result

Content

200 OK

Success

Everything worked as expected

400 Bad Request

Error

The request was unacceptable, often due to missing a required parameter.

401 Unauthorized

Error

No valid API key provided

403 Forbidden

Error

The APi doesn't have permissions to perform the request.

500 Internal Server Error

Failed

Something unexpected went wrong during the request.

Please contact FROGCAST if this continues, and include any error messages received from the failed request

502 Bad Gateway Error

Failed

Something unexpected went wrong during the request, probably due a server timeout. Try again after 30 seconds.

Please contact FROGCAST if this continues, and include any error messages received from the failed request

Set of requests

All the requirements are presented in this section.
You will find everything you need to create your first request very simply.

In the FROGCAST API, a Locationt is called a System.

Main API url https://api.frogcast.com/api/v1/

GET

Weather forecasts

After signing up and creating your first location, the corresponding UUID {system_uuid} can be found in your account.
With this parameter you can start using the API right away.

To get the forecast for a location, extend the endpoint URL using the UUID of the location in question (available on your account).
The API supports several additional settings that the user can adjust to modify the retrieved forecast.
The available parameters are described in the Settings section.

API endpoint https://api.frogcast.com/api/v1/forecast/{system_uuid}/

GET

All fields

To get a detailed list of all variables available on the Frogcast platform.

Each variable is identified by it's "id" field. Use that value when you want to request a new variable for a location for example

API endpoint https://api.frogcast.com/api/v1/allfields

GET

Unused fields

Gives you a list of fields that are not unused in your {system_uuid} location.
Allows you to quickly retrieve the missing "ids" fields to add them to your PATCH requests

API endpoint https://api.frogcast.com/api/v1/system/{uuid}/get_unused_fields

POST

Location

To add a location.

The ability to add one or more of the locations depends on your subscription contract.

The parameters of Location must be specified in a POST request with following requirements.
Requested parameters:

title : limited to 128 characters
name : limited to 32 characters
Latitude and longitude coordinates must be specified in decimal degrees (°).
is_favorite : favorite status. Must be specified in boolean.
is_active: Designates whether this object should be treated as active. Unselect this instead of deleting the location.Must be specified as a boolean.
subscribed_fields (or weather forecasts variables) must be specified by their respective id; the correspondance between the variables names and their id can be retrieved via this request.
location : Localisation of the system. Latitude and longitude coordinates must be specified in decimal degrees (°).
altitude is in meters (m).
tags :string denoting a tag for this system, for example a project name or a category.

API endpoint https://api.frogcast.com/api/v1/system/

# Imports
import requests
import json

# Configure API authentification
headers = {
'Content-type':'application/json',
'Accept':'application/json',
'Authorization':'Token {your token}'
}
url = " https://api.frogcast.com/api/v1/system/"

# Plant configuration
latitude = 45.19       # in decimal degrees
longitude = 5.82      # in decimal degrees

config = {
    "title": "My_Test_Site",    # this field is required
    "name": "My_Test_Site",   # this field is required
    "subscribed_fields": [    # this field is required
    {"field": 13, "with_quantiles": True },
    {"field": 78, "with_quantiles": True}
  ],
  "location": {           # this field is required
    "type": "Point",
    "coordinates": [longitude, latitude]
  },
  "altitude": 215.0,
  "tags" : "string"        # this field is required
      }

json_object = json.dumps(config)
result = requests.post(url, headers=headers, data=json_object)

print(json.loads(result.text))

Language

Python

The answer of the server must be 201.
The answer 201 returns a dictionary with the information and especially the uuid of the pvsystem you just created

PATCH

Location

To update a part of your system parameters

Must be specified by their respective requirested parameters.
The query can contain any number of parameters you want to modify; the list of available parameters is described in the POST request.

API endpoint https://api.frogcast.com/api/v1/system/{uuid}

PUT

Location

To update all of parameters of your system

Must be specified by their respective requirested parameters
The query must contain all parameters including the ones you don't want to modify; the list of available this request.

API endpoint https://api.frogcast.com/api/v1/system/{uuid}

DELETE

Location

To delete your system you need the {uuid_system}

API endpoint https://api.frogcast.com/api/v1/system/{uuid}

Requests parameters

There are different parameters to customize your query:

The timezone is UTC by default.

Parameters

Data Type

Description

data_format

String (str)

split (default): original format of the api
records: fully detailed record with name of field and value for each time step
tight: tight version of the data that can be used for data visualization

precision

Integer (int)

default = 2

horizon

Integer (int)

specified in minutes
available values depend on your contract

fields

String (str)

the variables available in the API call depend on your contract.
you can specify the list of fields separated by a ',' for example: t2m,ghi

time_step

String (str)

default is 60min
available values : 1,5,10,15,30,60

date_time_format

String (str)

default is in ISO 8601 UTC format, like "2022-01-01T00:00:00Z"
you can specify "time_stamp" to get unix time stamp

time_stamp_unit

String (str)

to be specified only if the unix timestamp format is requested
default is "s" to get unix timestamp in seconds,
but you can specify "ms" to get your data in milliseconds

Datasheet :

You will find here, the detailed specifications of all the variables proposed by Frogcats :

Main API url https://api.frogcast.com/api/v1/allfields

Category

Short Name

Long Name

Description

Unity

Radiation

ghi

all_sky_global_horizontal_irradiance

Global horizontal irradiance when the cloud cover is taken into account.

W.m-2

bni

all_sky_beam_normal_irradiance

Beam normal irradiance when the cloud cover is taken into account.

W.m-2

dhi

all_sky_diffuse_horizontal_irradiance

Diffuse horizontal irradiance when the cloud cover is taken into account.

W.m-2

bhi

all_sky_beam_horizontal_irradiance

Beam horizontal irradiance when the cloud cover is taken into account..

W.m-2

Clouds

hcc

high_cloud_cover

Proportion, ranging from 0 to 1, of the cloud cover produced by high altitude clouds.

[0-1]

lcc

low_cloud_cover

Proportion, ranging from 0 to 1, of the cloud cover produced by high altitude clouds.

[0-1]

mcc

medium_cloud_cover

Proportion, ranging from 0 to 1, of the cloud cover produced by medium altitude clouds. .

[0-1]

tcc

total_cloud_cover

Proportion of cloud cover ranging from 0 to 1.

[0-1]

Humidity

specific_humidity

Concentration (in g per kg) of water in the air at 2 meter height. This variable give information about the air humidity near the ground or sea surface.

g.kg

rh2m

2m_relative_humidity

Relative humidity meters above the ground.

tcwv

total_column_water_vapor

The total amount of water vapor in a vertical column of air.

kg.m-2

Precipitation

mtpr

mean_total_precipitation_rate

Precipitation rate in mm/h over your period of time considered. For example if your time step is 5min and the value is 12mm/h, the forecast estimate that 1mm of water will precipitate in these 5 minutes

mm.h-1

Pressure & Density

mlsp

mean_sea_level_pressure

Pressure in hPa calculated back to the sea level.

hPa

msp

mean_surface_pressure

hPa

Temperature

heat_index

The heat index provides information on human's perception of temperature above 27°C. The heat index takes into account the humidity of the air which impacts the ability of the body to regulate its temperature by evaporation of sweat.
No unit.

null

t2m

2m_temperature

Air temperature 2 meters above the ground.

°C

2m_dewpoint

Dewpoint at 2 meter height. The dewpoint is the temperature to which the air mass should be cooled to become saturated in water vapor. When compared to the air temperature at the same height, the dewpoint give information about the air humidity.

°C

apparent_temperature

The apparent temperature provides information on human's perception of the temperature. It is based on wind speed and relative humidity. If the temperature is above 26°C, the heat index is provided. If the temperature is below 10°C and the wind speed exceeds 1.4 m/s, the wind chill is computed. Otherwise, the temperature is returned
No unit.

null

wind

10m_gust

10m_wind_gust

Wind gust at 10m above ground

m.s-1

10m_wind_direction

Direction from which the wind blow at 10m above ground. (North = 0°, East= 90°, South = 180°, West= 270°)

10m_wind_speed

Average wind speed at 10m above ground.

m.s-1

Frogcast Tutorials

Learn how to use Frogcast interface