Booking Analysis Product

What is it?

The Booking Analysis suite of APIs enables partners to build work-flow based solutions against new and updated booking data.

How do I get it?

Minimum Requirements

  1. The caller must be a verified partner subscribed to the Booking Analysis product.
  2. The caller and location must be integrated with a verified instance of Amadeus Sales & Event Management – Advanced (R28 or Above).

How do I use it?

The rest of this documentation gives an overview of the APIs included in the product.

Included APIs

What's Included?

  1. Authentication
  2. Booking Analysis Configuration
  3. Management
  4. Location Export & Setup Data
  5. Notification
  6. Booking
  7. Booking Event
  8. Booking Room Block
  9. Booking Room Night
  10. Activity

You must be logged in with an active subscription to view these APIs.

What about Security?

All Booking Analysis APIs require AHWS authentication. See the authentication guide for details.

How do the APIs integrate?

The Booking Analysis APIs are designed to support the following work-flow:

  1. Amadeus Hospitality registers a new location with a partner's Booking Analysis integration. The location is given a default LocationId.
  2. The partner's integration is made aware of the new location by calling one of the following:
    • Location Export - Returns all locations associated with the calling user.
    • Get Unconfigured Locations - Returns all locations associated with the calling user which have not been configured by the partner.
  3. The partner uses Edit Location Id to update the location's default LocationId to the Id used in the partner's system.
  4. Setup data related to a location such as guestroom types, function rooms, and market segments can be retrieved and cached by the partner.
  5. The partner initiates an initial sync request. This creates notifications for historical and future bookings associated to the new location.
  6. The partner uses Configure to configure the location with the appropriate evaluation endpoint and credentials.
  7. The partner polls for notifications. This includes BookingAnalysisSynchronization notifications generated via an initial sync and Booking notifications generated when bookings are created or updated in Amadeus Sales & Event Management – Advanced.
  8. Notifications include a callback url which is used to retrieve the data associated with the notification.
  9. Activities can be created in Amadeus Sales & Event Management – Advanced.

Configuration

Configuring a new location

To configure a location for Booking Analysis, new locations must be identified, reassigned a new LocationId (optional), and configured.

Identifying new locations

New locations can be identified by calling Get Unconfigured Locations. This returns all locations associated with the calling user which have not been configured by the partner for the evaluation work-flow.

The Location Export API returns all locations associated with the calling user. A partner may choose to determine new locations via this full list.

Updating the LocationId

All new locations registered with a Booking Analysis integration are assigned a default LocationId. A partner may choose to reference the location via an identifier internal to their system. The Edit Location Id API can be leveraged to change the LocationId to this identifier. For example, the newly registered "Hotel One Two Three" was assigned the default LocationId "a1Sf2000002BnwFEAS." To change it to "HOTEL123" a request can be made using the example payload below:

  {
      "oldLocationCode": "a1Sf2000002BnwFEAS",  
      "newLocationCode": "HOTEL123"
  }
				
Subsequent references to the location in Booking Analysis requests and responses will use the new LocationId.

Setting configuration

To use the evaluation work-flow, all locations must be configured with:

  • An evaluation endpoint
  • An evaluation username (to communicate with the evaluation endpoint via basic authentication)
  • An evaluation password (to communicate with the evaluation endpoint via basic authentication)
The Booking Analysis Configure API sets these configuration values. For example, to configure the location "HOTEL123" with a booking analysis integration using the evaluation endpoint "http://example.com/" with the username "user" and password "password" a request can be made using the example payload below:

  {
      "location": "HOTEL123",  
      "evaluationEndpoint": "http://example.com/",
      "evaluationUsername": "user",
      "evaluationPassword": "password",
  }
				

This API can be called at any time to set or change the configuration for a given location.

Setup Data

Before receiving booking updates, partners may want to store locations and their associated setup data; for example guestroom types, function rooms, and market segments.

When booking data is retrieved via notifications, the returned data includes references to these entities via ids. For example, a booking event is returned with a MarketSegmentId, for example:

    {
        ...
        "MarketSegmentId": "0052E00000Hxu7MQAR[1208104]",
        ...
    }
In order to understand what these ids represent (what the name of the referenced market segment is in this example), the Location Export API can be leveraged.

Location Export

The Location Export API returns the list of all the Locations for which the calling user has access.

Get Guestrooms By Location

The Get Guestrooms By Location API returns the list of guestrooms associated with the provided location.

Get Setup Values By Location

