В этом руководстве описано, как создавать и редактировать адреса. С помощью 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"
}