W tym samouczku pokazujemy, jak tworzyć i edytować dane o lokalizacji. Interfejs API informacji o firmie w Google Moja Firma umożliwia:
- Utwórz nową lokalizację.
- Usuwanie lokalizacji.
- Uzyskaj lokalizację według nazwy zasobu.
- Wyświetlanie listy wszystkich lokalizacji na koncie.
- Zaktualizuj co najmniej 1 pole w przypadku lokalizacji
Lokalizacje mogą być używane w reklamach, ale aby mogły się wyświetlać w wyszukiwarce i Mapach, muszą być zweryfikowane. Dane o lokalizacji są reprezentowane przez zbiór accounts.locations.
Zanim zaczniesz
Zanim użyjesz interfejsu API informacji o firmie w Mojej Firmie, musisz zarejestrować swoją aplikację i uzyskać poświadczenia OAuth 2.0. Szczegółowe informacje o tym, jak zacząć korzystać z interfejsu Business Information API w Google Moja Firma, znajdziesz w artykule Konfiguracja podstawowa.
Tworzenie lokalizacji
Za pomocą interfejsu API informacji o firmie w Google Moja Firma możesz utworzyć nową lokalizację firmy za pomocą wywołania accounts.locations.create.
Aby utworzyć lokalizację, wykonaj te czynności:
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"
}
}
}
Usuwanie lokalizacji
Aby usunąć lokalizację, możesz użyć interfejsu API informacji o firmie w Google Moja Firma, wywołując metodę locations.delete.
Aby usunąć lokalizację, wykonaj te czynności:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Pobieranie lokalizacji według nazwy
Jeśli masz wiele firm powiązanych z kontem, możesz wybrać jedną lokalizację. Aby uzyskać dane o konkretnej lokalizacji, możesz użyć filtra według nazwy firmy za pomocą zapytania locations.get.
Aby uzyskać lokalizację według nazwy, wykonaj te czynności. Aby pobrać określone pola, musisz podać maskę odczytu. :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Zwracanie wersji Map Google
Aby zwrócić wersję lokalizacji w Mapach Google, dodaj do adresu URL żądania znak googleUpdated, jak w tym przykładzie:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Jeśli nie ma wyników, zwracany jest kod stanu HTTP 404 NOT FOUND. Więcej informacji o zarządzaniu aktualizacjami Google znajdziesz tutaj.
Wyświetlenie listy lokalizacji
Jeśli zarządzasz co najmniej 1 lokalizacją, możesz wyświetlić wszystkie lokalizacje powiązane z Twoim kontem. Użyj interfejsu API accounts.locations.list, aby wyświetlić listę wszystkich lokalizacji powiązanych z użytkownikiem.
Aby wyświetlić listę wszystkich lokalizacji, które są bezpośrednio własnością uwierzytelnionego użytkownika lub są przez niego zarządzane, wykonaj te czynności:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
Użyj symbolu wieloznacznego '-' dla konta w adresie URL żądania, aby uwzględnić wpisy należące pośrednio do konta (należące do niego lub zarządzane przez grupę):
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrowanie wyników podczas wyświetlania listy lokalizacji
Za pomocą filtrów możesz ograniczyć wyniki zwracane po wywołaniu zapytania accounts.locations.list. Aby filtrować żądanie, dodaj wyrażenie filtra do podstawowego adresu URL, jak pokazano w tym przykładzie:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22
Podstawowa składnia zapytań
Ograniczenie ma następującą składnię:<field><operator><value>,gdzie operator to równa się (=) lub zawiera (:). Operatory równa się (=) i zawiera (:) są równoważne we wszystkich polach z wyjątkiem locationName (patrz tabela poniżej).
Cudzysłowy są kodowane jako „%22”, a spacje jako znaki plusa (+).
O ile nie zaznaczono inaczej, wszystkie porównania są porównaniami tokenów, w których wielkość liter nie ma znaczenia. Na przykład „4 drive” będzie pasować do „4, Privet Drive”.
Łączenie wielu pól w zapytaniu filtra
Interfejs API umożliwia łączenie wszystkich ograniczeń pól za pomocą operatora AND. Jednak w przypadku słowa kluczowego LUB wszystkie ograniczenia muszą dotyczyć tego samego pola. Na przykład: locationName=A LUB labels=B nie jest dozwolony.
Przykład
Przykład poniżej zawiera wyrażenie filtra, które zwraca wszystkie lokalizacje o nazwie „Pepé Le Pew”. Pokazuje on kategorie „french_restaurant” lub „european_restaurant” oraz etykietę „Nowo otwarta”.
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
Wyszukaj według odległości lub konta
Ten przykład pokazuje, jak wyszukiwać lokalizacje w określonej odległości od punktu geograficznego:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
Aby odfiltrować lokalizacje w odległości do 1000 mil od Boulder w Kolorado w USA:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0
Lista wszystkich obsługiwanych pól filtra
Poniżej znajdziesz pełną listę wszystkich pól, których można używać do filtrowania:
| Pola | Opis i przykład |
|---|---|
| Pola dopasowywania ciągów znaków | |
title |
Nazwa firmy w środowisku
|
categories |
Kombinacja kategorii podstawowej i dodatkowych. Pamiętaj, że musisz pominąć ciąg „gcid:”. Jeśli istnieje kilka kategorii, filtr pasuje, gdy co najmniej jedna z nich odpowiada temu wzorcemu.
|
phone_numbers.primary_phone |
Podstawowy numer telefonu w formacie E.164 (np. „+441234567890”).
|
storefront_address.region_code |
Kod regionu CLDR kraju lub regionu adresu.
|
storefront_address.administrative_area |
Najwyższy podział administracyjny, który jest używany w przypadku adresów pocztowych w kraju lub regionie
|
storefront_address.locality |
Miejscowość w adresie.
|
storefront_address.postal_code |
Kod pocztowy w adresie.
|
metadata.place_id |
Jeśli lokalizacja została zweryfikowana i jest powiązana z Mapami Google lub wyświetlana w tych usługach, to pole jest równe identyfikatorowi miejsca.
|
openInfo.status |
Wskazuje, czy lokalizacja jest obecnie otwarta (
|
labels |
Kolekcja ciągów tekstowych umożliwiających tagowanie firmy. W przeciwieństwie do wszystkich innych pól ta wartość musi dokładnie odpowiadać pełnej etykiecie, łącznie z wielkością liter, a nie tylko znacznikowi. Jeśli np. etykieta to „XX YY”, ani „XX”, ani „xx yy” nie będą pasować.
|
storeCode |
Zewnętrzny identyfikator tej lokalizacji, który musi być unikalny na danym koncie.
|
| Funkcje | |
distance |
Umożliwia filtrowanie według odległości lokalizacji od punktu geograficznego.
|
Sortowanie według pola zapytania
Wyniki możesz sortować według nazwy firmy lub kodu sklepu w kolejności rosnącej lub malejącej. Wiele kryteriów sortowania jest rozdzielanych przecinkami w ciągu orderBy, jak w tym przykładzie:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Poprawianie lokalizacji
Aby zaktualizować co najmniej 1 pole lokalizacji za pomocą interfejsu locations.patch, użyj interfejsu API informacji o firmie w usłudze Moja Firma.
Aby zmienić co najmniej 1 pole lokalizacji, wykonaj te czynności:
Dodaj pola i zaktualizowane wartości za pomocą pola lokalizacji, a jako wartość pola fieldMask użyj listy zaktualizowanych pól rozdzielonych przecinkami.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}