The Get Setup Values By Location API returns the list of setup values associated with the provided location. Setup Values include:

  • BookingType
  • EventClassification
  • FunctionRoomSetup
  • HousingMethod
  • LostBusinessReason
  • MarketSegment
  • MeetingClass

Get Function Rooms By Location

The Get Function Rooms By Location API returns the list of function rooms associated with the provided location. The list includes Combo Function Room and Component Function Room information for each returned Function Room.

Types of Function Rooms

Type

Description

Combination

This type of Function Room consists of smaller rooms. For example, if the Grand Ballroom can be broken down and sold as Ballroom A, Ballroom B, and Ballroom C, then the Grand Ballroom is a Combination Function Room. These can be seen in the API in the collection "ComponentFunctionRooms". If an Id is present in the ComponentFunctionRooms collection, then that means the current Function Room is a combination room made up of smaller Function Rooms.

Indivisible Component

This type of Function Room cannot be divided into smaller rooms, but it can be combined with other Function Rooms to create a combination room. For example, Ballroom A from above is one component of the Grand Ballroom. These can be seen in the API in the collection "ComboFunctionRooms". If an Id is present in the ComboFunctionRooms collection, then that means the current Function Room is a component of a larger Function Room.

Standalone Component

This type of Function Room cannot be divided into smaller rooms or combined with other rooms. For example, a boardroom would not be divided into smaller rooms or part of a larger room. These Function Rooms would have null ComboFunctionRooms and ComponentFunctionRooms collections when returned by the API.

These APIs expose data that is seldom modified and do not generate notifications. For example, since new FunctionRooms do not generate notifications, the following flow is recommended:

  • When an update is received for a BookingEvent that contains an unrecognized FunctionRoomId, a call to Get Function Rooms by location should be triggered.
  • A weekly job should be scheduled that calls each setup data API to retrieve and cache the values.

Notifications

Summary

The Booking Analysis APIs leverages Amadeus Hospitality's Notification API.

There are two types of notifications generated as part of the Booking Analysis workflow. Each notification type contains a callbackUrl which is used to retrieve a BookingDocument or list of BookingDocuments.

EntityType

CallbackUrl

Summary

BookingAnalysisSynchronization Booking/Sync

This notification is generated via an initial sync request. It allows partners to retrieve historical and future booking data for a location via a callbackUrl. A request to the callbackUrl returns a list of BookingDocuments.

Booking Booking/Get

These notifications are generated whenever a booking or any one of its child entities are updated in the source system. Each notification allows a partner to retrieve the BookingDocument for the updated booking. A single receive call will never result in multiple notifications for the same booking. Partners should poll for these continuous updates.

Using Notification APIs

The typical workflow for using the Notification API is as follows:

  1. Poll for Notifications (receive) on a regular interval.
  2. Whenever notifications are returned from polling, call GET on the callbackURL returned as part of the notification response.
  3. Take the appropriate action with the response from the callbackURL based on the EntityType of the notification.
  4. Once a notification has been processed, it must be committed.

Retrieve Notifications

API: Notification Receive by Location

Type: HTTP POST

When calling to retrieve notifications for a given location, the LocationId must be specified as part of the path. The response body will contain a collection of notifications for that location. If no notifications are pending, the collection will be empty.

This API call is rate limited, see rate limits for details.

Each Notification returned will have the following properties needed to process the notification:

  • EntityType: Indicates the type of notification: Booking or BookingAnalysisSynchronization.
  • LocationId: The Id of the location the notification is associated with.
  • CallbackURL: The URL which can be called to retrieve the associated data.

Here is an example of what the full JSON payload returned looks like:

    [
        {
        "CallbackUrl": "https://api.newmarketinc.com/api/BookingAnalysis/Booking/GetAllBookingsByLocationId/e6457025-69d2-4b84-8468-139593ce76e8[81157]",
        "Id": "003b1a55-0000-0000-b218-000074753d00",
        "EntityId": "000018d6-0000-0000-b218-0000f5730200",
        "ExternalId": "ohgPk1A4RgidW014W_tS7wEq",
        "SentOn": "2018-09-04T14:27:01+00:00",
        "ReceivedOn": "2018-09-04T14:34:18+00:00",
        "LastStatusChangeOn": "2018-09-04T14:34:18+00:00",
        "EntityType": "Booking",
        "ExternalEntityId": "ohgPk1A4RgidW014W_tS7wEq",
        "Subject": "Booking Changed",
        "ReceivedCount": 1
        "LocationId" : "HOTEL123"
        },
        ...
    ]
			

