This tutorial shows how to create and edit location data. The My Business Business Information API provides you with the ability to do the following: - [Create a new location](https://developers.google.com/my-business/content/location-data#create-a-location). - [Delete a location](https://developers.google.com/my-business/content/location-data#delete-a-location). - [Get a location by resource name](https://developers.google.com/my-business/content/location-data#get-a-location-by-name). - [List all locations for an account](https://developers.google.com/my-business/content/location-data#list-locations). - [Update one or more fields for a location](https://developers.google.com/my-business/content/location-data#patch-a-location). Locations can be used in Ads, but they need to be [verified](https://support.google.com/business/answer/2911778) to be eligible to appear on Search and Maps. Location data is represented by the [accounts.locations](https://developers.google.com/my-business/reference/businessinformation/rest/v1/accounts.locations) collection. ## Before you begin Before you use the My Business Business Information API, you need to register your application and obtain OAuth 2.0 credentials. For details on how to get started with the My Business Business Information API, see [Basic setup](https://developers.google.com/my-business/content/basic-setup). ## Create a location You can use the My Business Business Information API to create a new location for a business with [accounts.locations.create](https://developers.google.com/my-business/reference/businessinformation/rest/v1/accounts.locations/create). > [!NOTE] > **Note:** The My Business Business Information API shares the same list of [required fields](https://support.google.com/business/answer/3370250) as the Business Profile UI. To create a location, use the following: HTTP ``` POST https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False { "storeCode": "GOOG-SYD", "languageCode": "en-AU", "title": "Google Sydney", "phoneNumbers": { "primaryPhone": "02 9374 4000" }, "storefrontAddress": { "addressLines": [ "Level 5", "48 Pirrama Road" ], "locality": "Pyrmont", "postalCode": "2009", "administrativeArea": "NSW", "regionCode": "AU" }, "websiteUri": "https://www.google.com.au/", "regularHours": { "periods": [ { "openDay": "MONDAY", "closeDay": "MONDAY", "openTime": "09:00", "closeTime": "17:00" }, { "openDay": "TUESDAY", "closeDay": "TUESDAY", "openTime": "09:00", "closeTime": "17:00" }, { "openDay": "WEDNESDAY", "closeDay": "WEDNESDAY", "openTime": "09:00", "closeTime": "17:00" }, { "openDay": "THURSDAY", "closeDay": "THURSDAY", "openTime": "09:00", "closeTime": "17:00" }, { "openDay": "FRIDAY", "closeDay": "FRIDAY", "openTime": "09:00", "closeTime": "17:00" } ] }, "categories": { "primaryCategory": { "name": "gcid:software_company" } } } ``` ## Delete a location You can use the My Business Business Information API to delete a location with [locations.delete](https://developers.google.com/my-business/reference/businessinformation/rest/v1/locations/delete). To delete a location, use the following: HTTP ``` DELETE https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId} ``` ## Get a location by name If you have many businesses associated with your account, you might want to get a single location. You can filter by the business' name to get a specific location with [locations.get](https://developers.google.com/my-business/reference/businessinformation/rest/v1/locations/get). To get a location by name, use the following. You must specify a readMask to retrieve specific fields. : HTTP ``` GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve} ``` ### Return the Google Maps version HTTP To return the Google Maps version of a location, append `googleUpdated` to the request URL, as in the following example: ``` GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve} ``` If there are no results, a `404 NOT FOUND` HTTP status code is returned. For more details on managing Google updates, see [Accept or reject updates](https://developers.google.com/my-business/content/accept-or-reject-updates). ### Return extended location data and edit status (v1alpha) To retrieve both the merchant-provided location data and the consumer-facing location data along with per-field edit lifecycle stages (such as `EDIT_LIFECYCLE_STAGE_PENDING` or `EDIT_LIFECYCLE_STAGE_REJECTED`), edit source (`SOURCE_API` or `SOURCE_UI`), and policy violation reasons in a single call, use [`locations.getExtended`](https://developers.google.com/my-business/reference/businessinformation/rest/v1alpha/locations/getExtended) in `v1alpha`: HTTP ``` GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}:getExtended ``` For full response examples and details on interpreting per-field edit status and policy violations, see [Check edit status for locations and attributes](https://developers.google.com/my-business/content/edit-status). ## List locations When you manage one or more locations, you might want to list all locations associated with your account. Use the [accounts.locations.list](https://developers.google.com/my-business/reference/businessinformation/rest/v1/accounts.locations/list) API to list all locations associated with a user. To list all locations directly owned or managed by an authenticated user, use the following: HTTP ``` GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve} ``` Use a `'-'` wildcard for the account in the request URL to include the indirectly owned listings (owned or managed via a group): HTTP ``` GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve} ``` ### Filter results when you list locations HTTP You can use filters to limit the results that are returned when you call [accounts.locations.list](https://developers.google.com/my-business/reference/businessinformation/rest/v1/accounts.locations/list). To filter a request, append a filter expression to the base URL as shown in this example: ``` GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22 ``` #### Basic query syntax A restriction has the following syntax: ``, where the operator is either EQUALS (=) or HAS (:). The EQUALS (=) and HAS (:) operators are equivalent for all fields except `locationName` (see table below). Quotation marks are encoded as "%22" and spaces as plus signs (**+**). Unless otherwise noted, all comparisons are case insensitive token comparisons. For example, "4 drive" would match "4, Privet Drive". #### Combine multiple fields in a filter query The API allows AND to connect all fields restrictions. However, when it comes to the OR keyword, all the restrictions have to apply to the same field. For example: `locationName=A` OR `labels=B` isn't allowed. ##### Example The following example shows a filter expression that returns all locations with the name "Pepé Le Pew." It shows categories for either "french_restaurant" or "european_restaurant," and a label of "newly open." ``` locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22 ``` #### Search by distance or account The following example shows how you can search for locations within a certain distance from a geographical point: HTTP ``` GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance} ``` To filter locations within 1000 miles of Boulder, Colorado USA: ``` GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0 ``` #### List of all supported filter fields The following is an exhaustive list of all fields that can be used for filtering: | **Fields** | **Description and example** | |---|---| | **String matching fields** || | `title` | The business' real world name `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title:"Bajis"` (matches any location name with "Bajis" as a substring) `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title="Bajis"` (matches any location name with "Bajis" as a token/word) | | `categories` | The combination of the primary category and the additional categories. Note that the "gcid:" has to be omitted. If there are multiple categories, this filter matches if at least one category matches this pattern. `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=categories="french_restaurant"` | | `phone_numbers.primary_phone` | The primary phone number in E.164 format (For example: "+441234567890"). `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=phone_numbers.primary_phone="+441234567890" ` | | `storefront_address.region_code` | The CLDR region code of the country/region of the address `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.region_code="US"` | | `storefront_address.administrative_area` | The highest administrative subdivision which is used for postal addresses of a country or region `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.administrative_area="CA"` | | `storefront_address.locality` | The city/town portion of the address `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.locality="New York"` | | `storefront_address.postal_code` | The postal code of the address `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.postal_code="12345"` | | `metadata.place_id` | If this location has been verified and is connected to/appears on Google Maps, this field is equal to the place ID for the location `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=metadata.place_id="12345"` | | `openInfo.status` | Indicates whether or not the Location is currently open for business (`OPEN`, `CLOSED_PERMANENTLY`) `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="OPEN"` `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="CLOSED_PERMANENTLY"` | | `labels` | A collection of free-form strings to allow you to tag your business. In contrast to all the other fields, this value must exactly match a full label including casing and not only a token. E.g. If a label is "XX YY", then neither "XX" or "xx yy" will match. `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=labels="newly open"` | | `storeCode` | External identifier for this location, which must be unique inside a given account `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storeCode="12345"` | | **Functions** || | `distance` | Allows you to filter based on the distance of the location from a geographical point. `https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(1.0, -25.0))<1000.0` |
### Sort by query field You can sort the results by business name or store code, in ascending or descending order. Multiple ordering criteria are separated by commas in the `orderBy` string, as in the following example: HTTP ``` GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode ``` ## Patch a location Use the My Business Business Information API to update one or more fields for a location with [locations.patch](https://developers.google.com/my-business/reference/businessinformation/rest/v1/locations/patch). > [!IMPORTANT] > **Important:** It is required that an `updateMask` is used in a patch request. Only include fields that need an update. To change one or more fields for a location, use the following: HTTP Add the fields and updated values with the location field, and use a comma-separated list of updated fields as the value for `fieldMask`. ``` PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title { "title": "Google Shoes" } ```