Hotels · Search

Find a hotel by name (JSON body)

The same search as GET /hotels/name-search, with the parameters in a JSON body.

POST/api/v1/hotels/search-by-name

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

Use whichever your client prefers. A body error answers 400: missing_field for a missing query, invalid_query for the text, invalid_limit and invalid_min_score for the numbers, and bad_request with a message that names the field for the two booleans; the GET form answers 422 for a query parameter that is missing. A limit above 100 is capped at 100 and the answer carries a coerced_value warning; the GET form refuses it with invalid_limit.

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
}'

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

Body

Required, JSON.

querystringrequired

The hotel name or a part of it, 2 to 100 characters. Typos and accents are tolerated.

limitinteger

Most hits to return, 1 to 100. A larger number is capped at 100, with a coerced_value warning. A whole number written as text ("10") is read as the number, with the same warning.

Between 1 and 100. Default 10.

min_scorenumber

Lowest match score to return, 0 to 100. A number written as text ("60") is read as the number, with a coerced_value warning.

Between 0 and 100. Default 60.

include_locationboolean

Add the address, city, country code and postal code to each hit. Ignored with include_details. The text true or false (also 1, 0, yes, no, on, off) is read as the boolean, with a coerced_value warning; null means the default.

Default true.

include_detailsboolean

Return the whole cached hotel document for each hit instead of the summary. About 26 KB per hit. Text is read as in include_location.

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	`missing_field`	Missing required field: 'query'
400	`invalid_query`	'query' must be 2 to 100 characters long.
400	`invalid_limit`	'limit' must be a positive integer.
400	`invalid_min_score`	'min_score' must be a number between 0 and 100.
400	`bad_request`	'include_details' must be a boolean
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.

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 }'

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

Body

Required, JSON.

querystringrequired

The hotel name or a part of it, 2 to 100 characters. Typos and accents are tolerated.

limitinteger

Most hits to return, 1 to 100. A larger number is capped at 100, with a coerced_value warning. A whole number written as text ("10") is read as the number, with the same warning.

Between 1 and 100. Default 10.

min_scorenumber

Lowest match score to return, 0 to 100. A number written as text ("60") is read as the number, with a coerced_value warning.

Between 0 and 100. Default 60.

include_locationboolean

Default true.

include_detailsboolean

Return the whole cached hotel document for each hit instead of the summary. About 26 KB per hit. Text is read as in include_location.

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	`missing_field`	Missing required field: 'query'
400	`invalid_query`	'query' must be 2 to 100 characters long.
400	`invalid_limit`	'limit' must be a positive integer.
400	`invalid_min_score`	'min_score' must be a number between 0 and 100.
400	`bad_request`	'include_details' must be a boolean
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

Body

Response

Errors

Related guides

Request

Body

Response

Errors

Related guides