Guide Search

Overview

The /v2/guide-search endpoint returns a paginated list of curated travel guides from the Obvlo content engine. You can filter by geography, free-text query, and guest personalisation attributes such as trip type and interests. By default, each guide result includes its embedded listings (points of interest). You can disable this with includeListings=false to get a lighter response.

Localised fields and the `lang` parameter

Guide fields (name, description, introText, keywords, attribution, centerLocation, preferences) and all localised fields of embedded listings carry translated content. The shape of these fields depends on whether lang is provided:

`lang`	Field shape	Example
Provided (e.g. `lang=en-GB`)	Plain value for the requested language.	`"name": "Top Restaurants in Shoreditch"`
Omitted	Language map — one key per available language code.	`"name": { "en-GB": "Top Restaurants in Shoreditch" }`

When lang is omitted, at least the default language (en-GB) is always included in the map.

Request

GET /v2/orgs/{orgId}/guide-search

Required parameters

Parameter	Type	Description
`orgId`	string	Your organisation ID.

Optional parameters

Parameter	Type	Default	Description
`profileId`	string	—	Scope results to a specific host profile.
`searchQuery`	string	—	Full-text query matched against guide names and descriptions.
`latlng`	string	—	Geo-center for proximity ranking. Format: `latitude,longitude` (e.g. `51.5074,-0.1278`).
`radius`	number	Profile default	Search radius in metres around `latlng`.
`page`	integer	`1`	Page number (1-based).
`hitsPerPage`	integer	`10`	Results per page. Maximum `20`.
`userCategory`	string	—	Filter by user category (e.g. `couple`, `family`, `solo`).
`tripType`	string	—	Filter by trip type (e.g. `leisure`, `business`).
`userInterests`	string	—	Comma-separated interest tags used for personalised ranking.
`includeListings`	string	`true`	Set to `false` to omit embedded listings from each guide.
`maxListingsPerGuide`	integer	`20`	Maximum listings to embed per guide when `includeListings=true`.
`rankBy`	string	`score`	Ranking strategy: `score` (relevance) or `distance` (nearest first, requires `latlng`).
`lang`	string	—	BCP 47 language code (e.g. `en-GB`). When provided, localised fields in guides and their embedded listings are returned as plain values for that language instead of language maps.

Examples

Basic search for an organisation

Basic search

curl "https://api.obvlo.com/v2/guide-search?orgId=YOUR_ORG_ID"

Geo-filtered search near London

Geo-filtered, near London

curl "https://api.obvlo.com/v2/guide-search?orgId=YOUR_ORG_ID&latlng=51.5074,-0.1278&radius=5000&hitsPerPage=5"

Personalised search for a couple on a leisure trip

Personalised search

curl "https://api.obvlo.com/v2/guide-search?orgId=YOUR_ORG_ID&userCategory=couple&tripType=leisure&userInterests=food,culture"

Search with a specific language

With parameter

curl "https://api.obvlo.com/v2/guide-search?orgId=YOUR_ORG_ID&lang=en-GB"

Search without embedded listings

Without embedded listings

curl "https://api.obvlo.com/v2/guide-search?orgId=YOUR_ORG_ID&includeListings=false"

Response

With lang=en-GB
Without lang (language map)

{
  "results": [
    {
      "id": "guide_abc123",
      "contentType": "guide",
      "name": "Top Restaurants in Shoreditch",
      "description": "A curated selection of the best places to eat...",
      "introText": "Shoreditch is known for its vibrant food scene...",
      "keywords": ["restaurants", "food", "shoreditch"],
      "geoLocation": [51.5247, -0.0755],
      "featured": false,
      "hostIds": ["host_xyz"],
      "listingIds": ["listing_1", "listing_2"],
      "languageCodes": ["en-GB", "fr-FR"],
      "updatedAt": 1739800000000,
      "geoDistance": 1234.5,
      "listings": [
        {
          "id": "listing_1",
          "contentType": "listing",
          "name": "Padella",
          "summary": "Acclaimed pasta restaurant in Borough Market.",
          "address": "6 Southwark St, London SE1 1TQ",
          "category": "restaurant",
          "geoLocation": [51.5051, -0.0906],
          "geoDistance": 950.0,
          "featured": false,
          "guideIds": ["guide_abc123"],
          "hostIds": ["host_xyz"],
          "score": 0.89,
          "searchId": "listing_1",
          "status": "active",
          "photos": []
        }
      ]
    }
  ],
  "total": 42,
  "pages": 5
}

