TMY API request-response technical description

Owned by Peter Huluk (Unlicensed)
Last updated: 06. 02. 2023 by Daniel Ranusa
5 min read

TMY API definition

The system currently exposes 3 different endpoints that support TMY data generation and retrieving. Each TMY API call expects a different data structure as defined below.

 

TMY data generation request

Request: each TMY data generation request has to contain:

  • Authorization header

  • Body

Response: result for the case of successful processing is:

  • requestId – the generated ID is further used as input in the status request

 

TMY data generation request status
Request: each TMY data generation status request has to contain:

  • Authorization header

  • requestId – the value is being used in the URL path

Response: result for the case of successful processing is:

  • URL from where generated data can be downloaded by any user

 

Generated output TMY data as body in message response

Request: each TMY data generation request has to contain:

  • Authorization header

  • requestId – the value is being used in the URL path

  • Output format - expected output data format specified in the URL path

Response: result for the case of successful processing is:

  • Output data – output data in message response

 

Subscription (Company + User) details request
Request: each subscription details request has to contain:

  • Authorization header

Response: result for the case of successful processing is:

  • Subscription details

 

TMY data generation request

Request method: POST

URL: https://api.solargis.com/tmy/data-request

 

Request message

Header:

Key

Value

Key

Value

authorization

Bearer {token generated by Company admin via UI}

 

Body:

Field name

Type

Mandatory

Supported Values

Description

Field name

Type

Mandatory

Supported Values

Description

latitude

Decimal

Yes

60N to 45S *

Coordinate to describe a position. Only numerical value - see the example below

longitude

Decimal

Yes

-180 to +180

Coordinate to describe a position. Only numerical value - see the example below

timeStep

Text

Yes

  • PT60M

  • PT15M

Supported TMY data frequency (time step) as ISO8601

tmyScenario

Text

Yes

P50

Supported probability of exceedance

outputFormats

Text

Yes

  • SOLARGIS_JSON

  • SOLARGIS_CSV

  • SAM

  • HELIOSCOPE

Supported output formats

siteName

Text

Yes

Free text

Free text

fileLabel

Text

No

Alphanumeric characters + underscore characterCoordinate to describe a position

Free text

 * Data for southern New Zealand is accessible, despite it being under 45° S latitude.

 

Request message example

POST: https://api.solargis.com/tmy/data-request

{   "latitude": 42.91,   "longitude": -114.84,   "timeStep": "PT60M",   "tmyScenario": "P50",   "outputFormats": ["SOLARGIS_CSV","SOLARGIS_JSON", "SAM", "HELIOSCOPE"],   "siteName": "Pro example Site",   "fileLabel": "pro_01" }

 

 

Response message

HTTP: 200 OK

Field name

Type

Mandatory

Length

Description

Field name

Type

Mandatory

Length

Description

requestId

string - random ID

Yes

 max 36

Request identifier

Response message example

{     "requestId": "5qmuSlqinM" }

 

 

TMY data generation request status

Request method: GET

URL: https://api.solargis.com/tmy/data-request/{requestId}

Request message

Header:

Key

Value

Key

Value

authorization

Bearer {token generated by Company admin via UI}

 

Body:

Field name

Type

Mandatory

Supported Values

Description

Field name

Type

Mandatory

Supported Values

Description

-

-

-

-

-

Note: Status request does not send body within request message – only requestId is being used as an identifier as part of the requested URL

 

Request message example

GET: https://api.solargis.com/tmy/data-request/5qmuSlqinM

Response message

HTTP: 200 OK

 

Field name

Type

Mandatory

Description

Field name

Type

Mandatory

Description

status

Text

Yes

Enum: queued, processing, success, reject, error, expired

statusCode

Text

No

 

statusMessage

Text

No

 

downloadUrl

Text

No

Is provided only once the processing of the data request was successful. Status = Success

 

  • Generated data are stored on the S3 environment for 7 days. After 7 days, system permanently deletes these generated data.

  • URL for data fetching retrieved from status API call is valid for 24 hours. After 24 hours, user has to send new request to get new valid URL.

 

 

Status description:

  • queued: request was successfully validated, subscription calculations were executed, the number of pending requests was increased, and the request was sent into Queue for further processing by our TMY Core team

  • processing: TMY Core team started processing the request read from the queue

  • success: request was successfully processed, and data were stored in AWS S3

  • reject: Validation in TMY Core failed. Most common issues: longitude and latitude point to the area for which we are not able to provide data, …

  • error: Unexpected server error during the request processing

  • Future status - expired: Status is not used yet. When the rules about request expiration will be introduced, information about the status will be provided

 

Response message example

HTTP 200 {     "status": "processing",     "statusCode": "102",     "statusMessage": "Request is being processed." }

 

 

 

Generated output TMY data in message response

Request method: GET

URL: https://api.solargis.com/tmy/data-request/{requestId}/{output format}

Supported output formats:

  • SOLARGIS_JSON

  • SOLARGIS_CSV

  • SAM

  • HELIOSCOPE

Request message

Header:

Key

Value

Key

Value

authorization

Bearer {token generated by Company admin via UI}

 

Body:

Field name

Type

Mandatory

Supported Values

Description

Field name

Type

Mandatory

Supported Values

Description

-

-

-

-

-

Note: Status request does not send body within request message – only requestId and expected output data format are being used as identifiers

 

Request message example

GET: https://api.solargis.com/tmy/data-request/5qmuSlqinM/SOLARGIS_JSON

Response message

HTTP: 200 OK

 

 

Subscription (Company + User) details request

Request method: GET

URL: https://api.solargis.com/customer/company-subscription/status

Request message

Header:

Key

Value

Key

Value

authorization

Bearer {token generated by Company admin via UI}

 

Body:

Field name

Type

Mandatory

Supported Values

Description

Field name

Type

Mandatory

Supported Values

Description

-

-

-

-

-

Note: User details request does not send body within request message

 

Request message example

GET: https://api.solargis.com/customer/company-subscription/status

 

Response message

HTTP: 200 OK

Field name

Type

Mandatory

Description

Field name

Type

Mandatory

Description

user

Object

No

User object for case of user token is being used

  • firstName

Text

No

First name

  • middleName

Text

No

Middle name

  • lastName

Text

No

Last name

  • email

Text

No

Email address

company

Object

Yes

Company object

  • sgCompanyId

Text

Yes

Company ID

  • name

Text

No

Company name

subscriptions

Array of Objects

Yes

List of all subscriptions assigned to user (in case of user token is being used / for Userless token only one subscription is returned

  • id

Text

Yes

Subscription identifier

  • validFrom

Datetime

Yes

Time of validity: From

  • validTo

Datetime

Yes

Time of validity: To

  • type

Text

Yes

Subscription type

  • consumptionActive

Text

Yes

Subscription can be consumed = true, else false

  • totalRequests

Number

Yes

Amount of all requests that can be called on the subscription

  • pendingRequests

Number

Yes

Amount of all requests that are being processed

  • finishedRequests

Number

Yes

Amount of all successful requests

  • name

Text

No

Subscription custom name

 

 

Response message example