OfferHub 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

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 `generic`

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 `swt`

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

Available Data Fields

This is an overview of all available data fields.

ALL = All interfaces AT = Alturos SM = Smeetz TO = TOMAS SH = STnet Hoteloffers SA = STnet Adventure Offers

Top-level fields:

Name	Format		Support
_meta	object	Interface specific meta data, see Interfaces	ALL
title	text	Offer title	ALL
teaser	text	Offer teaser	AT
description	text	Offer description	AT
`description_html`	html-text	Offer description as HTML	AT
`info_url`	url	Link to offer booking or info page	AT
`prices_from`	[]Price	Prices for offer and various services	AT
`max_capacity`	int	Max. number of persons this offer

Price:

Name	Format		Support
currency	text	ISO Code for Price currency.	AT
value	text	Price value	AT
converted	bool	True when this currency was converted	AT

List Offers

This endpoint provides output in several different formats.

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 3.2.5
`sort`	only if `skip` is used	string	One of: `id`
`lang`	no	string	One of the supported Content Languages
`engines`	no	[]string	a CSV-list of one or more Engines , get only offers from these engines

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 used	string	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

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.

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****.

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	Yes
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

Offers are mapped to zero or more activities, which could be interpreted as a general type of the offer.

GET https://api.openbooking.ch/v1/offers/activities
api-key: ${key}

[
  {
    "code": "tasting",
    "name": {
      "de": "Verkostung",
      "en": "Tasting",
      "fr": "Dégustation",
      "it": "Degustazione"
    }
  },
  {
    "code": "tour",
    "name": {
      "de": "Spaziergang",
      "en": "Tour",
      "fr": "Balade",
      "it": "Passeggiata"
    }
  },
  {
    "code": "gastronomy",
    "name": {
      "de": "Gastronomie",
      "en": "Gastronomy",
      "fr": "Gastronomie",
      "it": "Gastronomia"
    }
  },
  {
    "code": "family",
    "name": {
      "de": "Familie",
      "en": "Family",
      "fr": "Famille",
      "it": "Famiglia"
    }
  },
  {
    "code": "transport",
    "name": {
      "de": "Transport",
      "en": "Transport",
      "fr": "Transport",
      "it": "Trasporti"
    }
  },
  {
    "code": "package",
    "name": {
      "de": "Paket",
      "en": "Package",
      "fr": "Package",
      "it": "Package"
    }
  },
  {
    "code": "art",
    "name": {
      "de": "Kunst & Kultur",
      "en": "Art & Culture",
      "fr": "Art et culture",
      "it": "Arte e cultura"
    }
  }
]

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

Image

Describes an Image.

Field	Type	Remark
`url`	string
`title`	Translation
`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)
`activities`	Array of string	See Activities
`title`	Translation
`teaser`	Translation
`description`	Translation
`info_url`	Translation	Target link to the Offer’s website
`prices_from`	(#price-object)	The minimum (from) price in the requested currency
`spoken_languages`	[]string	see Spoken Languages
`images`	Array of Image	The first element is the thumbnail image.
`setting`	Coded Translation	Environment in which an event takes place (indoor, outdoor etc.)
`max_capacity`	number	Max. number of occupants per visit
`duration`	Translation
`event_location`	GeoCoordinates
`event_address`	Address
`event_dates`	Array of DateRange
`weekdays`	Array of Weekday
`transports`	Array of Transports
`segments`	Array of Coded Translation	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)
`ticket_info`	Translation	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 3.2.5

2024-01-20

Added description field to Price object

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

OfferHub API

Basics

Base URL

Authentication

Endpoints

General information

Formats

Format generic

Format swt

Available Data Fields

List Offers

Get single offer

Booking Widget

Enums

Engines

Languages

Currencies

Labels

Activities

Settings

Transports

Weekdays

Objects

Translation

Coded Translation

Price

Image

Geo Coordinates

Address

Date Range

Offer

Changelog

Interfaces

Alturos

Smeetz

STnet Adventures

STnet Hotels

TOMAS

Format `generic`

Format `swt`