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.

Sist oppdatert 2026-09-15 · Markdown · OpenAPI

• POST /api/terrain/jobs
• GET /api/terrain/jobs/{id}
• GET /api/terrain/jobs/{id}/fil
• POST /api/roof/jobs
• GET /api/roof/jobs/{id}
• GET /api/roof/jobs/{id}/tegning.png

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:

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.

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)

# 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 og takanalyse.