Location Search

cURL

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

import requests

url = "https://api.obvlo.com/v2/orgs/{orgId}/location-search?key="

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.obvlo.com/v2/orgs/{orgId}/location-search?key=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "results": [
    {
      "id": "<string>",
      "hostIds": [
        "<string>"
      ],
      "status": "<string>",
      "geoLocation": [
        123
      ],
      "address": {},
      "displayName": {},
      "area": {},
      "headline": {},
      "description": {},
      "keywords": {},
      "photos": [
        {
          "attributions": [
            "<string>"
          ],
          "category": "<string>",
          "id": "<string>",
          "images": [
            {
              "size": "<string>",
              "url": "<string>"
            }
          ],
          "keywords": [
            "<string>"
          ],
          "isGenerated": true,
          "genDescription": "<string>",
          "license": "<string>",
          "isLicensed": true
        }
      ],
      "radius": 123,
      "languageCodes": [
        "<string>"
      ],
      "geoDistance": 123
    }
  ],
  "total": 123,
  "pages": 123
}

GET

orgs

{orgId}

location-search

cURL

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

import requests

url = "https://api.obvlo.com/v2/orgs/{orgId}/location-search?key="

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.obvlo.com/v2/orgs/{orgId}/location-search?key=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "results": [
    {
      "id": "<string>",
      "hostIds": [
        "<string>"
      ],
      "status": "<string>",
      "geoLocation": [
        123
      ],
      "address": {},
      "displayName": {},
      "area": {},
      "headline": {},
      "description": {},
      "keywords": {},
      "photos": [
        {
          "attributions": [
            "<string>"
          ],
          "category": "<string>",
          "id": "<string>",
          "images": [
            {
              "size": "<string>",
              "url": "<string>"
            }
          ],
          "keywords": [
            "<string>"
          ],
          "isGenerated": true,
          "genDescription": "<string>",
          "license": "<string>",
          "isLicensed": true
        }
      ],
      "radius": 123,
      "languageCodes": [
        "<string>"
      ],
      "geoDistance": 123
    }
  ],
  "total": 123,
  "pages": 123
}

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:

`lang`	Field shape	Example
Provided (e.g. `lang=en-GB`)	Plain value for the requested language.	`"displayName": "Shoreditch"`
Omitted	Language 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

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 location names and descriptions.
`latlng`	string	—	Geo-center for proximity filtering. 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`.
`rankBy`	string	`distance`	Ranking strategy: `distance` (nearest first, requires `latlng`) or `score` (relevance).
`lang`	string	—	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/orgs/YOUR_ORG_ID/location-search?key=YOUR_API_KEY"

Geo-filtered search near London

Geo-filtered, near London

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

Text search anchored to a host profile

Text search

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

Sort by relevance instead of distance

Sort by relevance

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

Search with a specific language

With parameter

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

Response

With lang=en-GB
Without lang (language map)

{
  "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
}

{
  "results": [
    {
      "id": "location_abc123",
      "hostIds": ["host_xyz"],
      "status": "published",
      "displayName": { "en-GB": "Shoreditch", "fr-FR": "Shoreditch" },
      "headline": { "en-GB": "London's creative quarter", "fr-FR": "Le quartier cr\u00e9atif de Londres" },
      "description": { "en-GB": "A vibrant neighbourhood in east London...", "fr-FR": "Un quartier dynamique dans l'est de Londres..." },
      "address": { "en-GB": "Shoreditch, London, UK", "fr-FR": "Shoreditch, Londres, Royaume-Uni" },
      "area": { "en-GB": "East London", "fr-FR": "Est de Londres" },
      "keywords": { "en-GB": ["street art", "bars", "restaurants", "nightlife"], "fr-FR": ["art de rue", "bars", "restaurants"] },
      "geoLocation": [51.5246, -0.0771],
      "geoDistance": 850.3,
      "radius": 1200,
      "languageCodes": ["en-GB", "fr-FR"],
      "photos": []
    }
  ],
  "total": 12,
  "pages": 2
}

Response fields

Field	Type	Description
`results`	array	Array of matching location objects.
`total`	integer	Total number of matching locations.
`pages`	integer	Total number of pages.

Location object fields

Field	Type	Description
`id`	string	Unique location identifier.
`hostIds`	string[]	Host profiles this location belongs to.
`status`	string	Publication status (always `published` in API responses).
`displayName`	string \| object	Location name. Plain string when `lang` is provided; language map otherwise.
`headline`	string \| object	Short headline. Plain string when `lang` is provided; language map otherwise.
`description`	string \| object	Description. Plain string when `lang` is provided; language map otherwise.
`address`	string \| object	Address. Plain string when `lang` is provided; language map otherwise.
`area`	string \| object	Area or district name. Plain string when `lang` is provided; language map otherwise.
`keywords`	array \| object	Keywords. Array when `lang` is provided; language map of arrays otherwise.
`geoLocation`	[number, number]	Coordinates as `[latitude, longitude]`.
`geoDistance`	number	Distance in metres from the `latlng` centre (present when `latlng` is provided).
`radius`	number	Radius of the location area in metres.
`languageCodes`	string[]	Language codes available for this location.
`photos`	array	Array of photo objects. Each has `id`, `category`, `attributions`, `keywords`, and `images`.

Authorizations

key

string

query

required

Path Parameters

orgId

string

required

Organization Account Number

Query Parameters

profileId

string

Unique profile identifier

searchQuery

string

A text query containing a name and optionally a location

page

integer

Page index used to get next page of responses

hitsPerPage

integer

Hits per page, maximum 20

latlng

string

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

radius

number

Radius in meters from center of search

rankBy

string

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

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

Listing Search

Get Site Page Slugs

⌘I

Getting started

API

API reference

Widget implementation

Microsite implementation

Infrastructure guides

Language support

Preview

Overview

Localised fields and the `lang` parameter

Request

Required parameters

Optional parameters

Examples

Basic search for an organisation

Geo-filtered search near London

Text search anchored to a host profile

Sort by relevance instead of distance

Search with a specific language

Response

Response fields

Location object fields

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 London

​Text search anchored to a host profile

​Sort by relevance instead of distance

​Search with a specific language

​Response

​Response fields

​Location object fields

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 London

Text search anchored to a host profile

Sort by relevance instead of distance

Search with a specific language

Response

Response fields

Location object fields