Locations search

Query and search locations using the same technology that powers our Location Finder technology

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

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

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

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

{
    "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).

"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

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

See if a postal code is assigned to any location

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