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

Authentication

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

Frogcast 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 us 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 us 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 Location is called a System.

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

GET

Weather forecasts

1. Frogcast by request 

Once you’ve taken out a Frogcast by request subscription, you can obtain forecasts by querying the forecast endpoint with the latitude and longitude parameters you require.

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

2. Frogcast by location

If you’ve opted for Frogcast by location and created 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

Frogcast by location only

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

Frogcast by location only 

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

Frogcast by location only 

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

Frogcast by location only 

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

latitude*

Numeric (double)

  • in degrees and decimal degrees (-90° to +90°)
    example : 45.369

longitude*

Numeric (double)

  • in degrees and decimal degrees (-180° to +180°)
    example : 8.369

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

*mandatory for Frogcast by request subscriptions
  not to be used for locations

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

Frogcast Tutorials

Learn how to use Frogcast interface