# Asynkrone jobber

> Terrengkategori og takanalyse kan ta opptil et par minutter. Jobbendepunktene legger analysen i kø og lar deg hente status og resultat når den er ferdig.

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

## Når du bør bruke kø

To beregninger er for tunge til at et vanlig HTTP-kall alltid rekker fram: terrengkategori (leser høydemodeller ut til 10 km) og takanalyse (høydemodell 1 m, flyfoto og bildeanalyse). Begge finnes i to utgaver:

| Beregning | Synkront | I kø |
|---|---|---|
| Terrengkategori | `POST /api/terrain/category` (svarer innen 60 s) | `POST /api/terrain/jobs` |
| Takanalyse | `POST /api/roof/layout` (svarer innen 90 s) | `POST /api/roof/jobs` |

Bruk køen i alt som ikke er interaktiv testing. Den synkrone varianten gir `503 BACKEND_BUSY` når tjenesten er opptatt, og `504` når analysen tar for lang tid.

## Livsløpet til en jobb

1. **Opprett:** `POST` med samme kropp som det synkrone endepunktet. Svar `202 Accepted`:

    ```json
    {
      "jobb_id": "3f9a1c2b7d0e",
      "status": "queued",
      "posisjon": 2,
      "foran": 1,
      "estimert_sekunder": 45,
      "ventende_i_koen": 2
    }
    ```

    `posisjon` er plassen din i køen (1 = neste), `foran` antall jobber foran deg, `estimert_sekunder` et grovt anslag. Terrengjobber har i tillegg `format` og `bane`.

2. **Poll:** `GET /api/{terrain|roof}/jobs/{jobb_id}` gir samme konvolutt med oppdatert `status`:

    | `status` | Betyr |
    |---|---|
    | `queued` | Venter i kø |
    | `running` | Analysen kjører |
    | `done` | Ferdig; resultatet ligger i svaret |
    | `error` | Feilet; `feil: {status, melding}` forklarer |

3. **Hent resultat:** Ved `done` inneholder svaret `resultat` (JSON-analysen). For terrengkategori med `format: "pdf"` eller `"html"` får du i stedet `fil: "/terrain/jobs/{id}/fil"` og henter fila fra `GET /api/terrain/jobs/{id}/fil`. Takanalysen legger tegningen på `GET /api/roof/jobs/{id}/tegning.png` (`tegning_url` i svaret).

## Regler du må ta hensyn til

- **Levetid: 15 minutter** etter at jobben er ferdig. Deretter svarer `GET` med `404 NOT_FOUND`. Hent resultatet med én gang og lagre det selv.
- **Køstørrelse:** maks 20 ventende jobber per tjeneste. Er køen full, får du `503` med `code: "BACKEND_BUSY"` og `Retry-After` (anslått ventetid i sekunder, 30 når anslag mangler). Vent og opprett jobben på nytt.
- **Tidsavbrudd i tjenesten:** 180 s for terrengkategori, 120 s for takanalyse. Overskrides det, ender jobben som `error`.
- **Hastighet:** opprettelse er begrenset til 1 per sekund og 30 per time (terreng) eller 20 per time (tak) per IP-adresse. Polling teller ikke.
- **Id-format:** 12 heksadesimale tegn. Alt annet gir `404`.
- Fil før jobben er ferdig gir `409 NOT_READY`. Tegning etter at grunnlaget er borte gir `410 EXPIRED`.
- Statussvarene har `Cache-Control: private, no-store`; bare tegningen (`tegning.png`) kan caches i 15 minutter.

## Polling som oppfører seg pent

Poll hvert 2. sekund de første 20 sekundene, deretter hvert 5. sekund. Gi opp etter 5 minutter. Bruk `estimert_sekunder` fra første svar til å sette første ventetid.

```python
import time, requests

API = "https://api.solkart.no"
r = requests.post(f"{API}/api/terrain/jobs", json={"lat": 59.2185, "lon": 10.9298, "format": "json"}, timeout=15)
r.raise_for_status()
job = r.json()
jobb_id = job["jobb_id"]
time.sleep(min(job.get("estimert_sekunder", 5), 20))

deadline = time.time() + 300
while time.time() < deadline:
    s = requests.get(f"{API}/api/terrain/jobs/{jobb_id}", timeout=15).json()
    if s["status"] == "done":
        print(s["resultat"]["resultat"]["terrengkategori"])
        break
    if s["status"] == "error":
        raise RuntimeError(s["feil"]["melding"])
    time.sleep(2 if time.time() < deadline - 280 else 5)
```

```bash
# Opprett jobb for PDF-rapport
curl -s -X POST https://api.solkart.no/api/terrain/jobs \
  -H "Content-Type: application/json" \
  -d '{"lat": 59.2185, "lon": 10.9298, "format": "pdf", "sted": "Jegerveien 8, Fredrikstad"}'
# → {"jobb_id":"3f9a1c2b7d0e","status":"queued",...}

# Status
curl -s https://api.solkart.no/api/terrain/jobs/3f9a1c2b7d0e

# Fil når status er done
curl -s -o terrengkategori.pdf https://api.solkart.no/api/terrain/jobs/3f9a1c2b7d0e/fil
```

Detaljer om kroppen og resultatet står på [terrengkategori](/api/dokumentasjon/terrengkategori) og [takanalyse](/api/dokumentasjon/takanalyse).