Guide Search

cURL

curl --request GET \
  --url 'https://api.obvlo.com/v2/orgs/{orgId}/guide-search?key='

{
  "results": [
    {
      "contentType": "<string>",
      "description": {},
      "featured": false,
      "geoLocation": [
        123
      ],
      "hostIds": [
        "<string>"
      ],
      "id": "<string>",
      "keywords": {},
      "languageCodes": [
        "<string>"
      ],
      "listingIds": [
        "<string>"
      ],
      "name": {},
      "updatedAt": 123,
      "attribution": "<string>",
      "centerLocation": "<string>",
      "coverImage": {
        "attributions": [
          "<string>"
        ],
        "category": "<string>",
        "id": "<string>",
        "images": [
          {
            "size": "<string>",
            "url": "<string>"
          }
        ],
        "keywords": [
          "<string>"
        ],
        "isGenerated": true,
        "genDescription": "<string>",
        "license": "<string>",
        "isLicensed": true
      },
      "introText": {},
      "preferences": {},
      "priority": 1,
      "status": "<string>",
      "geoDistance": 123,
      "listings": [
        {
          "address": {},
          "contentType": "<string>",
          "featured": true,
          "geoLocation": [
            123
          ],
          "guideIds": [
            "<string>"
          ],
          "hostIds": [
            "<string>"
          ],
          "id": "<string>",
          "name": {},
          "photos": [
            {
              "attributions": [
                "<string>"
              ],
              "category": "<string>",
              "id": "<string>",
              "images": [
                {
                  "size": "<string>",
                  "url": "<string>"
                }
              ],
              "keywords": [
                "<string>"
              ],
              "isGenerated": true,
              "genDescription": "<string>",
              "license": "<string>",
              "isLicensed": true
            }
          ],
          "score": 123,
          "searchId": "<string>",
          "status": "<string>",
          "summary": {},
          "activityTags": {},
          "additionalTextAttributes": {},
          "category": {},
          "currencyCode": "<string>",
          "deliveryApps": [
            {
              "url": "<string>",
              "type": "<string>"
            }
          ],
          "embeds": [
            {
              "code": "<string>",
              "type": "<string>",
              "provider": "<string>"
            }
          ],
          "googleId": "<string>",
          "googleMapsUrl": "<string>",
          "googleRating": 123,
          "integratedCategories": {},
          "keywords": {},
          "languageCodes": [
            "<string>"
          ],
          "neighborhood": "<string>",
          "openingHours": {
            "isUnavailable": true,
            "nextCloseTime": "<string>",
            "openNow": true,
            "weekday_text": [
              "<string>"
            ],
            "periods": [
              {
                "open": {
                  "day": 123,
                  "time": "<string>",
                  "hours": 123,
                  "minutes": 123,
                  "hour": 123,
                  "minute": 123
                },
                "close": {
                  "day": 123,
                  "time": "<string>",
                  "hours": 123,
                  "minutes": 123,
                  "hour": 123,
                  "minute": 123
                }
              }
            ]
          },
          "phoneNumber": "<string>",
          "planVisit": {},
          "preferences": {},
          "priceLevel": 123,
          "priceLevelText": {},
          "priority": 123,
          "searchTerms": [
            "<string>"
          ],
          "serviceTypes": [
            "<string>"
          ],
          "socialMedia": [
            {
              "name": "<string>",
              "url": "<string>",
              "icon": "<string>",
              "target": "<string>"
            }
          ],
          "tableBooking": {
            "url": "<string>",
            "type": "<string>"
          },
          "tagline": {},
          "tripAdvisorRating": 123,
          "tripAdvisorUrl": "<string>",
          "websiteUrl": "<string>",
          "whatToExpect": {},
          "geoDistance": 123,
          "additionalData": {
            "dateTimestamp": 123,
            "date": {
              "start_date": "<string>",
              "when": "<string>"
            },
            "venue": {
              "link": "<string>",
              "name": "<string>",
              "reviews": 123
            },
            "ticket_info": [
              {
                "link": "<string>",
                "link_type": "<string>",
                "source": "<string>"
              }
            ]
          }
        }
      ]
    }
  ],
  "total": 123,
  "pages": 123
}

GET

orgs

{orgId}

guide-search

cURL

curl --request GET \
  --url 'https://api.obvlo.com/v2/orgs/{orgId}/guide-search?key='

