Child pages
  • New usage API
Skip to end of metadata
Go to start of metadata

We have implemented simple Usage API to get instant information about your Web Service's account usage.
You can simply enter any Usage API URL into browser or use automated HTTP GET call.

Following methods are available: 


Basic usage API

count

Returns count of successful calls of specified web service.

URL pattern:

https://solargis.info/ws/usage/{webservice}/count?key={key}

Replace {webservice} with either pvplanner or datadelivery and {key} with your access key you have obtained with your WS account

Examples:

https://solargis.info/ws/usage/datadelivery/count?key=demo
https://solargis.info/ws/usage/pvplanner/count?key=demo

Optional parameters:
  • from - count WS calls beginning with specified date, inclusive; format yyyy-MM-dd (e.g. 2014-01-01)
  • to - count WS calls until specified date, exclusive; format yyyy-MM-dd

Full example:

https://solargis.info/ws/usage/datadelivery/count?key=demo&from=2014-01-01&to=2015-01-01 (demo calls to datadelivery WS for year 2014)

limit/count

Returns current count of calls which are remaining (if any) or N/A otherwise. If 0 is returned, usage limit is reached and no more calls will be processed.

URL pattern:

https://solargis.info/ws/usage/{webservice}/limit/count?key={key}

Replace {webservice} with either pvplanner or datadelivery and {key} with your access key you have obtained with your WS account.

Examples:

https://solargis.info/ws/usage/datadelivery/limit/count?key=YOUR_KEY
https://solargis.info/ws/usage/pvplanner/limit/count?key=YOUR_KEY

 

DataDelivery information units API

data units

Returns sum of days of data returned from DataDelivery WS, also known as "Information Units" (data units). No matter of summarization used, number of requested days are counted.

URL pattern:

https://solargis.info/ws/usage/datadelivery/units?key={key}

Replace {key} with your access key you have obtained with your WS account.

Example:

https://solargis.info/ws/usage/datadelivery/units?key=demo

Optional parameters:
  • from - DataDelivery calls beginning with specified date, inclusive; format yyyy-MM-dd (e.g. 2014-01-01)
  • to - DataDelivery calls until specified date, exclusive; format yyyy-MM-dd
  • sum - filter by DataDelivery summarization, use one of: MONTHLY, DAILY, HOURLY, MIN_15
Full example:
https://solargis.info/ws/usage/datadelivery/units?key=demo&from=2014-01-01&to=2015-01-01&sum=HOURLY (retrieved data units in HOURLY summarization by demo account during year 2014)

limit/units

Returns current Information Units (data units) for DataDelivery WS, which are remaining (if any) or N/A otherwise. If 0 is returned, usage limit is reached and no more calls will be processed. Processing or request is also not possible if requested number of data units is exceeding remaining Information Units (data units).

URL pattern:

https://solargis.info/ws/usage/datadelivery/limit/units?key={key}

Replace {key} with your access key you have obtained with your WS account.

Examples:

https://solargis.info/ws/usage/datadelivery/limit/units?key=YOUR_KEY

DataDelivery site units API

Overview

Returns number of consumed site units for given billing period. Number of consumed site units is grouped by data request summarization and data request period where each combination of data period and data summarization represents one type of site unit.
The result is then presented in JSON format. For example:

https://solargis.info/ws/usage/datadelivery/sites?key=demo&from=2016-03-01&to=2016-04-01

will return result equivalent to this table:

data_perioddata_summarizationcount
HISTORICMIN_1510
RECENTHOURLY20
RECENTMIN_15150
FORECASTHOURLY30

which for billing period of March 2016 summarizes how many site units of each type were consumed, e.g. 10 units for type = "HISTORIC + MIN_15",  20 units for type = "RECENT + HOURLY" etc.

Only site unit types where count > 0 are included in the result.

Besides JSON (which is the default format), there are two other supported output formats: CSV and HTML
You can specify output format of the request by additional request parameter "format". For example to get the example above in HTML you can use:

