Hotels · Search

Search locations

Search cities and destinations by name and get back usable geo coordinates for hotel availability search.

GET/api/v1/hotels/locations/search

Turn what a user typed (a city, an area, an airport) into places with coordinates. The latitude and longitude of the place the user picks are the input of the geo search (search_advanced with a radius), which lists the hotels around that point.

Permission: Read

Query parameters

GET /api/v1/hotels/locations/search

Parameter	Type	Required	Default	Description
`query`	string	Yes		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.
`locale`	string	No	`en`	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.
`limit`	integer	No	`10`	Most places to return, 1 to 50. Places without coordinates are dropped before the limit is applied.

Request example

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

Response example

A real answer of the sandbox, with the raw objects shortened:

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

Field	Description
`success`	`true` when the lookup worked, also when nothing matches (`resultsCount` is then `0` and `locations` empty).
`resultsCount`	How many places are in `locations`.
`locations[].id`	The id of the place at the location provider: a city id, an airport code or a hotel id of the provider. Not a FX-Port hotel id.
`locations[].name`, `displayName`, `city`, `countryCode`	What to show in the list. `displayName` carries the context (`Tegucigalpa, Honduras`).
`locations[].latitude`, `longitude`	The only fields the geo search needs: send them as its `latitude` and `longitude`.
`locations[].type`	Always `location`. The kind of place is `raw.loctype`: `city`, `ap` (airport) or `hotel`.
`locations[].raw`	The record of the location provider, about 40 keys (`loctype`, `cityname`, `timezone`, the bounding box `box_*` ...). It is passed on as it is: unlisted keys can change, do not build on them.

From a place to a geo search

Show displayName for each place and let the user pick one. Results mix cities, airports and hotels: show an icon from raw.loctype if the list is long.
Send the latitude and longitude of the place to the geo search (search_advanced) with a radius in meters. The radius is mandatory and goes from 100 to 70,000: 5,000 to 15,000 is a good start for a city. A bigger radius means a bigger and slower answer.
When the user picked a hotel (raw.loctype is hotel), do not use its id. Search the hotel by name with name-search to get the FX-Port hotel id.

Typeahead

Wait about 300 ms after the last keystroke and cancel the request that is in flight.
A first lookup of a text takes 1 to 2.5 seconds, a repeated one about a second. Keep the answers for the session of the user instead of asking again for the same text.
The lookup is limited per IP address as well as per key: see Rate limits.
The answer is the same in the sandbox and on live.

Names

The keys of this answer are camelCase (resultsCount, displayName, countryCode) and have no snake_case twin. Add ?naming=snake to get every key in snake_case. See Conventions and naming.

Errors

HTTP	Code	Cause
`422`	`invalid_query`	`query` is blank, or longer than 64 characters.
`422`	`validation_error`	`query` is missing, or `limit` is outside 1 to 50.
`401`, `403`		The key is missing, wrong or not allowed: Authentication.
`429`	`rate_limit_exceeded`	Too many calls: Rate limits.

When its provider is slow or down, the lookup falls back to FX-Port's own records of places, so the raw object can then have other keys: one more reason not to build on it.

Geo searchThe next step: the hotels around the coordinates you picked.Hotel name searchFind one hotel by its name.API reference: Search destinationsEvery field and error.

Query parameters

GET /api/v1/hotels/locations/search

Parameter	Type	Required	Default	Description
`query`	string	Yes		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.
`locale`	string	No	`en`	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.
`limit`	integer	No	`10`	Most places to return, 1 to 50. Places without coordinates are dropped before the limit is applied.

Response example

A real answer of the sandbox, with the raw objects shortened:

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

Field	Description
`success`	`true` when the lookup worked, also when nothing matches (`resultsCount` is then `0` and `locations` empty).
`resultsCount`	How many places are in `locations`.
`locations[].id`	The id of the place at the location provider: a city id, an airport code or a hotel id of the provider. Not a FX-Port hotel id.
`locations[].name`, `displayName`, `city`, `countryCode`	What to show in the list. `displayName` carries the context (`Tegucigalpa, Honduras`).
`locations[].latitude`, `longitude`	The only fields the geo search needs: send them as its `latitude` and `longitude`.
`locations[].type`	Always `location`. The kind of place is `raw.loctype`: `city`, `ap` (airport) or `hotel`.
`locations[].raw`	The record of the location provider, about 40 keys (`loctype`, `cityname`, `timezone`, the bounding box `box_*` ...). It is passed on as it is: unlisted keys can change, do not build on them.

From a place to a geo search

Show displayName for each place and let the user pick one. Results mix cities, airports and hotels: show an icon from raw.loctype if the list is long.

Send the latitude and longitude of the place to the geo search (search_advanced) with a radius in meters. The radius is mandatory and goes from 100 to 70,000: 5,000 to 15,000 is a good start for a city. A bigger radius means a bigger and slower answer.

When the user picked a hotel (raw.loctype is hotel), do not use its id. Search the hotel by name with name-search to get the FX-Port hotel id.

Typeahead

Wait about 300 ms after the last keystroke and cancel the request that is in flight.

A first lookup of a text takes 1 to 2.5 seconds, a repeated one about a second. Keep the answers for the session of the user instead of asking again for the same text.

The lookup is limited per IP address as well as per key: see Rate limits.

The answer is the same in the sandbox and on live.

Errors

HTTP	Code	Cause
`422`	`invalid_query`	`query` is blank, or longer than 64 characters.
`422`	`validation_error`	`query` is missing, or `limit` is outside 1 to 50.
`401`, `403`		The key is missing, wrong or not allowed: Authentication.
`429`	`rate_limit_exceeded`	Too many calls: Rate limits.

When its provider is slow or down, the lookup falls back to FX-Port's own records of places, so the raw object can then have other keys: one more reason not to build on it.

Query parameters

Request example

Response example

From a place to a geo search

Typeahead

Names

Errors

Related

Query parameters

Request example

Response example

From a place to a geo search

Typeahead

Names

Errors

Related