Overview

A Location represents a physical business location in your account. It is the starting point for accessing and harnessing the various endpoints the API has to offer.

Location Object

The following table details all available fields for Location objects. Fields marked as mandatory are required when creating or updating locations.

Core Attributes

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`id`	String	Unique identifier in Base64 encoded format. Eg: `Location:<Location ID>` `TG9jYXRpb246MTIzNDU=`	-	✗	✓
`name`	String	Business name	-	✓	-
`storeId`	String	Custom store identifier	-	-	-
`subCategoryId`	Integer	Business primary category identifier. Refer to Categories Endpoint for valid primary categories.	-	✓	-
`subCategoryName`	String	Name of business subcategory ( Primary)	✓	-	-
`additionalCategoryIds`	Integer	Additional category classifications. Refer to Categories Endpoint. Supports up to 9 categories. Categories with primary flag as true or false can be used.	-	-	-

Address Information

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`street`	String	Street address	-	✓	-
`street1`	String	Specify additional address information	-	-	-
`city`	String	City name	-	✓	-
`postalCode`	String	Postal/ZIP code	-	✓	-
`stateIso`	String	State/Province ISO code ¹	-	✓	-
`countryIso`	String	Country ISO code ¹. Cannot be updated	-	✓	✗
`latitude`	String	Geographic latitude	✓	✗	✗
`longitude`	String	Geographic longitude	✓	✗	✗
`hideAddress`	Boolean	`true` indicates a Service Area Business	-	-	-

Contact Information

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`phone`	String	Business phone number. Ref here	-	✓	-
`ownerEmail`	String	Business owner's email	-	-	-
`ownerName`	String	Business owner's name	-	-	-
`googleAdsPhone`	String	Phone number used exclusively for Google Ads Ref here	-	-	-
`additionalPhones`	Array of Strings	Additional phone numbers (Supported only for Google) Ref here	-	-	-

Business Details

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`businessHours`	Object	Business Hours. Refer to the schema for details. Regular hours required to add special hours.	-	-	-
`temporarilyClosed`	Boolean	Set `true` to mark the location as temporarily closed and hide business hours	-	-	-
`description`	String	Business description. Min 200 char - 1500 char	-	✓	-
`tagline`	String	Business tagline	-	-	-
`yearOfIncorporation`	Integer	Business establishment year	-	-	-
`paymentMethods`	String[]	Accepted payment methods. Ref here	-	-	-

Online Presence

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`bizUrl`	String	Business website URL	-	-	-
`facebookUrl`	String	Facebook page URL	-	-	-
`twitterUrl`	String	Twitter profile URL	-	-	-
`linkedinUrl`	String	LinkedIn page URL	-	-	-
`youtubeUrl`	String	YouTube page URL	-	-	-
`instagramUrl`	String	Instagram page URL	-	-	-
`tiktokUrl`	String	TikTok page URL	-	-	-
`pinterestUrl`	String	Pinterest page URL	-	-	-
`videos`	String[]	List of video URLs	-	-	-
`locationPhotos`	Object	Returns `LOGO` and `COVER` photos of the location.	-	-	-

Publishing Configuration

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`enabledSiteIds`	Integer[]	Specify site IDs where business details should be published. Choose from sites in the location plan. Refer to Plan Sites	-	-	-
`submissionDisabledSiteIds`	Integer[]	Sites where publishing is disabled. Refer to Plan Sites	-	-	-

System Fields

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`databaseId`	Integer	Internal reference ID	✓	-	-
`archivalScheduledAt`	Timestamp	Timestamp set when an archival request is initiated for the location	✓	-	-
`archivedAt`	Timestamp	Timestamp marking the actual archival of the location, typically at the end of the billing cycle	✓	-	-
`tenure`	String	For multi-subscription accounts, specify the subscription tenure. Example: Monthly. Refer to Subscriptions	-	⚑	-

Restaurant and Food Business-Specific Fields

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`bookingUrl`	String	URL for booking services related to the location (Applicable for restaurant or food businesses)	-	-	-
`offeringsUrl`	String	URL showcasing menus (Applicable for restaurant or food businesses)	-	-	-
`reservationUrl`	String	URL for reservations (Applicable for restaurant or food businesses)	-	-	-

Categorization & Organization

Attribute	Type	Description	Read Only	Required for Create	Required for Update
`tags`	Array of Strings	Keywords associated with the location for categorization or search purposes	-	-	-
`folderId`	String `<UUID>`	Identifier for organizing locations into folders (Retrieve folders via query)	-	-	-

Notes

¹ Refer to the Places API for valid ISO codes
² Refer to Plan Sites for available site IDs
³ Only required for accounts with multiple subscriptions. Find about subscription
⁴ Get Primary Categories and Additional Categories here
⚑ Conditionally required

Business hours schema

Business hours

Phone Number Formats

Back to Contact info

Must follow the international E.164 format. Ref here.

Do not include the + sign or country code.

Remove parentheses and special characters.

Example:

Incorrect: (123)-456-7890, +1-123-456-7890

Correct: 1234567890

Supported Payment Methods

paymentMethods

Subcategories and Additional Categories

SubCategory

A Subcategory can be considered as the primary category for the location.

Only categories where PRIMARY is set to true are considered SubCategories.

AdditionalCategory

An Additional Category can be considered as the secondary category for the location.

Categories where PRIMARY is either true or false are considered AdditionalCategories.

Common Errors while creating a location

Error	Description
Insufficient Permissions	The API key or user account does not have the required permissions to perform this action.
Minimum 200 Characters for Business Description	The business description must be at least 200 characters long.
Must Be a Supported Country	The specified country is not supported. Refer to the list of allowed countries.
Not a Valid State	The provided state is invalid or does not exist for the selected country.
Invalid Postal Code	The postal code format is incorrect or does not match the country’s requirements.
Invalid Phone Number	The phone number format is invalid or does not meet country-specific guidelines.
Must Be a Valid Year (for Year of Incorporation)	The year of incorporation must be a valid four-digit year.
storeId Has Already Been Taken	The provided `storeId` is already in use. Please use a unique identifier.

Location Attributes

Overview#

Location Object#

Core Attributes#

Address Information #

Contact Information #

Business Details #

Online Presence#

Publishing Configuration #

System Fields #

Restaurant and Food Business-Specific Fields#

Categorization & Organization#

Notes#

Business hours schema#

Phone Number Formats#

Supported Payment Methods#

Subcategories and Additional Categories#

SubCategory#

AdditionalCategory#

Common Errors while creating a location#