TMY API request-response technical description
- Peter Huluk (Unlicensed)
- Daniel Ranusa
- Samuel Suri
- 1 TMY API definition
- 2 TMY data generation request
- 2.1 Request message
- 2.2 Response message
- 3 TMY data generation request status
- 3.1 Request message
- 3.2 Response message
- 4 Generated output TMY data in message response
- 4.1 Request message
- 4.2 Response message
- 5 Subscription (Company + User) details request
- 5.1 Request message
- 5.2 Response message
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 |
|---|---|
authorization | Bearer {token generated by Company admin via UI} |
Body:
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 |
| Supported TMY data frequency (time step) as ISO8601 |
tmyScenario | Text | Yes | P50 | Supported probability of exceedance |
outputFormats | Text | Yes |
| 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 |
|---|---|---|---|---|
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 |
|---|---|
authorization | Bearer {token generated by Company admin via UI} |
Body:
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 |
|---|---|---|---|
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 |
|---|---|
authorization | Bearer {token generated by Company admin via UI} |
Body:
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 |
|---|---|
authorization | Bearer {token generated by Company admin via UI} |
Body:
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 |
|---|---|---|---|
user | Object | No | User object for case of user token is being used |
| Text | No | First name |
| Text | No | Middle name |
| Text | No | Last name |
| Text | No | Email address |
company | Object | Yes | Company object |
| Text | Yes | Company ID |
| 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 |
| Text | Yes | Subscription identifier |
| Datetime | Yes | Time of validity: From |
| Datetime | Yes | Time of validity: To |
| Text | Yes | Subscription type |
| Text | Yes | Subscription can be consumed = true, else false |
| Number | Yes | Amount of all requests that can be called on the subscription |
| Number | Yes | Amount of all requests that are being processed |
| Number | Yes | Amount of all successful requests |
| Text | No | Subscription custom name |
Response message example