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

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

Formatted JSON representing hours of operation. More details here

contact_emails

list

Default contact emails for the business as a list of email address strings. Also used as the default recipients 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

careerplug_url

string

Full url link to their careers page

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:

{
    "added": "2012-12-19T15:27:59",
    "automatic_latlon": true,
    "business_id": 12345,
    "city": "Seattle",
    "contact_emails": ["contact@ourdomain.com", "contact2@ourdomain.com"],
    "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
}

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

{
    "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"
        }
    ]
}

Special case formatting

  • 24 hours, for every day

{
    "type": "primary",
    "hours": ["24_HOURS"]
}

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

{
    "@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"
    }
}

Example of extending schema for a restaurant

Using values specific to the @type of Restaurant.

"extra_schema": {
    "menu": "http://www.example.com/menu",
    "acceptsReservations": "True"
}

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.

"payment_forms": ["visa", "mastercard", "american-express"]

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.

"services_tags": ["service-one", "service-two"]

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

GET /api/v2/locations/

List all locations for a particular business

GET /api/v2/locations/?business_id=12345

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) 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

Additional values

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 adddistance (in miles or km depending on the project configuration).

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

Update a location

PUT /api/v2/locations/:location_id/

Delete a location

DELETE /api/v2/locations/:location_id/

PreviousBusinessesNextDomains

Last updated