# Locations search

## Search locations

Search locations using a geo-search query (City, State, Postal code) or using specific latitude and longitude coordinates. 

Locations are sorted by distance from the searched location.

`GET /_api/locations_search/`

### Search examples

#### Search with geo query - search string

`GET /_api/locations_search/?near_location=Seattle,%20WA`

#### Search with geo postal code query

`GET /_api/locations_search/?near_location=98121`

#### Search with latitude/longitude coordinates

`GET /_api/locations_search/?near_lat=39.8281&near_lon=-98.5795` 

### Filtering examples

#### Filtering by city

`GET /_api/locations_search/?city=Seattle`

#### Filtering by internal Customer ID

`GET /_api/locations_search/?partner_location_sub_id=CH104`

### Parameters

<table><thead><tr><th width="270">Name</th><th width="131.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>near_location</code></td><td>string</td><td>Geographic search query. Can take any input that could be passed to Google Geocoding including city, state, full address or postal code</td></tr><tr><td><code>near_lat</code></td><td>float</td><td><p>Example: <code>39.8281</code></p><p></p><p>Used in combination with <code>near_lon</code></p></td></tr><tr><td><code>near_lon</code></td><td>float</td><td><p>Example: <code>-98.5795</code></p><p></p><p>Used in combination with <code>near_lat</code></p></td></tr><tr><td><code>limit</code></td><td>integer</td><td>Number of locations to return</td></tr><tr><td><code>threshold</code></td><td>integer</td><td>Distance in <code>distance_unit</code> (miles/km) to restrict location search results</td></tr><tr><td><code>distance_unit</code></td><td>string</td><td><code>miles</code> (default) or <code>km</code></td></tr><tr><td><code>postal_code_match_type</code></td><td>string</td><td><p>Matching to location assigned postal code territories</p><p></p><p>Options:<br>- <code>only</code>: This will only return locations that have postal codes assigned that match<br>- <code>first</code>: This will return matching locations, but if no locations are assigned the postal code then normal geo-distance searched results will be returned</p></td></tr><tr><td><code>prefix</code></td><td>string</td><td><p>Passed as <code>prefix=true</code> - Enables canadian postal code prefix searching.</p><p></p><p>Used in combination with <code>postal_code_match_type</code><br><br>Example: <code>L0P 1B0</code> would match territory assignment in DevHub of <code>L0P</code></p></td></tr><tr><td><code>city</code></td><td>string</td><td>Filter results by city</td></tr><tr><td><code>state</code></td><td>string</td><td>Filter results by state code (i.e. <code>WA</code>)</td></tr><tr><td><code>country</code></td><td>string</td><td>Filter results by country code (i.e. <code>US</code>)</td></tr><tr><td><code>partner_location_sub_id</code></td><td>string</td><td>Filter results by internal customer ID field</td></tr></tbody></table>

### Response

Locations are returned within `objects`. If no locations are matched, `objects` will be an empty list.

For list of attributes returned for each location, see [Location model](/core-resources/locations.md#location-model)

```
{
    "meta": {
        "total_count": 25
        ...
    },
    "objects": [
        {...Location object...},
        {...Location object...},
    ]
}
```

The response will also contain distance details for each location and distance context.

In the resulting response `meta` we will add the latitude and longitude of the searched point for reference.

```json
{
    "meta": {
        "lat": 47.6062095,
        "lon": -122.3320708,
        ...
    }
}
```

In each of the the resulting Location objects, we add `distance` (in miles or km depending on `distance_unit`).

```javascript
"objects": [{
    "id": 123456,
    "location_name": "Belltown",
    ...
    "distance": 996.79
}]
```

## Additional examples

### Requesting additional "extra" formatted responses

We have addtiional utilities available to add additional properties to the Locations response. Specifically around auto-formatting options for Hours of operation and other data points that are helpful when rendering Location information

#### Passing extras example

Extras are passed as a comma separated list

`GET /_api/locations_search/?city=Seattle&extras=closes_next,is_open`

<table><thead><tr><th width="183.8914794921875">Extra option</th><th width="282">Description</th><th>Variable reference within Location</th></tr></thead><tbody><tr><td><code>closes_next</code></td><td>Formatted time string when the location closes for the current day in local time.<br><br>Example: <code>7:00 PM</code></td><td><code>formatted_hours.primary.today.closes_next</code></td></tr><tr><td><code>is_open</code></td><td>Is the Location currently open based on hours and timezone.<br><br>Example: <code>true</code></td><td><code>formatted_hours.primary.today.is_open</code></td></tr><tr><td><code>hours_days</code></td><td>Formatted hours of operation ranges for each day for the week and today, including day labels<br><br>Example:<br><code>{</code><br>    <code>"content": "8:00 AM - 7:00 PM",</code><br>    <code>"label_abbr": "Mon",</code><br>    <code>"label": "Monday"</code><br><code>}</code></td><td><code>formatted_hours.primary.days</code><br><br><code>formatted_hours.primary.today</code></td></tr><tr><td><code>hours_grouped</code></td><td>Similar to <code>hours_days</code>, but serial days with the same hours are grouped together.<br><br>Example:<br><code>{</code><br>    <code>"content": "8:00 AM - 7:00 PM",</code><br>    <code>"label_abbr": "Mon - Fri",</code><br>    <code>"label": "Monday - Friday"</code><br><code>}</code></td><td><code>formatted_hours.primary.grouped_days</code><br><br><code>formatted_hours.primary.today</code></td></tr><tr><td><code>todays_hours_of_operation</code></td><td>Hours of operation ranges for the current day<br><br>Example: <code>8:00 AM - 7:00 PM</code></td><td><code>todays_hours_of_operation</code></td></tr><tr><td><code>closes_opens_next</code></td><td><p>Information about when the Location closes next, or if it is currently closed, what is the next day and time do they open<br><br>Example of a current open location, but closes at 7pm local time<br><code>{</code><br>  <code>"action": "closes",</code><br>  <code>"date": "2026-05-11",</code><br>  <code>"day": "Monday"</code><br>  <code>"day_abbr": "Mon",</code><br>  <code>"is_today": true,</code><br>  <code>"time": "7:00 PM"</code><br><code>}</code><br></p><p>Example of a closed location, but opens on Wednesday at 9am local time<br><code>{</code><br>  <code>"action": "opens",</code><br>  <code>"date": "2026-05-13",</code><br>  <code>"day": "Wednesday"</code><br>  <code>"day_abbr": "Wed",</code><br>  <code>"is_today": false,</code><br>  <code>"time": "9:00 AM"</code><br><code>}</code></p></td><td><code>formatted_hours.primary.today.closes_opens_next</code></td></tr></tbody></table>

### See if a postal code is assigned to any location

```
GET /_api/locations_search/?
    near_location=98121&
    postal_code_match_type=only&
    limit=1
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.devhub.com/headless-cms/locations-search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.