{
  "results": [
    {
      "id": "guide_abc123",
      "contentType": "guide",
      "name": { "en-GB": "Top Restaurants in Shoreditch", "fr-FR": "Les meilleurs restaurants de Shoreditch" },
      "description": { "en-GB": "A curated selection of the best places to eat...", "fr-FR": "Une s\u00e9lection des meilleurs endroits..." },
      "introText": { "en-GB": "Shoreditch is known for its vibrant food scene...", "fr-FR": "Shoreditch est connue pour..." },
      "keywords": { "en-GB": ["restaurants", "food", "shoreditch"], "fr-FR": ["restaurants", "nourriture"] },
      "geoLocation": [51.5247, -0.0755],
      "featured": false,
      "hostIds": ["host_xyz"],
      "listingIds": ["listing_1", "listing_2"],
      "languageCodes": ["en-GB", "fr-FR"],
      "updatedAt": 1739800000000,
      "geoDistance": 1234.5,
      "listings": [
        {
          "id": "listing_1",
          "contentType": "listing",
          "name": { "en-GB": "Padella", "fr-FR": "Padella" },
          "summary": { "en-GB": "Acclaimed pasta restaurant in Borough Market.", "fr-FR": "Restaurant de p\u00e2tes reconnu au Borough Market." },
          "address": { "en-GB": "6 Southwark St, London SE1 1TQ", "fr-FR": "6 Southwark St, London SE1 1TQ" },
          "category": { "en-GB": "restaurant", "fr-FR": "restaurant" },
          "geoLocation": [51.5051, -0.0906],
          "geoDistance": 950.0,
          "featured": false,
          "guideIds": ["guide_abc123"],
          "hostIds": ["host_xyz"],
          "score": 0.89,
          "searchId": "listing_1",
          "status": "active",
          "photos": []
        }
      ]
    }
  ],
  "total": 42,
  "pages": 5
}

Response fields

Field	Type	Description
`results`	array	Array of guide objects (see below).
`total`	integer	Total number of guides matching the query.
`pages`	integer	Total number of pages at the requested `hitsPerPage`.

Guide object

Field	Type	Description
`id`	string	Unique guide identifier.
`contentType`	string	Always `"guide"`.
`name`	string \| object	Guide name. Plain string when `lang` is provided; language map otherwise.
`description`	string \| object	Guide description. Plain string when `lang` is provided; language map otherwise.
`introText`	string \| object	Intro text. Plain string when `lang` is provided; language map otherwise.
`keywords`	array \| object	Keywords. Array when `lang` is provided; language map of arrays otherwise.
`geoLocation`	array	Coordinates as `[latitude, longitude]`.
`coverImage`	object	Cover image with multiple size variants. See Image object.
`featured`	boolean	Whether the guide is featured.
`hostIds`	array	IDs of host profiles associated with this guide.
`listingIds`	array	IDs of listings included in this guide.
`languageCodes`	array	Language codes for which content is available.
`updatedAt`	integer	Last updated timestamp (Unix ms).
`geoDistance`	number	Distance in metres from the requested `latlng` (when provided).
`listings`	array	Embedded listing objects (when `includeListings=true`). Localised fields follow the same `lang` behaviour as top-level listing search results.

Image object

Field	Type	Description
`id`	string	Unique image identifier.
`category`	string	Image category tag.
`attributions`	array	Attribution strings for the image.
`images`	array	Array of `{ size, url }` variant objects.

Overview

Endpoints

Meta

V2 Multilingual

Overview

Localised fields and the `lang` parameter

Request

Required parameters

Optional parameters

Examples

Basic search for an organisation

Geo-filtered search near London

Personalised search for a couple on a leisure trip

Search with a specific language

Search without embedded listings

Response

Response fields

Guide object

Image object

Overview

Endpoints

Meta

V2 Multilingual

​Overview

​Localised fields and the lang parameter

​Request

​Required parameters

​Optional parameters

​Examples

​Basic search for an organisation

​Geo-filtered search near London

​Personalised search for a couple on a leisure trip

​Search with a specific language

​Search without embedded listings

​Response

​Response fields

​Guide object

​Image object

Overview

Localised fields and the `lang` parameter

Request

Required parameters

Optional parameters

Examples

Basic search for an organisation

Geo-filtered search near London

Personalised search for a couple on a leisure trip

Search with a specific language

Search without embedded listings

Response

Response fields

Guide object

Image object