Introduction

The objective of Citybreak BI API is to enable external partners to get hold of the booking data for external analysis. Applications such as BI-analysis tools could be built upon the data.

Release notes

BI API version 5

• BREAKING CHANGE The authentication return status codes are now moved from the existing Status field to AuthenticationStatus on a new result wrapper type to better indicate failed or expired authentication keys. The existing Status is renamed RetrievalStatus to clarify the difference.
• BREAKING CHANGE The GetManyAfterReservationId operation is renamed GetMany.
• BREAKING CHANGE The SearchAfterReservation operation is removed, use FindFirstAfter to find a starting point by date and GetMany to fetch reservations instead.
• BREAKING CHANGE SequenceId replaces ReservationVersionId in GetMany to simplify usage since ReservationVersionId is not sequential in nature. To continue retrieving reservations from a previous implementation, call GetData with your latest ReservationVersionId, note the SequenceId and use that from now on.
• BREAKING CHANGE Corrected Name/Value field on ComplementBase which were accidentally swapped.
• Added TrackingId - user defined tracking id from the booking client.
• Added ClientConfirmationPdfUrl - downloadable client confirmation PDF.
• Added CrmAnswers - a list of the answers to the customizable customer questions.
• Added ExternalBookingNumber - an optional reference to an external system’s booking.

Endpoints

The service is available via several protocols. A JSON-based OpenAPI service, a SOAP-compatible .NET WCF service and also an XML REST service.

JSON-based OpenAPI service

.NET WCF service

SOAP WSDL service

XML REST service

Methods

The methods provided enables you to download information about bookings.

FindFirstAfter

BookingSearchHit FindFirstAfter(string authToken, DateTime start);

/BookingInformationService.svc/xml/findfirstafter/{AUTHTOKEN}/{START}

/api/bookings/findfirstafter/{start}

This method enables you to find a starting point to retrieve booking data, it takes a start date and will return a SequenceId which you can use in the GetMany operation.

public class SearchHit {
   /// <summary>
   /// The date the booking was made.
   /// </summary>
   public DateTime BookingDate;

   /// <summary>
   /// The sequence id of the booking.
   /// </summary>
   public int SequenceId;

   /// <summary>
   /// The globally unique reservation version id the booking got.
   /// </summary>
   public int ReservationVersionId;

   /// <summary>
   /// The version of this booking. First version of the booking code has version 1.
   /// </summary>
   public int Version;

   /// <summary>
   /// The booking code the version has. The format is "CCCCnn" where C { A-Z } and n { 0-9 }
   /// </summary>
   public string BookingCode;
}

GetMany

GetManyResult GetMany(string authToken, int sequenceIdToStartWith, int numberOfItems, int numberOfItemsToSkip);

/BookingInformationService.svc/xml/getmany/{AUTHTOKEN}/{SEQUENCEIDTOSTARTWITH}/{NUMBEROFITEMS}/{NUMBEROFITEMSTOSKIP}

/api/bookings/getmany/{sequenceIdToStartWith}/{numberOfItems}/{numberOfItemsToSkip}

Returns a list of bookings from a SequenceId, pass 0 to receive the first batch of bookings. To continue batch retrieving data, pass the last booking’s SequenceId you received as sequenceIdToStartWith in subsequent calls. numberOfItemsToSkip should be set to 0 for single threaded batching. To enable multi threaded batching you can for example do four requests in parallel with the same sequenceIdToStartWith and 10 numberOfItems but with 0, 10, 20 and 30 numberOfItemsToSkip respectively. NB! This method could potentially return a great chunk of data. Please leave numberOfItems to 20 or below.

GetData

GetDataResult GetData(string authToken, int reservationVersion);

/BookingInformationService.svc/xml/get/{authToken}/{reservationVersion}

/api/bookings/get/{reservationVersion}

This method gets the interior of a single booking.

Bookings

When a booking is committed in Citybreak, a booking version is created. That version is assigned a globally unique id, known as bookingVersionId or reservationVersionId. The booking is also assigned a booking code. The format is four letters and two digits (ex AAAA01). That particular version is datestamped when it was committed into a reservation. This is known by the BookingDate.