{
  "results": [
    {
      "contentType": "<string>",
      "description": {},
      "featured": false,
      "geoLocation": [
        123
      ],
      "hostIds": [
        "<string>"
      ],
      "id": "<string>",
      "keywords": {},
      "languageCodes": [
        "<string>"
      ],
      "listingIds": [
        "<string>"
      ],
      "name": {},
      "updatedAt": 123,
      "attribution": "<string>",
      "centerLocation": "<string>",
      "coverImage": {
        "attributions": [
          "<string>"
        ],
        "category": "<string>",
        "id": "<string>",
        "images": [
          {
            "size": "<string>",
            "url": "<string>"
          }
        ],
        "keywords": [
          "<string>"
        ],
        "isGenerated": true,
        "genDescription": "<string>",
        "license": "<string>",
        "isLicensed": true
      },
      "introText": {},
      "preferences": {},
      "priority": 1,
      "status": "<string>",
      "geoDistance": 123,
      "listings": [
        {
          "address": {},
          "contentType": "<string>",
          "featured": true,
          "geoLocation": [
            123
          ],
          "guideIds": [
            "<string>"
          ],
          "hostIds": [
            "<string>"
          ],
          "id": "<string>",
          "name": {},
          "photos": [
            {
              "attributions": [
                "<string>"
              ],
              "category": "<string>",
              "id": "<string>",
              "images": [
                {
                  "size": "<string>",
                  "url": "<string>"
                }
              ],
              "keywords": [
                "<string>"
              ],
              "isGenerated": true,
              "genDescription": "<string>",
              "license": "<string>",
              "isLicensed": true
            }
          ],
          "score": 123,
          "searchId": "<string>",
          "status": "<string>",
          "summary": {},
          "activityTags": {},
          "additionalTextAttributes": {},
          "category": {},
          "currencyCode": "<string>",
          "deliveryApps": [
            {
              "url": "<string>",
              "type": "<string>"
            }
          ],
          "embeds": [
            {
              "code": "<string>",
              "type": "<string>",
              "provider": "<string>"
            }
          ],
          "googleId": "<string>",
          "googleMapsUrl": "<string>",
          "googleRating": 123,
          "integratedCategories": {},
          "keywords": {},
          "languageCodes": [
            "<string>"
          ],
          "neighborhood": "<string>",
          "openingHours": {
            "isUnavailable": true,
            "nextCloseTime": "<string>",
            "openNow": true,
            "weekday_text": [
              "<string>"
            ],
            "periods": [
              {
                "open": {
                  "day": 123,
                  "time": "<string>",
                  "hours": 123,
                  "minutes": 123,
                  "hour": 123,
                  "minute": 123
                },
                "close": {
                  "day": 123,
                  "time": "<string>",
                  "hours": 123,
                  "minutes": 123,
                  "hour": 123,
                  "minute": 123
                }
              }
            ]
          },
          "phoneNumber": "<string>",
          "planVisit": {},
          "preferences": {},
          "priceLevel": 123,
          "priceLevelText": {},
          "priority": 123,
          "searchTerms": [
            "<string>"
          ],
          "serviceTypes": [
            "<string>"
          ],
          "socialMedia": [
            {
              "name": "<string>",
              "url": "<string>",
              "icon": "<string>",
              "target": "<string>"
            }
          ],
          "tableBooking": {
            "url": "<string>",
            "type": "<string>"
          },
          "tagline": {},
          "tripAdvisorRating": 123,
          "tripAdvisorUrl": "<string>",
          "websiteUrl": "<string>",
          "whatToExpect": {},
          "geoDistance": 123,
          "additionalData": {
            "dateTimestamp": 123,
            "date": {
              "start_date": "<string>",
              "when": "<string>"
            },
            "venue": {
              "link": "<string>",
              "name": "<string>",
              "reviews": 123
            },
            "ticket_info": [
              {
                "link": "<string>",
                "link_type": "<string>",
                "source": "<string>"
              }
            ]
          }
        }
      ]
    }
  ],
  "total": 123,
  "pages": 123
}

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`	boolean	`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/orgs/YOUR_ORG_ID/guide-search?key=YOUR_API_KEY"

Geo-filtered search near London

Geo-filtered, near London

curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/guide-search?key=YOUR_API_KEY&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/orgs/YOUR_ORG_ID/guide-search?key=YOUR_API_KEY&userCategory=couple&tripType=leisure&userInterests=food,culture"

Search with a specific language

With parameter

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

Search without embedded listings

Without embedded listings

curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/guide-search?key=YOUR_API_KEY&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.

Authorizations

key

string

query

required

Path Parameters

orgId

string

required

Organization Account Number

Query Parameters

profileId

string

Unique profile identifier

searchQuery

string

A text query containing a name and optionally a location

page

integer

Page index used to get next page of responses

hitsPerPage

integer

Hits per page, maximum 20

latlng

string

Latitude and Longitude as the center of search, comma separated. Ex: 55.953251,-3.188267

radius

number

Radius in meters from center of search

userCategory

string

Adding a user category will only return guides that match the category. Possible values: business, family, friends, solo, or couples

tripType

string

Adding a trip type will rank guides based on trip type suitability. Possible values: business, pleasure, or both. Default: both

userInterests

string

Comma-separated list of user interests to rank results by weighted match. Available values can be retrieved from the /getPersonalizationOptions endpoint.

includeListings

boolean

Whether to include listings in the guide response

maxListingsPerGuide

integer

Maximum number of listings to include per guide

rankBy

string

Ranking strategy. One of: 'distance', 'relevance', 'score'

lang

string

BCP-47 language code (e.g. en-GB). When provided, localizable fields are returned as a single string instead of a language map.

Response

Success

results

object[]

required

Show child attributes

total

number

required

pages

number

required

API Reference

Listing Search

⌘I

Getting started

API

API reference

Widget implementation

Microsite implementation

Language support

Preview

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

Authorizations

Path Parameters

Query Parameters

Response

Getting started

API

API reference

Widget implementation

Microsite implementation

Language support

Preview

​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

Authorizations

Path Parameters

Query Parameters

Response

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