Volgen

Publiceren met een API koppeling

Wij hebben een nieuwe versie van dit document online gezet over het publiceren met een API koppeling. De werking is vrijwel gelijk, de informatie die u kunt opvragen is echter uitgebreid. Deze (Engelstalige) documentatie kunt u vinden onder deze link.

Introductie

Met de API kunt u alle informatie inladen en naar eigen wens plaatsen, indelen en vormgeven op uw eigen website. U bent niet afhankelijk van de vormgeving van HelpMee. De gegevens die u ontvangt van HelpMee worden geïndexeerd door zoekmachines alsof het uw eigen content is. Het enige nadeel is dat u of uw webbouwer over voldoende kennis moet beschikken om het te kunnen implementeren.

Inhoud van dit artikel

Stap 1: Koppeling activeren en API key opvragen

Heeft u al een API key gekregen, dan kunt u deze stap overslaan.

Log in op het dashboard voor makelaars via de mail of het login formulier (https://www.helpmee.nl/dashboard/login) en klik rechts bovenin op het tandwiel icoon (instellingen). Kies voor “Koppelingen”.

Vanuit de lijst kiest u voor “Eigen website (publiceren)”, klik op de button “Bewerken”.

Om de koppeling te activeren kiest u voor “Bewerken”. Vink vervolgens de optie “Ja, geef mij een API key zodat ik mijn data via XML/JSON kan benaderen” aan en klik op “opslaan”.

De koppeling is nu actief! De API Key is direct zichtbaar en zal bestaan uit cijfers en letters in een willekeurige reeks: 99999999-9999-9999-9999-999999999999

Stap 2: API koppeling aanroepen

Wij raden aan om programma te gebruiken zoals “Postman”. Dit is een Google Chrome app waarmee u eenvoudig een API kunt testen en informatie kunt ophalen.

API documentatie is te vinden op: https://helpmee.nl/api/public/doc
U kunt de API aanroepen om een overzicht te krijgen van actieve promoties/viral (via basis call) of om specifieke informatie te krijgen zoals kenmerken en anekdotes. De API is aan te roepen (via GET) met de volgende link:

https://helpmee.nl/api/public/v1/[SOORT]/?type=[TYPE]&id=[OBJECT-ID]&dateSince=[DATESINCE]

Hierin staan een aantal nader in te vullen variabelen (zie hieronder).
Het is verplicht om een API key in de header mee te sturen, in voorgaande hoofdstuk de instructie om een API key op te vragen. Zodra u een API key heeft, zult u deze in de header (key = apikey) van de request moeten zetten om te authenticeren.

Heeft u een organisatie brede key nodig, of een key voor meerdere vestigingen? Dat kan! U krijgt van ons een apikey-group, neem hiervoor contact op via service@kijkmijnhuis.nl

 

[SOORT]

Hier geeft u aan welke soort informatie u wilt opvragen, keuze is te maken uit

[TYPE]

Informatie van HelpMee promoties/virals is op 2 manieren aan te roepen:

  • Op basis van het unieke ID (zie [OBJECT-ID]) afkomstig uit HelpMee
    • In het geval dat u uit gaat van het unieke ID vanuit HelpMee is het type “helpmee”.
      • Voorbeeld: type=helpmee
  • Op basis van het unieke ID (zie [OBJECT-ID]) afkomstig uit uw softwarekoppeling
    • In het geval dat u uit gaat van het unieke ID vanuit uw softwarekoppeling, dan is het type de naam van uw softwarekoppeling.
      • Voorbeeld: type=realworks

[OBJECT-ID]

De Uuid van de promotie (viral). Dit is een unieke code die per object verschilt. Hierin zijn 2 opties; afhankelijk van de keuze die gemaakt is bij [TYPE]

  • Bij keuze type “helpmee
    • De object-id kunt u vinden in het makelaars dashboard bij een detail van een promotie onder het blokje “object informatie”.
    • Voorbeeld: id=5bc36089-560b-4890-b47f-0f3a09837f86
  • Bij keuze type softwarekoppeling zoals “realworks
    • De object ID vanuit de software koppeling, is een unieke code die per object verschilt en is alleen aanwezig indien het object is geïmporteerd. De object-id, indien aanwezig, wordt verstrekt door uw softwareleverancier maar is ook in te zien in het makelaars dashboard. Bekijk hiervoor de detailpagina van het object onder het blokje “object informatie”.
    • Voorbeeld: id=123456

[DATESINCE]

  • dateSince is de datum (datatype datetime) per wanneer u de data wilt ophalen
  • Voorbeeld: dateSince=2015-07-01 11:30:00
    • Hiermee zal dan alle data aangeroepen worden, dat na 1 juli 2015 11:30 is geplaatst
  • Aanroep mag ook zonder timestamp, dan wordt uitgegaan van 00:00:00

Voorbeeld URL met “standaard” HelpMee id

https://helpmee.nl/api/public/v1/facility/?type=helpmee&id=5bc36089-560b-4890-b47f-0f3a09837f86&dateSince=2015-03-01 11:30:00

Voorbeeld URL met softwarekoppeling id

https://helpmee.nl/api/public/v1/facility/?type=realworks&id=123456&dateSince=2015-03-01 11:30:00

Voorbeeld in PHP CURL methode

Hieronder een voorbeeld in PHP middels de CURL methode.

<?php 

$ch = curl_init(); 

curl_setopt($ch, CURLOPT_URL,"https://helpmee.nl/api/public/v1/facility/?type=helpmee&id=34a6e937-b90b-4754-acd2-b6c65c02a328&dateSince=2015-03-01 11:30:00"); 

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 

$headers = array(); 
$headers[] = 'apikey: 7011167D-B234-4AA5-A619-5FBA454B4B85'; 

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); 
$data = curl_exec ($ch); 

