Volgen

Publishing the soft side of your listing page using our API

Introduction

On HelpMee, users and their friends add the “soft side” of the house. They can add or endorse unique features, share stories and anecdotes, pinpoint interesting spots on a map and share photos and videos. Using our API, you can publish this content on your listing page. This way, Google will index this content like it is your own. You will only receive data, no mark-up. You can publish the HelpMee content exactly like you want it to.

This article has the following content:

Step 1: Getting an API key

To call our API, you would need a API key. We have keys available for agents (apikey), agent groups (apikey-group) and software suppliers (apikey-partner). If you have a login for HelpMee, you can get your API key by logging in and following the steps below. If you don’t have a login (yet), but you want to call our API, please contact service@kijkmijnhuis.nl.


Step 1: Login

Use the login link in your email or login using your credentials at: https://www.helpmee.nl/dashboard/login
After you have logged in, click on the settings icon (settings) and choose “couplings”.


Step 2: Activate and save

You will see a list of (active) couplings, look for “Website” and click on the button “Edit”.

Click on “edit”, select the option “Yes, give me an API key” and save it using the button “Save”.

Your API key is active and will be shown. The key usually consist of numbers and letters in random order, like: 99999999-9999-9999-9999-999999999999

Calling the API

Introduction

Technical documentation of the API calls can be found here: https://api.helpmee.nl/public/doc

To get content out of our API, you would need a valid API key. The API key needs to be send in the header of the request. For testing, we recommend using a program like “Postman”. This is a Google Chrome app which you can use to test our various API calls.

URL

The API can be called using GET on the following link:

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

In this example, there are variables in between [HOOKS] that need to be filled in:

[VARIANT]

The API has different variants that you can call to get certain content. All of the variants have paging (100 objects per page) enabled. The following variants are available to call:

viral

  • This variant returns a complete list of objects from HelpMee
  • This variant doesn’t need [TYPE] and [ID], to get info from a single object use the viral-detail call 
  • It contains the status of the object (for example: open, closed) 
  • It contains the url’s of the object (location where people can add content)
  • It contains the import source of the object (optional when we import object externally)
  • It contains id’s of the object (our HelpMee id and optional import id)
  • It contains dates (date of creation, date of update)
  • For more information, check out: https://api.helpmee.nl/public/doc#get--api-public-{version}-viral-

viral-detail

anecdote

  • This variant returns all anecdotes from a single object
  • In this variant you will need to supply a [TYPE] and an [ID]
  • Optional variable to add is [DATESINCE]
  • It contains user info in an array (id, name, image, thumb and type*)
  • It contains text, media and createdat
    • Media is another array, multiple images are possible
  • For more information, check out: https://api.helpmee.nl/public/doc#get--api-public-{version}-anecdote-

facility

  • This variant returns all facilities from a single object
  • In this variant you will need to supply a [TYPE] and an [ID]
  • Optional variable to add is [DATESINCE]
  • It contains user info in an array (id, name, image, thumb and type*) 
  • It returns the name of the facility, the category**, latitude, longitude and createdat 
  • For more information, check out: https://api.helpmee.nl/public/doc#get--api-public-{version}-facility-

feature

  • This variant returns all features from a single object
  • In this variant you will need to supply a [TYPE] and an [ID]
  • Optional variable to add is [DATESINCE]
  • It contains user info in an array (id, name, image, thumb and type*)
  • It returns the text of the feature and the endorsements in an array (users)
  • For more information, check out: https://api.helpmee.nl/public/doc#get--api-public-{version}-feature-

media

  • This variant returns all media from a single object
  • In this variant you will need to supply a [TYPE] and an [ID]
  • Optional variable to add is [DATESINCE]
  • It contains user info in an array (id, name, image, thumb and type*)
  • It returns a type (picture or video), imagename (location) or url (YouTube) for videos
  • You can decide to skip imported media (non user generated content) with a boolean: includeImportedMedia
  • For more information, check out: https://api.helpmee.nl/public/doc#get--api-public-{version}-media-

