Locations

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.
Location Model
Location object
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
Nested list of Phone objects​
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
hours
list
Formatted JSON representing hours of operation. More details here​
contact_email
string
Default contact email for the business. Also used as the default recipient on forms
payment_forms
list
List of forms of payment accepted. More details​
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
List of service tags. More info on service tags​
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
Assign additional schema.org values to a location. More info​
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.
Example object:
1
{
2
    "added": "2012-12-19T15:27:59",
3
    "automatic_latlon": true,
4
    "business_id": 12345,
5
    "city": "Seattle",
6
    "contact_email": "[email protected]",
7
    "country": "US",
8
    "country_name": "United States of America",
9
    "custom_fields": {
10
        "headline_one": "Example headline one",
11
        "headline_two": "Example headline two",
12
        "bullet_points": [
13
            "Bullet point one",
14
            "Bullet point two"
15
        ]
16
    },
17
    "description": "<p>This is a business description</p>",
18
    "extra_schema": {
19
        "menu": "http://www.example.com/menu",
20
        "acceptsReservations": "True"
21
    },
22
    "facebook_url": "http://www.facebook.com/mypage/",
23
    "formatted_address": "555 Main St, Seattle, WA 98109",
24
    "geocoded": "555 Main St, Seattle, WA 98109, USA",
25
    "gplus_url": null,
26
    "homepage_url": "",
27
    "hours": [
28
        {
29
            "type": "primary",
30
            "hours": [
31
                [["09:00:00", "17:00:00"]],
32
                [["09:00:00", "17:00:00"]],
33
                [["09:00:00", "17:00:00"]],
34
                [["09:00:00", "17:00:00"]],
35
                [["09:00:00", "17:00:00"]],
36
                [],
37
                []
38
            ],
39
            "notes": "Open on saturday by appointment only",
40
            "special_hours": [
41
                {
42
                    "hours": [],
43
                    "start_date": "2020-09-07",
44
                    "end_date": "2020-09-07"
45
                },
46
                {
47
                    "hours": [["10:00:00", "15:00:00"]],
48
                    "start_date": "2020-09-11",
49
                    "end_date": "2020-09-14"
50
                }
51
            ]
52
        },
53
        {
54
            "type": "secondary",
55
            "hours": [
56
                [["09:00:00", "17:00:00"]],
57
                [["09:00:00", "17:00:00"]],
58
                [["09:00:00", "17:00:00"]],
59
                [["09:00:00", "17:00:00"]],
60
                [["09:00:00", "17:00:00"]],
61
                [],
62
                []
63
            ]
64
        }
65
    }
66
    "id": 1234,
67
    "instagram_url": null,
68
    "lat": "47.65015390000000",
69
    "linkedin_url": null,
70
    "location_name": "Belltown",
71
    "location_url": null,
72
    "lon": "-122.37786910000000",
73
    "modified": "2012-12-19T15:34:32",
74
    "neighborhood": "Queen Anne",
75
    "partner_location_id": "location-12345",
76
    "partner_location_sub_id": "region-1",
77
    "payment_forms": ["visa", "mastercard", "american-express"],
78
    "payment_forms_notes": null,
79
    "phonemap": {
80
        "phone": "(206) 930-7689"
81
    },
82
    "phonemap_e164": {
83
        "phone": "(206) 930-7689"
84
    },
85
    "phones": [
86
        {
87
            "disable_autoformat": false,
88
            "e164": "(206) 930-7689",
89
            "extension": null,
90
            "id": 4321,
91
            "location_id": 1234,
92
            "number": "(206) 930-7689",
93
            "resource_uri": "/api/v2/phones/4321/",
94
            "type": "phone"
95
        }
96
    ],
97
    "pinterest_url": null,
98
    "postal_code": "98109",
99
    "price_range": 3,
100
    "private_street": null,
101
    "published": true,
102
    "resource_uri": "/api/v2/locations/1234/",
103
    "service_area_only": false,
104
    "service_areas": "Belltown, Downtown, South Lake Union",
105
    "services_tags": ["service-one", "service-two"],
106
    "state": "WA",
107
    "state_name": "Washington",
108
    "street": "555 Main St",
109
    "street2": "Apt 555",
110
    "tagline": null,
111
    "twitter_url": "https://twitter.com/mypage/",
112
    "user_id": 123,
113
    "year_opened": null,
114
    "yelp_url": null,
115
    "youtube_url": null
116
}
Copied!
Phone object (phones)
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
Hours of operation (hours)
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 []
Example of set of hours
1
{
2
    "type": "primary",
3
    "hours": [
4
        [["09:00:00", "17:00:00"]],
5
        [["09:00:00", "17:00:00"]],
6
        [["09:00:00", "17:00:00"]],
7
        [["09:00:00", "17:00:00"]],
8
        [["09:00:00", "17:00:00"]],
9
        [],
10
        []
11
    ],
12
    "notes": "Open on saturday by appointment only",
13
    "special_hours": [
14
        {
15
            "hours": [],
16
            "start_date": "2020-09-07",
17
            "end_date": "2020-09-07"
18
        },
19
        {
20
            "hours": [["10:00:00", "15:00:00"]],
21
            "start_date": "2020-09-11",
22
            "end_date": "2020-09-14"
23
        }
24
    ]
25
}
Copied!
Special case formatting
24 hours, for every day
1
{
2
    "type": "primary",
3
    "hours": ["24_HOURS"]
4
}
Copied!
Extra Schema.org (extra_schema)
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.
Example of automatic schema values
1
{
2
    "@type": "LocalBusiness",
3
    "@context": "http://schema.org",
4
    "name": "Business Name",
5
    "telephone": "+12065555555",
6
    "address": {
7
        "@type": "PostalAddress",
8
        "addressLocality":"Seattle",
9
        "addressCountry":{
10
            "@type": "Country",
11
            "name": "US"
12
        },
13
        "addressRegion": "WA",
14
        "streetAddress": "555 Main St",
15
        "postalCode": "98101"
16
    },
17
    "openingHours": [
18
        "Mo 08:00-18:00",
19
        "Tu 08:00-18:00",
20
        "We 08:00-18:00",
21
        "Th 08:00-18:00",
22
        "Fr 08:00-16:00",
23
        "Sa 09:00-15:00"
24
    ],
25
    "geo":{
26
        "@type": "GeoCoordinates",
27
        "latitude": "47.61416580000000",
28
        "longitude": "-122.34258330000000"
29
    }
30
}
Copied!
Example of extending schema for a restaurant
Using values specific to the @type of Restaurant.
1
"extra_schema": {
2
    "menu": "http://www.example.com/menu",
3
    "acceptsReservations": "True"
4
}
Copied!
Payment forms (payment_forms)
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
Example of sending payment forms
Note. These are always sent as lowercase.
1
"payment_forms": ["visa", "mastercard", "american-express"]
Copied!
Services tags (services_tags)
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.
1
"services_tags": ["service-one", "service-two"]
Copied!
Create a location
POST /api/v2/locations/
Required fields - Normal location
Attribute
business_id
street
city
state
postal_code
country
Required fields - Service area only location
Attribute
business_id
city
state
postal_code
country
List locations
List all locations for all businesses
1
GET /api/v2/locations/
Copied!
List all locations for a particular business
1
GET /api/v2/locations/?business_id=12345 
Copied!
Parameters
Name
Type
Description
business_id
string
Filter for locations associated with a particular Business
near_lat
float
Latitude to use in nearby location searches. See Distance Search for more details
near_location
string
Location search string to find nearby locations. See Distance Search for more details
near_lon
float
Longitude to use in nearby location searches. See Distance Search for more details
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
Distance in miles to restrict distance search results. See Distance Search for more details
Distance search
Locations can be searched and ordered by distance from a particular point or searched location (near_location) like a postal code or city/state.
1
GET /api/v2/locations/?
2
    business_id=12345&
3
    near_location=98121&
4
    threshold=4000&
5
    limit=20
Copied!
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.
1
GET /api/v2/locations/?
2
    business_id=12345&
3
    near_lat=47.6139939&
4
    near_lon=-122.34235389999999
5
    threshold=4000&
6
    limit=20
Copied!
For these searches, we add additional values to the resulting location object list that be used to display the distance.
1
{
2
    "id": 123456,
3
    "location_name": "Belltown",
4
    ...
5
    "distance": 996.79
6
}
Copied!
Update a location
PUT /api/v2/locations/:location_id/
Delete a location
DELETE /api/v2/locations/:location_id/