Destinations

A search by place needs a place the API knows by name. This is that list: every country and city that has hotels to offer, in one alphabetical list. A country comes first, then its cities. Nothing in it says where a place came from, and a city that is covered more than one way is listed once.

Query Parameters#

type

"country" | "city" optional

Only countries, or only cities. Omit for both.

country

string optional

Only this country’s destinations: an ISO-2 code (ZW) or an English name (Zimbabwe), in any case. A country that is not recognised returns an empty list, not an error.

q

string optional

Names that start with this text, in any case — har finds Harare. Matches cities and countries alike. Characters such as % and _ are taken literally.

limit

integer (≤200) default 50

How many destinations to return in one page.

cursor

string optional

The nextCursor from the previous page, unchanged. An invalid cursor is a 400.

curl "https://api.gatewaystream.com/api/v1/destinations?q=spring&country=US&limit=3" \
  -H "x-api-key: gws_sandbox_YOUR_KEY"

Response

destinations

object[] optional

The page of destinations, in the order described below.

nextCursor

string optional

Pass back as cursor for the next page. Absent on the last page.

The Destination Object#

type

"country" | "city" optional

What kind of place this is.

label

string optional

Ready to show in a list: Harare, Zimbabwe, or Springfield, IL, United States where a region tells same-named cities apart.

city

string | null optional

The city’s name. null on a country.

region

string | null optional

A state or province that tells apart cities with the same name — IL, South Australia. null when there is none.

country

string optional

The ISO-3166 alpha-2 code. This is what to send as destination.country in a search.

countryName

string optional

The country’s English name.

A country is the same object with the city and region empty:

{
  "type": "country",
  "label": "Zimbabwe",
  "city": null,
  "region": null,
  "country": "ZW",
  "countryName": "Zimbabwe"
}

Order is stable between requests: by country name, a country before its cities, then city name, then region. That is what makes the cursor reliable — a page boundary does not move between two calls.

Using One in a Search#

Send the destination's city and country as destination on POST /search, or just the country to search a whole country. You do not send the region: a city name that exists in several places, like Springfield, is searched in all of them.

{
  "checkIn": "2026-12-05",
  "nights": 2,
  "rooms": [{ "adults": 2, "childAges": [] }],
  "destination": { "city": "Springfield", "country": "US" }
}

Search as You Type#

// A search box: ask as the guest types, and show each result's ready-made label.
async function suggest(text) {
  const url = new URL('https://api.gatewaystream.com/api/v1/destinations');
  url.searchParams.set('q', text);
  url.searchParams.set('limit', '8');

  const res = await fetch(url, { headers: { 'x-api-key': process.env.GWS_API_KEY } });
  const { destinations } = await res.json();

  return destinations; // [{ label: 'Harare, Zimbabwe', city: 'Harare', country: 'ZW', … }]
}

• Wait a moment before asking. Debounce by 200–300 ms so a guest typing “harare” is one request, not six.
• The country list is stable. About two hundred countries change rarely. Fetch ?type=country&limit=200 once per session, or once a day, and cache it.
• Narrow once a country is chosen. ?type=city&country=ZW is a short list that can be shown whole.
• Use label for display. It already carries the region and country where they are needed to tell two places apart.

Status Codes#

200

The page — possibly empty, which is not an error.

400 validation_error

A bad query parameter: a limit above 200, an unknown type, or a cursor that is not one this API issued.

401 unauthorized

Missing or invalid x-api-key.

429 rate_limited

Too many requests. Back off for details.retryAfterSeconds.

503 mode_unavailable

This deployment has no configuration for the environment your key points at.