# Sol og horisont

> Horisontprofil i 720 retninger for et punkt i Norge, i tre nivåer: terreng fra DTM10 (gratis, uten nøkkel), fra takhøyde med nærfelt fra DOM 1 m, og presis analyse med skyggetap, PDF og CSV. Eksport til PVsyst, PV*SOL, SAM, HelioScope og Meteonorm.

Kilde: https://solkart.no/api/dokumentasjon/horisont · Sist oppdatert 2026-09-15 · Base-URL https://api.solkart.no · OpenAPI: https://solkart.no/openapi.json

## Tre nivåer

| Nivå | Endepunkt | Grunnlag | Bruk | Tilgang |
|---|---|---|---|---|
| 1 Terreng | `GET /api/horizon/terrain` | Kartverket DTM10, forhåndsberegnet for hele landet | Fjell og åser; input til PVGIS-lignende beregninger | Åpent, ingen kvote |
| 2 Tak | `POST /api/horizon/rooftop` | DOM 1 m (bygninger og trær) i nærfeltet, DTM10 utenfor | Horisont sett fra et tak, med nabobygg | Åpent i pilot, 5/s og 300/time per IP |
| 3 Presis | `POST /api/horizon/precise` | Som nivå 2, pluss skyggetap for en panelflate, PDF og CSV | Dokumentasjon i prosjektering | Åpent i pilot, 1/s og 30/time per IP |

Alle svarer med 720 asimutpunkter (0 til 359,5° med 0,5° oppløsning, 0 = nord, med klokka) og horisonthøyde i grader over horisontalplanet.

## GET /api/horizon/terrain

```bash
curl "https://api.solkart.no/api/horizon/terrain?lat=59.91&lon=10.75"
```

| Parameter | Standard | Beskrivelse |
|---|---|---|
| `lat`, `lon` | påkrevd | 57 til 72° N, 4 til 32° Ø |
| `format` | `json` | `json`, `binary`, `csv`, `pvsyst`, `pvsol`, `sam`, `helioscope`, `meteonorm`, `geojson` |

Svar `200` (ekte svar, Oslo sentrum; forkortet):

```json
{
  "lat": 59.91, "lon": 10.75,
  "tile_key": "599_107", "dtm_year": "2026",
  "api_tier": "terrain", "version": "v3.1",
  "n_azimuth": 720,
  "azimuth_deg": [0, 0.5, 1, 1.5, "…"],
  "elevation_deg": [1.99, 2.03, 1.97, 2.04, "…"],
  "dtm_ground_z_m": null
}
```

`format=binary` gir 1440 byte: 720 verdier som little-endian float16, for innbygging i egne verktøy. Eksportformatene leveres som fil (`Content-Disposition: inline; filename="tier1_horizon_<tile>_<lat>_<lon>.<ext>"`) i formatet verktøyet importerer direkte: PVsyst «Horizon file», PV*SOL, SAM «shading file», HelioScope, Meteonorm.

Hoder: `Cache-Control: public, max-age=86400`, `X-Horizon-Tile-Key`, `X-DTM-Year`, `X-Api-Tier: terrain`, `X-Api-Version: v3.1`.

Feil: `400` `lat og lon må være tall (grader, WGS84).` / `(lat, lon) er utenfor Norge-bbox [57, 72] × [4, 32].` / `format må være én av: …`; `404` `Ingen terrain-tile for <tile> …` (punktet er innenfor boksen, men utenfor rutenettet, typisk hav).

## POST /api/horizon/rooftop

Horisont fra et punkt over bakken, med bygninger og vegetasjon fra DOM 1 m i nærfeltet.

```bash
curl -X POST https://api.solkart.no/api/horizon/rooftop \
  -H "Content-Type: application/json" \
  -d '{"lat": 59.2185, "lon": 10.9298, "observer_height_m": 6.5}'
```

| Felt | Type | Standard | Beskrivelse |
|---|---|---|---|
| `lat`, `lon` | tall | påkrevd | 57 til 72 / 4 til 32 |
| `observer_height_m` | 0 til 50 | 3,0 | Observatørens høyde over terrenget (DTM), typisk takhøyde pluss 1 m |
| `observer_z_masl` | −50 til 3000 | | Absolutt høyde over havet; overstyrer `observer_height_m` |
| `include_tier1` | boolean | `true` | Fyll inn fjernhorisont fra nivå 1 utenfor DOM-dekningen |

`?format=` som nivå 1, unntatt `binary`.

Svar `200`:

