Работа с данными адресов

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

Чтобы создать адрес, используйте следующий код:

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

Как удалить адрес

С помощью My Business Business Information API вы можете удалить адрес, используя метод locations.delete.

Чтобы удалить адрес, используйте следующий код:

HTTP
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

Как получить данные об адресе по названию

Вы можете отфильтровать данные по названию организации, используя метод locations.get. Это удобно, когда с аккаунтом связано много компаний.

Чтобы получить данные об адресе по названию, необходимо указать readMask для извлечения конкретных полей: :

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

Как получить данные о версии Google Карт

HTTP

Чтобы получить данные о версии Google Карт для адреса, добавьте googleUpdated в URL запроса:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}

Если результатов нет, вернется код статуса HTTP 404 NOT FOUND. Подробнее об управлении изменениями, внесенными Google

Как получить список адресов

Чтобы получить список всех адресов, связанных с аккаунтом, воспользуйтесь API accounts.locations.list.

Если вам нужны адреса, которые принадлежат выполнившему аутентификацию пользователю или непосредственно управляются им, введите следующий запрос:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

Если нужно включить адреса, которые принадлежат группе или управляются ей, в URL запроса используйте вместо идентификатора аккаунта подстановочный знак '-':

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

Как отфильтровать результаты

HTTP

К списку адресов, полученному с помощью метода 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

Поиск по расстоянию или аккаунту

Ниже показано, как выполнить поиск адресов в определенном радиусе от географического местоположения.

HTTP
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

Официальное название компании.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title:"Bajis" (соответствует любому названию места, где есть подстрока "Bajis")

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title="Bajis" (соответствует любому названию места, где есть токен или слово "Bajis")

categories

Сочетание основной и дополнительных категорий. Учтите, что "gcid:" не нужно указывать. Если категорий несколько, этот фильтр выдает соответствие как минимум при одном совпадении.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=categories="french_restaurant"

phone_numbers.primary_phone

Основной номер телефона в формате E.164 (например, +441234567890).

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=phone_numbers.primary_phone="+441234567890"

storefront_address.region_code

Идентификатор CLDR для страны или региона, где находится адрес.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.region_code="US"

storefront_address.administrative_area

Высшая административная единица для почтовых адресов в стране или регионе.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.administrative_area="CA"

storefront_address.locality

Город в адресе.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.locality="New York"

storefront_address.postal_code

Почтовый индекс.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.postal_code="12345"

metadata.place_id

Если адрес подтвержден и показывается в Google Картах, поле соответствует идентификатору места для адреса.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=metadata.place_id="12345"

openInfo.status

Указывает, работает ли компания по определенному адресу (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

Набор строк свободного формата, в которые можно добавить теги для компании. В отличие от всех остальных полей, здесь значение должно в точности соответствовать ярлыку, включая регистр. Частичные запросы не поддерживаются. Например, ярлык XX YY не считается соответствующим запросу XX или xx yy.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=labels="newly open"

storeCode

Внешний идентификатор адреса. Должен быть уникальным в рамках аккаунта.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storeCode="12345"

Функции
distance

Позволяет фильтровать адреса по расстоянию от определенной географической точки.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(1.0, -25.0))<1000.0

Сортировка по полю запроса

Вы можете сортировать результаты по названию компании или коду филиала (по возрастанию или убыванию). Разные критерии сортировки в строке orderBy можно перечислить через запятую. Пример:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

Как изменить данные об адресе

Чтобы изменить данные в полях с помощью My Business Business Information API, воспользуйтесь методом locations.patch.

Используйте приведенный ниже код.

HTTP

Добавьте поля и новые значения. В качестве значения fieldMask перечислите через запятую поля, которые нужно обновить.

PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
    "title": "Google Shoes"
}