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");
}
})