Notifications are returned in bulk, each response contains up to 200 individual notifications.

Commit Notifications

API: Notification Commit

Type: HTTP POST

This call requires an array of Notification. You can use the payload you received from Notification/Receive. You should only commit notifications that you have finished processing successfully.

Once you receive a notification, you must commit it if you have successfully processed it. If you do not commit the notification after an hour, that same notification will be returned to you on your next polling cycle. Don't worry though, the callbackURL will always return the latest version of the entity you are requesting. You will never get old data.

You can leverage this in your favor. If processing a notification fails, just don't commit it and you will be able to receive it and try again a little later. If you don't commit a notification 24 hours (or 7 days for Booking Analysis Sync notifications) after you last receive it, the notification will be canceled and will not be given to you ever again.

You have the option to commit notifications either 1 at a time or in bulk. It may be easier to commit a notification immediately after processing, but it will consume more API calls. Both ways are valid and it is up to you to determine the most effective way to handle these notifications in your own system.

Recommendations and Notes

The BookingAnalysis product applies API usage quotas and rate limits to your API consumption. These limits should not affect the quality of your solution in any way.

These policies allow us to deliver a better quality of service to developers like you. Because of these policies, we would recommend a polling interval on Notification/Receive of once every 12 hours. For more information on polling intervals see Rate Limits.

Initial Sync

Initiating an Initial Sync

An initial sync for a given location is initiated via a Request Initial Synchronization request. This request should only be performed once as part of the initial configuration of a new location.

After a successful request, a notification will be generated with an EntityType of BookingAnalysisSynchronization. The callbackUrl on the notification can be used to retrieve historical and future bookings associated with the location.

Processing Notifications

The response from a sync notification's callbackURL is a List<BookingDocument>.

Each element of this list may be processed as a single BookingDocument would be during a continuous updates. Each BookingDocument may contain an Events, RoomBlocks, RoomNights, and OtherIncomes field which may contain a ContinuationCallbackResponse. This URL can be called to retrieve the various child entities related to the booking.

After every BookingDocument in the initial response has been processed, the callbackURL from the notification should be called again. For this and all subsequent calls, the ContinuationToken header received from the previous response must be used in the request. See Figure1 for a visual example of how to use Continuation Tokens.

Once all bookings have been returned, the response from the callbackURL will not return a ContinuationToken. Once this response has been processed, all historical and future bookings have been retrieved. After this, the notification should be set to committed.

Endpoints

The following endpoints are used throughout the initial sync process. The URLs are returned as a callbackUrl and should not be stored and only ever called as indicated by a particular callbackUrl.

Resource

Endpoint

Parameter

List<BookingDocument>

GetAllBookingsByLocationId

LocationId

List<BookingEvent>

GetAllBookingEventsByBookingId

BookingId

List<BookingRoomBlock>

GetAllBookingRoomBlocksByBookingId

BookingId

List<BookingRoomNight>

GetAllBookingRoomNightsByBookingId

BookingId

List<OtherIncome>

GetAllOtherIncomeByBookingId

BookingId

Continuation Tokens

These endpoints return the following headers in the response:

ContinuationToken

string

This is the continuation token value, we will use this value to send you the next chunk of data if your request results in more records than can be returned in a single call. you will get this call in the headers of the response, and you will then provide that header in your next request.

RemainingRecords

int

This represents the approximate number of records you still have to retrieve. It will decrement with every call you make to the endpoint.

When calling these endpoints, you will need to provide the ContinuationToken from the previous response as a header in your next request.

Continuation Token Workflow

Figure 1. Basic flow of requests/response with ContinuationToken

Considerations

  • To get all data, you must continue to call the endpoint until you get no continuation token in the header of a response.
  • Continuation Tokens do have an expiration date. By default it is good for 7 days.
  • In the rare event you get a 500 or 503 status code, simply retry the action later, with the continuation token you just used. This does require you to maintain your current continuation token until you receive a new one.
  • The default maximum number of records you will receive in any of these responses is 200.

Continuous Updates

A notification will be generated for all valid changes that occur in the source system. If a user updates any booking, or any child data on that booking, a notification for the booking will be generated.

That notification will have a CallbackURL to an endpoint that will return a BookingDocument resource, and you will need to follow the same process as initial sync to retrieve all of the children if their CallbackURLs are populated.

