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.
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>
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>
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.
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);
})
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))
Get a single accommodation by ID.
obManager.getAccommodation(id:String, cb:Function)
We offer a new way to transparently "Get accommodations" with or without availabilities with a generic response format. See getItems() below.
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 executedfinishProvider
a finish callback for every single booking providerfilter
a filter object, see belowtracktag
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 orall
. 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);
Use this call to create a query and get a Query ID back without acutally executing the query.
Get a Query by its hash.
obManager.getQuery(hash:String, cb:Function(err, value))
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 queryaccommodationId
is the accommodationId which you want to get the availabilities forcb
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
}
}
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 |
tags | no | string[] | |
options
can 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 | |
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")
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":{},
...
}, ...]
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
andfree
are integers in the formatyymmdd
- For each date in
arrival
there is a matchingminstay
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");
}
})
Last modified 3yr ago