NAV
shell php

Introduction

Welcome to Likibu’s API documentation!

This API gives you acces to (almost) all data available on likibu.com : vacation rentals search, accommodation details, destinations, …

Format

The API speaks JSON. All responses are in JSON format.

Authentication

# Pass the key as a query string parameter
curl "https://api.likibu.com/path/to/endpoint?key=your_likibu_api_key"

<?php

$client = new Likibu\Client("your_likibu_api_key");

Replace your_likibu_api_key with the key that you were assigned.

You need to authenticate with the API with a key in order to use the services. This key must be sent to each request.

This key authenticates your application and must not be exposed to your end users. All abusive use of the API will see it’s key banned.

The key must be sent as a query string parameter.

?key=your_likibu_api_key

Ping

Checks the API is online and operational.

curl "https://api.likibu.com/ping/?key=your_likibu_api_key"

<?php

$response = $client->ping();
die(json_encode($response));

Response : 

"pong"

Request

GET https://api.likibu.com/ping/?key=my_likibu_api_key

Response

Code Description
200 OK – Everything’s fine.
401 Unauthorized – API key missing or invalid.
403 Forbidden – Your API key doesn’t have access to this method. Please contact us if you need more rights.
500 Internal Server Error – Server error. Please contact us if the problem persists.

Real-time search

Likibu searches and agregates accommodations from many partners. The search is done in real time, in order to have the most relevant results and updated prices and availabilities.

You need to create a search session before to get the prices. Once the session is created, the API searches and aggregates the results of all our partners in the background. Please wait at least one second before starting to poll the results.

The searches can last between a few milliseconds and about 15 seconds.

The search process consists in the following steps :

Create search session

curl "https://api.likibu.com/search/?key=your_likibu_api_key" \
    -d "where=Amsterdam&checkin=2016-08-06&checkout=2016-08-13&guests=4&culture=fr&currency=eur"

<?php

$response = $client->initSearch([
    'where' => 'Amsterdam',
    'checkin' => '2016-08-06',
    'checkout' => '2016-08-13',
    'guests' => 4,
    'culture' => 'fr',
    'currency' => 'eur',
]);
die(json_encode($response));

{
    "search_id": "35v4zu17084b74xn1c010",
    "search_status_url": "https:\/\/api.likibu.com\/search\/35v4zu17084b74xn1c010\/status", 
    "search_results_url": "https:\/\/api.likibu.com\/search\/35v4zu17084b74xn1c010"
}

This method creates the search session. A search is defined by 5 parameters :

Request

This is a POST request. The API key must be sent in the query string, but the other data have to be sent as the request body.

POST https://api.likibu.com/search/?key=my_likibu_api_key

Parameters

Parameter Mandatory? Description Format
where Yes * Destination (city, neighbourhood, region…) String
destination_id Yes * Destination’s unique ID String
lng Yes * Longitude -180.0 ≥ x ≤ 180.0
lat Yes * Latitude -90.0 ≥ y ≤ 90.0
culture Yes User’s language Accepted values : fr, en, de, es, it, nl
currency Yes User’s currency ISO 4217 3 letters currency code (EUR, USD, GPB, CAD, …)
checkin Yes Checkin date YYYY-MM-DD. Must be a date in the future.
checkout Yes Checkout date YYYY-MM-DD. Must be greater than the checkin date. Cannot be more than 365 days after checkin date.

Response

Successful request returns 3 elements :

Code Description
201 Created – Search session successfully created.
401 Unauthorized – API key missing or invalid.
403 Forbidden – Your API key doesn’t have access to this method. Please contact us if you need more rights.
500 Internal Server Error – Server error. Please contact us if the problem persists.

Poll search status

curl "https://api.likibu.com/search/{search_id}/status?key=your_likibu_api_key"  

<?php

$response = $client->pollSearch('35v4zu17084b74xn1c010');
die(json_encode($response));

{
    "search_id": "35v4zu17084b74xn1c010",
    "bbox": [[5.07326326407,52.485816485905],[4.7061137195726,52.262237923337]],
    "where": "Amsterdam",
    "checkin": "2016-08-06",
    "checkout": "2016-08-13",
    "country_code":"NL",
    "status":{
        "is_complete":true,
        "partners": { ... }
    }
}

