Hotel name search

Find a hotel by the name a person types, and get its FX-Port hotel id to use in search_advanced, get_rates and get_hotel_info. The search compares your text with hotel names over every hotel FX-Port knows. It does not price anything and does not need dates.

Permission: Read

Two forms, one search

Use the form that fits your client. They run the same search and return the same answer.

curl 'https://api.fx-port.com/api/v1/hotels/name-search?query=Sofitel%20Algiers&limit=3&min_score=60' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"

curl https://api.fx-port.com/api/v1/hotels/search-by-name \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "Sofitel Algiers",
  "limit": 3,
  "min_score": 60,
  "include_location": true,
  "include_details": false
}'

Response

A real answer of the sandbox:

{
  "environment": "sandbox",
  "query": "Sofitel Algiers",
  "results_count": 2,
  "search_time": "0.060s",
  "hotels": [
    {
      "id": "sofitel_algiers_hamma_garden",
      "name": "Sofitel Algiers Hamma Garden",
      "match_score": 83.39,
      "match_type": "partial",
      "address": "172, rue Hassiba Benbouali, Algiers",
      "city": "Algiers",
      "country_code": "DZ",
      "postal_code": "16014"
    },
    {
      "id": "algiers_hotel",
      "name": "Algiers",
      "match_score": 76.67,
      "match_type": "partial",
      "address": "2845 South Las Vegas Boulevard Las Vegas, South Las Vegas Boulevard, Las Vegas",
      "city": "Las Vegas",
      "country_code": "US",
      "postal_code": "89109"
    }
  ]
}

Reading the score

The score says how close the name is to your text. It does not say that it is the hotel you mean. What the search returned in our probes (sandbox, 2026-11-01):

What to do with it:

• Treat a score of 80 or more as a likely match and anything below as a suggestion. In our probes, every hit from 80 up was the hotel we typed, and nearly every hit below was another hotel (Sofitel Algiers also finds a hotel called Algiers in Las Vegas at 76.67). Raise min_score to 80 to hide the weak ones, or lower it to 50 when you would rather show too much.
• Typos are tolerated only when the rest of the text is long enough to carry the match. A typo in a short text finds another hotel.
• Do not book the first hit without showing it. Show the name, the city and the country.

Details of each hit

With include_details=true each hit is the whole stored document of the hotel (snake_case, with images_ext, policy_struct and every room type) plus match_score and match_type, and no city or country_code at the top (they are in region). It is large: 48 KB for one hotel in our measurement (26 KB for the smallest we measured). It is not the shape of any other call, so a client that wants the hotel page should take the id of the hit and call get_hotel_info for that one hotel. For a result list use the summary, or the compact card of Mini and full hotel data.

Good practice

• Debounce a typeahead at about 300 ms and cancel the request in flight. The search engine runs a few searches at a time, and when it is busy the call answers 503 with service_busy and a Retry-After of 2 seconds: wait that long and ask again.
• The ids are the same in the sandbox and on live, but a hit is not necessarily bookable in the sandbox: see Sandbox testing. The test hotel test_hotel (Test Hotel (Do Not Book)) is found by name; test_hotel_do_not_book is not, so use its id as it is written there.
• The keys are snake_case and have no camelCase twin.

Errors

A search that finds nothing is not an error: the answer is 200 with results_count: 0 and an empty hotels.

Related