If multiple modifications are made to a booking or its child entities before you have received notifications, then we will only provide you a single notification. We aggregate all updates associated to a single booking into a single notification. This will not result in any missed updates.

The notification you receive will point to the latest version of that booking and ALL of its child entities. Because we are returning data in bulk, this will result in less API calls for you.

Resource Descriptions

The Booking Analysis APIs returns five types of data. Booking is the parent resource, and you will also receive data for children related to a Booking.

The Booking endpoints returns what is called a BookingDocument, which has all the standard Booking fields and four new fields to access child items. These fields will only be populated if the Booking has those child types.

{
        "Id": "03FE3MF3...",
        ...
        "Events": {
            "CallbackURL": "https://....",
            "ContinuationToken": "4FE2FJKK3495..."
        },
        "RoomBlocks": {
            "CallbackURL": "https://....",
            "ContinuationToken": "4FE2FJKK3495..."
        },
        "RoomNights": null,  // this booking has no Room Nights
        "OtherIncome": {
            "CallbackURL": "https://....",
            "ContinuationToken": "6FI4GFEPDSOI..."
        }
    }

The Booking Sync endpoint returns an array of BookingDocument. To retrieve children you will call the Entity.CallbackURL and put the Entity.ContinuationToken in the request header.

Now you will follow the same flow as defined in the Initial Sync section. If the Booking has no associated Events, that value will be NULL and there is no need to call in and try to retrieve those values.

Activities

