Sites & Strings
A site describes a PV system once and completely. After that you query forecasts and
historical data solely via the site_id — without sending the configuration every time.
This page explains the data model. The actual endpoints (create, update, delete, retrieve) are in the API Reference. Programmatic management is described by the Sites API.
Structure of a site
A site consists of three parts:
- Location —
latitude,longitude(required).elevation,timezoneand the terrain horizon are determined automatically. - Strings — a list of PV strings (sub-arrays) with their own geometry.
- Config — optional, system-wide fine configuration. Only explicitly set values are stored; everything else follows the current system defaults.
Create a site (body)
PV strings
Each string is a standalone sub-array. The site sums the power of all strings. When a site is created, a default string (10 kWp, 180° south, 30° tilt) is added automatically, which you can edit at any time.
| Field | Meaning |
|---|---|
id | Stable string id (e.g. str_9f3a1c08). Server-assigned and read-only. |
slope | Module tilt in degrees (0 = horizontal, 90 = vertical). |
orientation | Azimuth in degrees (0 = N, 90 = E, 180 = S, 270 = W). |
power_kw | Peak power of the string in kW. |
gcr | Ground coverage ratio for row shading (optional). |
near_field_shading | Near-field shading of the string (optional). |
Each string gets a stable id (e.g. str_9f3a1c08), minted by the server and returned with
the site. It is the join key for per-string data — the forecast/historical strings block carries
it as string_id, and measurement uploads are addressed by it.
The id is read-only: it is ignored on create. On a PATCH of strings (which replaces the
whole array), echo each string's id to keep it — and the data attached to it, e.g.
measurements. A string whose id is omitted is treated as removed; one with no id is treated as
new. Strings also still carry a positional string_index, so reading the site and forecast from the
same point in time keeps the order consistent.
Configuration (config)
The system-wide config is organized into groups. All fields are optional — if a group is missing, the system defaults apply.
| Group | Content |
|---|---|
modules | Module technology (monosi, multisi, perc, topcon, cdte), temperature coefficient, install year. |
mounting | Mounting type (open, mix, isol) and height above ground. |
inverter | Inverter clipping (max/min in % of DC rated power). |
losses | Losses & gains: cabling, conversion, albedo, snow sliding, diffuse model. |
shading | Use terrain horizon (use_terrain_horizon) and sky obstructions (sky_obstruction). |
tracking | Tracker type (fixed, single_axis, dual_axis) and axis parameters. |
Sparse storage: Only the values you explicitly set are stored. If we improve a default globally (e.g. a new irradiance model), existing sites benefit automatically.
The exact value ranges and defaults of each group are in the API Reference.
Automatically determined fields
From the coordinates, the following are determined and stored automatically on creation (and when the location changes):
elevation— height above sea level in meters.timezone— IANA timezone (e.g.Europe/Berlin), the basis for local timestamps.- Terrain horizon — feeds into the shading calculation.
Ephemeral sites
With is_ephemeral: true you mark a site as temporary/experimental. This feature requires a
suitable plan. Ephemeral sites are deleted automatically on the 1st of the following month. Making
an ephemeral site permanent (is_ephemeral: false) is always allowed.
Limits
| Limit | Behavior |
|---|---|
| Site limit | Maximum number of sites (can be unmetered). |
| String limit | Maximum strings per site. |
| Location change | Fixed at 1 location change per 30 days per site (plan-independent). |
Deletion & restore
Deleted sites are first marked as "pending deletion" (deleted_at set) and only
permanently removed 30 days later. Within this window they can be restored.
Details in the API Reference.