В этом руководстве описано, как создавать и редактировать данные адресов. С помощью My Business Business Information API можно выполнить следующие действия:
- Создать новый адрес
- Удалить адрес
- Получить данные об адресе по названию ресурса
- Получить список всех адресов для аккаунта
- Внести изменения в одно или несколько полей
Адреса можно использовать в Google Рекламе, но для показа в Поиске и Картах их необходимо подтвердить. Данные об адресах представлены в виде коллекции accounts.locations.
Подготовка
Прежде чем начинать работу с My Business Business Information API, необходимо зарегистрировать свое приложение и получить учетные данные OAuth 2.0. Подробную информацию о начале работы с My Business Business Information API можно найти в руководстве по базовой настройке.
Как создать адрес
С помощью My Business Business Information API вы можете создать новый адрес для компании, используя метод accounts.locations.create.
Чтобы создать адрес, используйте следующий код:
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"
}
}
}
Как удалить адрес
С помощью My Business Business Information API вы можете удалить адрес, используя метод locations.delete.
Чтобы удалить адрес, используйте следующий код:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Как получить данные об адресе по названию
Если с вашим аккаунтом связано много компаний, вам может быть необходимо получить данные о конкретном адресе. Это можно сделать с помощью фильтрации по названию, используя метод locations.get.
Чтобы получить данные об адресе по названию, необходимо указать readMask для извлечения конкретных полей: :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Как получить данные о версии Google Карт
Чтобы получить данные о версии Google Карт для адреса, добавьте googleUpdated в URL запроса, как в примере ниже:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Если результатов нет, вернется код статуса HTTP 404 NOT FOUND. Подробнее об управлении изменениями, внесенными Google…
Как получить список адресов
Если с вашим аккаунтом связано несколько адресов, вы можете при желании получить их полный список. Для одного адреса это тоже сработает. Воспользуйтесь API accounts.locations.list, чтобы получить список всех адресов, связанных с определенным пользователем.
Чтобы получить для выполнившего аутентификацию пользователя список непосредственно принадлежащих ему или управляемых им адресов, используйте следующий запрос:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
Чтобы получить список адресов, принадлежащих или управляемых опосредованно (в составе группы), используйте вместо аккаунта в URL запроса подстановочный знак '-':
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Как отфильтровать полученный список адресов
К списку адресов, полученному с помощью метода accounts.locations.list, можно применить фильтры. Для этого добавьте выражение фильтра к основному URL. Пример:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22
Основной синтаксис запросов
Для ограничения используется следующий синтаксис: <field><operator><value>. В нем применяется оператор РАВНО (=) или СОДЕРЖИТ (:). Операторы одинаково работают для всех полей, кроме locationName (см. в таблице ниже).
Кавычки кодируются как "%22", а пробелы заменяются знаками плюса (+).
Если не указано иное, все сравнения для токенов применяются без учета регистра. Например, по запросу "4 drive" можно получить результат "4, Privet Drive".
Как объединить несколько полей в запросе для фильтрации
API поддерживает оператор AND (И) для объединения ограничений. При этом оператор OR (ИЛИ) действует только тогда, когда ограничения распространяются на одно и то же поле. Пример неподдерживаемого запроса: locationName=A OR labels=B.
Пример
Ниже приведен пример выражения для фильтрации, при использовании которого выводятся все адреса с названием Pepé Le Pew. При этом применяются категории french_restaurant и european_restaurant а также ярлык newly open.
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
Поиск по расстоянию или аккаунту
Ниже показано, как выполнить поиск адресов в определенном радиусе от географического местоположения.
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
Фильтр для адресов, расположенных не более чем в 1000 миль от Боулдера, штат Колорадо, США.
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0
Список полей, которые поддерживают фильтрацию
Ниже приведен полный список полей, к которым можно применять фильтры.
| Поля | Описание и пример |
|---|---|
| Поля со строковым соответствием | |
title |
Официальное название компании.
|
categories |
Сочетание основной и дополнительных категорий. Учтите, что "gcid:" не нужно указывать. Если категорий несколько, этот фильтр выдает соответствие как минимум при одном совпадении.
|
phone_numbers.primary_phone |
Основной номер телефона в формате E.164 (например, +441234567890).
|
storefront_address.region_code |
Идентификатор CLDR для страны или региона, где находится адрес.
|
storefront_address.administrative_area |
Высшая административная единица для почтовых адресов в стране или регионе.
|
storefront_address.locality |
Город в адресе.
|
storefront_address.postal_code |
Почтовый индекс.
|
metadata.place_id |
Если адрес подтвержден и показывается в Google Картах, поле соответствует идентификатору места для адреса.
|
openInfo.status |
Указывает, работает ли компания по определенному адресу (
|
labels |
Коллекция строк в свободной форме, в которую вы можете добавить теги для компании. В отличие от всех остальных полей, здесь значение должно в точности соответствовать ярлыку, включая регистр. Частичные запросы не поддерживаются. Например, ярлык XX YY не считается соответствующим запросу XX или xx yy.
|
storeCode |
Внешний идентификатор адреса. Должен быть уникальным в рамках аккаунта.
|
| Функции | |
distance |
Позволяет фильтровать адреса по расстоянию от определенной географической точки.
|
Сортировка по полю запроса
Вы можете сортировать результаты по названию компании или коду филиала (по возрастанию или убыванию). Разные критерии сортировки в строке orderBy можно перечислить через запятую. Пример:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Как внести изменения в данные об адресе
Чтобы внести обновления в одно или несколько полей с помощью My Business Business Information API, воспользуйтесь методом locations.patch.
Используйте следующий код:
Добавьте поля и обновленные значения в поле для адреса. В качестве значения fieldMask перечислите через запятую поля, которые нужно обновить.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}