* Types of users available are:

  • agent
    • This type is a system type (for example: media coming from the API) 
  • agent-employee
    • This type is a contact person from the office
  • owner
    • This is the owner of the property
  • promoter
    • Friends, family and other subscribers
  • Anonymous
    • People that add anonymous, don’t make an account, or sign in anonymously

** These are all the categories for facilities:

  • pharmacy
  • bank
  • movie-theater
  • tool-shop
  • bike-shop
  • glass
  • landscaping
  • catering
  • doctor
  • barber
  • charging-station
  • old-paper
  • public-transport
  • parking
  • atm
  • recycle
  • mailbox
  • school
  • playground
  • sport
  • grocery-store
  • dentist
  • theater
  • dog-walk
  • dumpster
  • stores
  • hospital
  • remaining

[TYPE]

Based on the way object information is inserted in HelpMee, you will get to use a specific type. This is our reference to the import source. If the information was imported through an external system (for example: CRM system, XML, API) we use the name of your system as type.

For example, we import object information from a system called Realworks, the type is “realworks”. If the information was added manually we use the type “helpmee”.

[ID]

The Uuid of the object. Based on the type, we can define which unique id we can use to fetch information. Whenever we import object data, we will save the import id, so that we can always have matching ID’s. This way, you can always user your own system identifier to call our service.

  • Example id: XX123456

If the type is “helpmee”, you can find the id in the agent dashboard: Log in and select a single object to view details. You will find the id in the section “Object information”.

  • Example “helpmee” id: 5bc36089-560b-4890-b47f-0f3a09837f86

[DATESINCE]

This variable is optional. You can use the dateSince to define a date (datetime) to filter the information.

  • Example: 2015-07-01 11:30:00 
  • This will fetch al data, that is added after the 1st of July 2015 (11:30)

Examples

Code

Type HelpMee (manually added into HelpMee)

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

Type Other (imported into HelpMee)

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

PHP CURL

<?php 

$ch = curl_init(); 

curl_setopt($ch, CURLOPT_URL,"https://api.helpmee.nl/public/v1.1/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;

Visual

To get an idea of the content you can expect, or just as inspiration, check out these examples from others:

Iframe example

https://helpmee.nl/iframe/v1/?type=helpmee&id=6103057b-4a8c-4246-8dc3-6d21abbb867c

ERA

Check out the example of a listing page with added soft side from ERA.nl: Example 1 and Example 2.
(If you want to see more examples, search and view object listings on www.era.nl)

Mäklarhuset

Check out the example of a listing page with added soft side from maklarhuset.se: Example 1 and Example 2.
(If you want to see more examples, search and view object listings on www.maklarhuset.se)

For more information about Mäklarhuset Friends: www.maklarhuset.se/salja-bostad/friends

GarantieMakelaars

Check out the example of a listing page with added soft side from garantiemakelaars.nl: Example 1 and Example 2.
(If you want to see more examples, search and view object listings on www.garantiemakelaars.nl)

Step 3: Getting a callback

It is possible to receive a callback from our system, whenever content is added or changed. We can send a JSON POST request to an url of your choice. The information we send:

{
"our-object-id": "<our-object-id>",
"import-object-id": "<import-object-id>",
"import-source": "<import-source-key>",
"type": "<opened/updated/closed>"
}

<our-object-id>
This is our own object identifier, which we can match in our system

<import-object-id>
This will be your own unique object id, to match in your system

<import-source-key>
This is our reference to the import source, usually your company name

<type>
This is the type of call, we currently have 3 types:
• updated: content has been approved/added/changed
• opened: viral has been activated
• closed: viral has been closed down (sold or from the market)

Feedback and support

Do you have any questions, errors or were you just expecting more? :) We are always happy to help! Please share your thoughts and questions: service@kijkmijnhuis.nl

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

Opmerkingen