Navvo
API Reference

Similar places

A "more like this" row for a place page — places similar in meaning to a given place, with a nearby-in-the-same-category fallback.

Similar places

Given one place, return places like it, for a "More like this" or "You might also like" row on a place page. Navvo compares places by meaning: names, categories and what the place is. A specialty coffee roaster tends to surface other roasters and specialty cafés rather than any business with "coffee" in its name. When a place can't be compared that way, Navvo falls back to nearby places in the same category, and the response tells you which method answered.

Scope required: search

GET /search/similar

curl -s "https://navvo.io/api/v1/search/similar?slug=astrolabe-coffee-astrlab-abdali-mall-289197&limit=6" \
  -H "x-api-key: nvvo_YOUR_KEY"

Query parameters

id
string
The id of the reference place. Send id or slug.
slug
string
The slug of the reference place. Send id or slug.
locale
string
en (default) or ar: the language of each item's categoryName and address.
limit
number
Maximum number of places. Defaults to 10 and is clamped to 1–50.
lat
number
An optional origin latitude. With lon, items carry distanceKm.
lon
number
An optional origin longitude. Send it together with lat.
radiusKm
number
Only places within this many kilometres of lat/lon, from 0.1 to 500. It needs an origin. Without it, results are limited to places in Jordan.

Response

{
  "source": "vectors",
  "items": [
    {
      "id": "243270bc-4aa9-4253-a7e8-04fad61d8c38",
      "slug": "nebo-specialty-coffee-roasters-and-coffee-house-5eb58a",
      "nameEn": "Nebo Specialty coffee roasters and coffee house",
      "nameAr": null,
      "categories": ["coffee-roastery"],
      "canonicalCategorySlug": "coffee-roastery",
      "rawCategories": ["Coffee roastery"],
      "rating": 5,
      "sponsored": false,
      "center": "POINT(35.913329 31.95199)",
      "lat": 31.95199,
      "lng": 35.913329,
      "iconLightUrl": "https://navvo.io/uploads/category-icons/coffee-roastery-light.svg",
      "iconDarkUrl": "https://navvo.io/uploads/category-icons/coffee-roastery-dark.svg",
      "imageUrl": null
    }
  ]
}
FieldTypeDescription
sourcestringvectors: the places were compared by meaning. nearby: the fallback answered, with places in the same category near the reference place.
items[]arraySimilar places, best first. They use the same element shape as GET /search → places.items[]. The reference place itself and hidden places are never included. The list can be empty.
nearby is not an error. Some places can't be compared by meaning yet (for example, one added in the last few minutes), and meaning-based comparison can be switched off on a deployment. Both cases still return a useful row. Show the list either way, and use source only if you want different copy ("More like this" versus "Nearby in this category").

Errors

StatusWhen
400Neither id nor slug was sent; radiusKm was sent without lat/lon; or a parameter is out of range.
404No visible place has that id or slug.
401 / 403The key is missing or invalid, lacks the search scope, or is over quota.

Each call counts as 2 weighted requests (see Search → Metering & rate limits).

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 events

Report which search result a user opened and what they did next — consent-gated click and conversion events that measure and improve search.

Copyright © 2026