---
title: "Solargis LTA API endpoint"
slug: "lta-api-endpoint"
updated: 2026-02-11T18:37:28Z
published: 2026-02-11T18:37:28Z
---
> ## Documentation Index
> Fetch the complete documentation index at: https://kb.solargis.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Solargis LTA API endpoint
**In this document**
This article provides detailed guidance on using the Solargis Long-Term Averages (LTA) endpoint, including how to structure XML requests and responses, use HTTP headers, and test the API. It also covers client code snippets for Python, enabling developers to efficiently integrate Solargis data into their applications.
> [!TIP]
> **Note**: This API endpoint offers the [Long-Term Averages API](https://kb.solargis.com/docs/solargis-long-term-averages-api), which is part of the Solargis Prospect solution.
## How to use the Long-Term Averages API endpoint
To use the API effectively, follow this Python code example. This is the example of Python program for using the Solargis LTA API endpoint. First import required dependencies:
```python
import requests
import xmltodict # https://pypi.org/project/xmltodict/, pip install xmltodict
import pprint
```
Let's create a simple XML request - we will request Solargis long-term averaged solar, meteo and PV data:
```python
lat, lon = 48.61259, 20.827079 # Demo site
request_xml = f'''
11.11:18.0 7.5:15.53 15.0:10.94 352.5:17.29
'''
```
Authenticate towards the API endpoint and attach request headers. This time we will use a token as a query string inside the URL.
```python
api_token = 'demo_pvplanner' # Use your token provided by Solargis
url = f'https://solargis.info/ws/rest/pvplanner/calculate?key={api_token}'
headers = {'Content-Type': 'application/xml'}
```
Send HTTP POST request and collect long-term averages dataset - as python dictionary:
```python
with requests.post(url, data=request_xml, headers=headers) as response:
if not response.ok:
print(f'Failed API request with code {response.status_code}:\n{response.text}')
else:
datadict = xmltodict.parse(response.text) # transform XML document into Python dictionary
response_dict = datadict['ns3:calculateResponse']
# explore solar and climate data in the response:
climate_data = response_dict['ns3:irradiation']
climate_data_reference = climate_data['ns3:reference'] # general climate data
solar_data_inplane = climate_data['ns3:inplane'] # POA irradiance components
geometry_comparison = climate_data['ns3:comparison'] # comparison of the various geometry options with selected one
optimum_angle = climate_data.get('ns3:optimum') # optimum fixed angle for the selected location
# get PV calculation data:
pv_data = response_dict['ns3:calculation']
pv_data_output = pv_data['ns3:output'] # PV system output total and specific
pv_data_losses = pv_data['ns3:losses'] # PV system losses breakdown
```
Explore dataset content:
```python
print('\nClimate data reference:')
pprint.pprint(climate_data_reference)
print('\nSolar data in-plane:')
pprint.pprint(solar_data_inplane)
print('\nGeometry comparison:')
pprint.pprint(geometry_comparison)
print('\nOptimum angle:')
pprint.pprint(optimum_angle)
print('\nPV data output:')
pprint.pprint(pv_data_output)
print('\nPV losses:')
pprint.pprint(pv_data_losses)
```
```plaintext
Climate data reference:
{'ns3:Alb': {'@monthly': '0.22 0.21 0.14 0.16 0.18 0.18 0.17 0.17 0.17 0.16 '
'0.14 0.16',
'@yearly': '0.17'},
'ns3:Dhd': {'@monthly': '0.55 0.90 1.44 2.01 2.44 2.69 2.59 2.21 1.61 1.07 '
'0.64 0.45',
'@yearly': '1.55'},
'ns3:Dnid': {'@monthly': '1.68 2.40 3.43 3.64 4.08 4.29 4.14 4.36 3.40 2.58 '
'1.54 1.24',
'@yearly': '3.06'},
'ns3:Dnim': {'@monthly': '52.1 67.1 106.3 109.2 126.5 128.6 128.3 135.0 102.0 '
'80.0 46.2 38.4',
'@yearly': '1119.7'},
'ns3:Ghd': {'@monthly': '0.93 1.70 3.03 4.13 5.06 5.54 5.31 4.84 3.38 2.06 '
'1.06 0.67',
'@yearly': '3.15'},
'ns3:Ghm': {'@monthly': '28.7 47.6 93.8 123.8 157.0 166.3 164.7 150.0 101.3 '
'63.9 31.8 20.8',
'@yearly': '1149.7'},
'ns3:Prec': {'@monthly': '41.8 41.9 43.6 62.5 84.7 82.2 98.0 74.0 65.6 55.4 '
'53.1 45.0',
'@yearly': '747.8'},
'ns3:Pwat': {'@monthly': '99.0 105.0 100.0 115.0 137.0 184.0 261.0 264.0 '
'202.0 149.0 119.0 106.0',
'@yearly': '153.0'},
'ns3:Rh': {'@monthly': '86.0 81.0 71.0 67.0 72.0 73.0 73.0 75.0 79.0 83.0 '
'87.0 88.0',
'@yearly': '78.0'},
'ns3:Td': {'@monthly': '-2.3 -0.2 3.9 9.8 14.8 18.8 20.6 20.2 15.1 9.4 4.0 '
'-1.0',
'@yearly': '9.5'},
'ns3:Tmax': {'@monthly': '0.8 3.4 8.2 14.3 19.0 22.8 24.7 24.5 19.2 13.3 6.9 '
'1.4'},
'ns3:Tmin': {'@monthly': '-4.3 -3.1 -0.0 4.7 9.8 13.8 15.7 15.4 11.1 6.3 2.1 '
'-2.5'},
'ns3:Ws': {'@monthly': '2.1 2.3 2.6 2.6 2.4 2.3 2.1 2.0 2.2 2.0 2.0 2.0',
'@yearly': '2.2'},
'ns3:invar': {'@monthly': '-1.0 -1.0 -1.0 -1.0 -1.0 -1.0 -1.0 -1.0 -1.0 -1.0 '
'-1.0 -1.0',
'@yearly': '-1.0'}}
Solar data in-plane:
{'ns3:Did': {'@monthly': '0.60 0.97 1.53 2.05 2.41 2.63 2.56 2.27 1.69 1.15 '
'0.70 0.47',
'@yearly': '1.59'},
'ns3:Gid': {'@monthly': '1.40 2.39 3.81 4.64 5.27 5.59 5.45 5.33 4.06 2.77 '
'1.54 0.98',
'@yearly': '3.61'},
'ns3:Gim': {'@monthly': '43.4 67.0 118.0 139.2 163.5 167.8 169.0 165.4 121.7 '
'85.8 45.9 30.3',
'@yearly': '1317.0'},
'ns3:Rid': {'@monthly': '0.01 0.02 0.02 0.03 0.04 0.05 0.04 0.04 0.03 0.02 '
'0.01 0.01',
'@yearly': '0.03'},
'ns3:ShLoss': {'@monthly': '18.7 9.5 5.3 3.6 3.1 3.0 3.0 3.3 4.1 7.3 13.3 '
'25.4',
'@yearly': '5.7'}}
Geometry comparison:
{'ns3:horizontal': {'@percentOpt': '86.8', '@yearlySum': '1150.0'},
'ns3:optimum': {'@percentOpt': '100.0', '@yearlySum': '1324.0'},
'ns3:selected': {'@percentOpt': '99.5', '@yearlySum': '1317.0'},
'ns3:tracker2x': {'@percentOpt': '118.6', '@yearlySum': '1570.0'}}
Optimum angle:
{'@fixed': '28.0'}
PV data output:
{'ns3:Esd': {'@monthly': '1.26 2.13 3.28 3.84 4.25 4.44 4.31 4.26 3.34 2.37 '
'1.35 0.87',
'@yearly': '2.98'},
'ns3:Eshare': {'@monthly': '3.6 5.5 9.3 10.6 12.1 12.2 12.3 12.1 9.2 6.7 3.7 '
'2.5',
'@yearly': '100.0'},
'ns3:Esm': {'@monthly': '39.2 59.6 101.6 115.3 131.7 133.1 133.7 132.1 100.3 '
'73.4 40.4 27.1',
'@yearly': '1087.5'},
'ns3:Etm': {'@monthly': '11760.0 17880.0 30480.0 34590.0 39510.0 39930.0 '
'40110.0 39630.0 30090.0 22020.0 12120.0 8130.0',
'@yearly': '326250.0'},
'ns3:PR': {'@monthly': '73.4 80.5 81.5 79.8 78.1 76.9 76.7 77.3 79.1 79.4 '
'76.3 66.6',
'@yearly': '77.9'}}
PV losses:
{'ns3:acLoss': {'@PRc': '78.7',
'@PRp': '98.6',
'@lossAbs': '-16',
'@lossRel': '-1.43',
'@output': '1099'},
'ns3:angular': {'@PRc': '89.6',
'@PRp': '95.1',
'@lossAbs': '-65',
'@lossRel': '-4.94',
'@output': '1252'},
'ns3:availability': {'@PRc': '77.9',
'@PRp': '99.0',
'@lossAbs': '-11',
'@lossRel': '-1.0',
'@output': '1088'},
'ns3:conversion': {'@PRc': '86.6',
'@PRp': '96.6',
'@lossAbs': '-42',
'@lossRel': '-3.35',
'@output': '1210'},
'ns3:dcLoss': {'@PRc': '81.9',
'@PRp': '94.5',
'@lossAbs': '-66',
'@lossRel': '-5.45',
'@output': '1144'},
'ns3:global': {'@PRc': '100.0', '@PRp': '100.0', '@output': '1397'},
'ns3:inverter': {'@PRc': '79.8',
'@PRp': '97.5',
'@lossAbs': '-29',
'@lossRel': '-2.53',
'@output': '1115'},
'ns3:terrain': {'@PRc': '94.3',
'@PRp': '94.3',
'@lossAbs': '-80',
'@lossRel': '-5.73',
'@output': '1317'},
'ns3:total': {'@PRc': '77.9',
'@lossAbs': '-309',
'@lossRel': '-22.12',
'@output': '1088'}}
```
You can also test the API in command-line tools like cURL:
```bash
curl -i -X POST "https://solargis.info/ws/rest/pvplanner/calculate?key=demo" -H "Content-Type: application/xml" -d '
11.11:18.0 7.5:15.53 15.0:10.94 352.5:17.29
'
```
For greater interactivity you can test the API in featured applications like Postman.
After sending the request, review the HTTP response to understand the data structure and content returned by the API.
**full XML request example**
```xml
11.11:18.0 7.5:15.53 15.0:10.94 352.5:17.29
```
### Returned HTTP response headers
Alongside standard HTTP response headers, such as the content-type or date, the LTA API provides custom Solargis headers that help customers with usage monitoring and troubleshooting.
- **solargis-request-id**: every API transaction gets a unique ID for later reference, e.g. b785345a-430d-44bb-aa09-7e63acfeb9bb.
The users can check their API consumption after each call. We are adding these custom response headers in each call (specific headers are present in the response only if your subscription applies for the specific limit):
- **solargis-usage-total** and **solargis-limit-total**: counter and limit for total number of calls, the counter is valid for the entire subscription validity range.
- **solargis-usage-unique-locations**and **solargis-limit-unique-locations**: counter and limit for number of unique locations visited by the subscription, the counter is valid for the entire subscription validity range.
### Error codes
Error responses do not affect usage counters.
| HTTP Status | Error | Description |
| --- | --- | --- |
| 400 | Bad Request | Raised for various XML validation and parsing errors. It is a client error. |
| 401 | Unauthorized | Raised for authentication-related errors, wrong or non-existing tokens or usernames. |
| 405 | Method Not Allowed | Raised when the HTTP method is not allowed e.g., getting the resource which supports only POST method. |
| 429 | Too Many Requests | Raised when the call rate or other limit is exceeded. |
| 500 | Internal Server Error | Raised for unexpected internal errors caused by Solargis. |
### How usage is limited in the API
API usage is subject to various limits across different areas and it is determined by your subscription.
Limits relate to call rates:
- **Total Call Rate Limit**: The total number of calls allowed for the entire subscription period. This API endpoint is limited mostly by total limit as the long-term averages dataset update rate is only once per year.
- **Call Rate Limit per Minute (Fair Use Policy)**: Ensures fair usage by limiting the number of calls per minute.
Although an API subscription grants users global access, it may be limited to a specific number of unique locations. This typically applies for Free trials or Education subscriptions.
- **Number of Unique Locations**: Limits the number of unique locations a subscription can access. Evaluating unique locations is based on concatenating the latitude and longitude tuple into its text representation. Therefore, even a tiny change in the decimal place is considered a new location, with no rounding or buffering around the site location.
We also offer a demonstration API subscription that anyone can use to test all API capabilities on a single, unmetered location. You can see the use of the demo account in the Python program example above.
## XML request
---
### calculateRequest - the root element of the request
**Element**: `<calculateRequest>`
- **Namespace**: [http://solargis.info/schema/ws-pvplanner.xsd](http://solargis.info/schema/ws-data.xsd)
- **Description**: The root element of the XML request, : `<calculateRequest>` has one optional attribute:
- `@optimize`
- **Content**:
- Required elements:
- One `<site>` element.
**Attributes**
| Attribute | Required | Description | Type |
| --- | --- | --- | --- |
| `@optimize` | No | If 'true' the PV array geometry tilt angle is ignored during the PV calculation, instead the optimal tilt angle for the location is used. Optimum angle value is also returned in response. | boolean |
### Site
**Element**: `<site>`
- **Namespace**: [http://solargis.info/schema/common-pv.xsd](http://solargis.info/schema/common-pv.xsd)
- **Description**: The `<site>` element specifies the geographical location and environmental condition of a site and may include additional details about PV technology and PV array geometry.
- **Content**:
- One `<geometry>` element.
- One `<system>` element.
- One `<terrain>` element.
- One `<horizon>` element.
**Attributes**
| Attribute | Required | Description | Format/Example |
| --- | --- | --- | --- |
| `@lat` | Yes | Latitude of the site in decimal degrees. | Example: `48.61259` |
| `@lng` | Yes | Longitude of the site in decimal degrees. | Example: `20.827079` |
**Example**
```xml
```
#### Terrain
**Element**: `<terrain>`
- **Namespace**: [http://solargis.info/schema/common-geo.xsd](http://solargis.info/schema/common-geo.xsd)
- **Description**: The `<terrain>` element defines ground terrain characteristics, such as elevation, slope tilt, and azimuth orientation.
- **Content**: None (attributes only).
**Attributes**
| Attribute | Required | Description | Default/Example |
| --- | --- | --- | --- |
| `@elevation` | No | Elevation above mean sea level in meters. If omitted, the value is retrieved from the SRTM terrain database. | Example: `246` |
| `@azimuth` | No | Orientation of tilted terrain in degrees (0° = North, 180° = South, measured clockwise). Has no effect on flat terrain (tilt=0). Default is 180°. | Default: `180`, Example: `176` |
| `@tilt` | No | Slope tilt of the terrain in degrees (0° = flat ground, 90° = vertical surface). Default is 0°. | Default: `0`, Example: `3.1` |
**Example**
```xml
```
#### Horizon
**Element**: `<horizon>`
- **Namespace**: [http://solargis.info/schema/common-geo.xsd](http://solargis.info/schema/common-geo.xsd)
- **Description**: The `<horizon>` element allows users to define a custom skyline to account for distant or nearby obstructions, such as hills, trees, buildings, or poles.
- **Content**:
- A string containing a space-delimited list of azimuth and horizon height pairs in the format [azimuth in degrees: 0-360]:[horizon height in degrees: 0-90].
**Example**
```xml
0:3.6 123:5.6 359:6
```
**FAQs about the horizon**
How to remove shading losses due to terrain horizon from the long-term averaged data? Just send completely flat horizon in the XML request: `<geo:horizon>0:0 360:0</geo:horizon>`
Is it possible to get Solargis horizon data from the XML response? No, it is not possible to obtain Solargis horizon data from the XML response if it was not included in the XML request. When a customer does not include a horizon definition in the XML request, the XML response will not contain the horizon data used for the PV calculation. However, if a customer includes their custom horizon data (downloaded from Solargis Prospect or another source) in the XML request, the XML response will show the same horizon data to confirm that it was used.
#### PV array geometry
**Element**: `<geometry>`
- **Namespace**: [http://solargis.info/schema/common-pv.xsd](http://solargis.info/schema/common-pv.xsd)
- **Description**: The `<geometry>` element specifies the mounting type of the PV system, which is used for calculating GTI (Global Tilted Irradiation) and PVOUT (Photovoltaic Output). If this element is omitted and GTI/PVOUT is requested, flat-lying PV panels are assumed (GTI = GHI).
- **Content**: None (attributes only).
**Attributes**
| Attribute | Required | Description | Default/Example |
| --- | --- | --- | --- |
| `@type` | Yes | Specifies the mounting geometry type. Accepted values are: `GeometryFixedOneAngle, GeometryOneAxisHorizontalNS, GeometryOneAxisInclinedNS, GeometryOneAxisVertical, GeometryTwoAxisAstronomical.` | Example: pv:`GeometryFixedOneAngle` |
| `@azimuth` | No | True geographical azimuth in degrees (0° = North, 90° = East, 180° = South, 270° = West). Required for `GeometryFixedOneAngle`. Defaults to 180° for trackers. | Example: `180` |
| `@tilt` | No | Tilt of the panel surface in degrees (0° = horizontal, 90° = vertical). Required for `GeometryFixedOneAngle and GeometryOneAxisVertical.` | Example: `25` |
| `@axisTilt` | No | Tilt of the inclined rotating axis in degrees (0° = horizontal, 90° = vertical). Applicable only to GeometryOneAxisInclinedNS. Defaults to 30°. | Example: `30` |
**Examples**
Fixed-angle geometry:
```xml
```
Horizontal single-axis tracker:
```xml
```
Inclined single-axis tracker:
```xml
```
Vertical single-axis tracker:
```xml
```
Two-axis astronomical tracker:
```xml
```
#### PV System
**Element**: `<system>`
- **Namespace**: [http://solargis.info/schema/common-pv.xsd](http://solargis.info/schema/common-pv.xsd)
- **Description**: The `<system>` element defines the parametrization of the PV system and is required for simulating the PVOUT parameter.
- **Content**:
- Required elements:
- `<module>`: Specifies the characteristics of the PV modules.
- `<inverter>`: Defines the inverter properties.
- `<losses>`: Details losses in the PV system.
**Attributes**
| Attribute | Required | Description | Default/Example |
| --- | --- | --- | --- |
| `@installedPower` | Yes | Total installed DC power of the PV system in kilowatts-peak (kWp). Must be greater than zero. The value represents the sum of panel ratings measured under STC. | Example: `10.5` |
| `@installationType` | No | Installation type of the PV system. Accepted values are `FREE_STANDING` (default), `ROOF_MOUNTED`, and `BUILDING_INTEGRATED`. This attribute helps estimate module cooling. | Default: `FREE_STANDING`, Example: `ROOF_MOUNTED` |
| `@availability` | Yes | PV system availability [%] | Example: `99` |
#### PV Module
**Element**: `<module>`
- **Namespace**: [http://solargis.info/schema/common-pv.xsd](http://solargis.info/schema/common-pv.xsd)
- **Description**: Parametrization of the PV system modules. All modules in one PV system are considered of the same type.
- **Content**: None (attributes only)
**Attributes**
| Attribute | Required | Description | Default/Example |
| --- | --- | --- | --- |
| `@type` | Yes | Enumerated codes for materials used in PV modules. Use 'CSI' for crystalline silicon, 'ASI' for amorphous silicon, 'CDTE' for cadmium telluride, 'CIS' for copper indium selenide. For the estimate of module's surface reflectance we use an approach described [here](https://pvpmc.sandia.gov/modeling-steps/1-weather-design-inputs/shading-soiling-and-reflection-losses/incident-angle-reflection-losses/martin-and-ruiz-model/). | Example: `CSI` |
#### Inverter
**Element**: `<inverter>`
- **Namespace**: [http://solargis.info/schema/common-pv.xsd](http://solargis.info/schema/common-pv.xsd)
- **Description**: The `<inverter>` element defines the properties of the PV system inverter and is required for simulating the PVOUT parameter. All inverters in a single system are assumed to be identical.
- **Content**:
- `<efficiency>`: Specifies inverter efficiency modeling.
#### Inverter efficiency
**Element**: `<efficiency>`
- **Namespace**: [http://solargis.info/schema/common-pv.xsd](http://solargis.info/schema/common-pv.xsd)
- **Description**: The `<efficiency>` element specifies how inverter efficiency is modeled. If omitted, efficiency defaults to a constant 97.5%.
- **Content**: None (attributes only).
**Attributes**
| Attribute | Required | Description | Example |
| --- | --- | --- | --- |
| `@xsi:type` | Yes | Efficiency modeling type. Accepted values: `pv:EfficiencyConstant`. | `pv:EfficiencyConstant` |
| `@value` | No | Required for `pv:EfficiencyConstant`. Specifies a constant efficiency percentage (e.g., Euro or CEC efficiency). Valid range: 70–100%. | `value="97.5"` |
**Examples**
Constant efficiency:
```xml
```
#### PV losses
**Element**: `<losses>`
- **Namespace**: http[://solargis.info/schema/common-pv.xsd](http://solargis.info/schema/common-pv.xsd)
- **Description**: The `<losses>` element estimates power losses in the PV system. If omitted, default loss values are applied.
- **Content**: None (attributes only)
**Attributes**
| Attribute | Required | Description | Example |
| --- | --- | --- | --- |
| `@dc` | Yes | Overall estimated losses on the DC side [%] | `5.5` |
| `@ac` | Yes | Overall estimated losses on the AC side [%] | `1.5` |
**Example**
```xml
```
## XML response
---
The root element of the XML response is `<calculateResponse>`, which contains:
- The`<site>` element from the XML request together with `terrain`, `horizon`, `geometry` and `system` sub elements.
- The `irradiation` element with its sub elements:
- `reference`: Climate reference data for the location.
- `inplane`: Section about POA irradiance and its compoments including shading losses.
- `comparison`: Comparison of multiple scenarios of the PV mounting geometry towards the optimal solution.
- `optimum`: Optimum tilt angle calculated by Solargis for the requested location.
- The `calculation` element with its sub elements:
- `output`: PV energy output in long-term averaged monthly, daily and yearly values for both the nominal output per 1 kWp installed (in kWh/kWp) and for the total installed capacity (in kWh), plus the calculated performance ratio (in %).
- `losses`: Breakdown of PV losses (in absolute and relative values) caused by different factors.
**XML response example**
```xml
11.11:18.0 7.5:15.53 15.0:10.94 22.5:10.59 30.0:13.06 37.5:14.47 45.0:14.47 52.5:13.76 60.0:12.35 67.5:11.29 75.0:8.12 82.5:4.59 90.0:1.41 97.5:0.35 105.0:0.35 112.5:0.35 120.0:0.35 127.5:0.35 135.0:0.0 142.5:0.0 150.0:0.35 157.5:1.41 165.0:2.47 172.5:2.47 180.0:2.82 187.5:3.18 195.0:2.82 202.5:2.47 210.0:2.47 217.5:2.47 225.0:3.18 232.5:3.18 240.0:2.47 247.5:2.12 255.0:2.12 262.5:2.82 270.0:3.88 277.5:6.71 285.0:8.47 292.5:10.24 300.0:11.29 307.5:12.71 315.0:14.12 322.5:15.53 330.0:16.24 337.5:16.94 345.0:17.29 352.5:17.29
PV system: 1.0 kWp, crystalline silicon, fixed roof, azim. 175° (south), inclination 45°
```