In our Sales & Catering product, there is an ability to create activities for a user, these activites are simple reminders that notify the user when they are logged into the application. The activity contains a few important details such as:

  • Location Id - This is the Id of the location the requested user is associated to.
  • Assigned To - This is the Id of the user being assigned the task.
  • Subject - A brief description of the Activity (i.e. "Your booking report is ready", Call customer", "Confirm booking", etc)
  • Status - This should always be "Not Started".
  • Priority - This is the priority level of the task ("Low", "Medium", "High").
  • Related To - This is the Id of the entity the activity is associated to. For example, if the activity is a notification that an analysis has been completed on a booking, you could provide the booking Id here. This field is not required, but will provide more information on the activity.

Here is an example of what a task may look like:

example of what a task may look like

API

You can find even more information on the Legacy Activity API

Where are User Ids?

In order to keep our customer's personal information secure user information is not made directly available. There are a number of fields on the associated resources that are user Ids. These are the Ids you will be able to set in the Assigned To when creating the activity. All user information is returned on the Booking record. If you are attempting to create an activity that is related to one of the child resources (Booking Event, Room Block, Room Night, Other Income) you can use the ExternalCreatedById or ExternalModifiedById from any record where it is available.

User Id Fields

  • BookedById - The Id of the user that booked this business, the booking also has the Name and Email field for this user.
  • CateringManagerId - The Catering Manager for this business, the booking also has the Name and Email field for this user.
  • ServiceManagerId - The Service Manager for this business, the booking also has the Name and Email field for this user.

Error Scenarios

When you pass the correct information in you will receive 200 - OK and 202 - Accepted status codes.

If things go wrong, you can inspect the Http Status Code and the request body to determine what failed and how to correct your call.

HTTP Status Codes

Reason

200 The server has successfully processed the request.
201 Created - resource was created.
202 Accepted - request has been accepted but the resource change has not been applied.
204 The server successfully processed the request but is returning no content.
400 The request could not be understood. Please check the response for additional information.
401 The request did not include the correct authentication.
403 The server understood the request but is not able to fulfill because of insufficient permission.
404 The requested resource was not found.
405 The server does not provide access to the URL for the HTTP Verb requested.
500 The server has encountered a problem, please try again.
503 The service is temporarily unavailable. If the length of the delay is known a Retry-After header is given. It is recommended that the client delay for this interval before sending another request to the service. If no Retry-After is provided the client should handle as a 500 error.

Calling OAuth

The most common error status code you will get from the OAuth service is a 403 - Forbidden. The error property in the response body will tell you what was not accepted.

  • access_denied means you have an incorrect Username and Password pair. The user might not exist or the password provided was wrong.

  • unauthorized_client means there is incorrect information in the client_id and client_secret fields. Ensure you are using the correct values that you received from Amadeus Hospitality when you acquired your credentials.

You may also get a 405 - Method Not Allowed if you call OAuth endpoints with the GET verb instead of POST.

In the rare event you get a 500 or 503 status code, simply retry the action later.

For more information about OAuth refer to our Authentication Guide.

Calling a Sync Endpoint

There are a few different status codes you can get depending on the data you provide or the status of AHWS.

400 - Bad Request

This means that the service got your request, but was unable to complete it due to missing or invalid inputs. This could be because:

  • You did not provide a Continuation Token when you should have
  • The Continuation Token provided was invalid
  • The Continuation Token provided has expired (remember tokens expire after 7 days)
  • You used a different `identifier` in the url than the Continuation Token was assigned for

401 - Unauthorized

If there is no ChannelLocation relationship between the calling user and the Location you will receive an Unauthorized.

403 - Out of call volume quota

We will be limiting calls to BookingAnalysis/Booking/GetBookingDocumentById to 400 calls every 24 hours, and Notification/Receive to 1 call every 12 hours. If a user calls these endpoints more than the given amount, they will get a 403 with a payload that looks like this

                {
                    "statusCode": 403,
                    "message": "Out of call volume quota. Quota will be replenished in 09:37:46."
                } 
                

When receiving this response, you must wait until your quota is replenished before you can make the call again.

429 - Rate Limit is Exceeded

We will also be limiting calls to all our APIs to 500 API calls in a single minute. Upon hitting this quota you will get a 429 with a payload that looks like this.

            { 
                "statusCode": 429, 
                "message": "Rate limit is exceeded. Try again in 32 seconds." 
            }
                

Upon receiving this response, you must wait for the duration of time specified in the response in order to begin making API calls again.

500 and 503

If you call an endpoint that uses a Continuation Token and get a 500 or 503 in response, resend the call a later time using the same Continuation Token you provided.

Error flow

Troubleshooting

Most 500 status codes are temporary, and normal service should return after a few seconds or minutes. You should retry a call in these instances.

If you are consistently receiving 500 status codes, you can use information in the response to help our Support team track down the error faster. The response Header will contain the following keys:

  • Ni-TrackingId
  • Ni-CorrelationId
These values can greatly decrease the time it will take to identify issues.

Rate Limits and Usage Quotas

In order to effectively monitor and protect our platform, this product will have usage quotas and rate limits enforced on calling users. There is a fixed number of calls that can be made in a 24 hour time period for specific APIs, as well as a maximum number of calls that can be made against all the APIs in the product over 60 seconds. Limits are enforced by a combination of the provided Location Id and the calling user's provided Subscription Key.

Usage Quotas

What to expect?

If a usage quota has been exceeded the response will be a 403 with a body like the example below:

{
    "statusCode": 403,
    "message": "Out of call volume quota. Quota will be replenished in 09:37:46."
} 
            

Notification - Receive by Location

This API is limited to 1 call every 12 hours. per Location. Once notifications have been returned, we will not actively limit the calls to process the data in the notification.

Notification - Receive

In order to prevent any misconfigurations from affecting multiple locations, the base Receive API will not allow subscribers of this product to call it. To receive notifications, Receive by Location must be called. This operation will return a 400 noting the operation is unavailable.

Booking Analysis - Request Initial Synchronization

This API is setup to only be called once per location, during the configuration and setup of a new location. If another Initial Sync Notification is required, contact Amadeus Hospitality.

Rate Limit

What to expect?

With the large number of requests made during Initial Sync portion of this integration, you may be worried about hitting usage quotas and being shut down in the middle of the process. You don't need to be! We do not enforce a quota on the number of times you can call the sync and child endpoints. You are limited to only making 500 calls in a single minute. This includes all APIs including Authentication, but it excludes requests generated via the Evaluate Booking process. . If you hit this limit you will only need to pause for a minute, and then your limit will be reset, at which point you can continue with your syncing of data. Rate limits are required to ensure steady service loads across all integrating partners. If you do end up hitting your rate limit you will be returned an HttpStatus of 429 with a payload like:

{ 
    "statusCode": 429, 
    "message": "Rate limit is exceeded. Try again in 32 seconds." 
}
			

Concurrency Limit

What to expect?

Simiarly to the rate limit, a concurrency limit is applied to the entire product on a per-subscription basis. This policy is in place to prevent large request spikes from negatively impacting the system. The current value used for the concurrency limit is 50 concurrent requests. If this number is exceeded at any point, you will receive an HttpStatus of 429 just like when hitting a rate limit, but the response payload will differ slightly. It will look like:

{
    "statusCode": 429,
    "message": "Concurrency limit exceeded."
}