---
updatedAt: 2026-07-15T12:53:34.000Z
agentTools:
  projectIndex: https://docs.cupid.travel/llms.txt
---

# Group similar rooms from multiple suppliers for a property

The Room Map API consolidates and groups similar rooms from multiple suppliers for a given property. It analyzes room information and groups rooms with similar characteristics together.

  **Key Parameters**

- `propertyName` and `propertyID`: Used to identify the property for room mapping
- `parameters.createGroups`: Must be set to `true` to enable room grouping
- `parameters.outputAggregation`: Specifies which attributes to use for grouping
- `supplierList`: List of suppliers - for each supplier you can have multiple rooms

 ### Recommended Output Aggregation Parameters

For optimal grouping results, include at least these parameters:

- roomClass
- roomType
- bedType
- roomView 

 ### Key Features

1. **Room Grouping**
    - Rooms with similar characteristics are grouped automatically
    - Same room can appear in multiple groups
    - Each group has a unique `groupCode`
    - Empty room names appear in `unmapped` array
2. **Debug Mode**
    - Set `debug: true` to see all extracted entities
    - Unextracted values show as "none" in debug mode
3. **Language Support**
    - Currently only English is supported

### Best Practices

1. Provide descriptive room names with key characteristics
2. Include known room attributes as optional fields to improve grouping accuracy
3. Use debug mode during integration
4. Store groupCode if you need to reference specific groups
5. Always include the recommended outputAggregation parameters for optimal results

### Note on Room Prices

If you include price information, please ensure that all prices for a particular hotel request are in the same currency. The API does not perform currency conversion or management.

To experiment with this API, use the sandbox key: 
```e2R4t6Y8u0i3O5p7A9s1D3f5G7h9J2k4```

# OpenAPI definition

