Hotels · Search

Search destinations and get coordinates

Turns the text a user typed (a city, an area, an airport, a hotel) into places with coordinates.

GET/api/v1/hotels/locations/search

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

Pass the latitude and longitude of the place the user picks to search_advanced, with a radius. The results mix cities, airports and hotels of a location provider: the id is the provider's, not a FX-Port hotel id, and type is always location (the kind of place is raw.loctype). Places without coordinates are dropped. The answer is the same in the sandbox and on live. Cache the answers for a user's session and debounce typeahead calls (about 300 ms).

curl 'https://api.fx-port.com/api/v1/hotels/locations/search?query=Tegucigalpa&limit=3' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"

Response200

{
  "environment": "sandbox",
  "success": true,
  "query": "Tegucigalpa",
  "resultsCount": 2,
  "locations": [
    {
      "id": "20119",
      "name": "Tegucigalpa",
      "displayName": "Tegucigalpa, Honduras",
      "city": "Tegucigalpa",
      "countryCode": "HN",
      "latitude": 14.094204124743296,
      "longitude": -87.19410705810549,
      "type": "location",
      "raw": {
        "id": "20119",
        "displayname": "Tegucigalpa, Honduras",
        "loctype": "city",
        "cid": 107,
        "lat": 14.094204124743296,
        "lng": -87.19410705810549,
        "cc": "HN",
        "country": "Honduras",
        "timezone": "America/Tegucigalpa",
        "utc": "-06:00",
        "ap": "TGU"
      }
    },
    {
      "id": "TGU",
      "name": "Toncontin",
      "displayName": "Toncontin, Tegucigalpa, Honduras, (TGU)",
      "city": "Tegucigalpa",
      "countryCode": "HN",
      "latitude": 14.06088,
      "longitude": -87.2172,
      "type": "location",
      "raw": {
        "id": "TGU",
        "displayname": "Toncontin, Tegucigalpa, Honduras, (TGU)",
        "loctype": "ap",
        "cid": 107,
        "lat": 14.06088,
        "lng": -87.2172,
        "cc": "HN",
        "country": "Honduras",
        "airportname": "Toncontin",
        "ap": "TGU"
      }
    }
  ]
}

Request

Query parameters

querystringrequired

The text to look for: a city, an area, an airport or a hotel name, 1 to 64 characters once spaces and control characters are cleaned.

localestring

Language of the names: en, fr, ar, es, de, it, ru, tr, ja, ko ... Written ll or ll-RR (es-AR); any other value answers in English.

Default en.

limitinteger

Most places to return, 1 to 50.

Between 1 and 50. Default 10.

Response

200The places that match, best first. locations is empty when nothing matches.

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.

successboolean

true when the lookup worked, also with no result.

querystring

The text you searched for.

resultsCountinteger

How many places are in locations.

locationsarray of object

The places that match, best first. Places without coordinates are dropped before limit is applied.

ShowHide 9 attributes

idstring

The id of the place at the location provider (a city id, an airport code or a hotel id of the provider). It is not a FX-Port hotel id.

namestring

Name of the place.

displayNamestring

Name with its context, for a list.

citystring

City of the place.

countryCodestring

ISO 3166-1 alpha-2 country code.

latitudenumber

Latitude: send it to search_advanced.

longitudenumber

Longitude: send it to search_advanced.

typestring

Always location. The kind of place is raw.loctype: city, ap (airport), hotel ...

rawobject

The record of the location provider, about 40 keys (loctype, lat, lng, cc, cityname, timezone, box_*, destination_images ...). Best effort: unlisted keys can change.

Errors

Status	Code	Example message
422	`validation_error`	Input should be less than or equal to 50

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

{ "environment": "sandbox", "success": true, "query": "Tegucigalpa", "resultsCount": 2, "locations": [ { "id": "20119", "name": "Tegucigalpa", "displayName": "Tegucigalpa, Honduras", "city": "Tegucigalpa", "countryCode": "HN", "latitude": 14.094204124743296, "longitude": -87.19410705810549, "type": "location", "raw": { "id": "20119", "displayname": "Tegucigalpa, Honduras", "loctype": "city", "cid": 107, "lat": 14.094204124743296, "lng": -87.19410705810549, "cc": "HN", "country": "Honduras", "timezone": "America/Tegucigalpa", "utc": "-06:00", "ap": "TGU" } }, { "id": "TGU", "name": "Toncontin", "displayName": "Toncontin, Tegucigalpa, Honduras, (TGU)", "city": "Tegucigalpa", "countryCode": "HN", "latitude": 14.06088, "longitude": -87.2172, "type": "location", "raw": { "id": "TGU", "displayname": "Toncontin, Tegucigalpa, Honduras, (TGU)", "loctype": "ap", "cid": 107, "lat": 14.06088, "lng": -87.2172, "cc": "HN", "country": "Honduras", "airportname": "Toncontin", "ap": "TGU" } } ] }

Request

Query parameters

querystringrequired

The text to look for: a city, an area, an airport or a hotel name, 1 to 64 characters once spaces and control characters are cleaned.

localestring

Language of the names: en, fr, ar, es, de, it, ru, tr, ja, ko ... Written ll or ll-RR (es-AR); any other value answers in English.

Default en.

limitinteger

Most places to return, 1 to 50.

Between 1 and 50. Default 10.

Response

200The places that match, best first. locations is empty when nothing matches.

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.

successboolean

true when the lookup worked, also with no result.

querystring

The text you searched for.

resultsCountinteger

How many places are in locations.

locationsarray of object

The places that match, best first. Places without coordinates are dropped before limit is applied.

ShowHide 9 attributes

idstring

The id of the place at the location provider (a city id, an airport code or a hotel id of the provider). It is not a FX-Port hotel id.

namestring

Name of the place.

displayNamestring

Name with its context, for a list.

citystring

City of the place.

countryCodestring

ISO 3166-1 alpha-2 country code.

latitudenumber

Latitude: send it to search_advanced.

longitudenumber

Longitude: send it to search_advanced.

typestring

Always location. The kind of place is raw.loctype: city, ap (airport), hotel ...

rawobject

The record of the location provider, about 40 keys (loctype, lat, lng, cc, cityname, timezone, box_*, destination_images ...). Best effort: unlisted keys can change.

Status

Code

Example message

422

validation_error

Input should be less than or equal to 50

Request

Query parameters

Response

Errors

Related guides

Request

Query parameters

Response

Errors

Related guides