> ## Documentation Index > Fetch the complete documentation index at: https://docs.obvlo.com/llms.txt > Use this file to discover all available pages before exploring further. # Listing Search > Search individual listings — restaurants, attractions, and experiences — with geo, category, and personalisation filters. ## 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 ```http theme={null} 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 ```bash Basic search theme={null} curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/listing-search?key=YOUR_API_KEY" ``` ### Geo-filtered search near Paris ```bash Geo-filtered, near Paris theme={null} 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 ```bash Filter by activity tags theme={null} 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 ```bash Personalised search theme={null} 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 ```bash Ranked by distance theme={null} curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/listing-search?key=YOUR_API_KEY&latlng=51.5074,-0.1278&rankBy=distance" ``` ## Response ```json theme={null} { "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 } ``` ```json theme={null} { "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](#opening-hours-object). | | `photos` | array | Array of photo objects. See [Image object](#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. | ## OpenAPI ````yaml GET /v2/orgs/{orgId}/listing-search openapi: 3.0.3 info: title: Obvlo Content Engine description: Obvlo Content Engine API version: 4.0.0 servers: - url: https://api.obvlo.com security: [] paths: /v2/orgs/{orgId}/listing-search: get: tags: - V2 Multilingual description: >- Search for listings matching criteria. Returns matching listings with localized content. operationId: v2SearchListings parameters: - name: orgId in: path required: true description: Organization Account Number schema: type: string - name: profileId in: query required: false description: Unique profile identifier schema: type: string - name: userCategory in: query required: false description: >- Adding a user category will only return guides that match the category. Possible values: business, family, friends, solo, or couples schema: type: string - name: tripType in: query required: false description: >- Adding a trip type will rank guides based on trip type suitability. Possible values: business, pleasure, or both. Default: both schema: type: string - name: userInterests in: query required: false description: >- Comma-separated list of user interests to rank results by weighted match. Available values can be retrieved from the /getPersonalizationOptions endpoint. schema: type: string - name: page in: query required: false description: Page index used to get next page of responses schema: type: integer - name: hitsPerPage in: query required: false description: Hits per page, maximum 20 schema: type: integer - name: searchQuery in: query required: false description: A text query containing a name and optionally a location schema: type: string - name: radius in: query required: false description: Radius in meters from center of search schema: type: number - name: latlng in: query required: false description: >- Latitude and Longitude as the center of search, comma separated. Ex: 55.953251,-3.188267 schema: type: string - name: rankBy in: query required: false description: 'Ranking strategy. One of: ''distance'', ''relevance'', ''score''' schema: type: string - name: activityTags in: query required: false description: Comma-separated list of activity tags to filter listings schema: type: string - name: lang in: query required: false description: >- BCP-47 language code (e.g. en-GB). When provided, localizable fields are returned as a single string instead of a language map. schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: results: type: array items: type: object properties: activityTags: anyOf: - type: object additionalProperties: type: array items: type: string - type: array items: type: string additionalTextAttributes: anyOf: - type: object additionalProperties: type: object properties: photos: type: string duration: type: string bestTimeToVisit: type: string crowdLevels: type: string gettingThere: type: string additionalProperties: false - type: object properties: photos: type: string duration: type: string bestTimeToVisit: type: string crowdLevels: type: string gettingThere: type: string additionalProperties: false address: anyOf: - type: object additionalProperties: type: string - type: string category: anyOf: - type: object additionalProperties: type: string - type: string contentType: type: string currencyCode: type: string deliveryApps: type: array items: type: object properties: url: type: string type: type: string required: - url - type additionalProperties: false embeds: type: array items: type: object properties: code: type: string type: type: string provider: type: string required: - code - type - provider additionalProperties: false featured: type: boolean geoLocation: type: array items: type: number minItems: 2 maxItems: 2 googleId: type: string googleMapsUrl: type: string googleRating: type: number guideIds: type: array items: type: string hostIds: type: array items: type: string id: type: string integratedCategories: anyOf: - type: object additionalProperties: type: array items: type: object properties: category_id: type: string full_label: type: array items: type: string required: - category_id - full_label additionalProperties: false - type: array items: type: object properties: category_id: type: string full_label: type: array items: type: string required: - category_id - full_label additionalProperties: false keywords: anyOf: - type: object additionalProperties: type: array items: type: string - type: array items: type: string languageCodes: type: array items: type: string name: anyOf: - type: object additionalProperties: type: string - type: string neighborhood: type: string openingHours: type: object properties: isUnavailable: type: boolean nextCloseTime: type: string openNow: type: boolean weekday_text: type: array items: type: string periods: type: array items: type: object properties: open: type: object properties: day: type: number time: type: string hours: type: number minutes: type: number hour: type: number minute: type: number required: - day additionalProperties: false close: type: object properties: day: type: number time: type: string hours: type: number minutes: type: number hour: type: number minute: type: number required: - day additionalProperties: false nullable: true required: - open additionalProperties: false additionalProperties: false phoneNumber: type: string photos: type: array items: type: object properties: attributions: type: array items: type: string category: type: string id: type: string images: type: array items: type: object properties: size: type: string url: type: string required: - size - url additionalProperties: false keywords: type: array items: type: string isGenerated: type: boolean genDescription: type: string license: type: string isLicensed: type: boolean required: - attributions - category - id - images - keywords additionalProperties: false planVisit: anyOf: - type: object additionalProperties: type: string - type: string preferences: anyOf: - type: object additionalProperties: type: object properties: timeOfDay: type: array items: type: string timeOfYear: type: array items: type: string tripType: type: array items: type: string userCategories: type: array items: type: string userInterests: type: array items: type: string weatherType: type: array items: type: string additionalProperties: false - type: object properties: timeOfDay: type: array items: type: string timeOfYear: type: array items: type: string tripType: type: array items: type: string userCategories: type: array items: type: string userInterests: type: array items: type: string weatherType: type: array items: type: string additionalProperties: false priceLevel: type: number priceLevelText: anyOf: - type: object additionalProperties: type: string - type: string priority: type: number score: type: number searchId: type: string searchTerms: type: array items: type: string serviceTypes: type: array items: type: string socialMedia: type: array items: type: object properties: name: type: string url: type: string icon: type: string target: type: string required: - name - url - icon additionalProperties: false status: type: string summary: anyOf: - type: object additionalProperties: type: string - type: string tableBooking: type: object properties: url: type: string type: type: string required: - url - type additionalProperties: false nullable: true tagline: anyOf: - type: object additionalProperties: type: string - type: string tripAdvisorRating: type: number tripAdvisorUrl: type: string websiteUrl: type: string nullable: true whatToExpect: anyOf: - type: object additionalProperties: type: string - type: string geoDistance: type: number additionalData: anyOf: - type: object properties: dateTimestamp: type: number date: type: object properties: start_date: type: string when: type: string required: - start_date - when additionalProperties: false venue: type: object properties: link: type: string name: type: string reviews: type: number required: - link - name - reviews additionalProperties: false ticket_info: type: array items: type: object properties: link: type: string link_type: type: string source: type: string required: - link - link_type - source additionalProperties: false required: - dateTimestamp - date - venue - ticket_info additionalProperties: false - type: object properties: vendor: type: object properties: vendorId: type: number vendorName: type: string vendorUniqueueId: type: number vendorIcon: type: string required: - vendorId - vendorName - vendorUniqueueId additionalProperties: false required: - vendor additionalProperties: false required: - address - contentType - featured - geoLocation - guideIds - hostIds - id - name - photos - score - searchId - status - summary additionalProperties: false total: type: number pages: type: number required: - results - total - pages additionalProperties: false '400': description: No matches security: - api_key: [] components: securitySchemes: api_key: type: apiKey name: key in: query ````