> ## 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. # Location Search > Search geographic locations such as neighbourhoods, districts, and areas of interest by proximity and keyword. ## 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 ```http theme={null} 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 ```bash Basic search theme={null} curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/location-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/location-search?key=YOUR_API_KEY&latlng=51.5074,-0.1278&radius=10000&hitsPerPage=5" ``` ### Text search anchored to a host profile ```bash Text search theme={null} 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 ```bash Sort by relevance theme={null} 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 ```bash With lang parameter theme={null} curl "https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/location-search?key=YOUR_API_KEY&lang=en-GB" ``` ## Response ```json theme={null} { "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 } ``` ```json theme={null} { "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`. | ## OpenAPI ````yaml GET /v2/orgs/{orgId}/location-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}/location-search: get: tags: - V2 Multilingual description: >- Search for locations matching criteria. Returns matching locations (neighbourhoods, districts, areas) with localized content. operationId: v2SearchLocations 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: 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: id: type: string hostIds: type: array items: type: string address: anyOf: - type: object additionalProperties: type: string - type: string displayName: anyOf: - type: object additionalProperties: type: string - type: string area: anyOf: - type: object additionalProperties: type: string - type: string headline: anyOf: - type: object additionalProperties: type: string - type: string description: anyOf: - type: object additionalProperties: type: string - type: string keywords: anyOf: - type: object additionalProperties: type: array items: type: string - type: array items: 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 radius: type: number status: type: string languageCodes: type: array items: type: string geoLocation: type: array items: type: number minItems: 2 maxItems: 2 geoDistance: type: number required: - id - hostIds - status - geoLocation 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 ````