Skip to main content

​
Overview

The /v2/host-home endpoint is designed to power the initial load of a host-scoped experience. A single request returns everything needed to render the home screen:
  • The host profile (branding, search config, embedded UI config, location anchor)
  • The first page of guides, each with nested listings
  • A page of geo areas (neighbourhoods) scoped to the host
Geo defaults and search radius are resolved from the host profile automatically. Pass latlng to override the geo centre (for example, to centre results on the guest’s current location), or radius to override the search radius. Preference filters (userCategory, tripType, userInterests) are applied to both guide and listing ranking.

​
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. Geo area (location) fields (displayName, headline, description, address, area, keywords) also carry translated content. The shape of these fields depends on whether lang is provided:
langField shapeExample
Provided (e.g. lang=en-GB)Plain value for the requested language."name": "Top Restaurants in Shoreditch"
OmittedLanguage 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}/host-home

​
Required parameters

ParameterTypeDescription
orgIdstringYour organisation ID.
profileIdstringID of the host profile.

​
Optional parameters

ParameterTypeDefaultDescription
langstring—BCP 47 language code (e.g. en-GB, fr-FR). When provided, localised fields in guides, their embedded listings, and geo areas are returned as plain values for that language instead of language maps.
latlngstring—Geo centre override as lat,lng (e.g. 51.508,-0.125). Defaults to the host’s stored location.
radiusinteger—Search radius in metres from the geo centre. Defaults to the host’s configured search radius.
guideTypestring—Filter guides by type. featured returns only featured guides; omit to return all guides.
userCategorystring—Filter by user category (e.g. couple, family, solo).
tripTypestring—Filter by trip type (e.g. leisure, business).
userInterestsstring—Comma-separated interest tags for personalised ranking.
rankBystringscoreRanking strategy for guides and listings: score, distance, or relevance.
guidesPageinteger1Page number for guide results (1-based).
guidesPerPageinteger10Number of guides per page. Maximum 20.
maxListingsPerGuideinteger20Maximum number of listings embedded per guide. Maximum 20.
geoareasPageinteger1Page number for geo area results (1-based).
geoareasPerPageinteger10Number of geo areas per page. Maximum 20.

​
Examples

​
Basic home screen load

Basic home screen load
curl "https://api.obvlo.com/v2/host-home?orgId=YOUR_ORG_ID&profileId=YOUR_HOST_ID&key=YOUR_API_KEY"

​
Geo-anchored load centred on the guest’s location

Geo-anchored load
curl "https://api.obvlo.com/v2/host-home?orgId=YOUR_ORG_ID&profileId=YOUR_HOST_ID&latlng=51.508,-0.125&radius=3000&key=YOUR_API_KEY"
Featured guides only
curl "https://api.obvlo.com/v2/host-home?orgId=YOUR_ORG_ID&profileId=YOUR_HOST_ID&guideType=featured&lang=en-GB&key=YOUR_API_KEY"

​
Personalised load for a couple on a leisure trip

Personalised load
curl "https://api.obvlo.com/v2/host-home?orgId=YOUR_ORG_ID&profileId=YOUR_HOST_ID&userCategory=couple&tripType=leisure&userInterests=food,culture&key=YOUR_API_KEY"

​
Example response

Example response
{
  "host": {
    "id": "hotel-grand",
    "name": "The Grand Hotel",
    "orgId": "YOUR_ORG_ID",
    "geoLocation": [51.5074, -0.1278],
    "primaryLocation": {
      "displayName": "The Grand Hotel",
      "address": "1 Grand Place, London",
      "locationId": "loc-001",
      "measurement": "metric"
    },
    "searchConfig": { "searchRadius": 4000 },
    "embeddedConfigs": [
      {
        "id": "embed-config-001",
        "name": "Default Widget",
        "createdAt": 1700000000000,
        "selectedLayout": "Default"
      }
    ],
    "currencyCode": "GBP",
    "currencySymbol": "£",
    "timeZoneName": "Europe/London"
  },
  "guides": {
    "results": [
      {
        "id": "guide-001",
        "name": { "en-GB": "Top Restaurants" },
        "description": { "en-GB": "The best places to eat in London." },
        "geoLocation": [51.508, -0.125],
        "geoDistance": 850,
        "listings": [
          {
            "id": "listing-001",
            "contentType": "listing",
            "name": { "en-GB": "Sketch" },
            "summary": { "en-GB": "An iconic multi-room restaurant and arts venue." },
            "address": { "en-GB": "9 Conduit St, London W1S 2XG" },
            "geoLocation": [51.511, -0.142],
            "geoDistance": 1200,
            "featured": false,
            "guideIds": ["guide-001"],
            "hostIds": ["hotel-grand"],
            "score": 0.91,
            "searchId": "listing-001",
            "status": "active",
            "photos": []
          }
        ]
      }
    ],
    "total": 12,
    "pages": 2
  },
  "geoareas": {
    "results": [
      {
        "id": "area-001",
        "displayName": { "en-GB": "Soho" },
        "description": { "en-GB": "A vibrant neighbourhood known for its nightlife and culture." },
        "geoLocation": [51.513, -0.131],
        "geoDistance": 1400
      }
    ],
    "total": 5,
    "pages": 1
  }
}

​
Response fields

​
Top-level

FieldTypeDescription
hostobjectHost profile, including embeddedConfigs. See Get Host Profile for full field reference.
guidesobjectPaginated guide results with nested listings.
geoareasobjectPaginated geo area (neighbourhood) results scoped to the host.

​
guides

FieldTypeDescription
resultsobject[]Array of guide objects, each containing a listings array of embedded listing objects.
totalintegerTotal number of matching guides.
pagesintegerTotal number of pages.
Each guide and its embedded listings follow the same shapes as the Guide Search endpoint.

​
geoareas

FieldTypeDescription
resultsobject[]Array of geo area objects (neighbourhoods).
totalintegerTotal number of geo areas for this host.
pagesintegerTotal number of pages.
Each geo area follows the same shape as the Location Search endpoint.
When lang is omitted, all localised fields are returned as language maps with at least the default language (en-GB) present. If a translation is missing for the requested lang, the response falls back to the host’s default language.