1. Support Hub
  2. TripBuilder
  3. IBE - Internet Booking Engine

IBE URL Parameter API

When using the IBE on your website, you'll notice that the URL in your browser shows URL parameters starting in nz-. This type of parameters are attached to the URL by the TripBooster IBE and provide two important features:

  1. Support for Bookmarks and Page Refreshes
    These IBE URL parameters represent state information for what is loaded by the IBE. By maintaining it in the browsers URL, it is possible to bookmark a specific page loaded in the IBE or to perform a page refresh without losing the context in the IBE.

  2. API to Control What the IBE Loads
    The reversed use case applies as well of course. By explicitly setting certain IBE URL parameters, one can control what to load in the IBE.

This chapter gives an overview of supported IBE URL parameters.

Content (nz-url)

The URL parameter nz-url is the most important of all parameters and defines the TripBuilder path to be loaded into the IBE. It is automatically updated while a user browses TripBuilder pages in the IBE. The value of nz-url has always to be URL-encoded.

Examples:

  • Load a list of templates:
    www.your-domain.com/ibe?nz-url=%2Ftravel%2Froutes
    (value of nz-url decoded is /travel/routes)
  • Load a specific template:
    www.your-domain.com/ibe?nz-url=%2Ftravel%2Froutes%2Ftrip-123
    (value of nz-url decoded is /travel/routes/trip-123)
  • Load a personalized itinerary:
    www.your-domain.com/ibe?nz-url=%2Fitineraries%2Fozilf0xqcy3q
    (value of nz-url decoded is /itineraries/ozilf0xqcy3q)

 

Optionally, it is possible to define what value nz-url takes if not defined:

<div id="nz-planner" data-init-url="/travel/routes"></div>

Language (nz-lang)

nz-lang tells the IBE to load the content in a specific language. Applicable languages have to be configured in Cockpit Settings first.

  • Example URL loading the list of itinerary templates in German:
    www.your-domain.com/ibe?nz-lang=de&nz-url=%2Ftravel%2Froutes

Trip Filters (nz-template-filters)

By default, the IBE search results come without filters on top. However, they can be easily enabled on a case by case basis:

  • Setting nz-template-filters URL parameter to true. Example URL for loading the filters:
    www.your-domain.com/tours?nz-template-filters=true&nz-url=%2Ftravel%2Froutes

Want to always show the trip filters? Then best enable them on the embed code directly:

<div id="nz-planner" data-template-filters="true"></div>

Template Search

While the full power of template search comes with the Discovery API, certain aspects of the API are available via URL parameters. The aforementioned URL /travel/routes that can be loaded by the IBE provides a search/filter API to only show specific templates.

The filtering is based on tags that can be freely assigned to any template in Cockpit Inventory. For instance, tags can be based on countries, target customer groups (“family”, “honeymooners”, etc.) or any other category.

Tags are used in the filter API by means of the parameters listed below. A ranking algorithm evaluates all filter parameters, and filters and sorts the list of itinerary templates accordingly.

Parameter Description
required

Optional. Comma-separated list of tags.

Tags listed as required must be present on an itinerary template otherwise the itinerary template is filtered out.

If several tags are passed, only templates having all those tags will be returned.

preferred

Optional. Comma-separated list of tags.

Tags listed as preferred increase the importance of those itinerary templates containing one or several of the preferred tags.

It is possible to mention the same tag several times, which will add additional weight for templates with that tag when doing the sorting.

disfavored

Optional. Comma-separated list of tags.

Tags listed as disfavored decrease the importance of those itinerary templates containing one or several of the disfavored tags.

 

Example

The following example URL displays only templates tagged usa, with matching templates tagged mountain ending up higher in the list and matching templates tagged city ending up lower in the list.

www.your-domain.com/tours?nz-url=%2Ftravel%2Froutes%3Frequired%3Dusa%26preferred%3Dmountain%26disfavoured%3Dcity

  • (decoded value of nz-url is /travel/routes?required=usa&preferred=mountain&disfavoured=city)

By listing a tag several times, the weight of the tag is increased. 

Example

  • preferred=usa,usa,canada

In this example, the USA templates would rank higher than the Canada templates