Search and Filter Hotel Mapping Results

After a mapping job reaches COMPLETED status, you can search through the individual hotel match results. The search endpoint lets you filter by hotel name, location, your own partner IDs, the matched reference hotel, or specific supplier IDs. Results are paginated and include match confidence scores, match methods, and supplier external IDs.

Search endpoint

POST /api/v1/mapping/{mappingJobId}/results/search

All filters in the request body are optional. Omit any filter you don’t need — null values are ignored.

Request fields

Field	Type	Description
`hotelName`	string	Partial hotel name (contains, case-insensitive)
`city`	string	City name (exact match, case-insensitive)
`country`	string	Country (exact match, case-insensitive)
`partnerHotelId`	string	Your internal hotel ID (exact match)
`matchedReferenceHotelId`	string	Reference database hotel ID (exact match)
`supplierIds`	array of UUIDs	Limit results to hotels that have external IDs for these suppliers
`page`	integer	Page number, 0-indexed (default: `0`)
`size`	integer	Results per page (default: `20`)

Run a search

Send a POST request with your desired filters. This example finds all hotels named “Hilton” in Paris that have Expedia or Booking.com external IDs:

curl -X POST \
  https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/results/search \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hotelName": "Hilton",
    "city": "Paris",
    "supplierIds": [
      "11111111-aaaa-bbbb-cccc-dddddddddddd",
      "22222222-aaaa-bbbb-cccc-dddddddddddd"
    ],
    "page": 0,
    "size": 20
  }'

Read the response

The response wraps results in a paginated envelope:

{
  "results": [
    {
      "id": "99887766-5544-3322-1100-aabbccddeeff",
      "partnerHotelId": "hotel-001",
      "partnerHotelName": "Hilton Paris Downtown",
      "partnerHotelAddress": "123 Rue de Rivoli",
      "partnerHotelCity": "Paris",
      "partnerHotelCountry": "France",
      "matchedReferenceHotelId": "ref-456",
      "matchedReferenceHotelName": "Hilton Paris Opera",
      "matchConfidence": 95.50,
      "matchMethod": "standard",
      "supplierExternalIds": {
        "11111111-aaaa-bbbb-cccc-dddddddddddd": "EXP-789012",
        "22222222-aaaa-bbbb-cccc-dddddddddddd": "BK-345678"
      },
      "createdAt": "2026-04-25T10:07:42Z",
      "updatedAt": "2026-04-25T10:07:42Z"
    }
  ],
  "totalResults": 43,
  "page": 0,
  "size": 20,
  "totalPages": 3
}

Paginate through results

Use page and size to walk through large result sets. Pages are 0-indexed.

curl -X POST \
  https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/results/search \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "size": 20
  }'

Continue incrementing page until page >= totalPages - 1.

Understanding match fields

`matchMethod`

The matchMethod field tells you how a hotel was matched:

Value	Meaning
`"standard"`	Matched by the fuzzy pipeline (STANDARD or HYBRID fallback phase)
`"id_to_id"`	Matched by supplier ID (ID_TO_ID or HYBRID first phase)
`null`	No match found

Hotels with matchMethod: null have a null matchedReferenceHotelId and matchedReferenceHotelName.

`matchConfidence`

A decimal score from 0 to 100 representing how confident the fuzzy pipeline is in the match. A score of 100 means an exact match. ID_TO_ID matches do not produce a confidence score.

`supplierExternalIds`

A map of supplier UUID to that supplier’s external hotel ID. Only suppliers with a known external ID for the matched reference hotel are included. If you filtered by supplierIds in the request, the response only contains results where at least one of those supplier IDs has an entry in this map.

"supplierExternalIds": {
  "11111111-aaaa-bbbb-cccc-dddddddddddd": "EXP-789012",
  "22222222-aaaa-bbbb-cccc-dddddddddddd": "BK-345678"
}

Use these IDs to cross-reference the matched hotel in your own supplier systems.

Filter reference

By hotel name
By location
By partner ID
By reference hotel
By supplier

hotelName is a partial, case-insensitive search. It matches any hotel whose name contains the string.

{ "hotelName": "grand" }

This returns results like “The Grand Budapest”, “Grand Hyatt”, and “Le Grand Hotel”.

city and country are exact matches (case-insensitive). Combine them to narrow results to a specific city.

{ "city": "Rome", "country": "Italy" }

partnerHotelId is an exact match against your own internal hotel identifier.

{ "partnerHotelId": "hotel-001" }

matchedReferenceHotelId is an exact match against the reference database hotel ID. Use this to find all your partner hotels that mapped to the same reference hotel.

{ "matchedReferenceHotelId": "ref-456" }

supplierIds filters to results that have external IDs for at least one of the listed suppliers. Supply an array of supplier UUIDs.

{
  "supplierIds": [
    "11111111-aaaa-bbbb-cccc-dddddddddddd"
  ]
}

Unmatched hotels (no matchedReferenceHotelId) are always excluded when filtering by supplier, since they have no supplier external IDs.

Error responses

HTTP status	Cause
`400 Bad Request`	Negative `page` or `size` value
`401 Unauthorized`	Missing or invalid token, or the mapping job belongs to a different organization
`404 Not Found`	Mapping job ID does not exist

​Search endpoint

​Request fields

​Understanding match fields

​matchMethod

​matchConfidence

​supplierExternalIds

​Filter reference

​Error responses