This methods checks the status of the search. Searches on small destinations with only a few accommodations can only take a few milliseconds. Searching on big cities or entire regions can take 15 seconds.

You need to periodically call this method until the search is complete. Every 200ms for example.

Request

GET https://api.likibu.com/search/{search_id}?key=my_likibu_api_key

Parameters

Parameter Mandatory? Description Format
search_id Yes Search session ID String

Response

Code Description
200 OK
401 Unauthorized – API key missing or invalid.
403 Forbidden – Your API key doesn’t have access to this method. Please contact us if you need more rights.
500 Internal Server Error – Server error. Please contact us if the problem persists.

Data

Parameter Description Format
search_id Search session ID String
bbox Bounding box Array [GeoJSON point (NW), GeoJson point (SE)]
where Destination name String
checkin Checkin date YYYY-MM-DD
checkout Checkout date YYYY-MM-DD
country_code Country code 2 letters ISO 3166
status.is_complete Is the search complete? Bool
status.partners Search status details, partner by partner Object

Fetch search results

curl "https://api.likibu.com/search/{search_id}?key=your_likibu_api_key"  

<?php

$response = $client->getSearch('35v4zu17084b74xn1c010', [
    'type' => ['villa', 'house'],
    'privacy_type' => ['entire_home'],
    'amenities' => ['pool', 'bbq'],
]);
die(json_encode($response));

