Search

Free-text search over Navvo's place catalogue. One query box handles Arabic, English, Arabizi (Arabic written in Latin letters and digits, such as saydaliyeh or mat3am) and mixed queries. Navvo recognises category words (pharmacy, صيدلية), areas (cafe in Abdoun), "near me" and "open now" phrases, tolerates typos, and ranks by how well a place's name matches before it weighs distance and popularity.

Query understanding is deterministic: it is a set of rules and curated vocabularies, not an AI model, so the same query always reads the same way and never waits on a model. Everything runs on Navvo's own infrastructure.

Typo tolerance covers short words too. Take an English word of four to six letters that no place name uses but that is one letter away from a word place names do use. Navvo also searches its corrected form next to the query as typed, and ranks the two result sets together: cafr finds cafés and hotl finds hotels. The correction comes from the words in Navvo's own place names and favours the commonest typing slips, such as a neighbouring key or two swapped letters. Arabizi words are never corrected this way, because they are Arabic written in Latin letters, not misspellings.

Scope required: search

GET /search

Search for places by free-text query.

curl -s "https://navvo.io/api/v1/search?q=coffee&lat=31.9539&lon=35.9106&limit=10" \
  -H "x-api-key: nvvo_YOUR_KEY"

Query parameters

Request headers

These headers are all optional. The first four control what Navvo records; Search analytics & privacy explains the model behind them.

Response

Every response carries Cache-Control: no-store. Each response has a fresh queryId, so a cached copy would tie the user's clicks to someone else's search. Don't cache /search responses in a service worker or CDN.

Each places.items[] element:

{
  "query": "coffee",
  "locale": "en",
  "queryId": "AaDxmIYgiEC1I4ZdHCWiERmR",
  "understanding": {
    "unavailable": false,
    "purpose": "search_understanding",
    "parsed": { "language": "en", "intent": "place", "category": "Coffee Shop", "categories": ["coffee-shop", "cafe", "coffee-stand", "cafeteria", "cat-cafe", "tea-house"] }
  },
  "places": {
    "items": [
      {
        "id": "e3bacbd9-1e5d-474c-b84e-2fe7e1556541",
        "slug": "coffee-factory-co-jabal-amman-a3ddbd",
        "nameEn": "Coffee Factory & Co. - Jabal Amman",
        "nameAr": null,
        "categories": ["coffee-shop"],
        "canonicalCategorySlug": "coffee-shop",
        "rawCategories": ["Coffee shop"],
        "rating": 4.6,
        "sponsored": false,
        "center": "POINT(35.905152 31.952061)",
        "lat": 31.952061,
        "lng": 35.905152,
        "iconLightUrl": "https://navvo.io/uploads/category-icons/coffee-shop-light.svg",
        "iconDarkUrl": "https://navvo.io/uploads/category-icons/coffee-shop-dark.svg",
        "imageUrl": "https://navvo.io/uploads/place-images/e3/e3bacbd9-1e5d-474c-b84e-2fe7e1556541-dc3949fa.webp",
        "distanceKm": 0.55
      }
    ],
    "total": 1000,
    "page": 1,
    "limit": 10
  },
  "near": { "lat": 31.9539, "lng": 35.9106 },
  "index": { "provider": "navvo-search", "configured": true, "available": true, "mode": "keyword" }
}

Query understanding

understanding tells you how Navvo read the query. The results already reflect it, so you don't have to act on it. Use it for interface hints instead, such as showing an "Open now" chip when the user typed "open now". A set of rules produces it with no model involved, so identical queries always read identically and unavailable is always false. The field is kept for compatibility.

Everything useful sits under understanding.parsed:

Keys appear only when they apply. For cafe in Abdoun:

"parsed": { "language": "en", "intent": "category", "category": "Coffee Shop", "categories": ["coffee-shop", "cafe", "coffee-stand", "cafeteria", "cat-cafe", "tea-house"], "locality": "Abdoun" }

Facets

facets=category,amenities adds counts you can turn into filter chips:

"facets": {
  "category": [
    { "slug": "coffee-shop", "name": { "en": "Coffee Shop", "ar": "مقهى" }, "count": 812 },
    { "slug": "cafe", "name": { "en": "Cafe", "ar": "مقهى" }, "count": 108 },
    { "slug": "coffee-roastery", "name": { "en": "Coffee Roastery", "ar": "محمصة قهوة" }, "count": 10 }
  ],
  "amenities": [
    { "slug": "wheelchair-accessible-entrance", "count": 301 },
    { "slug": "delivery", "count": 188 }
  ]
}

• Each list is sorted by count, highest first. A category's name.en or name.ar can be null.
• Counts cover places that match the query's words and your filters. items can also include nearby or meaning-based results, so the counts guide a filter UI rather than break down the list exactly.
• Pass a slug straight back as category= or amenities= to apply the filter.
• facets is absent when you didn't ask for it, and can be absent when the fallback answered (index.available: false).

Highlights

With highlight=true, an item whose name matches the query carries highlight.nameEn and/or highlight.nameAr. Each is the name, HTML-escaped, with the matched words wrapped in <em>…</em>. A key is present only when that name contains a match:

"highlight": { "nameEn": "<em>Coffee</em> Factory &amp; Co. - Jabal Amman" }

The string is safe to insert as HTML. The most robust approach, though, is to render it as text nodes: split on the tags and decode the entities yourself, and never pass it to innerHTML or dangerouslySetInnerHTML:

