Listing Search - Obvlo Developer Docs

cURL

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

{
  "results": [
    {
      "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}

listing-search

cURL

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

{
  "results": [
    {
      "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/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/orgs/YOUR_ORG_ID/listing-search?key=YOUR_API_KEY"

Geo-filtered search near Paris

Geo-filtered, near Paris

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

Filter by activity tags

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

Personalised search with a specific language

Personalised search

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

Ranked by distance

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

Authorizations

key

string

query

required

Path Parameters

orgId

string

required

Organization Account Number

Query Parameters

profileId

string

Unique profile identifier

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.

page

integer

Page index used to get next page of responses

hitsPerPage

integer

Hits per page, maximum 20

searchQuery

string

A text query containing a name and optionally a location

radius

number

Radius in meters from center of search

latlng

string

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

rankBy

string

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

activityTags

string

Comma-separated list of activity tags to filter listings

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

Guide Search

Location Search

⌘I

​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

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 Paris

Filter by activity tags

Personalised search with a specific language

Ranked by distance

Response

Response fields

Listing object

Opening hours object

Image object