````json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Cupid Room Map API",
    "description": "The **Cupid Room Map API** is designed to synchronize and connect room inventories from different suppliers for a specific hotel. This functionality enhances the efficiency of managing hotel room portfolios and enables the straightforward comparison of room features among multiple vendors. This is an aggregation based solution",
    "version": "3.0"
  },
  "servers": [
    {
      "url": "https://room-match.cupid.travel"
    }
  ],
  "security": [
    {
      "apikeyAuth": []
    }
  ],
  "paths": {
    "/room_map": {
      "post": {
        "tags": [
          "Room Map"
        ],
        "summary": "Group similar rooms from multiple suppliers for a property",
        "description": "The Room Map API consolidates and groups similar rooms from multiple suppliers for a given property. It analyzes room information and groups rooms with similar characteristics together.\n\n  **Key Parameters**\n\n- `propertyName` and `propertyID`: Used to identify the property for room mapping\n- `parameters.createGroups`: Must be set to `true` to enable room grouping\n- `parameters.outputAggregation`: Specifies which attributes to use for grouping\n- `supplierList`: List of suppliers - for each supplier you can have multiple rooms\n\n ### Recommended Output Aggregation Parameters\n\nFor optimal grouping results, include at least these parameters:\n\n- roomClass\n- roomType\n- bedType\n- roomView \n\n ### Key Features\n\n1. **Room Grouping**\n    - Rooms with similar characteristics are grouped automatically\n    - Same room can appear in multiple groups\n    - Each group has a unique `groupCode`\n    - Empty room names appear in `unmapped` array\n2. **Debug Mode**\n    - Set `debug: true` to see all extracted entities\n    - Unextracted values show as \"none\" in debug mode\n3. **Language Support**\n    - Currently only English is supported\n\n### Best Practices\n\n1. Provide descriptive room names with key characteristics\n2. Include known room attributes as optional fields to improve grouping accuracy\n3. Use debug mode during integration\n4. Store groupCode if you need to reference specific groups\n5. Always include the recommended outputAggregation parameters for optimal results\n\n### Note on Room Prices\n\nIf you include price information, please ensure that all prices for a particular hotel request are in the same currency. The API does not perform currency conversion or management.\n\nTo experiment with this API, use the sandbox key: \n```e2R4t6Y8u0i3O5p7A9s1D3f5G7h9J2k4```",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomTypeMapping"
              },
              "examples": {
                "basic example": {
                  "value": {
                    "debug": false,
                    "parameters": {
                      "outputAggregation": [
                        "roomType",
                        "roomClass",
                        "bedType",
                        "roomView",
                        "roomOccupancy",
                        "roomAmenities",
                        "boardType",
                        "cancellationPolicy",
                        "roomSmoking",
                        "roomCount",
                        "nerRoomName",
                        "roomLocation",
                        "roomAccessibility"
                      ]
                    },
                    "propertyName": "Hyatt",
                    "propertyId": "123455",
                    "supplierList": [
                      {
                        "supplierName": "supplier A",
                        "supplierId": "121",
                        "supplierRooms": [
                          {
                            "roomId": "24501",
                            "roomName": "Small Room King bed"
                          }
                        ]
                      },
                      {
                        "supplierName": "supplier B",
                        "supplierId": "456",
                        "supplierRooms": [
                          {
                            "roomId": "24502",
                            "roomName": "Small Room King bed"
                          }
                        ]
                      }
                    ]
                  }
                },
                "with optional fields": {
                  "value": {
                    "debug": false,
                    "parameters": {
                      "outputAggregation": [
                        "roomType",
                        "roomClass",
                        "bedType",
                        "roomView",
                        "roomOccupancy",
                        "roomAmenities",
                        "boardType",
                        "cancellationPolicy",
                        "roomSmoking",
                        "roomCount",
                        "nerRoomName",
                        "roomLocation"
                      ]
                    },
                    "propertyName": "Hyatt",
                    "propertyId": "123455",
                    "supplierList": [
                      {
                        "supplierName": "supplier A",
                        "supplierId": "121",
                        "supplierRooms": [
                          {
                            "roomId": "24501",
                            "roomName": "Small Room King bed",
                            "bedType": "king",
                            "roomType": "standard",
                            "roomClass": "small",
                            "roomOccupancy": "2"
                          },
                          {
                            "roomId": "24503",
                            "roomName": "Deluxe Ocean View Room Queen Bed",
                            "bedType": "queen",
                            "roomView": "ocean",
                            "roomClass": "deluxe",
                            "roomAmenities": "wifi,tv,minibar"
                          }
                        ]
                      },
                      {
                        "supplierName": "supplier B",
                        "supplierId": "456",
                        "supplierRooms": [
                          {
                            "roomId": "24502",
                            "roomName": "Small Room King bed",
                            "roomType": "standard",
                            "boardType": "room-only",
                            "cancellationPolicy": "free-cancellation",
                            "roomCount": "1"
                          },
                          {
                            "roomId": "24504",
                            "roomName": "Superior Twin Room City View Non-Smoking",
                            "bedType": "twin",
                            "roomView": "city",
                            "roomClass": "superior",
                            "roomSmoking": "no",
                            "roomOccupancy": "2"
                          }
                        ]
                      }
                    ]
                  }
                },
                "abbreviations": {
                  "value": {
                    "debug": false,
                    "parameters": {
                      "outputAggregation": [
                        "roomType",
                        "roomClass",
                        "bedType",
                        "roomView",
                        "boardType",
                        "roomOccupancy",
                        "roomAmenities",
                        "roomSmoking",
                        "cancellationPolicy",
                        "roomCount",
                        "roomView",
                        "roomAccessibility"
                      ]
                    },
                    "propertyName": "Hyatt Grand Central New York",
                    "propertyId": "123455",
                    "supplierList": [
                      {
                        "supplierName": "Bcom",
                        "supplierId": "121",
                        "supplierRooms": [
                          {
                            "roomId": "1",
                            "roomName": "SDBL R/O"
                          },
                          {
                            "roomId": "1",
                            "roomName": "2 Queens Non-Smoking Mountain View"
                          },
                          {
                            "roomId": "1212",
                            "roomName": "Semi Double Room only"
                          },
                          {
                            "roomId": "11221",
                            "roomName": "Royal Superior King Room w/b"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Server": {
                "schema": {
                  "type": "string",
                  "example": "nginx/1.18.0 (Ubuntu)"
                }
              },
              "Date": {
                "schema": {
                  "type": "string",
                  "example": "Fri, 28 Jul 2023 08:46:27 GMT"
                }
              },
              "Content-Type": {
                "schema": {
                  "type": "string",
                  "example": "application/json"
                }
              },
              "Content-Length": {
                "schema": {
                  "type": "integer",
                  "example": "1614"
                }
              },
              "Connection": {
                "schema": {
                  "type": "string",
                  "example": "keep-alive"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoomMappingResponse"
                },
                "examples": {
                  "Mapped Rooms with single group": {
                    "value": {
                      "aggregation": [
                        {
                          "groupCode": "22619bbb",
                          "groupName": "Small Room with One King Bed",
                          "groupRooms": [
                            {
                              "bedType": "one king bed",
                              "boardType": "none",
                              "cancellationPolicy": "none",
                              "cleanDescription": "small room king bed",
                              "nerRoomName": "none",
                              "roomAccessibility": "none",
                              "roomAmenities": "none",
                              "roomClass": "small",
                              "roomCount": "none",
                              "roomDescription": "Small Room King bed",
                              "roomIds": "24501",
                              "roomLocation": "none",
                              "roomOccupancy": "none",
                              "roomSmoking": "none",
                              "roomType": "room",
                              "roomView": "none",
                              "supplierId": "121",
                              "supplierName": "supplier A"
                            },
                            {
                              "bedType": "one king bed",
                              "boardType": "none",
                              "cancellationPolicy": "none",
                              "cleanDescription": "small room king bed",
                              "nerRoomName": "none",
                              "roomAccessibility": "none",
                              "roomAmenities": "none",
                              "roomClass": "small",
                              "roomCount": "none",
                              "roomDescription": "Small Room King bed",
                              "roomIds": "24502",
                              "roomLocation": "none",
                              "roomOccupancy": "none",
                              "roomSmoking": "none",
                              "roomType": "room",
                              "roomView": "none",
                              "supplierId": "456",
                              "supplierName": "supplier B"
                            }
                          ],
                          "vernacName": "Small Room With One King Bed"
                        }
                      ],
                      "property": "Hyatt",
                      "propertyId": "123455",
                      "unmapped": []
                    }
                  },
                  "Mapped Rooms With Multiple Groups": {
                    "value": {
                      "aggregation": [
                        {
                          "groupCode": "5d857ff0",
                          "groupName": "Semi Double Room with Room Only",
                          "groupRooms": [
                            {
                              "bedType": "none",
                              "boardType": "room only",
                              "cancellationPolicy": "none",
                              "cleanDescription": "semi double r.o.",
                              "nerRoomName": "none",
                              "roomAccessibility": "none",
                              "roomAmenities": "none",
                              "roomClass": "none",
                              "roomCount": "none",
                              "roomDescription": "SDBL R/O",
                              "roomIds": "1",
                              "roomLocation": "none",
                              "roomOccupancy": "none",
                              "roomSmoking": "none",
                              "roomType": "semi double room",
                              "roomView": "none",
                              "supplierId": "121",
                              "supplierName": "Bcom"
                            },
                            {
                              "bedType": "none",
                              "boardType": "room only",
                              "cancellationPolicy": "none",
                              "cleanDescription": "semi double r.o.",
                              "nerRoomName": "none",
                              "roomAccessibility": "none",
                              "roomAmenities": "none",
                              "roomClass": "none",
                              "roomCount": "none",
                              "roomDescription": "Semi Double Room only",
                              "roomIds": "1212",
                              "roomLocation": "none",
                              "roomOccupancy": "none",
                              "roomSmoking": "none",
                              "roomType": "semi double room",
                              "roomView": "none",
                              "supplierId": "121",
                              "supplierName": "Bcom"
                            }
                          ],
                          "vernacName": "Semi Double Room With Room Only"
                        },
                        {
                          "groupCode": "2ce5cf03",
                          "groupName": "Room with Two Queen Beds and Mountain View (Non Smoking)",
                          "groupRooms": [
                            {
                              "bedType": "two queen beds",
                              "boardType": "none",
                              "cancellationPolicy": "none",
                              "cleanDescription": "2 queens non smoking mountain view",
                              "nerRoomName": "none",
                              "roomAccessibility": "none",
                              "roomAmenities": "none",
                              "roomClass": "none",
                              "roomCount": "none",
                              "roomDescription": "2 Queens Non-Smoking Mountain View",
                              "roomIds": "1",
                              "roomLocation": "none",
                              "roomOccupancy": "none",
                              "roomSmoking": "non smoking",
                              "roomType": "room",
                              "roomView": "mountain view",
                              "supplierId": "121",
                              "supplierName": "Bcom"
                            }
                          ],
                          "vernacName": "Room With Two Queen Beds And Mountain View (Non Smoking)"
                        },
                        {
                          "groupCode": "7389d625",
                          "groupName": "Superior King Room with Breakfast",
                          "groupRooms": [
                            {
                              "bedType": "none",
                              "boardType": "breakfast",
                              "cancellationPolicy": "none",
                              "cleanDescription": "royal superior king room breakfast",
                              "nerRoomName": "none",
                              "roomAccessibility": "none",
                              "roomAmenities": "none",
                              "roomClass": "superior",
                              "roomCount": "none",
                              "roomDescription": "Royal Superior King Room w/b",
                              "roomIds": "11221",
                              "roomLocation": "none",
                              "roomOccupancy": "none",
                              "roomSmoking": "none",
                              "roomType": "king room",
                              "roomView": "none",
                              "supplierId": "121",
                              "supplierName": "Bcom"
                            }
                          ],
                          "vernacName": "Superior King Room With Breakfast"
                        }
                      ],
                      "property": "Hyatt Grand Central New York",
                      "propertyId": "123455",
                      "unmapped": []
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "headers": {
              "Date": {
                "schema": {
                  "type": "string",
                  "example": "Fri, 28 Jul 2023 08:46:27 GMT"
                }
              },
              "Content-Type": {
                "schema": {
                  "type": "string",
                  "example": "application/json"
                }
              },
              "Content-Length": {
                "schema": {
                  "type": "integer",
                  "example": 1614
                }
              },
              "Connection": {
                "schema": {
                  "type": "string",
                  "example": "keep-alive"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "wrong parameters": {
                    "value": {
                      "error": "Invalid Request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "headers": {
              "Server": {
                "schema": {
                  "type": "string",
                  "example": "nginx/1.18.0 (Ubuntu)"
                }
              },
              "Date": {
                "schema": {
                  "type": "string",
                  "example": "Fri, 28 Jul 2023 08:46:27 GMT"
                }
              },
              "Content-Type": {
                "schema": {
                  "type": "string",
                  "example": "application/json"
                }
              },
              "Content-Length": {
                "schema": {
                  "type": "integer",
                  "example": 1614
                }
              },
              "Connection": {
                "schema": {
                  "type": "string",
                  "example": "keep-alive"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "Wrong API key": {
                    "value": {
                      "error": "Invalid API key"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apikeyAuth": {
        "name": "X-API-Key",
        "type": "apiKey",
        "in": "header"
      }
    },
    "schemas": {
      "RoomTypeMapping": {
        "type": "object",
        "required": [
          "parameters",
          "propertyName",
          "propertyId",
          "supplierList"
        ],
        "properties": {
          "parameters": {
            "$ref": "#/components/schemas/Parameters"
          },
          "propertyName": {
            "type": "string",
            "example": "hyatt",
            "description": "Name of the property"
          },
          "propertyId": {
            "type": "string",
            "example": "123455",
            "description": "Unique Id of the property"
          },
          "supplierList": {
            "type": "array",
            "xml": {
              "name": "supplierList",
              "wrapped": true
            },
            "items": {
              "$ref": "#/components/schemas/Suppliers"
            }
          },
          "debug": {
            "type": "boolean",
            "example": false,
            "description": "Debug mode - True/False"
          }
        }
      },
      "Suppliers": {
        "type": "object",
        "required": [
          "supplierName",
          "supplierId",
          "supplierRooms"
        ],
        "properties": {
          "supplierName": {
            "type": "string",
            "example": "supplier A",
            "description": "Name of the supplier"
          },
          "supplierId": {
            "type": "string",
            "example": "121",
            "description": "Unique ID for the supplier"
          },
          "supplierRooms": {
            "type": "array",
            "xml": {
              "name": "roomList",
              "wrapped": true
            },
            "items": {
              "$ref": "#/components/schemas/Rooms"
            }
          }
        }
      },
      "Rooms": {
        "type": "object",
        "required": [
          "roomId",
          "roomName"
        ],
        "properties": {
          "roomId": {
            "type": "string",
            "example": "24501",
            "description": "Unique ID for the room"
          },
          "roomName": {
            "type": "string",
            "example": "Superior Room King bed",
            "description": "Description of the room"
          },
          "roomType": {
            "type": "string",
            "example": "Superior Room",
            "description": "Type of the room"
          },
          "boardType": {
            "type": "string",
            "example": "room only",
            "description": "Board type - room only, full board, half board, B&B, breakfast"
          },
          "cancellationPolicy": {
            "type": "string",
            "example": "free-cancellation",
            "description": "Cancellation policy - free-cancellation, non-refundable"
          },
          "roomCount": {
            "type": "integer",
            "example": 5,
            "description": "Number of rooms available"
          },
          "bedType": {
            "type": "string",
            "example": "king",
            "description": "Type of bed - single, twin, double, queen or king"
          },
          "roomView": {
            "type": "string",
            "example": "sea",
            "description": "View included in the room - sea, ocean, mountain, city, garden etc"
          },
          "roomOccupancy": {
            "type": "string",
            "example": "2",
            "description": "Number of people that can be accommodated in the room"
          },
          "roomAmenities": {
            "type": "string",
            "example": "free wifi, tv, minibar",
            "description": "Amenities included in the room separated by comma"
          },
          "roomClass": {
            "type": "string",
            "example": "deluxe",
            "description": "Class of the room - standard, deluxe, superior, suite"
          },
          "roomSmoking": {
            "type": "string",
            "example": "smoking",
            "description": "Smoking preference - smoking, non-smoking"
          },
          "roomFloor": {
            "type": "string",
            "example": "floor",
            "description": "We detect startFloor & endFloor from room name"
          },
          "areaRoom": {
            "type": "string",
            "example": "30 sqm",
            "description": "Area of the room"
          },
          "price": {
            "type": "number",
            "format": "float",
            "example": 259.99,
            "description": "The price of the room (optional)"
          }
        }
      },
      "Parameters": {
        "type": "object",
        "properties": {
          "outputAggregation": {
            "$ref": "#/components/schemas/OutputAggregation"
          }
        }
      },
      "OutputAggregation": {
        "type": "array",
        "xml": {
          "name": "outputAggregation",
          "wrapped": true
        },
        "items": {
          "$ref": "#/components/schemas/Aggregation"
        }
      },
      "Aggregation": {
        "type": "string",
        "example": "roomType",
        "description": "Aggregation types - roomType, roomClass, roomView, roomAccessibility, cancellationPolicy etc",
        "enum": [
          "roomType",
          "roomClass",
          "bedType",
          "roomView",
          "roomOccupancy",
          "roomAmenities",
          "boardType",
          "cancellationPolicy",
          "roomSmoking",
          "roomCount",
          "nerRoomName",
          "roomLocation",
          "roomAccessibility",
          "roomFloor",
          "areaRoom"
        ]
      },
      "RoomMappingResponse": {
        "type": "object",
        "properties": {
          "property": {
            "type": "string",
            "description": "The name of the property."
          },
          "propertyId": {
            "type": "string",
            "description": "A unique identifier for the property."
          },
          "aggregation": {
            "type": "array",
            "description": "List of grouped room mappings based on room type and supplier.",
            "items": {
              "$ref": "#/components/schemas/RoomGroup"
            }
          },
          "unmapped": {
            "type": "array",
            "description": "List of rooms that could not be mapped to any group.",
            "items": {
              "$ref": "#/components/schemas/UnmappedRoom"
            }
          }
        },
        "required": [
          "property",
          "propertyId",
          "aggregation"
        ]
      },
      "RoomGroup": {
        "type": "object",
        "properties": {
          "groupName": {
            "type": "string",
            "description": "The standardized name of the room group."
          },
          "vernacName": {
            "type": "string",
            "description": "The supplier-provided name of the room group."
          },
          "groupCode": {
            "type": "string",
            "description": "A unique code for identifying the room group."
          },
          "groupRooms": {
            "type": "array",
            "description": "List of rooms within this group, provided by various suppliers.",
            "items": {
              "$ref": "#/components/schemas/GroupRoom"
            }
          }
        },
        "required": [
          "groupName",
          "groupCode",
          "groupRooms"
        ]
      },
      "GroupRoom": {
        "type": "object",
        "properties": {
          "supplierName": {
            "type": "string",
            "description": "The name of the supplier providing this room."
          },
          "supplierId": {
            "type": "string",
            "description": "A unique identifier for the supplier."
          },
          "roomIds": {
            "type": "string",
            "description": "The supplier-provided unique identifier(s) for the room."
          },
          "roomDescription": {
            "type": "string",
            "description": "The description of the room provided by the supplier."
          },
          "cleanDescription": {
            "type": "string",
            "description": "A cleaned, standardized version of the room description."
          },
          "bedType": {
            "type": "string",
            "description": "Details about the bed type in the room. If unknown, 'none'."
          },
          "roomLocation": {
            "type": "string",
            "description": "The location of the room within the property. If unknown, 'none'."
          },
          "roomView": {
            "type": "string",
            "description": "The view from the room, if available. If unknown, 'none'."
          },
          "roomClass": {
            "type": "string",
            "description": "The classification of the room (e.g., deluxe, standard)."
          },
          "roomCount": {
            "type": "string",
            "description": "Information about the room count (e.g., one bedroom, two bedroom). If unknown, 'none'."
          },
          "roomType": {
            "type": "string",
            "description": "The type of the room (e.g., studio, apartment)."
          },
          "roomOccupancy": {
            "type": "string",
            "description": "Details about room occupancy. If unknown, 'none'."
          },
          "boardType": {
            "type": "string",
            "description": "The type of board (e.g., bed and breakfast, all-inclusive). If unknown, 'none'."
          },
          "nerRoomName": {
            "type": "string",
            "description": "A standardized name derived using Named Entity Recognition (NER). If unknown, 'none'."
          },
          "roomFloor": {
            "type": "string",
            "description": "It is used for room floor detection from the name."
          },
          "startFloor": {
            "type": "string",
            "description": "If room floor is detected, we get a the detected start floor here"
          },
          "endFloor": {
            "type": "string",
            "description": "If room floor is detected, we get a the detected end floor here"
          },
          "roomArea": {
            "type": "string",
            "description": "The area of the room. If unknown, 'none'."
          },
          "price": {
            "type": "number",
            "format": "float",
            "example": 259.99,
            "description": "The price of the room (optional)"
          }
        },
        "required": [
          "supplierName",
          "supplierId",
          "roomIds"
        ]
      },
      "UnmappedRoom": {
        "type": "object",
        "properties": {
          "supplierName": {
            "type": "string",
            "description": "The name of the supplier providing the unmapped room."
          },
          "supplierId": {
            "type": "string",
            "description": "A unique identifier for the supplier."
          },
          "roomIds": {
            "type": "string",
            "description": "The supplier-provided unique identifier(s) for the unmapped room."
          },
          "roomDescription": {
            "type": "string",
            "description": "The description of the room provided by the supplier, if available."
          },
          "price": {
            "type": "number",
            "format": "float",
            "example": 259.99,
            "description": "The price of the room (optional)"
          }
        },
        "required": [
          "supplierName",
          "supplierId",
          "roomIds"
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  }
}
````