Documentation / Guides
Autosuggest
Turn what a traveller types into ranked cities, areas, landmarks, airports and hotels, with the area to search.
Call it
Autosuggest runs at https://suggest.plexe.ai with its own keys: create one in the autosuggest console and send it in the X-API-Key header. Call it on each keystroke, debounced by 100 to 150 ms.
curl "https://suggest.plexe.ai/api/suggest?q=ao%20na&limit=8" \
-H "X-API-Key: $PLEXE_SUGGEST_KEY"
Only q is required. The other parameters shape the list:
limit: suggestions to return, 1 to 20; 8 by default.types: comma-separated entity types to keep, for examplecity,airport. Omit for every type.country: an ISO-2 country to favour, such as your market. It breaks ties; it does not filter.latandlon: a position to favour nearby results. Send both.language: show place names and breadcrumbs in a language such asde,frorzh. Matching works in every language either way; hotel names stay as they are.session_id: your identifier for one typing session, echoed in the response.
Prefixes match from the first letter. Hotels are included from three characters, and typos are tolerated from four. Any script works: 東京, دبي, อ่าวนาง.
Read a suggestion
The response is query, took_ms (server time) and results, best first. Places and hotels share one shape; fields that apply to one kind only are left out when empty. Field names are snake_case, the shape the search box widget reads.
{"id": "gn:1158377", "type": "city", "subtype": "PPL", "name": "Ao Nang",
"label": "Ao Nang, Krabi, Thailand", "country_code": "TH", "lat": 8.0458, "lon": 98.81035,
"hotel_count": 589, "score": 11.015, "highlight": [[0, 2], [3, 5]], "search_type": "Polygon"}
id: stable. Places aregn:…, airportsap:…, countriescc:…, hotelsh:….type:city,metro_area,neighborhood,island,point_of_interest,airport,province_state,district,country,train_station,metro_station,bus_stationorhotel.nameandlabel: what to show, and the breadcrumb that tells two places of one name apart.highlight: character ranges ofnamethat match what was typed, for bolding.hotel_count: hotels in or near a place; always 1 for a hotel.score: only the order means anything; values are not comparable across queries.child_of: set on a destination listed under the first suggestion. When an island, region or country comes first, its main destinations follow it; indent those rows.hotel_idandregion_id: on hotels, the Plexe property id and the place the hotel belongs to.
Places and hotel lists
When the traveller picks a place, GET /api/regions/{id} returns it with its ancestors (parent_ids), the viewport a map should show, and search: the area to search a supplier with. That is a circle (center, radius_km) for cities, areas, landmarks and airports, and a polygon or multipolygon for islands, island nations and regions. Add format=zentrumhub for ZentrumHub's own region shape.
GET /api/regions/{id}/hotels pages through the hotels the place counts, most popular first, up to 250 a page (page, per_page). total equals the place's hotel_count.
Search box widget
A ready-made search box, @plexe/autosuggest, is a web component with no dependencies, with a React wrapper. It calls from the traveller's browser, so it needs a website key: a key locked to the sites you list on it, created in the autosuggest console. Never put a server key in a page.
<script type="module" src="https://suggest.plexe.ai/widget/v1.js"></script>
<plexe-autosuggest api-key="plx_..." placeholder="Where to?"></plexe-autosuggest>
It raises plexe-select with the chosen suggestion in event.detail.
Limits
Autosuggest keys have their own plans and limits, shown in the autosuggest console. The free plan allows 5,000 requests a day.
Place data comes from GeoNames (CC BY 4.0), OurAirports (public domain) and Wikidata (CC0); island outlines © OpenStreetMap contributors, ODbL 1.0.