Room Mapping API¶

The Room Mapping API provides room matching capabilities, allowing partners to automatically map room inventory between different suppliers using semantic name analysis empowered by AI-based techniques. It leverages modern AI and large language models to continuously improve matching accuracy, adapt to variations in naming conventions, and better understand contextual nuances across different suppliers over time.

Overview¶

The room mapping engine normalizes room descriptions, extracts semantic features (bed types, views, layout, amenities), and scores matches between target and source room inventories. This enables:

• Inventory reconciliation — Match your own room inventory against supplier rooms
• Multi-supplier mapping — Map rooms from one supplier to another
• Feature extraction — Understand the parsed semantic breakdown of each room name

Room mapping must be enabled for your partner account. Contact Evocative to request access. The only supported language is English.

Endpoints¶

POST /api/mapping/rooms¶

Map rooms for a single hotel. Provide your target rooms (reference inventory) and source rooms (to be matched), and the API returns which source rooms match which targets.

Authentication: Required (X-Api-Key)

Authorization: Requires room mapping enabled for partner

Request Body:

When you leave targetRooms empty, the API fetches the room inventory for hotelId from the Evocative content catalog and uses it as the matching target. Auto-populated target rooms carry id (the Evocative room identifier) and description; supplierCode and roomCode are omitted. If the hotel is unknown or has no room content, the request proceeds with an empty target set (all your source rooms will come back under unmappedSourceRooms).

Room Object (used in both targetRooms and sourceRooms):

Example Request

curl -X POST "<BASE_URL>/api/mapping/rooms" \
     -H "X-Api-Key: YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "hotelId": "12345",
       "hotelName": "Grand Hotel Berlin",
       "country": "DE",
       "targetRooms": [
         {
           "supplierCode": "INT",
           "id": "room-1",
           "description": "Deluxe Double Room with City View",
           "roomCode": "DDR-CV",
           "price": 150.00
         },
         {
           "supplierCode": "INT",
           "id": "room-2",
           "description": "Standard Twin Room",
           "roomCode": "STR",
           "price": 120.00
         }
       ],
       "sourceRooms": [
         {
           "supplierCode": "EAN",
           "id": "ext-1",
           "description": "Dlx Dbl City View",
           "roomCode": "EAN-DDR"
         },
         {
           "supplierCode": "EAN",
           "id": "ext-2",
           "description": "Twin Standard",
           "roomCode": "EAN-STR"
         },
         {
           "supplierCode": "EAN",
           "id": "ext-3",
           "description": "Presidential Suite",
           "roomCode": "EAN-PS"
         }
       ]
     }'

Example Request — auto-populated target rooms

Omit targetRooms to have the API fetch the hotel's room inventory automatically:

curl -X POST "<BASE_URL>/api/mapping/rooms" \
     -H "X-Api-Key: YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "hotelId": "R:12345",
       "hotelName": "Grand Hotel Berlin",
       "country": "DE",
       "sourceRooms": [
         {
           "supplierCode": "EAN",
           "id": "ext-1",
           "description": "Dlx Dbl City View",
           "roomCode": "EAN-DDR"
         }
       ]
     }'

Responses:

• 200 OK: Mapping results returned successfully
• 401 Unauthorized: Invalid/missing API key
• 403 Forbidden: Room mapping not enabled for this partner
• 429 Too Many Requests: Rate limit exceeded
• 502 Bad Gateway: Mapping service unavailable

Response Schema (200 OK):

Mapped Room Object:

Example Response

{
  "hotelId": "12345",
  "mappedRooms": [
    {
      "targetRoom": {
        "supplierCode": "INT",
        "id": "room-1",
        "description": "Deluxe Double Room with City View",
        "roomCode": "DDR-CV",
        "price": 150.00
      },
      "sourceRooms": [
        {
          "supplierCode": "EAN",
          "id": "ext-1",
          "description": "Dlx Dbl City View",
          "roomCode": "EAN-DDR",
          "price": null
        }
      ]
    },
    {
      "targetRoom": {
        "supplierCode": "INT",
        "id": "room-2",
        "description": "Standard Twin Room",
        "roomCode": "STR",
        "price": 120.00
      },
      "sourceRooms": [
        {
          "supplierCode": "EAN",
          "id": "ext-2",
          "description": "Twin Standard",
          "roomCode": "EAN-STR",
          "price": null
        }
      ]
    }
  ],
  "unmappedSourceRooms": [
    {
      "supplierCode": "EAN",
      "id": "ext-3",
      "description": "Presidential Suite",
      "roomCode": "EAN-PS",
      "price": null
    }
  ]
}

POST /api/mapping/rooms/batch¶

Map rooms for multiple hotels in a single request. Each item follows the same format as the single-hotel endpoint.

Authentication: Required (X-Api-Key)

Authorization: Requires room mapping enabled for partner

Request Body:

Example Request

curl -X POST "<BASE_URL>/api/mapping/rooms/batch" \
     -H "X-Api-Key: YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "items": [
         {
           "hotelId": "12345",
           "hotelName": "Grand Hotel Berlin",
           "country": "DE",
           "targetRooms": [...],
           "sourceRooms": [...]
         },
         {
           "hotelId": "67890",
           "hotelName": "Seaside Resort Bali",
           "country": "ID",
           "targetRooms": [...],
           "sourceRooms": [...]
         }
       ]
     }'

Responses:

• 200 OK: Batch mapping results returned
• 401 Unauthorized: Invalid/missing API key
• 403 Forbidden: Room mapping not enabled for this partner
• 429 Too Many Requests: Rate limit exceeded
• 502 Bad Gateway: Mapping service unavailable

Response Schema (200 OK):

Each result follows the same schema as the single-hotel response.

Example Response

{
  "results": [
    {
      "hotelId": "12345",
      "mappedRooms": [
        ...
      ],
      "unmappedSourceRooms": [
        ...
      ]
    },
    {
      "hotelId": "67890",
      "mappedRooms": [
        ...
      ],
      "unmappedSourceRooms": [
        ...
      ]
    }
  ]
}

Best Practices¶

1. Provide descriptive room names — The more detail in the description field, the better the matching accuracy. Include bed types, views, and room categories when available.

2. Include country — The country field enables locale-aware matching and conditional rules that vary by region.

3. Use batch for bulk operations — When mapping rooms for multiple hotels, use the batch endpoint to reduce HTTP overhead.

4. Handle unmapped rooms gracefully — Some source rooms may not match any target. Display these separately in your UI or apply fallback logic.

5. Skip targetRooms when you don't maintain your own inventory — If you only want to map supplier rooms against Evocative's room catalog for a hotel, omit targetRooms and the API will fill it in from our inventory for the given hotelId. Provide targetRooms explicitly when you want to match against your own reference list.