OpenBooking
Search
⌃K

Reference

For the convenience to our API consumers, we offer a JavaScript SDK, which enables you to set-up your custom UI quickly and connect to our real-time Socket.IO-based Pusher channel to speed up Query runtime.

Overview

1. Integrate the SDK in your website

Production Version:
<script src="<https://api.openbooking.ch/js/ob.min.js>"></script>
Development Version:
<script src="<https://api.openbooking.ch/js/ob.dev.js>"></script>

2. Instantiate an instance of OBManager

OBManager is the main object to communicate with the OpenBooking API client-side.
<script>
var ob = new OBManager("<https://api.openbooking.ch>", "[PUT YOUR TOKEN HERE]");
</script>

Method Reference

Getting accommodation core data

setAcceptLanguage()...

countAccommodations()

Returns the number of available accommodation objects (core data) using the provided filter.
var filter = {
type: "hotel"
}
obManager.countAccommodations(filter: Object, cb: function(err, val))
The filter is an Object containing filter parameters, for example { type: "apartment" } will return just the accommodations that match that criteria.
Filter Parameters: see "parameter" table below.
cb: Will be called with the results.

getAccommodations()

Fetch accommodation core objects based on an optional filter.
ob.getAccommodations(filter:Object, skip:Integer, limit:Integer, cb:Function(err, val))
The filter is an Object containing filter parameters, for example { type: "apartment" } will return just the accommodations that match that criteria.
Filter Parameters: see "parameter" table below.
skip is to skip some items, if empty it will default to 0.
limit is to set the limit of the accommodations retrieved, defaults to 100.
cb will be called everytime we get accommodations, example of a cb function(err, accommodations)
var filter = {visible:true, features:"restaurant", ...};
ob.getAccommodations(filter, 10, 0, function(err, data) {
console.log(err);
console.log(data);
})

getAllAccommodations()

If you need to get all the accommodations, instead of using the 2 above functions you can use this one. Will return you all the accommodations, 100 at the time, means tha cb will be called many times.
obManager.getAllAccommodations(filter:Object, cb:Function(err, val))

getAccommodation()

Get a single accommodation by ID.
obManager.getAccommodation(id:String, cb:Function)

Running availability queries

We offer a new way to transparently "Get accommodations" with or without availabilities with a generic response format. See getItems() below.

makeQuery()

The main feature of Openbooking is making queries. When a query is issued we will contact the Booking Engines and return the data to you.
obManager.makeQuery(query:Object, [options:Object], cb:Function(err, data:Array, requestid:String))
With the options parameter, which is NOT mandatory, you can pass an object with the following fields:
  • finish a callback which is called when the Query is fully executed
  • finishProvider a finish callback for every single booking provider
  • filter a filter object, see below
  • tracktag a short string used to distinguish different queries from another. Max length 30 characters, no whitespace. Tracktags beginning with underscore are reserved for internal use.
When making a query, see example below, you will get, through the cb, the availabilities that you receive and the library stores it in a DataManager which are easily querable for you afterwards. Basicaly when a result comes you can add it to your page via jQuery or you can just load the data again from the DataManager included in the library, so you can filter and sort the data directly.
Example of a query:
{
"checkin": "2015-07-12T00:00:00.000",
"checkout": "2015-07-14T00:00:00.000",
"rooms": [{"adults": "2","children": 0}],
"language": "de",
"currency": "CHF"
}
Filtering:
You can pass a filter parameter with an object with the following fields:
  • type: can be a type or all. Currently the following types are supported: hotel, appartment, offer
  • reference_id: pass an accommodationId here to get results only for a single accommodation
// makeQuery returns a requestid which is also passed to the callbacks
// Example:
var my_app_state = {};
var ob = new OBManager('https://api.openbooking.ch', token);
ob.finishedProviderCB = function(data) {
if(data.requestid == my_app_state.last_requestid) {
...
}
};
ob.finishedCB = function(data) {
if(data.requestid == my_app_state.last_requestid) {
...
}
};
var resultCB = function (err, data, requestid) {
if(requestid == my_app_state.last_requestid) {
...
}
};
var hash_or_query = ...;
var options = {tracktag: "mycustomtracktag"};
my_app_state.last_requestid = ob.makeQuery(hash_or_query, options, resultCB);

createQuery()

Use this call to create a query and get a Query ID back without acutally executing the query.

getQuery()

Get a Query by its hash.
obManager.getQuery(hash:String, cb:Function(err, value))

getResultsByOriginPerAccommodationId()

When we get availabilities and we want to book a room, maybe, if we group our availabilities by accommodation, we want to show the accommodation and all its availabilities to do this you can use this method.
obManager.getResultsByOriginPerAccommodationId(origin:String, accommodationId:String, cb:Function)
origin is the hash of the query
accommodationId is the accommodationId which you want to get the availabilities for
cb is the callback that returns the availabilities. Provide a Function with the following signature:
function (err, data) {
if (err) {
console.log("Something went wrong, most likely the query origin did not exist");
return
}
if (data && data.length > 0) {
data.forEach(
function(aResult){
// do something with the results
}
)}
} else {
// No results found
// Query is either too old or results are expired/not cached
}
}

