> ## 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. # Guide Search > Search curated travel guides by location, keywords, trip type, and personalisation parameters. ## 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 ```http theme={null} 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 ```bash Basic search theme={null} curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/guide-search?key=YOUR_API_KEY" ``` ### Geo-filtered search near London ```bash Geo-filtered, near London theme={null} 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 ```bash Personalised search theme={null} 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 ```bash With lang parameter theme={null} curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/guide-search?key=YOUR_API_KEY&lang=en-GB" ``` ### Search without embedded listings ```bash Without embedded listings theme={null} curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/guide-search?key=YOUR_API_KEY&includeListings=false" ``` ## Response ```json theme={null} { "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 } ``` ```json theme={null} { "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](#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. | ## OpenAPI ````yaml GET /v2/orgs/{orgId}/guide-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}/guide-search: get: tags: - V2 Multilingual description: >- Search for guides matching criteria. Returns matching guides with optional nested listings. operationId: v2SearchGuides 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: searchQuery in: query required: false description: A text query containing a name and optionally a location 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: 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: radius in: query required: false description: Radius in meters from center of search schema: type: number - 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: includeListings in: query required: false description: Whether to include listings in the guide response schema: type: boolean - name: maxListingsPerGuide in: query required: false description: Maximum number of listings to include per guide schema: type: integer - name: rankBy in: query required: false description: 'Ranking strategy. One of: ''distance'', ''relevance'', ''score''' 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: attribution: anyOf: - type: object additionalProperties: type: string - type: string centerLocation: anyOf: - type: object additionalProperties: type: string - type: string contentType: type: string coverImage: 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 description: anyOf: - type: object additionalProperties: type: string - type: string featured: default: false type: boolean geoLocation: type: array items: type: number minItems: 2 maxItems: 2 hostIds: type: array items: type: string id: type: string introText: anyOf: - type: object additionalProperties: type: string - type: string keywords: anyOf: - type: object additionalProperties: type: array items: type: string - type: array items: type: string languageCodes: type: array items: type: string listingIds: type: array items: type: string name: 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 priority: type: number minimum: 0 status: type: string updatedAt: type: number geoDistance: type: number listings: 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 required: - contentType - description - featured - geoLocation - hostIds - id - keywords - languageCodes - listingIds - name - updatedAt 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 ````