// "<em>Coffee</em> Factory &amp; Co." -> [{ text: "Coffee", match: true }, { text: " Factory & Co.", match: false }]
function highlightSegments(html) {
  const decode = (s) => s
    .replace(/&lt;/g, "<").replace(/&gt;/g, ">")
    .replace(/&quot;/g, '"').replace(/&#39;/g, "'")
    .replace(/&amp;/g, "&");
  return html.split(/(<em>.*?<\/em>)/g).filter(Boolean).map((part) => {
    const m = part.match(/^<em>(.*)<\/em>$/);
    return { text: decode(m ? m[1] : part), match: Boolean(m) };
  });
}

didYouMean and every field of GET /search/suggestions are plain text and carry no markup.

Result details

An item can carry what a results list or a map card shows: reviewCount, categoryName, priceRange, priceLevel, address, area, hours and highlights. Each comes from the place record and is left out when the place has no such data, so check that a field is there before you use it. The same fields appear on zero-result suggestions and on similar places.

hours describes today in Jordan time. It is worked out when the search runs, so don't cache a response for more than a few minutes.

"hours": { "state": "closed", "opensAt": "09:00", "opensDay": "sunday" }

A place that closes at 2 a.m. is still open after midnight, with "closesAt": "02:00".

Ranking

Every candidate first lands in a match band. Bands never mix, so a better band always ranks above a worse one:

1. Exact. The query is the place's name or one of its alternative names, including after a spelling variant (an Arabizi query converted to Arabic, for example).
2. Strong. The name contains every word of the query spelled correctly, or, with mode=typeahead, starts with what the user typed.
3. Complete. Every word matches, allowing for typos, or the words match across the name, category and neighbourhood (cafe abdoun finds a café in Abdoun), or the place belongs to the category the query asks for.
4. Partial. Only some of the words match.
5. Meaning-based. The place was found only by meaning-based matching.

Within a band, Navvo combines distance from the origin, popularity (review volume and map prominence), text relevance, typos, and editorial boosts. A few rules shape that order:

• Category searches level the field. For pharmacy or صيدلية قريبة, a place literally named "Pharmacy" gets no head start. Nearby, popular places in the category lead.
• Areas move the origin. In cafe in Abdoun, results rank around Abdoun rather than around lat/lon. Without a connecting word (cafe abdoun), your origin stays and places in Abdoun get a boost. If the whole query is an area, Navvo searches for it by name.
• Supporting features step back. Bus stops, car parks, taxi stands, gates, entrances and ATMs rank below the main place unless the query asks for them.
• Jordan first. Without an origin, places in Jordan rank ahead of equally good matches abroad.
• A far branch doesn't outrank nearby ones. With an origin, an exact name match more than 25 km away competes on distance with nearer places whose names contain the query, so carrefour from Amman lists Amman's branches first. A major place keeps its lead however far it is (Petra, Al-Aqsa Mosque).
• "Open now" in the query demotes places known to be closed (open first, then unknown hours, then closed) even without openNow=true. openNow=true removes everything that isn't open.
• Sponsored places that are relevant to the query get a small boost within their band. They never jump to a better band. Results pinned by a Navvo rule carry promoted: true, and also sponsored: true when the placement is paid.

sort=distance and sort=rating replace this order entirely.

Meaning-based matching

Keyword matching finds places whose names and categories contain the query's words. Meaning-based matching also finds places that fit a description, such as quiet place to study or مكان للعشاء مع العائلة, even when no word matches, including across Arabic and English. It runs entirely on Navvo's own infrastructure, so query text never goes to a third party.

• It is only a fallback. It adds results only when keyword matching finds few strong matches. A query that already has good name matches is not changed, and meaning-based results always rank below keyword results (band 5).
• It needs some evidence in the query: at least one word must match the catalogue (typos allowed), or the query must name a category or carry a filter. Random letters and off-topic questions get no meaning-based results.
• It needs a query of at least two complete words, mode=submit, and a query that isn't a pure category search. It never runs for typeahead.
• Navvo waits at most 350 ms for it. If it is slower or unavailable, you get the keyword results without it and no error.
• semantic=off disables it. semantic=on allows it on API-key requests, where auto behaves like off.
• index.mode on the response is hybrid when meaning-based matching contributed to that response, and keyword otherwise.

No results

When nothing matches, places.items is empty and places.total is 0. Navvo never fills the list with unrelated places. Instead:

• suggestions[] lists popular places near the origin, or popular places in Jordan when there is no origin, in the same shape as the items. Show them under a heading such as "No results — popular places", not as results.
• didYouMean appears when the query looks like a misspelling of something in Navvo's vetted vocabulary (category names and well-known place names). Offer it as a link that re-runs the search.

Pagination

page and limit page through one ranked list. Each query ranks at most its top 200 candidates, so stop when a page comes back with fewer than limit items. Don't compute the last page from places.total, which is an estimate.

To fetch a place's full details (hours, photos, entrances), call GET /places/{slug} with the slug from a result.

Errors

If the search index is unreachable, /search doesn't fail. A simpler database fallback answers instead, and index.available is false. Error bodies follow the standard shape in Conventions.

Metering & rate limits

Each search request counts as one request against your key's per-minute and per-day quota, and as weighted requests for your plan's billing (see plans & metering). An unlimited key has no quota, but its requests are still weighted:

Meaning-based matching does not change the weight of a request. Requests without an API key get meaning-based matching within an approximate hourly budget per client IP address: about 120 searches in which meaning-based matching actually runs. Beyond it they silently use keyword matching only.

Index status & monitoring

Every response carries an index object: