Skip to main content

​
Overview

The /v2/location-search endpoint returns a paginated list of geographic locations from the Obvlo content engine. Locations represent areas of interest such as neighbourhoods, districts, or city zones. You can filter by proximity and search by keyword.

​
Localised fields and the lang parameter

The fields displayName, headline, description, address, area, and keywords 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."displayName": "Shoreditch"
OmittedLanguage map — one key per available language code."displayName": { "en-GB": "Shoreditch" }
When lang is omitted, at least the default language (en-GB) is always included in the map.

​
Request

GET /v2/orgs/{orgId}/location-search

​
Required parameters

ParameterTypeDescription
orgIdstringYour organisation ID.

​
Optional parameters

ParameterTypeDefaultDescription
profileIdstring—Scope results to a specific host profile.
searchQuerystring—Full-text query matched against location names and descriptions.
latlngstring—Geo-center for proximity filtering. Format: latitude,longitude (e.g. 51.5074,-0.1278).
radiusnumberProfile defaultSearch radius in metres around latlng.
pageinteger1Page number (1-based).
hitsPerPageinteger10Results per page. Maximum 20.
rankBystringdistanceRanking strategy: distance (nearest first, requires latlng) or score (relevance).
langstring—BCP 47 language code (e.g. en-GB). When provided, localised fields are returned as plain values instead of language maps.

​
Examples

​
Basic search for an organisation

Basic search
curl "https://api.obvlo.com/v2/location-search?orgId=YOUR_ORG_ID&key=YOUR_API_KEY"

​
Geo-filtered search near London

Geo-filtered, near London
curl "https://api.obvlo.com/v2/location-search?orgId=YOUR_ORG_ID&latlng=51.5074,-0.1278&radius=10000&hitsPerPage=5&key=YOUR_API_KEY"

​
Text search anchored to a host profile

Text search
curl "https://api.obvlo.com/v2/location-search?orgId=YOUR_ORG_ID&profileId=YOUR_PROFILE_ID&searchQuery=shoreditch&key=YOUR_API_KEY"

​
Sort by relevance instead of distance

Sort by relevance
curl "https://api.obvlo.com/v2/location-search?orgId=YOUR_ORG_ID&profileId=YOUR_PROFILE_ID&rankBy=score&key=YOUR_API_KEY"

​
Search with a specific language

With parameter
curl "https://api.obvlo.com/v2/location-search?orgId=YOUR_ORG_ID&lang=en-GB&key=YOUR_API_KEY"

​
Response

{
  "results": [
    {
      "id": "location_abc123",
      "hostIds": ["host_xyz"],
      "status": "published",
      "displayName": "Shoreditch",
      "headline": "London's creative quarter",
      "description": "A vibrant neighbourhood in east London known for its street art and independent restaurants.",
      "address": "Shoreditch, London, UK",
      "area": "East London",
      "keywords": ["street art", "bars", "restaurants", "nightlife"],
      "geoLocation": [51.5246, -0.0771],
      "geoDistance": 850.3,
      "radius": 1200,
      "languageCodes": ["en-GB", "fr-FR"],
      "photos": [
        {
          "id": "photo_1",
          "category": "exterior",
          "attributions": [],
          "keywords": [],
          "images": [
            { "size": "lg", "url": "https://cdn.obvlo.com/photos/photo_1_lg.jpg" }
          ]
        }
      ]
    }
  ],
  "total": 12,
  "pages": 2
}

​
Response fields

FieldTypeDescription
resultsarrayArray of matching location objects.
totalintegerTotal number of matching locations.
pagesintegerTotal number of pages.

​
Location object fields

FieldTypeDescription
idstringUnique location identifier.
hostIdsstring[]Host profiles this location belongs to.
statusstringPublication status (always published in API responses).
displayNamestring | objectLocation name. Plain string when lang is provided; language map otherwise.
headlinestring | objectShort headline. Plain string when lang is provided; language map otherwise.
descriptionstring | objectDescription. Plain string when lang is provided; language map otherwise.
addressstring | objectAddress. Plain string when lang is provided; language map otherwise.
areastring | objectArea or district name. Plain string when lang is provided; language map otherwise.
keywordsarray | objectKeywords. Array when lang is provided; language map of arrays otherwise.
geoLocation[number, number]Coordinates as [latitude, longitude].
geoDistancenumberDistance in metres from the latlng centre (present when latlng is provided).
radiusnumberRadius of the location area in metres.
languageCodesstring[]Language codes available for this location.
photosarrayArray of photo objects. Each has id, category, attributions, keywords, and images.