https://solargis.info/ws/usage/datadelivery/sites?key=demo&from=2016-03-01&to=2016-04-01&format=HTML

 To check number of remaining site units please use following links:


Data periods

Each dataDelivery call is associated with one or more time periods depending on the "dateFrom", "dateTo" fields of the request. There are three types of time periods recognized by dataDelivery ws:

  • HISTORIC = all data older than beginning of previous month
  • RECENT = all data between beginning of previous month (inclusive) and today (exclusive)
  • FORECAST = all data where "dateTo" >= today

In case one request falls into multiple time periods, each time period is recorded on its own, therefore one request can be counted for example as RECENT access and also as a FORECAST access.

Site units

One site-unit represents one unique combination of (location + year + month + data summarization + data period) that was accessed in at least one data request during the billing period.

For example, following three requests made during billing period of March 2016:

  • dateFrom=2016-02-01, dateTo=2016-02-01, summarization = MIN_15, latitude = 0, longitude = 0
  • dateFrom=2016-02-02, dateTo=2016-02-02, summarization = MIN_15, latitude = 0, longitude = 0
  • dateFrom=2016-02-01, dateTo=2016-02-29 summarization = MIN_15, latitude = 10, longitude = 10

would be counted as 2 site units of type "RECENT + MIN_15"

In case one request falls into multiple months then each month represents new site unit.

For example following requests made during billing period of March 2016:

  • dateFrom=2016-01-01, dateTo=2016-01-31, summarization = MIN_15, latitude = 0, longitude = 0
  • dateFrom=2015-12-10, dateTo=2016-01-05, summarization = MIN_15, latitude = 0, longitude = 0

would be counted as 3 site units of type "HISTORIC + MIN_15", while following requests:

  • dateFrom=2015-12-01, dateTo=2015-12-01, summarization = MIN_15, latitude = 0, longitude = 0
  • dateFrom=2015-12-31, dateTo=2015-12-31, summarization = MIN_15, latitude = 0, longitude = 0

would be counted as only one site unit of type "HISTORIC + MIN_15"

In case one location is accessed with different summarizations then each summarization also represents new site unit.

For example following requests made during billing period of March 2016:

  • dateFrom=2016-02-01, dateTo=2016-02-01, summarization = MIN_15, latitude = 0, longitude = 0
  • dateFrom=2016-02-15, dateTo=2016-02-15, summarization = HOURLY, latitude = 0, longitude = 0
  • dateFrom=2016-02-01, dateTo=2016-02-29, summarization = MIN_30, latitude = 10, longitude = 10

would be counted as following:

data_perioddata_summarizationcount
RECENTHOURLY1
RECENTMIN_301
RECENTMIN_151

(thus including both HOURLY and MIN_15 for site with the same latitude / longitude)

Billing period.

Basic billing period is one month. When parameters "from" and "to" are used to specify billing periods longer than one month, first the partial results for each month will be calculated and then the partial results will be summed up for the final result.
If the specified billing period is shorter than one month, or is not a whole multiple of a month then the last partial billing period will be adjusted to length shorter than one month.

RECENT and FORECAST site units charged in previous billing period won't be charged in the next billing period. That is to assure that each month of data (of type RECENT or FORECAST) is charged only once, regardless of during which billing periods the requests were made.

For example following RECENT request made during billing period of March 2016:

  • dateFrom=2016-03-01, dateTo=2016-03-30, summarization = MIN_15, latitude = 0, longitude = 0

will be counted as 1 site unit, while this RECENT request made during period of April 2016:

  • dateFrom=2016-03-31, dateTo=2016-03-31, summarization = MIN_15, latitude = 0, longitude = 0
will be counted as 0 site units, because this site unit was already charged during March billing period.

Requests made during previous billing period do not affect billing of HISTORIC data.


  • No labels
Write a comment…