Felkontraktet

200 OK med en tom lista betyder två saker: att världen är tom, eller att frågan aldrig gick fram. Samma bytes, motsatt innebörd. Vi har mätt femton varianter av det felet i källor vi själva använder, och kontraktet nedan finns för att vi inte ska skicka det vidare.

Regel 1: tomt är ett besked, inte ett fel

Går frågan fram och svaret är tomt får du 200 och en tom lista. Går frågan inte fram får du 502 eller 503 med ett skal-fält i klartext. En backend som inte svarar blir aldrig en tom lista hos dig.

Regel 2: null betyder omätt, aldrig noll

"spridning": {
  "traffar": 0, "kommuner": 0,
  "entydig": null,
  "skal": "frågan matchar inget ortnamn — spridningen är OMÄTT för den här frågan"
}

entydig: null betyder att frågan inte gick att mäta (en gatuadress är inget ortnamn). Behandla det aldrig som true. Får du inte peka fel: kräv entydig === true, annars fråga användaren.

Samma regel gäller hojd_m: null med nodata: true (ingen höjddata i punkten — inte havsnivå) och swing: null i valresultaten (distriktet får inte jämföras — inte noll förändring).

Regel 3: ett tak är inte ett antal

antal är hur många rader du fick. total (ortnamn) och antal_i_fonstret (avverkning) är hur många som finns, räknat före limiten, och avkortad/trunkerad säger att taket klippte.

Fyra olika ortnamn gav i vår egen mätning exakt 50 träffar var, för 50 var taket. Ett API som bara lämnar radantalet lär dig publicera limiten som ett resultat.

Regel 4: "inte svept" är okänt, inte noll

Register vi hämtar kommunvis bär ett tillståndsfält: kommunen_ar_svept, tillstand: "inlast". Är det falskt eller saknas är antalet okänt. Skriv inte "noll skyddsrum i kommunen" på ett svar som betyder att vi inte hämtat kommunen än — vi gjorde det misstaget själva, för 174 kommuner, och det är därför fältet finns.

Regel 5: en bild som inte kan fyllas levereras inte

/v1/render/vinjett svarar 503 med lagsta_fyllande_zoom när kartan inte kan täcka ytan, i stället för att skicka en bild med hål. Huvudet X-Fyllnad (0–1) säger hur stor del som fylldes.

Tre sätt att ligga utanför Sverige

De ser lika ut för den som skriver koden och betyder olika saker i svaret:

• Utanför koordinatfönstret (Paris): 422. Vi frågar inte ens — talet kan inte vara en punkt i Sverige.
• I fönstret, utanför landet (Oslo): uppslag som kräver en kommun ger 404 med skäl. Höjden ger 200 med hojd_m: null och nodata: true, och omvänd geokodning 200 med namn: null. Det är inte samma sak som noll meter över havet.
• I landet, men utan data i punkten (en sjö mitt i skogen): 200 med nodata: true. Frågan gick fram; kartan har ingen höjd där.

Statuskoder