When a booking is changed, a brand new booking version is created with a complete different bookingVersionId with the same booking code. This booking version will mark all products that are removed as Removed, all products not changed as NotChanged and new products with status New.

ReservationVersionId is non-sequential, so to simplify batch retrieval operations we provide a sequential SequenceId to be used instead.

Actors

There are several actors in a booking. What you probably are looking for is to analyze the organizers view. The organizer is the “owner” of the booking. There are also other actors that you may want to pay attention to.

GetDataResult / GetManyResult object

This result object simply wraps the BookingInformationResult object(s). We communicate the result of the authentication through this object.

       /// <summary>
       /// Gets or sets the booking result if the status of the authentication was Ok
       /// </summary>
       /// <value>
       /// The booking.
       /// </value>
       public BookingInformationResult BookingResult { get; set; }

       /// <summary>
       /// Gets the authentication status of the operation
       /// </summary>
       /// <value>
       /// The authentication status.
       /// </value>
       public AuthenticationStatus Status { get; set; }

       /// <summary>
       /// Gets or sets the key expire date.
       /// </summary>
       /// <value>
       /// The key expire date.
       /// </value>
       public DateTime KeyExpireDate { get; set; }

The enumeration AuthenticationStatus contains the status of the authentication. If the status is different from Ok, the BookingResult property is empty.

   /// <summary>
   /// Tells the status of the authentication
   /// </summary>
   public enum AuthenticationStatus
    {
       /// <summary>
       /// The operation went ok, check the result
       /// </summary>
       Ok = 0,

       /// <summary>
       /// The authentication failed
       /// </summary>
       Fail = 2,

       /// <summary>
       /// The API key expired
       /// </summary>
       ApiKeyExpired = 3,
    }

BookingInformationResult object

The booking information result object simply wraps a BookingInformation object. We communicate the result of the retrieval through this object. The class contains three fields.

       /// <summary>
       /// Gets or sets the booking if the status of the retrieval was Ok
       /// </summary>
       /// <value>
       /// The booking.
       /// </value>
       public BookingInformation Booking { get; set; }

       /// <summary>
       /// Gets the retrieval status of the operation
       /// </summary>
       /// <value>
       /// The retrieval status.
       /// </value>
       public BookingRetrievalStatus RetrievalStatus { get; set; }

The enumeration BookingRetrievalStatus contains the status of the retrieval. If the status is different from Ok, the Booking property is empty.

   /// <summary>
   /// Tells the status of the operation retrieve a booking
   /// </summary>
   public enum BookingRetrievalStatus
    {
       /// <summary>
       /// The operation went ok, check the result
       /// </summary>
       Ok = 0,

       /// <summary>
       /// The operation failed, no result available
       /// </summary>
       Fail = 1,

       /// <summary>
       /// The user had no access to the booking.
       /// </summary>
       NoAccessToBooking = 4,

       /// <summary>
       /// The item is not yet ready to be downloaded. Try again in a while.
       /// </summary>
       Delayed = 5,
    }

The fail represents a state where we were unable to deliver the result of the booking. This simply means that you can’t get the result. You should however not be dependent on it. There will be a successor if booking version if changes should be communicated. If you feel that you are missing out of something, please contact Citybreak Support that will take it further.

BookingInformation object

This is the container for all information for a specific version of a booking.

MainProduct

Extending Product with a list of sub products that are associated with the main product. They are bought under the same agreement and may include business restrictions when buying them, like they may be mandatory included when buying the main product.

SubProduct

A product that is associated with a MainProduct.

Product

The base class for MainProduct and SubProduct.

ProductOrganizationInfo

Summary of the economy for a specific organization in the context of a product.

ProducttypeInfo

Statistics

Creating statistics from booking versions

Views

