# 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](https://api-docs.devhub.com/core-resources/locations#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>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 next 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></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
```