Documentation🖇 Quick LinksAPI

POC - Step By Step Guide

Suggest Edits

Overview

The Room Mapping API was developed to provide a straightforward yet powerful solution for delivering mapped room data to customers.

This API allows clients to map their inventory at the room level by consolidating rooms from different suppliers and organizing them effectively. This enables clients to offer a comprehensive user experience by presenting clear and concise room offerings.

This guide will walk you through the steps to perform quick and effective proof of concept (POC).

POC Goals

  • ✔️ Understanding the Room Mapping API.
  • 🗝️ Key considerations and recommendations.
  • 🎯 Evaluating the results effectively.

Steps for completing the POC

Step 1 - Obtain test API Key

To obtain a test API key, you can either request a personal key from the sales team or use the following key:
X-API-KEY: 7671ae5e-9f4e-4a71-8242-c7691a9275a5.

For list of Hotels supported by the Test API Key - Click here.

Step 2 - Identifying the Hotel

To identify a hotel, you have two options:

  • Supplier ID and Supplier Hotel Key: The preferred method is to identify the hotel by forwarding the Supplier ID and Supplier Hotel ID in the request. (Preferred option)
    For list of Supplier IDs supported by Room Mapping - Click here..
  • Gimmonix Hotel ID: You can also identify the hotel by specifying the Gimmonix Hotel IDs in the request.

👍

NOTE:

The hotel identification is solely for identifying hotels.
If you've used Supplier X to identify the hotel, you can still map rooms from Suppliers Y and Z.

Step 3 - Map Rooms

Once you have obtained the test API key and understood how to identify hotels for mapping rooms, you can proceed to start mapping rooms.

To initiate a Room Mapping Request, you can use the interactive experiment available at this link.

How to map rooms :

  1. Insert the API Key in the authentication header :

  2. Identify the hotel.
    In this guide, we used the Supplier ID along with the Supplier Hotel ID.
    For this example, we'll use the supplier Expedia (Expedia's Supplier ID = 1165) and the hotel being used is Expedia's Hotel ID - 3909080 (Hilton Pattaya).

    Fill in the Supplier ID and Supplier Hotel ID (HotelKey) in the respective sections :

  3. The final step is to start mapping rooms. To do this, please fill in the room data accordingly.
    As an example, we will use the following fields:

    • rateDescription = KING FAMILY OCEAN SUITE ... 78 SQM SEPARATE LIVING ROOM LOUNGE ACCESS ... COMP EXTRA BED LARGE BATHROOM WITH BATHTUB.
    • OfferRateId = 1 (This field is used to correlate the room between the request and response - can be a random number or string).

  4. Click 'Try It!' to initiate the request :

  5. The response will provide the room mapping information, including the Gimmonix room ID, room name, type, views, size, perks, description,images and more.
    Example Room Mapping Response : 

    {
  "hotelRooms": [
    {
      "gimmonixRoomId": "4291574-6",
      "gimmonixRoomName": "King Family Ocean Suite",
      "roomMaxOccupancy": 3,
      "isSmoking": false,
      "roomType": [
        "SUITE"
      ],
      "roomView": [
        "OCEAN"
      ],
      "balcony": [
        "BALCONY"
      ],
      "roomDescriptions": [
        {
          "language": "en",
          "line": 0,
          "paragraph": "SUITE KING SIZE BED"
        }
      ],
      "perks": [
        {
          "value": "TEA"
        },
        {
          "value": "Cable channels"
        },
        {
          "value": "Bath"
        },
        {
          "value": "Bath or shower"
        },
        {
          "value": "Safety deposit box"
        },
        {
          "value": "HEATING"
        },
        {
          "value": "TELEPHONE"
        },
        {
          "value": "LAPTOP"
        },
        {
          "value": "Air conditioning"
        },
        {
          "value": "Fold-up bed"
        },
        {
          "value": "HAIRDRYER"
        },
        {
          "value": "Privacy curtain"
        },
        {
          "value": "Balcony"
        },
        {
          "value": "Pants press"
        },
        {
          "value": "BATHROBE"
        },
        {
          "value": "REFRIGERATOR"
        },
        {
          "value": "DESK"
        },
        {
          "value": "Ironing facilities"
        },
        {
          "value": "Seating Area"
        },
        {
          "value": "Free toiletries"
        },
        {
          "value": "TOILET"
        }
      ],
      "bedTypes": [
        "KING"
      ],
      "images": [
        {
          "imageUrl": "http://photos.hotelbeds.com/giata/bigger/13/137081/137081a_hb_ro_150.jpg",
          "imageDescription": "Room"
        },
        {
          "imageUrl": "http://photos.hotelbeds.com/giata/bigger/13/137081/137081a_hb_ro_089.jpg",
          "imageDescription": "Room"
        },
        {
          "imageUrl": "http://photos.hotelbeds.com/giata/bigger/13/137081/137081a_hb_ro_088.jpg",
          "imageDescription": "Room"
        },
        {
          "imageUrl": "http://photos.hotelbeds.com/giata/bigger/13/137081/137081a_hb_ro_090.jpg",
          "imageDescription": "Room"
        },
        {
          "imageUrl": "http://photos.hotelbeds.com/giata/bigger/13/137081/137081a_hb_ro_091.jpg",
          "imageDescription": "Room"
        }
      ],
      "mappedRooms": [
        {
          "offerRateId": "1",
          "riskScore": 0
        }
      ]
    }
  ]
}

Step 4 - Key considerations and recommendations

  • 'offerRateId': The client's internal offer rate ID. This unique ID/string is used to correlate rates between the request and response and can be any value.
  • 'roomName' / 'rateDescription': These two fields are the most important and recommended to include. Forwarding at least one of them is mandatory.
  • 'roomKey': This is the supplier's unique RoomKey.
    This field is not mandatory since not all suppliers support it, but Gimmonix highly recommends including it when available.
  • All other fields: These can be included to ensure more accurate mapping, but they are not mandatory.

Step 5 - Evaluation

How to evaluate your results ?

  • Room names contains the main marketing elements available on the hotel website.
  • 100% of the rates sent are mapped (other than dormitory in 4 and 5 stars hotels).
  • No errors where the 'Gimmonix room name' include elements not promised by the supplier.

👍

NOTE:

When evaluating the mapped rooms, it is recommended to compare them with the hotel's website.

Evaluation - example

When there's a chance for error, we can simply compare the mapped room details to the information available on the hotel's website:

The room was mapped to 'King Family Ocean Suite'. By navigating to the hotel's website, we can verify that this room was mapped correctly, both in terms of the room name and the perks it offers, including bedding and room images.

Support: During & After the POC

If you require any assistance, have questions or need clarification, you have two options available:

  1. Search in our Documentation for the information you need. (Recommended)
  2. Submit a support ticket to our dedicated support team.

Going Pre-Live / Live

Please refer to the following Article : Working With Us - Room.Works.

Demo

Room Mapping API Example

Updated about 1 month ago