OpenBooking REST API
Table of Contents
1. Introduction
1.1. Overview
This documentation describes the following OpenBooking components which can be used by our subscribers
Turn-key solutions for easy integration
- White Label - Integrate OpenBooking into your website with a single line of code
REST-based APIs for deep integration in your web projects or server side applications
- Accommodations - Accommodation core data and availability queries
- Offers - Tourist experiences and offers from many different sources
Get support
- Login to the Admin App and click on the Chat icon on the bottom left
- Send an email to support@openbooking.ch
- Give us a call: +41 32 511 1919
2. Accommodations
2.1. White Label
Integrate OpenBooking into your website with a single line of code.
Figure 1: White Label "Graubünden Ferien"
2.2. Pros and Cons
Advantages of using our White Label
- Zero additional expenses with new offer types or booking provider
- Zero additional expenses with new regions
- Zero expenses for continuous development
- Ready for use within a few hours
- Latest features are added to the OpenBooking whitelabel first
- Occupancy calendar included by default
- Export stock data to your CRM for free
- Implementation in minutes and at no costs
- Real-Time search and autosuggest included
- Customize the whitelabel to your visual needs or CI
- Image processing service included
Code example
<div data-whitelabel data-lang = "fr" data-group="{YOUR-API-KEY}" data-currency = "CHF" /> <script src="https://ui.openbooking.ch/ui/v1/server/ob-whitelabel.js"></script>
Advantages of building your own UI
- Build your own offer search on top of OpenBooking
- Zero costs for booking provider connection maintenance
- Access every data set in OpenBooking
- Fully documented interface reference
- Build websites and apps
- Get the latest features via API first
- Image processing service license for your custom integration
- Export stock data, regions and availabilities directly into your Website/CMS
Drawbacks
- Building your own interface often leads to additional expenses
- Interface sometimes needs to be adopted to the new features or settings
- New whitelabel features need to be added by your agency
- Usually ready for use after long-term development
2.3. Open Data Interface (ODI)
Become a data supplier
Are you an OTA, DMS or Booking provider with your own or contracted accommodations? Read on to learn how to connect to OpenBooking and increase your distribution channels.
- What you will need
OpenBooking uses open and easy standards to provide interfaces to connect your data to our API. To become a data supplier, you must meet the following requirements:
- Send accommodation core data whenever it gets updated or once a day. Currently, we support three types of accommodations: Hotels, Apartments, Packages/Offers
- Have a webservice running that can respond to real-time availability queries within a reasonable amount of time (<= 3 secs)
- Have a landing page where we can pass the user after they have decided which object they want to book, including query data (checkin, checkout, persons, object id etc.)
- Send the booking data back to OpenBooking if and after a booking took place
Interfaces are based on HTTP/JSON requests. We provide extensive code examples in our Developer Portal, so it'll be easy for you to get started.
- Workflow
- Sign our technical agreement
- Obtain an access token
- Host your accommodation inventory JSON on a public server
- Provide Endpoint for availability queries
- Send actual bookings
- Sign up now!
It's totally easy and completely free for you to become an OpenBooking data supplier. Be part of the community.
Accommodation Interface Specification
As a provider of accommodations services you can connect your system to OpenBooking via the OpenBooking Data Interface ODI. Based on open standards (JSON/REST) you provide your core and booking data to OpenBooking directly from your system.
There are 3 different parts of ODI you have to implement:
- Core data of accommodations and offers including general availability information for apartments
- Real-time webservice for availability-search and price calculation
- Data of bookings that took place via OpenBooking leads
All data is exchanged in JSON format. We provide the appropriate JSON schema files which you can use to validate your JSON files against.
Before you can start integrating into OpenBooking, you must request an Import-Key. The Import-Key is a string token which indicates for which OpenBooking client you provide the data. You need one Import-Key per client you provide data for through OpenBooking.
Figure 2: Conceptual overview
- Step 1: Providing core data
OpenBooking imports core data for accommodations and offers via JSON/HTTP on a daily basis. You provide the data in the following way:
- Creating an Index JSON file per OpenBooking client/Import key. The Index JSON includes URL-based references to all the accommodation files for this client.
- Create one JSON file per accommodation/offer.
- Place the files on an HTTP/HTTPS accessible server where OpenBooking has access to.
- Register the Index JSON for every client with OpenBooking incl. an escalation email address where our index process can send error reports to (currently you have to send us an email with the details. We’re working on a self-service dashboard solution).
- Create the Index JSON
The Index JSON is like a sitemap.xml, but in JSON format. It contains an array with URLs to all the accommodation JSON files that OpenBooking should index/crawl for a specific client daily. It looks like this:
{ "_v": 1, "importkey": "882a4ee419", "comment": "This is for Wallis Valais Promotion", "accommodations": [ { "url": "https://www.mybookingsystem.ch/acco1.json", "ts": 232321323 }, { "url": "https://www.mybookingsystem.ch/acco2.json", "ts": 242424242 } ] }
The Index JSON can have any name, it doesn’t have to be “index.json”.
Key Data Type Usage _v
string ODI format version specifier. Must be 1 importkey
string Identifies the relation between the data provider (you) and the OpenBooking client. The import key is provided to you by OpenBooking. comment
string Free text, not used by OpenBooking accommodations
array .url
string URL of the JSON for a single accommodation .ts
integer Unix Timestamp when this file was last updated. OpenBooking will only import/process files which where the timestamp changed since the last import - Create the accommodation JSON files
You have to create one JSON file per accommodation/offer you want to ingest into OpenBooking. Accommodation JSON files can be reused for different clients/import keys, if they do not contain any client specific data. Otherwise you must create different JSON files for every client. An accommodation JSON file looks like this:
[Accommodation Schema](https://jsonschema.openbooking.ch/accommodation.json)
Make sure your JSON validates against this JSON schema. The fields are documented in the JSON schema.
- Step 2: Real-time webservice for availability-search with price calculation
Whenever a user is searching for vacancies on one of the OpenBooking implementations, our backend system retrieves availabilities and prices from a number of different data sources in real-time. To connect to OpenBooking, you must provide a live web service.
The webservice gets search parameters like checkin, checkout date, number of persons, etc. and must respond with free vacancies and the prices matching exactly the given search parameters.
This is how your API must look like: [Webservice Schema]
3. Offers
In contrast to accommodations, the Offers API offers a meta-search for tourist services, which may or may not include accommodation services. Such offers are e.g. city tours, tastings, guided tours etc.
Here, too, OpenBooking offers a large number of integrations to retrieve offers from different providers and platforms in a unified API.
3.1. Concepts
Offers are globally imported by OpenBooking and shared among all clients ("groups"). Some data fields can be modified (i.e. "overrides"). These modifications apply either to the group or globally.
- Tags are group-specific
- Labels are global
- Overrides are global (at the moment)
Labels
Labels are provided by Approved Labeling Partners (ALP). ALPs are authorized to add certain labels to offers which can then be used to filter and display these labels.
Overrides
Some fields can be overridden if the source data is missing or must be corrected.
Currently, the following data fields support overrides:
- Max. Capacity (Persons)
- Title
3.2. REST API
This document describes our REST-based API for retrieving and integrating offers into content management systems or websites.
Basics
The Offers API uses JSON as its data exchange format and is generally modeled on our Accommodations API. Queries must be authenticated with API keys. These are provided by OpenBooking to customers. If you are interested in using this API, please drop an email to info@openbooking.ch.
Parameters are attached as query parameters in the URL.
Base URL
The Offers API is available through our general host using the following schema:
https://api.openbooking.ch/{version}/{resource}
Authentication
Unless otherwise noted, all requests must be authenticated using an API key. This key is included in the HTTP request as a header:
GET https://api.openbooking.ch/v1/offers api-key: [insert-api-key-here]
Endpoints
- General information
- Endpoints return only offers that are assigned to the account
- Offers can be assigned in our Admin App
- Offers contain either a link to an external booking page, or an embeddable JavaScript Widget
- List Offers
GET https://api.openbooking.ch/v1/offers/list
This endpoint is designed to be used by Browser clients. Offers will only be delivered in one language with one currency. Language and currency can be requested explicitly or detected via the user's browser. It is optimized to contain only content relevant for list display.
- Parameters
Key Required? Type Remark limit
no (default: 100) int Limit the number of returned rows, max: 100 skip
no (default: 0) int Skip the number of rows. Works only in conjuction with sort
format
no (default: 1
)int One of: 1
,2
,3
. See Formatssort
only if skip
is usedstring One of: id
lang
no string One of the supported [Content Languages](#content-languages) engines
no []string a CSV-list of one or more [Engines](#engines) , get only offers from these engines
- Parameters
- Get single offer
GET https://api.openbooking.ch/v1/offers/detail/:id
This endpoint is designed to retrieve a single offer,
In contrast, the
List Offers
endpoint is designed for client-side use (see below).- Parameters
Key Required? Type Remark limit
no (default: 100) int Limit the number of returned rows, max: 100 skip
no (default: 0) int Skip the number of rows. Works only in conjunction with sort
sort
only if skip
is usedstring One of: id
- Response
Key Type Remark total
int Total number of found rows limit
int Number of returned rows skip
int Skipped rows error
string If an error occurred, this field is an error description data
[]Offer
- Parameters
- Booking Widget
GET https://api.openbooking.ch/v1/offers/widget/:lang/:id
Returns an HTML fragment that can be directly embedded into an HTML page and displays an interactive booking widget. Support for widgets depends on the [Engine](#engines).
The widget code is dynamically generated should not be imported or cached by server-side import processes. This feature is intended for browser-side implementations only.
Formats
The format of the offers in regard to the language-specific fields can be changed to fit specific requirements. The following formats are currently supported:
- Format 1
All language texts are returned within each field:
{ "title": { "de": "Stadtführung durch Basel", "en": "City tour of Basel", "fr": "Visite guidée de la ville de Bâle", "it": "Visita della città di Basilea" } }
- Format 2
Offer object contains a key for each language containing the full object in that language.
{ "de": {"title" : "Stadtführung durch Basel" }, "en": {"title" : "City tour of Basel" }, "fr": {"title" : "Visite guidée de la ville de Bâle" }, "it": {"title" : "Visita della città di Basilea" } }
- Format 3
Offer is only returned in a single language, useful for browser-side implementations. The language is selected either by using the
lang
query parameter or based on the users browser language (based onAccept-Language
header):{ "title" : "Stadtführung durch Basel" }
Enums
- Engines
Every offer is provided by an engine, which is the source of the offer data. The following engines are currently supported:
ID Engine Widget available stnethot STnet Hotels No stnetadv STnet Adventures No alturos Alturos Planned smeetz Smeetz No tomas TOMAS Yes - Languages
There are two different kinds of languages: Content Language and Spoken Language.
The difference is:
- Content Languages are what the API supports for translations of texts
- Spoken Languages are what a provider might offer as a spoken language for an offer, meaning, which languages are offered during the experience
- Spoken Languages
Designators are encoded in three-letter ISO 639-2/B format.
Language 3-letter code German deu Swiss German gsw English eng French fra Italian ita Spanish spa Nederlands nld Romansh roh Portuguese por Chinese zho Russian rus Japanese jpn Turkish tur - Content Languages
Designators are encoded in two-letter ISO 639-1 format.
The following languages are supported:
Language 2-letter code German de English en French fr Italian it Spanish es Nederlands nl Chinese zh
- Currencies
Currency designators are encoded in three-letter ISO 4217 format.
The following currencies are supported:
Currency Code CAD Canadian Dollar CHF Swiss Francs CNY Chinese Yuan (Renminbi) EUR Euro USD US Dollar - Labels
ALP Label Swiss Wine Tour swt - Activities
Activity ID Tasting tasting Tour tour Gastronomy gastronomy Family family Transport transport Package package Art art - Settings
Setting ID Indoor indoor Outdoor outdoor Indoor and Outdoor inoutdoor - Transports
Transport ID Car car Bus bus Train train Boat boat Tram tram Cable car cablecar Funicular funicular - Weekdays
The available weekdays are
mo
,tu
,we
,th
,fr
,sa
,su
.
Objects
- Translation
A translation is an object that returns strings in multiple languages. The format depends in the selected
format
parameter.Example (Format 1):
{ "de": "Stadtführung durch Basel", "en": "City tour of Basel", "fr": "Visite guidée de la ville de Bâle", "it": "Visita della città di Basilea" }
The languages available in the object depend on the configuration of your account. If you need more languages, please contact our support.
- Coded Translation
Similar to translation but contains an additional code field which can be used to filter objects.
Example:
{ "code": "city", "name": { "de": "Stadtführung durch Basel", "en": "City tour of Basel", "fr": "Visite guidée de la ville de Bâle", "it": "Visita della città di Basilea" } }
The languages available in the object depend on the configuration of your account. If you need more languages, please contact our support.
- Price
Describes a price incl. currency and a conversion indicator.
Field Type Remark currency
string Probably "CHF" value
string Amount, returned as a formatted string converted
bool Whether the amount was automatically converted description
[Translation](#translation-object) - Image
Describes an Image.
Field Type Remark url
string title
[Translation](#translation-object) copyright
string - Geo Coordinates
Field Type Remark lat
float lng
float - Address
Field Type Remark id
string name
string street
string city
string zip
string country
string - Date Range
Field Type Remark from_date
string YYYY-MM-DD to_date
string YYYY-MM-DD - Offer
Field Type Remark id
string created_at
timestamp updated_at
timestamp engine
string The source engine of this offer (see [Engines](#engines)) activities
Array of string See [Activities](#activities) title
[Translation](#translation-object) teaser
[Translation](#translation-object) description
[Translation](#translation-object) info_url
[Translation](#translation-object) Target link to the Offer's website prices_from
[][Price](#price-object) The minimum (from) price in the requested currency spoken_languages
[]string see [Spoken Languages](#spoken-languages) images
Array of [Image](#image-object) The first element is the thumbnail image. setting
[Coded Translation](#codedtr-object) Environment in which an event takes place (indoor, outdoor etc.) max_capacity
number Max. number of occupants per visit duration
[Translation](#translation-object) event_location
[GeoCoordinates](#geo) event_address
[Address](#address) event_dates
Array of [DateRange](#date-range) weekdays
Array of [Weekday](#weekdays) transports
Array of [Transports](#transports) segments
Array of [Coded Translation](#codedtr-object) Target customer group (families, "nature lovers" etc…) labels
Array of string tags
Array of string widget_available
bool If this offer can be booked directly via a JavaScript widget (see [Booking Widget](#booking-widget)) ticket_info
[Translation](#translation-object) Where tickets can be purchased
Changelog
2023-11-13
All fields are now contained within a single offer.
- Smeetz: using the correct data type (products, not groups)
- TOMAS: switched to XML data source
- API:
ticket_info
field added
2024-01-11
Support for various data Formats
2024-01-20
Added description
field to Price object
3.3. Interfaces
OpenBooking imports Offers from various external interfaces. In this section, we describe various different aspects of each interface.
Alturos
Languages: de, fr, it en
Supported fields:
- Title
- Teaser
- Info URL
- Prices From (single price, CHF)
- Max. Capacity
- Activities
- Images (with Title)
- Event Location (Lng, Lat)
Unsupported fields:
- Description
- Spoken Languages
- Setting
- Duration
- Place
- Segments
- Tags
- Ticket Info
- Event Address
- Event Dates
- Widget
Smeetz
Languages: en
Supported fields:
- Title
- Teaser
- Description
- Info URL
- Prices From (single price)
- Images (no title)
- Spoken Languages
- Setting
- Max. Capacity
- Segments
- Tags
- Event Address
- Event Location
- Event Dates
- Activities
- Ticket Info
Unsupported fields:
- Duration
- Place
- Widget
STnet Adventures
Supported fields:
- Title
- Teaser
- Description
- Info URL
- Max. Capacity
- Prices From
- Image (no title, no copyright)
- Spoken Languages
- Setting
- Duration
- Place
- Segments
- Event Address
STnet Hotels
Supported fields:
- Title
- Description
- Info URL
- Prices From
- Images (no title, no copyright)
- Place
- Event Address
Unsupported fields:
- Teaser
- Spoken Languages
- Setting
- Duration
- Max. Capacity
- Segments
- Tags
- Ticket Info
- Widget
TOMAS
Languages: depends on Destination
Supported fields:
- Title
- Teaser
- Description
- Max. Capacity
- Images (Title, Copyright)
- Activities
- Widget
- Event Address
- Event Location (Lng, Lat)
- Prices From
Unsupported fields:
- Info URL
- Spoken Languages
- Setting
- Duration
- Place
- Segments