curl_close ($ch); 
echo $data;

Basis call functie

Met de basis call functie krijgt u de algemene gegevens terug van HelpMee. Met behulp van deze call kunt u zien welke promoties/virals er actief zijn en welke objecten onlangs zijn gewijzigd. Hiermee kunt u voorkomen dat constant alle objecten opnieuw worden ingeladen.

De API is aan te roepen (via GET) met de volgende link: 

https://helpmee.nl/api/public/v1/viral/

Het is verplicht om een API key in de header mee te sturen, in voorgaande hoofdstuk de instructie om een API key op te vragen. Zodra u een API key heeft, zult u deze in de header (key = apikey) van de request moeten zetten om te authenticeren.

Heeft u een organisatie brede key nodig, of een key voor meerdere vestigingen? Dat kan! U krijgt van ons een apikey-group, neem hiervoor contact op via service@kijkmijnhuis.nl

De gegevens die u kunt terug verwachten:

  • Hash / id
  • Datum laatste wijziging
  • Datum aangemaakt
  • Url van de promotiepagina (op helpmee.nl)
  • Specifieke url voor onderdelen
    • anecdotes
    • facility
    • features
    • media
    • message

Callback functie

Het is mogelijk om te werken met een callback functie. Wij roepen dan een URL aan (naar uw keuze, op uw server) en geven object id + gegevens mee. Met behulp van deze call krijgt u direct inzicht in welke objecten u dient opnieuw in te laden. Deze call is potentieel maatwerk, afhankelijk van uw keuze. Voor meer informatie neem contact op via: service@kijkmijnhuis.nl

 

Voorbeelden implementaties

Bekijk voorbeelden van diverse partijen om een indruk te krijgen van de mogelijkheden:

Een interactief voorbeeld is bijvoorbeeld het iFrame: https://helpmee.nl/iframe/v1/?type=helpmee&id=6103057b-4a8c-4246-8dc3-6d21abbb867c 

Nog feedback of vragen?

Had u nog meer stappen verwacht? Of komt u er misschien niet uit, laat het ons weten via: service@kijkmijnhuis.nl

Was dit artikel nuttig?
Aantal gebruikers dat dit nuttig vond: 0 van 0
Hebt u meer vragen? Een aanvraag indienen

Opmerkingen