API Reference
Search suggestions
Autocomplete suggestions for a search box — category, place and area names from Navvo's own vocabulary, plus search phrases the Navvo team has reviewed.
Search suggestions
Suggestions to show under a search box while the user types, or before they type anything. They come from Navvo's own vocabulary: category names in Arabic, English and Arabizi, well-known places and their alternative names, and curated areas, plus search phrases the Navvo team has reviewed and approved. Suggestions are never generated automatically from what people type: an approved phrase may first have been noticed in people's searches, but nothing becomes a suggestion without that review.
Scope required: search
GET /search/suggestions
curl -s "https://navvo.io/api/v1/search/suggestions?q=abd&locale=en&limit=5" \
-H "x-api-key: nvvo_YOUR_KEY"
Query parameters
q
string
What the user has typed so far. It matches word prefixes in Arabic, English and Arabizi. Leave it empty to get a starter list of top categories and well-known landmarks for the
locale, which suits an empty, focused search box. The starter list comes from the suggestions index, which is built nightly or when a Navvo administrator rebuilds it; until it has been built, an empty q returns an empty list. Anything past 100 characters is ignored.locale
string
en or ar, or a full language tag such as ar-JO (tags starting with ar resolve to ar, everything else to en). It only matters when q is empty, where it picks the language of the starter list. With a non-empty q, the script of the query decides the language instead.limit
number
Maximum number of suggestions. Defaults to
8 and is clamped to 1–20.Response
{
"query": "abd",
"suggestions": [
{ "text": "Abdali Mall", "kind": "place", "slug": "abdali-mall-e18cf2", "categorySlug": "shopping-mall" },
{ "text": "Abdoun", "kind": "area" },
{ "text": "Abdali", "kind": "area" }
]
}
| Field | Type | Description |
|---|---|---|
query | string | Your q, echoed. |
suggestions[] | array | Ordered best first. It can be empty. |
suggestions[].text | string | The label to show. It is plain text with no markup, so render it as text. |
suggestions[].kind | string | category, place, area or term (see below). |
suggestions[].slug | string | For place: the place slug, for GET /places/{slug}. |
suggestions[].categorySlug | string | For category: the category to filter by. For place: the place's primary category, which you can use to pick an icon. |
What to do when the user picks one
kind | What it is | Suggested action |
|---|---|---|
category | A category name (Pharmacy, صيدلية, Saydaliyya) | Run GET /search with q=<text>, or show that category directly with category=<categorySlug>. |
place | A well-known place | Open the place with GET /places/{slug}. Don't run another search. |
area | A neighbourhood, district or city | Run GET /search with q=<text>, or keep it as a locality (cafe in <text>). |
term | A search phrase Navvo has reviewed | Run GET /search with q=<text>. |
Suggestions and results work well together. While the user types, call this endpoint and
GET /search with mode=typeahead in parallel, then show suggestions above the first few results. Suggestions answer "what might they mean?" and results answer "which places match?".Suggestion lists are rebuilt nightly from the catalogue, so catalogue changes can take up to a day to show up here.
GET /search picks them up within minutes.Errors
| Status | When |
|---|---|
400 | locale is longer than 35 characters, or a parameter has the wrong type. |
401 / 403 | The key is missing or invalid, lacks the search scope, or is over quota. |
Each call counts as 1 weighted request (see Search → Metering & rate limits).