Doing both: get Accommodations and Availabilities in a single request

getItems( parameters, options ) -> Items

getItems() returns an instance of the Items objects, which allows you to easily paginate and sort.
Example:
var items = ob.getItems({
types: ["apartment"],
checkin: "",
checkout: "",
rooms: [{
adults: 2,
children: 0,
childrens_age: []
}]
}, {
tracktag: "",
pageSize: 15
}).sortBy("price")
parameters can contain the following keys:
Parameter
Required?
Type
Example
types
yes
string[]
["apartment"]
language
yes
string
de
currency
yes
string
CHF
checkin
no
string
2020-10-30
checkout
no
string
2020-10-31
rooms
no
Room[]
TODO
facts_bedrooms
no
int
2
facts_maxadults
no
int
2
facts_type
no
string
visible
no
boolean
true
quality
no
int[]
2,3,4
places
no
string[]
place IDs
st_code
no
string
DEPRECATED
Use tag search in form of "stcode:123456"
classification
no
int[]
Only for apartments with STV classification
DEPRECATED
Use tag search in form of "stv:classification:1"
price_min
no
int
150
price_max
no
int
300
features
no
string[]
["feature1","feature2"]
accommodationid
no
string[]
["57a9e5033d53230c10227f26"]
exclude_accommodationid
no
string[]
["57a9e5033d53230c10227f26"]
provider_name
no
string
reka
position
no
float64[]
47.3825516,8.5280023 (lat/lng)
radius
no
int
in meters, use together with position
bbox
no
float64[]
46.451062,9.766425,46.594009,9.985023 (left upper lat/lng, right lower lat/lng)
fulltext
no
string
i.e. chalet mary
See Fulltext Query Syntax for all possibilities
tags
no
string[]
optionscan contain the follow keys:
Parameter
Type
Default
Description
pageSize
int
100
Max. 100
tracktag
string
resolve_features
boolean
false
resolve_places
boolean
false
lowest_price_only
boolean
false
One return the cheapest offer(result) per accommodation
additional_properties
boolean
false
Fetch additional fields:
'group', 'provider', 'street', 'phone', 'email', 'media', 'onDemand', "terms", "description_rate_code"
trackingurl
boolean
false

Items.sortBy( sortString ) -> Items

sortString can be one of the following values.
Default sort order is ascending. For descending sort order add prefix -
Sort type
Note
name
price
classification
apartments only
quality
facts_bedrooms
apartments only
facts_maxadults
apartments only
random
position
used together with position/radius filter. The order is always "nearest first", descending is not supported
contentscore
sort by content quality
Example:
.sortBy("-price")

Items.page( pageIndex, cb ) -> promise

Items.nextPage( cb ) -> promise

Items.prevPage( cb ) -> promise

Items.reset()

Items.currentPage( cb ) -> promise

Items.pageCount( cb ) -> promise

Items.count( cb ) -> promise

Items Callback

Callback signature:
function(err, page) {}
Page is an array of a "light" accommodation objects:
[{
"id": "",
"name": {},
"name_add": {},
"images": [],
"imagesServices": [],
"ranks": [],
"provider_name": "",
"features": [],
"quality": "",
"superior": true,
"position": {},
"visible":true,
"type":"apartment",
"city":"Nendaz",
"city_normalized":"",
"externals":[],
"hookData":{},
"price":{},
...
}, ...]

Retrieve Availability calendar for a single accommodation

getAvailabilities(accommodationId, cb) -> promise

You can pass a callback cb or leave it undefined to get a promise as return value. Returns a calendar with Arrival days, available days and minimum stays in this format:
[{
accommodation: "57a9d0c58f28830d008c7302",
arrival: [161128,161129,161130,161201,161202,161203,161204,161205,161206,161207,161208,161209,161210,161211,161212,161213,161214,161215,161216,161217,161218,161219,161220,161221,161222,161223,161224,161231,170121,170211,170318,170325,170401,170415,170429],
free: [161128,161129,161130,161201,161202,161203,161204,161205,161206,161207,161208,161209,161210,161211,161212,161213,161214,161215,161216,161217,161218,161219,161220,161221,161222,161223,161224,161225,161226,161227,161228,161229,161230,161231,170101,170102,170103,170104,170105,170106,170121,170122,170123,170124,170125,170126,170127,170211,170212,170213,170214,170215,170216,170217,170318,170319,170320,170321,170322,170323,170324,170325,170326,170327,170328,170329,170330,170331,170401,170402,170403,170404,170405,170406,170407,170415,170416,170417,170418,170419,170420,170421,170429,170430],
minstay: [3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,7,7,7,7,7,7,7,7],
provider: "57a9d0b173de570c00977fee"
}, ...]
  • The dates in arrival and free are integers in the format yymmdd
  • For each date in arrival there is a matching minstay element, denoting the number of minimum stay days for a particular arrival day
  • different providers can report different availability data
Example:
ob.getAvailabilities(id).then(function(availabilities) {
if(availabilities.length > 0) {
...
} else {
console.log("for accommodation '"+id+"' there is currently no availability data");
}
})