What is an API request?

What is an API request?

Methodology

‣
Resolution and Accuracy
‣
Solar and Weather
‣
Power and Tuning
‣
Data Sources and FAQ

Commercial Products

Commercial User GuideCommercial User Guide
‣
Live and Forecast
‣
Historic
‣
Typical Meteorological Year (TMY)
‣
Grid Aggregations
‣
Geographic Horizon Angles

Hobbyist and Research Products

‣
Home Hobbyist Accounts
‣
Researchers and Academic Accounts

Help & Support

‣
Changes and Announcements
‣
Plans And Subscriptions
‣
Evaluation and Testing
‣
Authentication
‣
Developer Guides
‣
Third Party Applications
‣
Troubleshooting and FAQs

What you need to know when requesting data through the Solcast API

What does 'request' mean? How many requests does it take to get the data you need.

What is an API request?

If you've checked out our pricing page, or the Solcast API Toolkit, you'll have likely noticed we talk about 'requests' in reference to our data products.

Solcast calculates an individual API request using the following formula:

icon
1 API Request = Location x API Endpoint x File Format

The definition of a location can be a combination of latitude and latitude or a resource ID (for advanced PV).

If you make a request using a resource ID and would like to make the same request for radiation and weather, you will need to ensure that the latitude and longitude values are identical to the values used for the Advanced PV site. If they are different, it will be considered two locations.

An API endpoint can be any of the following:

  • Radation and Weather
  • Rooftop PV Power
  • Advanced PV Power

Our common file formats:

  • HTML (default file format if no other value is provided)
  • JSON
  • CSV
  • JSON Columnar

What is the output data duration of the request?

For TMY data products, one request is equivalent as One Location X One (TMY) Year of Data.

For Historical Time Series data, one request is calculated as One Location X One Month of Data.

For Live and Forecast data, each request is calculated as One Location X Requested Forecast/Live Duration of Data.

For example if you made a csv request at Bondi Beach in Australia for Radiation and Weather, and then using the exact same latitude and longitude for Bondi Beach but instead for Rooftop PV Power, you will have used 1 location allowance and 1 request for Radiation and Weather and 1 request for Rooftop PV Power. You can see this breakdown in your Managed Subscription view within the Solcast Toolkit.

For evaulation users, each product endpoint will have it’s own unique limit. Please see Manage Subscription to view specific limits.

There are 3 limitations on the Solcast API.

  1. Rate limit (per product) - Standard limits are: Live and Forecast (L&F) 1,000/min, TMY 30/min, TimeSeries 60/min. Exceeding the rate limit will return an error with the message "Rate Limit Exceeded"
  2. Location limit (per product) - A count of the number of unique lat/lons for which data has been requested. For L&F, this resets daily. For TMY and TimeSeries, this can be configured to reset either monthly or yearly depending on need. This number is defined by commercial scope. Exceeding the location limit will return an error with the message "Unique Locations Limit Exceeded"
  3. Request limit (per endpoint) - The number of API calls that can be made to a particular endpoint. This number is defined by product choice.  Exceeding the request limit will return an error with the message "Transaction Limit Exceeded"

Read our API documentation for further detailed information.

💡
Helpful Tip You can use our 'unmetered' locations while you practice using the Solcast data APIs. This means you can run as many tests as you need, without using up requests from your included plan. This is useful for testing your code, or implementing the Solcast API in a development environment.

Example Monthly TMY Plan:

  • TMY plan, for up to (5) unique locations each month
  • Location limit = 5, which resets every month
  • Requests for TMY plans are 10x the number of locations, so you'd have 50 requests
  • This allows for 5 unique TMYs to be accessed within a 30 day period (each month). The reason for including 50 requests is to enable access to multiple parameters or file types for each location. For example: Setting probability of P50 or P95 and export format as a csv or json or PVsyst format or SAM format.
  • 1 request = 1 location x 1 (typical meteorological years worth of data)

Example Monthly Time Series Plan:

  • Time Series Starter plan, for up to (1) unique locations each month
  • Location limit = 1, which resets monthly
  • 1 request = 1 (location) x 1 (month of data)
💡
For all plans, the request count and the location count are independent. In the TMY example above, you can hit the location limit in just 6 API calls if 6 unique locations are requested. The sixth unique location would get a 429 error "Unique Locations Limit Exceeded". Or you could make 50 API calls to just 1 location. Any additional API calls would get a 429 error "Transaction Limit Exceeded" and you will no longer be able to make any additional requests until the end of the month, even for new unique locations.

What happens if I’ve run out of request?

In most instances the user’s API request limits are set to reset per Coordinated Universal Time (UTC) day.

This means that the quota of API requests available to the user will refresh at the beginning of each UTC day, providing a standardised and globally recognised time reference. It's crucial for users to be mindful of this reset timing to effectively manage their API usage and ensure uninterrupted access to the desired services. By aligning with the UTC day, this approach ensures a consistent and fair allocation of API resources for users across different time zones, promoting a streamlined and equitable experience for all.