Работа с данными о местоположении

В этом руководстве показано, как создавать и редактировать данные о местоположении. API бизнес-информации My Business предоставляет вам возможность делать следующее:

Местоположение можно использовать в рекламе, но для его показа в Поиске и на Картах их необходимо подтвердить . Данные о местоположении представлены коллекцией account.locations .

Прежде чем начать

Прежде чем использовать API бизнес-информации My Business, вам необходимо зарегистрировать свое приложение и получить учетные данные OAuth 2.0. Подробную информацию о том, как начать работу с API My Business Business Information, см. в разделе Базовая настройка .

Создать локацию

Вы можете использовать API бизнес-информации My Business, чтобы создать новое местоположение для компании с помощью account.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"
      }
     }
}

Удаление местоположения

Вы можете использовать API бизнес-информации My Business, чтобы удалить местоположение с помощью location.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 Maps

HTTP

Чтобы вернуть версию местоположения на Картах Google, добавьте googleUpdated к URL-адресу запроса, как показано в следующем примере:

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

Если результатов нет, возвращается код состояния HTTP 404 NOT FOUND . Более подробную информацию об управлении обновлениями Google можно найти здесь.

Список мест

Если вы управляете одним или несколькими филиалами, вам может потребоваться перечислить все филиалы, связанные с вашей учетной записью. Используйте API account.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> , где оператором является либо EQUALS (=), либо HAS (:). Операторы EQUALS (=) и HAS (:) эквивалентны для всех полей, кроме locationName (см. таблицу ниже).

Кавычки кодируются как «%22», а пробелы — как знаки плюса ( + ).

Если не указано иное, все сравнения являются сравнениями токенов без учета регистра. Например, «4-й проезд» будет соответствовать «4, Тисовый проезд».

Объединение нескольких полей в запросе фильтра

API позволяет И соединить все ограничения полей. Однако когда дело доходит до ключевого слова OR, все ограничения должны применяться к одному и тому же полю. Например: locationName=A OR labels=B не допускается.

Пример

В следующем примере показано выражение фильтра, которое возвращает все местоположения с именем «Пепе Ле Пью». Здесь отображаются категории «французский_ресторан» или «европейский_ресторан» и метка «недавно открытый».

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

Исправление местоположения

Используйте API бизнес-информации My Business, чтобы обновить одно или несколько полей для местоположения с помощью location.patch .

Чтобы изменить одно или несколько полей для местоположения, используйте следующее:

HTTP

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

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