What you are probably looking for is to take some sort of action depending on the data you download. If you are doing operational reports, like an arrival list to see who is arriving today, who is staying and who is leaving you are only interested in the latest version of a booking code. This is known as a Net List. If you are statistics about performance you are looking at a gross list.

Depending on the type of queries you would like to respond to, you are likely to want to separate products so that they could be queried separately not bundled in a booking. You probably don’t want to query all products in a reservation version at the same time, but apply filter on product categories for instance.

Net list

This simply means that you will only focus on the latest version of a specific booking code. As soon as you receive a new version you simply throw away the old one and replaced the information with the contents just downloaded. This means that when you create a report on arrivals in June the contents may differ at any one time when generating the report. A new booking changing the numbers may have been recorded between two different generations and the numbers may have changed. Please note that even if the last arrival is in the past, there is no guarantee that a next version will not be available later on.

They should be treated as snap shots in time when the report was generated.

Typical queries made into a net data sets are based on arrival and departure of specific product items.

Gross list

A gross list is simply an aggregated view of all versions of a booking. The query is based on booking date and the result can never change regardless when a report was created. If a product is added +1 product is added to the time span. If a product was not changed between versions +0 products were added. If a product was removed -1 product is added to the gross summary.

This is done by adding all products from version 1. When version 2 is recorded, the version 1 is negated at the time of booking of version 2. Then all products still active in version 2 is added.

• Version 1 created at t1 contains one Double room from Jan 1 to Jan 10.

• Version 2 created at t2 the double room was changed to Jan 5 to Jan 6, and a single room was added Jan 6 to Jan 10.

At t1 the reservation summary went: +1 product +9 room nights

At t2 the reservation summary went: -1 product -9 room nights +2 products +4 +1 room nights

• A report for a period only including t1 will report +1 product and +9 room nights.
• A report for a period only including t2 will report +1 product and -4 room nights.
• A report for a period including both periods will report +2 products and 5 room nights.

If these were all versions of the booking, a net report will report the current state of the booking as +2 products and +5 room nights.

Calculating Guests

There are different views on this operation.

The number of guests in a booking can’t be calculated in the generic case. Consider the following scenario: There are two rooms in a booking. One between May 1 to May 2 and the other between May 10 to May 12 with two adults each. You can’t assume that it is the same two adults in the first room as in the second.

The one that makes the reservation may create a guest list. The list that is reflected directly under the booking object. It may be correct in terms of calculating the number of guests in the booking. There is no guarantee for it to be correct.

However, for most statistical operations this is not a problem. You are likely to analyze the number of guests per room, since that is the statistical entity most operations analyze. The number of guests in a room are the sum of the GuestLinks on the MainProduct. You also need to find possible extra bed guests. This is done by checking up on the SubProducts for the specified MainProduct. Since guest links may be found on all sorts of sub products you need to calculate only the ones with a ProductType of 14. The ProductType is found under the property ProductTypeInfo.

Statistical entities

Stay time

This is applicable to Category type Accommodation and is the number of nights a product is used.

Room nights

This is applicable to Category type Accommodation and is the stay time for a product. Sum the number stay time for each product to get the total number of room nights in a booking.

Guest nights

This is applicable to category type Accommodation and is the stay time multiplied with number of guest links on a product. This is calculated per product.

Other types

ProducttypeType

The type is described by an int. Although it is unique, the subtype depends on the category. If you need for more types than accommodation, let the Citybreak team know.

Webhook

We can provide a webhook call on each booking version made in the system. It will be a call to a static POST endpoint with the following body:

public class WebhookBookingModel
{
    public int Version { get; set; }

    public int ReservationVersionId { get; set; }

    public DateTime BookingDate { get; set; }

    public int SalesPointId { get; set; }

    public string Currency { get; set; }

    public decimal VAT { get; set; }

    public decimal Price { get; set; }

    public DateTime AutoCancelDate { get; set; }

    public DateTime CancellationDate { get; set; }

    public string BookingCode { get; set; }

    public bool IsMobileBooking { get; set; }

    public int? SellerOrganizationId { get; set; }

    public int AgentOrganizationId { get; set; }
}