```json
{
  "azimuth_deg": ["…720"], "elevation_deg": ["…720"],
  "tier1_used": true,
  "near_horizon_only": ["…720 grader"],
  "dtm_ground_z_m": 12.4,
  "observer_height_above_dtm_m": 6.5,
  "observer_z_masl": 18.9,
  "dom_year": "2023", "dtm_year": "2026",
  "api_tier": "rooftop", "version": "v3.1",
  "compute_ms": 2140
}
```

`near_horizon_only[i]` er horisonthøyden i grader fra nærfeltet alene (DOM, uten fjernhorisont fra nivå 1), så du kan se hvor mye nabobygg og vegetasjon bidrar i hver retning. Hoder: `X-Worker-Request-Id`, `X-API-Tier: rooftop`, `X-Quota-Remaining`.

Feil (`code`): `400 INVALID_INPUT` med presis melding (`Felt 'lat' må være et tall.`, `observer_height_m=<v> er utenfor [0, 50] m.`, `format=binary er kun støttet på Tier 1 …`); `405 METHOD_NOT_ALLOWED`; `429 RATE_LIMITED` med `Retry-After`; `502 BACKEND_ERROR`; `504 BACKEND_TIMEOUT` (10 s).

## POST /api/horizon/precise

Synkron, 3 til 15 s. Gir i tillegg skyggetap for en panelflate og lenker til PDF og CSV som er gyldige en begrenset tid.

```bash
curl -X POST https://api.solkart.no/api/horizon/precise \
  -H "Content-Type: application/json" \
  -d '{"lat": 59.2185, "lon": 10.9298, "observer_height_m": 6.5, "panel_az_deg": 180, "panel_tilt_deg": 25}'
```

| Felt | Type | Standard | Beskrivelse |
|---|---|---|---|
| `lat`, `lon`, `observer_height_m`, `observer_z_masl` | | som nivå 2 | |
| `panel_az_deg` | 0 til 360 | | Panelets asimut, 0 = nord |
| `panel_tilt_deg` | 0 til 90 | | Panelets helning |
| `email` | streng | | Mottaker av rapporten (valgfritt) |

Svar `200` (utdrag):

```json
{
  "job_id": "9c1e…",
  "azimuth_deg": ["…720"], "elevation_deg": ["…720"], "n_azimuth": 720,
  "dtm_ground_z_m": 12.4, "observer_height_above_dtm_m": 6.5, "observer_z_masl": 18.9,
  "annual_yield_reduction_pct": 3.8,
  "shaded_daylight_hours_pct": 9.1,
  "annual_shade_hours": 412,
  "near_field_objects": [ { "azimuth_deg": 214, "elevation_deg": 18.5, "distance_m": 14.2, "height_above_module_m": 4.1, "kind": "building", "shading_impact_score": 0.42 } ],
  "pdf_url": "https://…", "csv_url": "https://…", "expires_at": "2026-09-16T18:40:00Z",
  "is_stub": false,
  "dom_year": "2023", "dtm_year": "2026", "api_tier": "precise", "version": "v3.1", "compute_ms": 8400
}
```

| Felt | Enhet | Beskrivelse |
|---|---|---|
| `annual_yield_reduction_pct` | % | Årlig produksjonstap fra horisontskygge for den oppgitte panelflaten |
| `shaded_daylight_hours_pct` | % | Andel av dagslystimene der sola står under horisonten |
| `annual_shade_hours` | timer/år | Timer med skygge |
| `near_field_objects[]` | | Objekter i nærfeltet som gir skygge, med retning, avstand og påvirkning |
| `pdf_url`, `csv_url`, `expires_at` | | Signerte lenker som varer i 7 døgn; last ned før `expires_at` |

Ved andre formater enn JSON ligger `X-Precise-Pdf-Url`, `X-Precise-Csv-Url` og `X-Precise-Job-Id` i hodene. Feilene er som for nivå 2 (tidsavbrudd 60 s i stedet for 10 s), med i tillegg `Felt 'email' ser ikke ut til å være en gyldig e-postadresse.` og `panel_tilt_deg=<v> er utenfor [0, 90].`.

## Bruk horisonten i egne beregninger

- **PVGIS:** PVGIS tar horisonten som en liste med høyder per asimut; bruk `elevation_deg` direkte (PVGIS forventer 0 = nord, med klokka, som her), eventuelt tynnet til 48 punkter.
- **pvlib:** `pvlib.shading` og `irradiance.get_total_irradiance` kan ta horisontprofilen; interpoler `elevation_deg` på solens asimut per time og sett direkte innstråling til 0 når solhøyden er under horisonten.
- **PV-kalkulatoren** på solkart.no gjør dette allerede (`horizon=1` er standard i [`/api/pv/calc`](/api/dokumentasjon/pv)).

Samme data i nettleseren, med solbane for valgfri dato: [solkart.no/sol-og-horisont](/sol-og-horisont).