Listing Search

Overview

The /v2/listing-search endpoint returns a paginated list of individual listings from the Obvlo content engine. Listings represent single points of interest such as restaurants, hotels, attractions, or experiences. You can filter by geography, free-text query, activity tags, and guest personalisation attributes.

Localised fields and the `lang` parameter

Several listing fields (name, summary, tagline, address, category, activityTags, keywords, priceLevelText, planVisit, whatToExpect, additionalTextAttributes, preferences, integratedCategories) 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 — a single string (or array/object) for the requested language.	`"summary": "A great place to eat."`
Omitted	Language map — one key per available language code.	`"summary": { "en-GB": "A great place to eat.", "fr-FR": "Un excellent endroit." }`

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

Request

GET /v2/orgs/{orgId}/listing-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 listing names and descriptions.
`latlng`	string	—	Geo-center for proximity ranking. Format: `latitude,longitude` (e.g. `51.5074,-0.1278`).
`radius`	string	—	Search radius in metres around `latlng`.
`page`	string	`"1"`	Page number (1-based).
`hitsPerPage`	string	`"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.
`activityTags`	string	—	Comma-separated activity tags to filter results (e.g. `outdoor,family-friendly`).
`lang`	string	—	BCP 47 language code for localised response fields (e.g. `en`, `fr`, `de`).
`rankBy`	string	`score`	Ranking strategy: `score` (relevance) or `distance` (nearest first, requires `latlng`).

Examples

Basic search for an organisation

Basic search

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

Geo-filtered search near Paris

Geo-filtered, near Paris

curl "https://api.obvlo.com/v2/listing-search?orgId=YOUR_ORG_ID&latlng=48.8566,2.3522&radius=2000&hitsPerPage=10"

Filter by activity tags

curl "https://api.obvlo.com/v2/listing-search?orgId=YOUR_ORG_ID&activityTags=outdoor,family-friendly"

Personalised search with a specific language

Personalised search

curl "https://api.obvlo.com/v2/listing-search?orgId=YOUR_ORG_ID&userCategory=couple&tripType=leisure&lang=en-GB"

Ranked by distance

curl "https://api.obvlo.com/v2/listing-search?orgId=YOUR_ORG_ID&latlng=51.5074,-0.1278&rankBy=distance"

Response

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

{
  "results": [
    {
      "id": "listing_abc123",
      "contentType": "listing",
      "name": "Padella",
      "summary": "Acclaimed pasta restaurant in Borough Market.",
      "tagline": "Hand-rolled pasta made fresh daily.",
      "address": "6 Southwark St, London SE1 1TQ",
      "neighborhood": "Borough Market",
      "category": "restaurant",
      "activityTags": ["food", "casual-dining"],
      "geoLocation": [51.5051, -0.0906],
      "geoDistance": 850.2,
      "googleRating": 4.6,
      "googleMapsUrl": "https://maps.google.com/?q=Padella",
      "priceLevel": 2,
      "priceLevelText": "££",
      "openingHours": {
        "openNow": true,
        "periods": [
          {
            "open": { "day": 1, "time": "1200" },
            "close": { "day": 1, "time": "2145" }
          }
        ]
      },
      "photos": [
        {
          "id": "photo_xyz",
          "category": "food",
          "attributions": ["© Padella"],
          "keywords": [],
          "images": [
            { "size": "small", "url": "https://cdn.obvlo.com/photos/small/photo_xyz.jpg" },
            { "size": "large", "url": "https://cdn.obvlo.com/photos/large/photo_xyz.jpg" }
          ]
        }
      ],
      "languageCodes": ["en-GB", "fr-FR"],
      "featured": false,
      "guideIds": ["guide_abc123"],
      "hostIds": ["host_xyz"],
      "score": 0.92,
      "searchId": "listing_abc123",
      "status": "active"
    }
  ],
  "total": 128,
  "pages": 13
}

{
  "results": [
    {
      "id": "listing_abc123",
      "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." },
      "tagline": { "en-GB": "Hand-rolled pasta made fresh daily.", "fr-FR": "P\u00e2tes faites \u00e0 la main chaque jour." },
      "address": { "en-GB": "6 Southwark St, London SE1 1TQ", "fr-FR": "6 Southwark St, London SE1 1TQ" },
      "neighborhood": "Borough Market",
      "category": { "en-GB": "restaurant", "fr-FR": "restaurant" },
      "activityTags": { "en-GB": ["food", "casual-dining"], "fr-FR": ["food", "casual-dining"] },
      "geoLocation": [51.5051, -0.0906],
      "geoDistance": 850.2,
      "googleRating": 4.6,
      "priceLevel": 2,
      "priceLevelText": { "en-GB": "\u00a3\u00a3", "fr-FR": "\u00a3\u00a3" },
      "photos": [],
      "languageCodes": ["en-GB", "fr-FR"],
      "featured": false,
      "guideIds": ["guide_abc123"],
      "hostIds": ["host_xyz"],
      "score": 0.92,
      "searchId": "listing_abc123",
      "status": "active"
    }
  ],
  "total": 128,
  "pages": 13
}

Response fields

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

Listing object

Field	Type	Description
`id`	string	Unique listing identifier.
`contentType`	string	Always `"listing"`.
`name`	string \| object	Listing name. Plain string when `lang` is provided; language map otherwise.
`summary`	string \| object	Short description. Plain string when `lang` is provided; language map otherwise.
`tagline`	string \| object	One-line tagline. Plain string when `lang` is provided; language map otherwise.
`address`	string \| object	Street address. Plain string when `lang` is provided; language map otherwise.
`neighborhood`	string	Neighbourhood or area name (not localised).
`category`	string \| object	Primary category. Plain string when `lang` is provided; language map otherwise.
`activityTags`	array \| object	Activity tags. Array when `lang` is provided; language map of arrays otherwise.
`geoLocation`	array	Coordinates as `[latitude, longitude]`.
`geoDistance`	number	Distance in metres from the requested `latlng` (when provided).
`googleRating`	number	Google Places rating (0–5).
`googleMapsUrl`	string	Link to Google Maps.
`phoneNumber`	string	Contact phone number.
`websiteUrl`	string	Official website URL.
`priceLevel`	integer	Numeric price level (1–4).
`priceLevelText`	string \| object	Price label (e.g. `££`). Plain string when `lang` is provided; language map otherwise.
`openingHours`	object	Opening hours data. See Opening hours object.
`photos`	array	Array of photo objects. See Image object.
`languageCodes`	array	Language codes for which content is available.
`score`	number	Relevance score (0–1) used for ranking.
`status`	string	Listing status (e.g. `active`).

Opening hours object

Field	Type	Description
`openNow`	boolean	Whether the listing is currently open.
`nextCloseTime`	string	ISO 8601 datetime of next closing time.
`isUnavailable`	boolean	`true` if opening hours data is not available.
`periods`	array	Array of `{ open, close }` period objects.

Each period has open and close objects with:

Field	Type	Description
`day`	integer	Day of week (0 = Sunday, 6 = Saturday).
`time`	string	24h time string without colon (e.g. `"0900"`).

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 Paris

Filter by activity tags

Personalised search with a specific language

Ranked by distance

Response

Response fields

Listing object

Opening hours 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 Paris

​Filter by activity tags

​Personalised search with a specific language

​Ranked by distance

​Response

​Response fields

​Listing object

​Opening hours 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 Paris

Filter by activity tags

Personalised search with a specific language

Ranked by distance

Response

Response fields

Listing object

Opening hours object

Image object