{
    "search_id": ...,
    "status": ...,
    "bbox": ...,
    "where": ...,
    "checkin": ...,
    "checkout": ...,
    "country_code": ...,
    "total_results": ...,
    "total_pages": ...,
    "min_price": ...,
    "max_price": ...,
    "offers": [
        { ... Offer ... },
        { ... Offer ... },
        { ... Offer ... }
    ],
    "facets": {
        "partner_id": { ... Facet ... },
        "privacy_type": { ... Facet ... },
        "type": { ... Facet ... },
        "amenities": { ... Facet ... },
        "is_instant_booking_available": { ... Facet ... }
    }

Use this method to fetch the results, filter and sort them. Please make sure the status is “complete” before using filters.

Request

GET https://api.likibu.com/search/{search_id}?key=my_likibu_api_key

Parameters

Parameter Mandatory? Description Format
search_id Yes Search session ID String
per_page No Number of results, per page Integer, default = 24
page No Page number Integer, default = 1
sort No Sort type Possible values : reco (default), price_asc, price_desc, price_discount
privacy_type ** No Privacy type filter See appendix
type ** No Accommodation type filter See appendix
amenities ** No Amenities filter See appendix
partner_id * No Partner ID filter Integer
price_min No Min price, nightly Integer, in the currency used at session creation
price_max No Max price, nightly Integer, in the currency used at session creation

Response

Code Description
200 OK
401 Unauthorized – API key missing or invalid.
403 Forbidden – Your API key doesn’t have access to this method. Please contact us if you need more rights.
500 Internal Server Error – Server error. Please contact us if the problem persists.

Data

search_id, status, bbox, where, checkin, checkout, country_code : .

Paramètre Description Format
search_id see previous chapter
status see previous chapter
bbox see previous chapter
where see previous chapter
checkin see previous chapter
checkout see previous chapter
checkout see previous chapter
country_code see previous chapter
total_results Total results Integer
total_pages Total number of pages Integer
min_price Minimum price Integer
max_price Maximum price Integer
offers Offers details Offer, see next chapter
facets Facets details Facet, see next chapter

Offer

Offer details

Parameter Description Format
id Offer unique ID String
title Title String
description Description String
url Redirection URL String
thumbnails Thumbnails Array
photos Photos Array
price_sojourn Total price Integer
price Nightly price Integer
currency Currency String, ISO 4217
source.id Offer’s provider ID Integer
source.slug Offer’s provider slug String
source.name Offer’s provider name String
lat Latitude Float
lng Longitude Float
rating Average user’s rating (/5) Float
rating_count Number of user’s ratings Integer
max_guests Maximum number of guests Integer
is_instant_booking_available Is instant booking available? Boolean
bedrooms Number of bedrooms Integer
bathrooms Number of bathrooms Integer
surface Surface, in sqare meters Integer
amenities Amenities list Array. See appendix
privacy_type Privacy type String. See appendix
type Accommodation type String. See appendix

Facet

Number of results per search filter:

Parameter Description Format
privacy_type Privacy type Array. Possibles keys: Voir annexe
amenities Amenities list Array. Possibles keys: Voir annexe
is_instant_booking_available Bookable immediately Array. Possibles keys: “T” (true) & “0” (false)
partners Partners Array
is_p2p Particular to particular Array. Possibles keys: “T” (true) & “0” (false)
type Accommodation type Array. Possibles keys: Voir annexe
master_type Global type Array

Destinations

Access Likibu’s destinations tree and search for destinations.

Fulltext destinations search. Can be used for autocompletion widgets, to suggest destinations to your users.

curl "https://api.likibu.com/destinations/search?key=your_likibu_api_key&q=Barcel&culture=fr&size=5"

<?php

$response = $client->getDestinationsPredictions('barcel', 'fr', 5);
die(json_encode($response));

{
    "results": [
        {
            "id": 2641,
            "name": "Barcelone",
            "parent_name": "Catalogne",
            "results": 16996,
            "country_code": "ES"
        }, {
            "id": 4157,
            "name": "Barcelonnette",
            "parent_name": "Alpes-de-Haute-Provence",
            "results": 27,
            "country_code": "FR"
        }, {
            "id": 5136,
            "name": "Barcellona Pozzo di Gotto",
            "parent_name": "Sicile",
            "results": 22,
            "country_code": "IT"
        }, {
            "id": 12766,
            "name": "Faucon-De-Barcelonnette",
            "parent_name": "Alpes-de-Haute-Provence",
            "results": 10,
            "country_code": "FR"
        }, {
            "id": 13307,
            "name": "Barcelona",
            "parent_name": "Venezuela",
            "results": 0,
            "country_code": "VE"
        }
    ],
    "took": 4
}

Request

GET "https://api.likibu.com/destinations/search?key=your_likibu_api_key&q=Barcel&culture=fr&size=5"

Parameters

Parameter Mandatory? Description Format
q Yes Searched destination String
culture Yes User’s language String. Accepted values : fr, en, de, it, es, nl
size No Number of results to fetch Integer. Default = 10

Response

Code Description
200 OK
401 Unauthorized – API key missing or invalid.
403 Forbidden – Your API key doesn’t have access to this method. Please contact us if you need more rights.
500 Internal Server Error – Server error. Please contact us if the problem persists.

Data

Parameter Description Format
results[].id Destination’s unique ID Integer
results[].name Destination name String
results[].parent_name Destination’s parent name String
results[].results Estimated number of accommodations Integer
results[].country_code Country code 2 letters ISO 3166
took Execution time, in milliseconds Integer

Details

Fetch destination’s details. Allows you to browse the destination tree and see the nearest destinations.

curl "https://api.likibu.com/destinations/5370?key=your_likibu_api_key&culture=fr"

<?php

$response = $client->getDestination(5370, [
    'culture' => 'fr',
]);
die(json_encode($response));

{
    "id": 5370,
    "results": 4350,
    "name": "Amsterdam",
    "location": [
        52.370734222619,
        4.9076865975088
    ],
    "Ancestors": [
        {
            "id": 1,
            "name": "Monde"
        }, {
            "id": 2365,
            "name": "Europe de l'ouest"
        }, {
            "id": 5368,
            "name": "Pays-Bas"
        }, {
            "id": 14141,
            "name": "Hollande-Septentrionale"
        }
    ],
    "Children": [
        {
            "id": 16066,
            "name": "Jordaan",
            "results": 530,
            "Children": []
        }, {
            "id": 16067,
            "name": "Centre Historique d'Amsterdam",
            "results": 1271,
            "Children": []
        }, ...
    ],
    "Siblings": [
        {
            "id": 8668,
            "name": "Bloemendaal",
            "results": 8
        }, {
        "id": 8713,
        "name": "Hollands Kroon",
        "results": 145
        }, ...
    ],
    "Nearest": [
        {
            "id": 8658,
            "name": "Amstelveen",
            "distance": 11.2,
            "results": 20
        },
        {
            "id": 8794,
            "name": "Zaandam",
            "distance": 12.6,
            "results": 33
        }, ...
    ]
}

Request

GET "https://api.likibu.com/destinations/{destination_id}?key=your_likibu_api_key&culture=fr"

Parameters

Parameter Mandatory? Description Format
destination_id Yes Integer
culture Yes User’s language String. Possible values : fr, en, de, it, es, nl

Response

Code Description
200 OK
401 Unauthorized – API key missing or invalid.
403 Forbidden – Your API key doesn’t have access to this method. Please contact us if you need more rights.
500 Internal Server Error – Server error. Please contact us if the problem persists.

Data

Parameter Description Format
id Destination’s unique ID Integer
name Translated destination name String
parent_name Translated destinatino’s parent name. String
results Estimated number of accommodations Integer
location Geolocation GeoJSON point
Ancestors[] Parent destinations { id: Integer, name: String }
Children[] Children destinations { id: Integer, name: String, results: Integer, Children: [{}] }
Siblings Sibling destinations { id: Integer, name: String, results: Integer }
Nearest Nearest destinations { id: Integer, name: String, results: Integer, distance: Integer }

Accommodations

Accommodations search, listing, details

Accommodations list

Search and list accommodations.

curl "https://api.likibu.com/rooms/?key=your_likibu_api_key&destination_id=5370&culture=fr&currency=eur"

<?php

$response = $client->search([
    'destination_id' => 5370,
    'culture' => 'fr',
    'currency' => 'eur',
]);
die(json_encode($response));

{
    "totalResults": 4510,
    "page": 1,
    "totalPages": 188,
    "priceMin": 8,
    "priceMax": 9000,
    "results": [
        { ... Offer ... },
        { ... Offer ... },
    ],
    "facets": {
        "partner_id": { ... Facet ... },
        "privacy_type": { ... Facet ... },
        "type": { ... Facet ... },
        "amenities": { ... Facet ... },
        "is_instant_booking_available": { ... Facet ... }
    }
}

Request

GET "https://api.likibu.com/rooms/?key=your_likibu_api_key&..."

Parameters

Parameter Mandatory? Description Format
where Yes * Destination on where to search String
destination_id Yes * Destination’s unique ID String
lng Yes * Longitude -180.0 ≥ x ≤ 180.0
lat Yes * Latitude -90.0 ≥ y ≤ 90.0
culture Yes User’s language Accepted values : fr, en, de, es, it, nl
currency Yes User’s currency ISO 4217 3 letters currency code (EUR, USD, GPB, CAD, …)
checkin Yes Checkin date YYYY-MM-DD. Must be a date in the future.
checkout Yes Checkout date YYYY-MM-DD. Must be greater than the checkin date. Cannot be more than 365 days after checkin date.
per_page No Number of results, per page Integer, default = 24
page No Page number Integer, default = 1
sort No Sort type Possible values : reco (default), price_asc, price_desc
privacy_type ** No Privacy type filter See appendix
type ** No Filtre / type de logement See appendix
amenities ** No Amenities filter See appendix
partner_id * No Partner ID filter Integer
guests No Number of guests Integer
price_min No Min price, nightly Integer, in the currency used at session creation
price_max No Max price, nightly Integer, in the currency used at session creation

Response

Code Description
200 OK
401 Unauthorized – API key missing or invalid.
403 Forbidden – Your API key doesn’t have access to this method. Please contact us if you need more rights.
500 Internal Server Error – Server error. Please contact us if the problem persists.

Data

Parameter Description Format
results[].id Identifiant unique de la destination Integer
results[].name Nom de la destination, dans la langue choisie String
results[].parent_name Nom de la destination parente du résultat. String
results[].results Estimation du nombre de logements de cette destination Integer
results[].country_code Code pays de la destination ISO 3166, 2 lettres
took Temps d'éxécution de la recherche en millisecondes Integer

Accommodation details

Returns accommodation’s details.

curl "https://api.likibu.com/rooms/8742e5ee7b5d5c367ecf54da4266ce7451e14943?key=your_likibu_api_key&culture=fr&currency=eur"

<?php

$response = $client->getOffer('8742e5ee7b5d5c367ecf54da4266ce7451e14943', [
    'culture' => 'fr',
    'currency' => 'eur',
]);
die(json_encode($response));

{
    "id": "8742e5ee7b5d5c367ecf54da4266ce7451e14943",
    "source": { ... Source ... },
    "title": "Appartement avec petit-déjeuner et vélos",
    "description": "",
    "type": "apartment",
    "privacy_type": "entire_apartment",
    "photos": [
        "https://likibu-images.s3.eu-central-1.amazonaws.com/wimdu/874/8742e5ee7b5d5c367ecf54da4266ce7451e14943/0/medium.jpg",
        ...
    ],
    "rating": 4.7,
    "rating_count": 152,
    "url": "http://www.likibu.com/fr/r/8742e5ee7b5d5c367ecf54da4266ce7451e14943?",
    "partner_url": "http://www.likibu.com/t/8742e5ee7b5d5c367ecf54da4266ce7451e14943/fr?",
    "price_nightly": 95,
    "price_eur": 95,
    "price_sojourn": 95,
    "price_weekly": 665,
    "price_monthly": 2850,
    "currency": "eur",
    "location": {
        "location": [
            4.89514,
            52.3428
        ],
        "city": "Amsterdam",
        "country": "NL",
        "destination_id": [
            5370,
            14141,
            5368,
            2365
        ]
    },
    "place": {
        "rooms": 2,
        "bedrooms": 1,
        "bathrooms": 1,
        "surface": 25,
        "amenities": ["family", "kitchen", "tv", "breakfast", "net"]
    },
    "booking": {
        "is_instant_booking_available": true,
        "min_nights": 2,
        "max_nights": 2,
        "checkin_at": "",
        "checkout_at": "",
        "max_guests": 2,
        "booked_at": []
    },
    "availability": {
        "availability": "",
        "total_price": 95
    }
}

Request

GET "https://api.likibu.com/rooms/{room_id}?key=your_likibu_api_key&..."

Parameters

Parameter Mandatory? Description Format
culture Yes User’s language Accepted values : fr, en, de, es, it, nl
currency Yes User’s currency ISO 4217 3 letters currency code (EUR, USD, GPB, CAD, …)
checkin Yes Checkin date YYYY-MM-DD. Must be a date in the future.
checkout Yes Checkout date YYYY-MM-DD. Must be greater than the checkin date. Cannot be more than 365 days after checkin date.

Response

Code Description
200 OK
401 Unauthorized – API key missing or invalid.
403 Forbidden – Your API key doesn’t have access to this method. Please contact us if you need more rights.
500 Internal Server Error – Server error. Please contact us if the problem persists.

Data

Offer object, with the following additionnal parameters :

Paramètre Description Format
availability.availability Availability “available”, “unavailable”, “”
availability.total_price Total sojourn price Integer

Appendix

“type” List

Code Description
apartment Apartment
house House
villa Villa
chalet Lodge, cabin, …
boat Boat, house boat, …
castle Castle
bnb Bed & breakfast
camping Camping, mobil-homes, …
hotel Appart-hotel
room Room
resort Vacation residence, club, …
unusual Treehouse, yurt, …
bungalow Bungalow
hostel Hostel
riad Riad
any Unknown

“privacy_type” List

Code Description
entire_apartment Entire home
private_room Private room
shared_room Shared room
any Unknown

“amenities” List

Code Description
ac Air Conditioning
accessible Wheelchair accessible
babycot Babycot
balcony Balcony
bbq Barbecue
breakfast Breakfast
dishwasher Dishwasher
elevator Elevator
events Suited for events
family Suited for families
fireplace Fireplace
garden Garden
golf Golf
gym Gym
jacuzzi Jacuzzi
kitchen Kitchen
linen Linen included
net Internet, wi-fi, …
parking Parking
pets Pets allowed
pool Pool
sauna Sauna
seaview Seaview
smoke Smokers allowed
tv TV
washer_dryer Washer/Dryer
shell php