Hotels · Search

Find a hotel by name

Fuzzy search over the names of every hotel FX-Port knows.

GET/api/v1/hotels/name-search

Requires an API key with Read permission; a Read+Write key works too.

It tolerates typos, partial names and accents. Each hit carries the FX-Port hotel id to send as hotel_id to get_rates and search_advanced. Hits with a match_score below about 80 are often other hotels (a search for Sofitel Algiers also finds a hotel called Algiers in Las Vegas): show the score or keep the best few. The ids are the same in the sandbox and on live, and a hit is not necessarily bookable in the sandbox. POST /hotels/search-by-name takes the same fields as a JSON body.

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

Response200

{
  "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"
    }
  ]
}

Request

Query parameters

querystringrequired

The hotel name or a part of it, 2 to 100 characters.

limitinteger

Most hits to return, 1 to 100. A number outside that range, or text that is not a number, answers 400 invalid_limit.

Between 1 and 100. Default 10.

min_scorenumber

Lowest match score to return, 0 to 100. A number outside that range, or text that is not a number, answers 400 invalid_min_score.

Between 0 and 100. Default 60.

include_locationboolean

Add the address, city, country code and postal code to each hit.

Default true.

include_detailsboolean

Return the whole cached hotel document of each hit (about 26 KB each) instead of the summary.

Default false.

Response

200The hotels that match, best match first.

environmentstring

The environment of the key that made the call: sandbox for fxp_test_ keys, live for fxp_live_ keys. Present in every JSON body.

One of sandbox, live.

request_idstring

The id of the request, also in the X-Request-Id header.

warningsarray of object

Present only when the request used a previous spelling of a field or something the endpoint ignored.

ShowHide 5 attributes

codestring

What the warning is about.

One of deprecated_field, ignored_field, coerced_value, deprecated_value, deprecated_endpoint.

fieldstring

The request field the warning is about.

replacementstring

The name to use instead, for deprecated_* warnings.

messagestring

A sentence that says what happened and what to do.

documentation_urlstring

Where the naming rules are explained.

querystring

The text you searched for.

results_countinteger

How many hotels are in hotels.

search_timestring

Time the search took, as text with its unit, such as 0.061s.

hotelsarray of object

The hotels that match, best match first.

ShowHide 8 attributes

idstring

The FX-Port hotel id: send it as hotel_id.

namestring

Name of the hotel.

match_scorenumber

How well the name matches your text, 0 to 100, two decimals. Below about 80 the hit is often another hotel.

Between 0 and 100.

match_typestring

How the name matched.

One of exact, partial, fuzzy.

addressstring

Street address.

citystring

City.

country_codestring

ISO 3166-1 alpha-2 country code.

postal_codestring

Postal code; an empty string when unknown.

Errors

Status	Code	Example message
400	`invalid_query`	'query' must be 2 to 100 characters long.
400	`invalid_limit`	'limit' must be at most 100.
400	`invalid_min_score`	'min_score' must be a number between 0 and 100.
400	`bad_request`	Query cannot be empty
422	`validation_error`	Field required
503	`service_busy`	Hotel name search is busy right now. Retry in a couple of seconds.

The shape of the error body depends on the endpoint. See Errors for every shape and code.

{ "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" } ] }

Request

Query parameters

querystringrequired

The hotel name or a part of it, 2 to 100 characters.

limitinteger

Most hits to return, 1 to 100. A number outside that range, or text that is not a number, answers 400 invalid_limit.

Between 1 and 100. Default 10.

min_scorenumber

Lowest match score to return, 0 to 100. A number outside that range, or text that is not a number, answers 400 invalid_min_score.

Between 0 and 100. Default 60.

include_locationboolean

Add the address, city, country code and postal code to each hit.

Default true.

include_detailsboolean

Return the whole cached hotel document of each hit (about 26 KB each) instead of the summary.

Default false.

Response

200The hotels that match, best match first.

environmentstring

The environment of the key that made the call: sandbox for fxp_test_ keys, live for fxp_live_ keys. Present in every JSON body.

One of sandbox, live.

request_idstring

The id of the request, also in the X-Request-Id header.

warningsarray of object

Present only when the request used a previous spelling of a field or something the endpoint ignored.

ShowHide 5 attributes

codestring

What the warning is about.

One of deprecated_field, ignored_field, coerced_value, deprecated_value, deprecated_endpoint.

fieldstring

The request field the warning is about.

replacementstring

The name to use instead, for deprecated_* warnings.

messagestring

A sentence that says what happened and what to do.

documentation_urlstring

Where the naming rules are explained.

querystring

The text you searched for.

results_countinteger

How many hotels are in hotels.

search_timestring

Time the search took, as text with its unit, such as 0.061s.

hotelsarray of object

The hotels that match, best match first.

ShowHide 8 attributes

idstring

The FX-Port hotel id: send it as hotel_id.

namestring

Name of the hotel.

match_scorenumber

How well the name matches your text, 0 to 100, two decimals. Below about 80 the hit is often another hotel.

Between 0 and 100.

match_typestring

How the name matched.

One of exact, partial, fuzzy.

addressstring

Street address.

citystring

City.

country_codestring

ISO 3166-1 alpha-2 country code.

postal_codestring

Postal code; an empty string when unknown.

Errors

Status	Code	Example message
400	`invalid_query`	'query' must be 2 to 100 characters long.
400	`invalid_limit`	'limit' must be at most 100.
400	`invalid_min_score`	'min_score' must be a number between 0 and 100.
400	`bad_request`	Query cannot be empty
422	`validation_error`	Field required
503	`service_busy`	Hotel name search is busy right now. Retry in a couple of seconds.

The shape of the error body depends on the endpoint. See Errors for every shape and code.

Request

Query parameters

Response

Errors

Related guides

Request

Query parameters

Response

Errors

Related guides