Introduction
On our platform, 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 content exactly like you want it to.
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/developers (apikey-partner).
Do you have an login?
If you have a login for our platform, you can get your API key by logging in and clicking on the settings icon and choosing “couplings”. Look for “Website” and click “Edit”. Select the option “Yes, give me an API key” and save it. 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
Getting an API key without login
If you don’t have a login (yet), but you want to call our API, please contact service@moving.digital.
Calling the API
Introduction
Technical documentation of the API calls can be found here:
https://app.diorama.nl/api/public/doc/viral
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”.
URL
The API can be called using GET on the following link:
https://app.diorama.nl/api/public/v1.4/[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 Placert
- 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 Placert id and optional import id)
- It contains dates (date of creation, date of update)
- For more information, check out: https://app.diorama.nl/api/public/doc/viral#get–api-public-{version}-viral-
viral-detail
- This is the same call as viral, but for a single object
- In this variant you will need to supply a [TYPE] and an [ID]
- For more information, check out: https://app.diorama.nl/api/public/doc/viral#get–api-public-{version}-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://app.diorama.nl/api/public/doc/viral#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://app.diorama.nl/api/public/doc/viral#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://app.diorama.nl/api/public/doc/viral#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://app.diorama.nl/api/public/doc/viral#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 Placert, 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.
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, no import)
https://app.diorama.nl/api/public/v1.4/facility/?type=helpmee&id=5bc36089-560b-4890-b47f-0f3a09837f86&dateSince=2015-03-01 11:30:00
Type Other (imported into Placert)
https://app.diorama.nl/api/public/v1.4/facility/?type=realworks&id=123456&dateSince=2015-03-01 11:30:00
PHP CURL
<!--?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,”https://app.diorama.nl/api/public/v1.4/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;
-->
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": "",
"import-object-id": "",
"import-source": "",
"type": ""
}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 – 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@moving.digital
We are always happy to help! Please share your thoughts and questions: service@moving.digital