Dokumentation

Innehåll

1. Inledning
2. Autentisering
3. Sökning
4. Formatering

1. Inledning

   Det här dokumentet utgör en kortfattad beskrivning för utvecklare som vill hämta bostadsannonser ur Boolis API. Annonser hämtas via HTTP-GET och returneras som en XML eller JSON-sträng med de nyaste annonserna först. Alla annonser hämtas via api.booli.se/listing/ och kräver att man har tilldelats ett id och en nyckel från Booli.

2. Autentisering

   Autentisering sker genom att parametrarna callerId, time, unique och hash skickas med i förfrågan.
   • callerId - Ert tilldelade användarnamn, t.ex. ”boolipartner.se”
   • time - Datum och tid på formatet ISO 8601, t.ex. ”2004-02-12T15:19:21+00:00”. Klockorna på era servrar får inte gå mer än 5 minuter fel.
   • unique - En 16 tecken lång sträng som slumpgenereras för varje förfrågan, t.ex. ”f4508htyuk98fe4f”
   • hash - En sha1hash enligt sha1(callerId + time + key + unique), t.ex. ”6b76a4ede12897d42dabc2a5f9270bbdb76985af”
   Attributet key är er tilldelade nyckel vilken inte ska skickas med i förfrågan, t.ex. ”LhCvbMsW7W1pvwlb39C1P1krXdipWoD5nn6iERjl”.

3. Sökning

   Bostadsannonserna kan begränsas till ett visst geografisk område, prisklass, objekttyp etc.

   1. Geografisk avgränsning

      För att avgränsa sökningen till ett geografiskt område anges områdets namn ensamt eller tillsammans med förälderområden i förfrågan, t.ex:

      • api.booli.se/listing/Stockholm/Vasastan

      • api.booli.se/listing/Östermalm

      • api.booli.se/listing/Uppsala

   2. Söka utifrån en viss geografisk position

      För att hitta bostadsannonser kring en viss geografisk position kan en punkt och en radie skickas med för att definiera en cirkel. Punkten definieras av latitude och longitude på WGS- 84 format samt en radie angiven i kilometer. Följande definierar en cirkel med 1km radie mitt i Stockholm:

      • api.booli.se/listing?centerLat=59.3311&centerLong=18.0599&radius=1

   3. Filtrering

      Ett filter kan anges för att endast få bostadsannonser av en viss typ eller inom en viss prisklass. Filtret anges i förfrågan som filter:värde, t.ex:

      • api.booli.se/listing?typ=lägenhet&pris=500000-2000000

      • api.booli.se/listing?typ=villa,fritidshus&boarea=50-200

      Du kan filtrera din sökning på följande parametrar:
      • pris - anges som minpris-maxpris. Använd max om du inte vill ha ett maxvärde, t.ex. 500000-max
      • typ - kommaseparerad lista innehållandes en eller flera bostadstyper (lägenhet,villa,fritidshus,gård,tomt-mark,radhus,parhus,kedjehus,övrigt)
      • rum - kommaseparerad lista innehållandes de antal rum du är intresserad av (1,2,3,4,5). 5 innebär 5 eller fler
      • maxhyra - maxhyran för bostaden
      • boarea - anges som minarea-maxarea i kvm. Använd max om du inte vill ha ett maxvärde, t.ex. 80-max
      • tomtarea - anges som minarea-maxarea kvm. Använd max om du inte vill ha ett maxvärde, t.ex. 800-max
      • annonstid - max antal dagar bostaden får ha legat ute på marknaden, t.ex. 7 för att endast visa senaste veckans bostäder
      • prissankta - 1 för att endast visa bostäder vars utropspris sänkts
      • bild - 1 för att endast visa bostäder som har tillhörande bild

   4. Offset och count

      Du kan använda dig av variablerna offset och count för att stega dig igenom resultaten. I resultatet skickas det med ett totalListingsCount som du med hjälp av offset och count kan stega dig upp till. Anger du inte några av dessa variabler skickas de första 25 träffarna tillbaka.

4. Formatering

   Resultatet kan fås på JSON eller XML-format, detta styrs genom parametern format, t.ex:

   • api.booli.se/listing/Uppsala?format=json

   • api.booli.se/listing/Uppsala?format=xml

5. Gotchas

   Här är några gotchas som kan vara bra att känna till
   • Alla tecken i parametrarna ska urlencodas från UTF-8
   • Om api:t säger att tiden som du skickar inte är inom 5 minuter, dubbelkolla att strängen du skickar verkligen är i ISO 8601-format och att den sista tidsförskjutningen är ok. I Sverige kan tids-strängen till exempel se ut så här "2011-01-20T12:05:00+01:00"
   • Om du får olika antal resultat på booli.se och genom API:t så behöver inget vara fel. De privatsålda objekten vi visar upp på booli.se får vi nämligen tyvärr inte skicka med på grund av tråkiga avtal :\

Exempel i PHP

$listingResource = 'http://api.booli.se/listing';
   
// Add circle
$cntLat = 59.8569131;
$cntLong = 17.6359056;
$radiusKm = 1;
$listingResource .=
	'?centerLat=' . $cntLat .
	'&centerLong='. $cntLong .
	'&radius=' . $radiusKm;

// Add objectType and price filter
$listingResource .= '&typ=lägenhet&pris=500000-2000000';

// Add format string
$listingResource .= '&format=json';

// Add authentication data
$rnd = rand(0, PHP_INT_MAX);
$now = date('c');
$callerId = "boolipartner.se";
$privateKey = "LhCvbMsW7W1pvwlb39C1P1krXdipWoD5nn6iERjl";
$hash = sha1($callerId . $now . $privateKey . $rnd);

$authData = array(
	'callerId' => $callerId,
	'time' => $now,
	'unique' => $rnd,
	'hash' => $hash
);

// Create authentication data string
$listingResource .= '&' . http_build_query($authData);

// Setup the url with GET parameters
$curl = curl_init($listingResource);

// Tell cUrl to return data instead of echoing it
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

// Send the HTTP request
$raw = curl_exec($curl);

// Decode result
$result = json_decode($raw);

// Dump result
var_export($result, true);