Booli API

all our base are belong to you

Introduktion

Boolis API ger dig åtkomst till Boolis data och möjlighet att interagera via tredjepartsapplikationer. API:et följer principerna för REST. I den här guiden och i utforskaren hittar du förhoppningsvis allt du behöver för komma igång. Skulle du ha några frågor eller stöta på problem så kan du kontakta oss här.

I vårt användaravtal finns information om hur man får använda API:et. Utöver det legala så uppskattar vi om du kodar med ansvar :) Gör inte onödigt många requests, cacha lagom länge, berätta vem du är genom att använda lämpliga headers, User-Agent och Referrer. I vissa fall kan vi göra undantag från avtalet, kontakta oss om du är intresserad av att veta mer om detta.

Frågor och diskussioner passar utmärkt här. Vid större uppdateringar och ärenden utöver det vanliga kommer vi att skicka e-post. Vi lovar att inte bli spammiga!

Autentisering

Alla anrop autentiseras genom parametrarna callerId, time, unique och hash som skickas med i frågan. Ett exempel på hur en fråga till API:et kan se ut visas här:

https://api.booli.se/listings?q=nacka&limit=3&offset=0&callerId=[callerId]&time=1323793365&unique=3116053465361547264&hash=a053d19fcced8e180df1a40b3fc95b6560eee1af

calledId är det namn du angav då du registrerade dig.

time är en UNIX timestamp.

unique är en 16 tecken lång sträng som slumpgenereras för varje förfrågan, t.ex. ”f4508htyuk98fe4f”.

hash är en sha1hash sha1(callerId + time + key + unique) som en 40-char hexadecimal, t.ex. ”6b76a4ede12897d42dabc2a5f9270bbdb76985af”, där key är den privata nyckel du tilldelats.

Format

Det svarsformat som finns tillgängligt är JSON, enligt application/json, kodat som UTF-8. Det formatet ska alltid specificeras i frågans Accept-header. Ett exempel, med curl:

curl -H 'Accept: application/vnd.booli-v2+json' https://api.booli.se/listings?q=nacka[autentisering]

Svar och fel

Svarskoden finns alltid i svarets header. De svar som finns är:

• 200 OK: Allt gick bra (gäller GET, PUT, eller DELETE).
• 201 Created: Skapad (gäller POST).
• 400 Bad Request: Frågan var inte giltigt utformad.
• 403 Forbidden: Autentiseringen misslyckades.
• 404 Not Found: Frågan ställdes till en resurs som inte finns.
• 405 Method Not Allowed: Ej tillåten metod (t.ex. försök till att skicka en POST till en URL som bara accepterar GET).
• 406 Not Acceptable: Servern kan inte uppfylla kraven från frågan (dessa ställs med Accept-headern).
• 500 Internal Server Error: Något gick fel hos Booli.
• 503 Service Unavailable: API går för tillfället inte att nå. De flesta frågor som resulterar i felkoder (4XX eller5XX) innehåller ytterligare kort information om vad som gick fel.

Paginering

För att minska mängden information som skickas vid varje svar finns en system för paginering. Följande attribut skickas med som hjälp:

{"count": 23, // Antalet som skickades"totalCount": 48, // Det totala antalet som finns tillgängligt på servern"offset": 25, // Från vilket position resultaten ska hämtas"limit": 25, // Max antal som skickas tillbaka från servern}

Det vanliga är att första frågan har offset=0 samt limit satt till något som passar applikationen, den får dock inte överstiga 500 som är högsta tillåtna gräns. För att sedan hämta efterföljande bostadsannonser i nästa fråga så sätter man offset till det värde man har på limit och lämnar limit orörd. count och totalCount finns med som stöd vid presentation.

Versionshantering

API:et kan komma att uppdateras. Vi kommer inte att uppdatera namn på resources, däremot kan vi lägga till attribut och underresurser. Vill du frysa din applikation till en viss API-version är det möjligt, men det är inte något vi rekommenderar. Detta görs genom att sätta tidigare nämnd Accept-header till application/vnd.booli-v2+json. Exempel:

curl -H 'Accept: application/vnd.booli-v2+json' https://api.booli.se/listings?q=nacka[autentisering]

Booliloggan

Enligt vårt användaravtal ska en Booli-logga visas vid användande av API:et och den finns att ladda ner här som .png eller .ai.