Locations
The Locations resource is the primary way our system stores structured information about a Business location. It is a sub-resource of "Business" and also one or multiple locations can be assigned to a Site.
A location object contains the following fields
Attribute | Type | Description |
id | integer | unique id of the location |
business_id | integer | Reference id to the Business this location is under |
user_id | integer | Reference id to the User that created this business |
published | boolean | Should this location show in Store Locators or Location directory modules. Default is true |
location_name | string | Name of this location to identify different locations within a single Business |
street | string | Street address |
street2 | string | Apartment or unit number |
city | string | City |
state | string | State code |
country | string | 2 character country code |
postal_code | string | Postal / zip code |
neighborhood | string | Neighborhood |
phones | list | |
description | string | HTML-formatted business description |
partner_location_id | string | Unique ID reference to partner IDs |
partner_location_sub_id | string | Non-unique ID reference to partner IDs |
google_places_id | string | The Google Place ID for this location. When set can be used for optimized directions links and schema |
directions_url | string | Generated URL for Google Maps directions |
hours | list | |
contact_email | string | Default contact email for the business. Also used as the default recipient on forms |
payment_forms | list | |
payment_forms_notes | string | Additional payment forms or notes |
price_range | integer | Price range indicated by 1-4 and used to represent $-$$$$ |
private_street | string | Street address but used for service area businesses. This field will not be displayed by default on maps or within templates |
service_area_only | boolean | Toggle to set this location as a "service-area only" business |
service_areas | string | Location service areas - neighborhoods, cities, zip codes |
services_tags | list | |
tagline | string | Tagline or main headline for the location |
year_opened | integer | Year opened |
facebook_url | string | Full url link to their Facebook page |
gplus_url | string | Full url link to their Google plus page |
homepage_url | string | Full url link to their external website if applicable |
instagram_url | string | Full url link to their Instagram profile |
linkedin_url | string | Full url link to their LinkedIn profile |
pinterest_url | string | Full url link to their Pinterest page |
twitter_url | string | Full url link to their Twitter profile |
yelp_url | string | Full url link to their Yelp profile |
youtube_url | string | Full url link to their Youtube page |
added | timestamp | Date and time location was created |
modified | timestamp | Date and time location was modified |
automatic_latlon | boolean | If true, we will automatically geocode the address and set the lat and lon fields |
extra_schema | object | |
lat | float | Latitude coordinate |
lon | float | Longitude coordinate |
location_url | string | Full url link to the location page associated with this location. This is used by our Store Locator module |
custom_fields | object | Custom field values assigned to the location for use in Location Finders, etc. |
{
"added": "2012-12-19T15:27:59",
"automatic_latlon": true,
"business_id": 12345,
"city": "Seattle",
"contact_email": "[email protected]",
"country": "US",
"country_name": "United States of America",
"custom_fields": {
"headline_one": "Example headline one",
"headline_two": "Example headline two",
"bullet_points": [
"Bullet point one",
"Bullet point two"
]
},
"description": "<p>This is a business description</p>",
"directions_url": "https://maps.google.com/maps/dir//...",
"extra_schema": {
"menu": "http://www.example.com/menu",
"acceptsReservations": "True"
},
"facebook_url": "http://www.facebook.com/mypage/",
"formatted_address": "555 Main St, Seattle, WA 98109",
"geocoded": "555 Main St, Seattle, WA 98109, USA",
"google_places_id": "ChIJgUbEo8cfqokR5lP9_Wh_DaM",
"gplus_url": null,
"homepage_url": "",
"hours": [
{
"type": "primary",
"hours": [
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[],
[]
],
"notes": "Open on saturday by appointment only",
"special_hours": [
{
"hours": [],
"start_date": "2020-09-07",
"end_date": "2020-09-07"
},
{
"hours": [["10:00:00", "15:00:00"]],
"start_date": "2020-09-11",
"end_date": "2020-09-14"
}
]
},
{
"type": "secondary",
"hours": [
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[],
[]
]
}
}
"id": 1234,
"instagram_url": null,
"lat": "47.65015390000000",
"linkedin_url": null,
"location_name": "Belltown",
"location_url": null,
"lon": "-122.37786910000000",
"modified": "2012-12-19T15:34:32",
"neighborhood": "Queen Anne",
"partner_location_id": "location-12345",
"partner_location_sub_id": "region-1",
"payment_forms": ["visa", "mastercard", "american-express"],
"payment_forms_notes": null,
"phonemap": {
"phone": "(206) 930-7689"
},
"phonemap_e164": {
"phone": "+12065555555"
},
"phones": [
{
"disable_autoformat": false,
"e164": "(206) 930-7689",
"extension": null,
"id": 4321,
"location_id": 1234,
"number": "(206) 930-7689",
"resource_uri": "/api/v2/phones/4321/",
"type": "phone"
}
],
"pinterest_url": null,
"postal_code": "98109",
"price_range": 3,
"private_street": null,
"published": true,
"resource_uri": "/api/v2/locations/1234/",
"service_area_only": false,
"service_areas": "Belltown, Downtown, South Lake Union",
"services_tags": ["service-one", "service-two"],
"state": "WA",
"state_name": "Washington",
"street": "555 Main St",
"street2": "Apt 555",
"tagline": null,
"twitter_url": "https://twitter.com/mypage/",
"user_id": 123,
"year_opened": null,
"yelp_url": null,
"youtube_url": null
}
A phone object contains the following fields
Attribute | Type | Description |
id | integer | unique id of the phone |
location_id | integer | Reference id to the Location this phone is under |
type | string | type of the phone - options are phone secondary tollfree fax |
number | string | Formatted version of the phone number |
extension | string | Extension of the phone |
Except for the special case formatting, this object is a list of 7 items which represent each day.
Each day can can have one-four time ranges. For example, two time ranges denotes a "lunch-break". No time ranges denotes closed.
- 9am-5pm
[["09:00:00", "17:00:00"]]
- 9am-12pm and 1pm-5pm
[["09:00:00", "12:00:00"], ["13:00:00", "17:00:00"]]
- Closed - send an empty list
[]
{
"type": "primary",
"hours": [
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[["09:00:00", "17:00:00"]],
[],
[]
],
"notes": "Open on saturday by appointment only",
"special_hours": [
{
"hours": [],
"start_date": "2020-09-07",
"end_date": "2020-09-07"
},
{
"hours": [["10:00:00", "15:00:00"]],
"start_date": "2020-09-11",
"end_date": "2020-09-14"
}
]
}
- 24 hours, for every day
{
"type": "primary",
"hours": ["24_HOURS"]
}
Our platform auto-generates location-based
JSON-LD
schema.org values for each location. This is embedded into any site that is published on the platform to syndicate these values to web search engines.The
extra_schema
gives that ability to extend or replace the existing auto-generated schema values.{
"@type": "LocalBusiness",
"@context": "http://schema.org",
"name": "Business Name",
"telephone": "+12065555555",
"address": {
"@type": "PostalAddress",
"addressLocality":"Seattle",
"addressCountry":{
"@type": "Country",
"name": "US"
},
"addressRegion": "WA",
"streetAddress": "555 Main St",
"postalCode": "98101"
},
"openingHours": [
"Mo 08:00-18:00",
"Tu 08:00-18:00",
"We 08:00-18:00",
"Th 08:00-18:00",
"Fr 08:00-16:00",
"Sa 09:00-15:00"
],
"geo":{
"@type": "GeoCoordinates",
"latitude": "47.61416580000000",
"longitude": "-122.34258330000000"
}
}
Using values specific to the
@type
of Restaurant
."extra_schema": {
"menu": "http://www.example.com/menu",
"acceptsReservations": "True"
}
Predefined list of payment forms supported by this location.
List of all valid payment forms:
visa
, mastercard
, american-express
, discover
, diners-club
, debit
, checks
, credit-card
, cash
, vouchers
, bank-deposit
, money-orders
, cashiers-checks
, paypal
, financing-available
, carecredit
, most-insurance-plans
, layaway
, money-transfers
, line-of-credit
, store-card
, google-wallet
, travelers-checks
, invoice
, cheque
, interac
Note. These are always sent as lowercase.
"payment_forms": ["visa", "mastercard", "american-express"]
These are structured tags that can be assigned to a location. These are primarily used for filtering Location Finder results. But these tags can also be used within templates to hide and show content or build a list of applicable services.
These tags should be lowercase and can contain alphanumeric and dashes (
-
) characters."services_tags": ["service-one", "service-two"]
POST /api/v2/locations/
Attribute |
business_id |
street |
city |
state |
postal_code |
country |
Attribute |
business_id |
city |
state |
postal_code |
country |
List all locations for all businesses
GET /api/v2/locations/
List all locations for a particular business
GET /api/v2/locations/?business_id=12345
Name | Type | Description |
business_id | string | Filter for locations associated with a particular Business |
near_lat | float | |
near_location | string | |
near_lon | float | |
partner_business_id | string | Used to lookup/search for locations matching a particular internal id |
partner_location_id | string | Used to lookup/search for locations matching a particular internal id |
threshold | int |
Locations can be searched and ordered by distance from a particular point or searched location (
near_location
) string like a postal code or city/state.GET /api/v2/locations/?
business_id=12345&
near_location=98121&
threshold=4000&
limit=20
If you already have the search location (latitude and longitude), you can pass those directly into the request using
near_lat
and near_lon
to speed up the response time and avoid an API call to geocode the search.GET /api/v2/locations/?
business_id=12345&
near_lat=47.6139939&
near_lon=-122.34235389999999
threshold=4000&
limit=20
For these distance searches, we also add additional values to the response with some 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 the project configuration)."objects": [{
"id": 123456,
"location_name": "Belltown",
...
"distance": 996.79
}]
PUT /api/v2/locations/:location_id/
DELETE /api/v2/locations/:location_id/
Last modified 10d ago