В этом руководстве показано, как создавать и редактировать данные о местоположении. API бизнес-информации My Business предоставляет вам возможность делать следующее:
- Создайте новое местоположение .
- Удалить местоположение .
- Получите местоположение по имени ресурса .
- Перечислите все местоположения для учетной записи .
- Обновите одно или несколько полей для местоположения .
Местоположение можно использовать в рекламе, но для его показа в Поиске и на Картах их необходимо подтвердить . Данные о местоположении представлены коллекцией account.locations .
Прежде чем вы начнете
Прежде чем использовать API бизнес-информации My Business, вам необходимо зарегистрировать свое приложение и получить учетные данные OAuth 2.0. Подробную информацию о том, как начать работу с API My Business Business Information, см. в разделе Базовая настройка .
Создать локацию
Вы можете использовать API бизнес-информации My Business, чтобы создать новое местоположение для компании с помощью account.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" } } }
Удаление местоположения
Вы можете использовать API бизнес-информации My Business, чтобы удалить местоположение с помощью location.delete .
Чтобы удалить местоположение, используйте следующее:
DELETE https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Получить местоположение по названию
Если с вашей учетной записью связано много компаний, возможно, вам захочется указать одно местоположение. Вы можете фильтровать по названию компании, чтобы получить конкретное местоположение с помощью Locations.get .
Чтобы получить местоположение по имени, используйте следующее. Вы должны указать readMask для получения определенных полей. :
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Верните версию Google Maps
Чтобы вернуть версию местоположения на Картах Google, добавьте googleUpdated
к URL-адресу запроса, как показано в следующем примере:
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Если результатов нет, возвращается код состояния HTTP 404 NOT FOUND
. Более подробную информацию об управлении обновлениями Google можно найти здесь.
Список мест
Если вы управляете одним или несколькими местоположениями, возможно, вам захочется перечислить все местоположения, связанные с вашей учетной записью. Используйте API account.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>
, где оператором является либо 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
Поиск по расстоянию или аккаунту
В следующем примере показано, как можно искать местоположения на определенном расстоянии от географической точки:
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
Исправление местоположения
Используйте API бизнес-информации My Business, чтобы обновить одно или несколько полей для местоположения с помощью location.patch .
Чтобы изменить одно или несколько полей для местоположения, используйте следующее:
Добавьте поля и обновленные значения с полем местоположения и используйте список обновленных полей, разделенный запятыми, в качестве значения для fieldMask
.
PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title { "title": "Google Shoes" }