Z tego samouczka dowiesz się, jak tworzyć i edytować dane o lokalizacji. Interfejs My Business Business Information API umożliwia wykonywanie tych czynności:
- tworzenie nowej lokalizacji.
- usuwanie lokalizacji;
- pobieranie lokalizacji według nazwy zasobu.
- wyświetlanie listy wszystkich lokalizacji na koncie.
- aktualizowanie co najmniej 1 pola lokalizacji.
Lokalizacje można używać w reklamach, ale aby mogły się wyświetlać w wyszukiwarce i Mapach, muszą zostać zweryfikowane aby mogły się wyświetlać. Dane o lokalizacji są reprezentowane przez accounts.locations.
Zanim zaczniesz
Zanim zaczniesz korzystać z interfejsu My Business Business Information API, musisz zarejestrować aplikację i uzyskać dane logowania OAuth 2.0. Więcej informacji o tym, jak zacząć korzystać z interfejsu My Business Business Information API, znajdziesz w artykule Podstawowa konfiguracja.
Tworzenie lokalizacji
Za pomocą interfejsu My Business Business Information API możesz utworzyć nową lokalizację firmy za pomocą accounts.locations.create.
Aby utworzyć lokalizację, użyj tych elementów:
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
Za pomocą interfejsu My Business Business Information API możesz usunąć lokalizację za pomocą metody locations.delete.
Aby usunąć lokalizację, użyj tych elementów:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Pobieranie lokalizacji według nazwy
Jeśli z Twoim kontem jest powiązanych wiele firm, możesz pobrać pojedynczą lokalizację. Aby uzyskać konkretną lokalizację, możesz filtrować według nazwy firmy za pomocą metody locations.get.
Aby pobrać lokalizację według nazwy, użyj tych elementów. Aby pobrać konkretne pola, musisz określić readMask. :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Zwracanie wersji Map Google
Aby zwrócić wersję lokalizacji w Mapach Google, dodaj
googleUpdated do adresu URL żądania, 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 w artykule
Akceptowanie i odrzucanie aktualizacji.
Wyświetlenie listy lokalizacji
Gdy zarządzasz co najmniej 1 lokalizacją, możesz wyświetlić listę wszystkich lokalizacji powiązanych z Twoim kontem. Aby wyświetlić listę wszystkich lokalizacji powiązanych z użytkownikiem, użyj interfejsu accounts.locations.list API.
Aby wyświetlić listę wszystkich lokalizacji, których właścicielem lub administratorem jest uwierzytelniony użytkownik, użyj tych elementów:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
Aby uwzględnić wpisy, które nie są bezpośrednio powiązane z kontem (należą do grupy lub są przez nią zarządzane), użyj symbolu wieloznacznego '-' w adresie URL żądania, aby uwzględnić
wpisy, które nie są bezpośrednio powiązane z kontem (należą do grupy lub są przez nią zarządzane):
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrowanie wyników podczas wyświetlania listy lokalizacji
Aby ograniczyć liczbę wyników zwracanych przez wywołanie accounts.locations.list, możesz użyć filtrów. 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 EQUALS (=) lub HAS (:). Operatory EQUALS (=) i HAS (:)
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 plus (+).
O ile nie wskazano inaczej, wszystkie porównania są porównaniami tokenów bez uwzględniania wielkości liter. Na przykład „4 drive” będzie pasować do „4, Privet Drive”.
Łączenie wielu pól w zapytaniu z filtrem
Interfejs API umożliwia łączenie wszystkich ograniczeń pól za pomocą operatora AND. Jeśli jednak chodzi o słowo kluczowe OR, wszystkie ograniczenia muszą dotyczyć tego samego pola. Na przykład locationName=A OR labels=B jest niedozwolone.
Przykład
Ten przykład pokazuje wyrażenie filtra, które zwraca wszystkie lokalizacje o nazwie „Pepé Le Pew”. Wyświetla kategorie „french_restaurant” lub „european_restaurant” oraz etykietę „newly open”.
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
Wyszukiwanie 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 filtrować lokalizacje w promieniu 1600 km od Boulder w stanie 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
Oto pełna lista wszystkich pól, których można używać do filtrowania:
| Pola | Opis i przykład |
|---|---|
| Pola dopasowania ciągu znaków | |
title |
Prawdziwa nazwa firmy
|
categories |
Połączenie kategorii głównej i kategorii dodatkowych. Pamiętaj, że musisz pominąć „gcid:”. Jeśli jest kilka kategorii, ten filtr pasuje, jeśli co najmniej 1 kategoria pasuje do tego wzorca.
|
phone_numbers.primary_phone |
Główny numer telefonu w formacie E.164 (np. „+441234567890”).
|
storefront_address.region_code |
Kod regionu CLDR kraju/regionu adresu
|
storefront_address.administrative_area |
Najwyższy podział administracyjny używany w przypadku adresów pocztowych kraju lub regionu
|
storefront_address.locality |
Część adresu odpowiadająca miastu
|
storefront_address.postal_code |
Kod pocztowy adresu
|
metadata.place_id |
Jeśli ta lokalizacja została zweryfikowana i jest połączona z Mapami Google lub się w nich wyświetla, to pole jest równe identyfikatorowi miejsca tej lokalizacji
|
openInfo.status |
Wskazuje, czy lokalizacja jest obecnie otwarta
(
|
labels |
Zbiór ciągów znaków w dowolnym formacie, które umożliwiają oznaczanie firmy. W przeciwieństwie do wszystkich innych pól ta wartość musi dokładnie pasować do pełnej etykiety, w tym do wielkości liter, a nie tylko do tokena. Jeśli np. etykieta to "XX YY", to nie będzie pasować ani "XX", ani "xx yy".
|
storeCode |
Identyfikator zewnętrzny tej lokalizacji, który musi być unikalny w danym koncie
|
| Funkcje | |
distance |
Umożliwia filtrowanie na podstawie 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. Poszczególne kryteria sortowania są oddzielone przecinkami w ciągu znaków orderBy, jak w tym przykładzie:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Aktualizowanie lokalizacji
Za pomocą interfejsu My Business Business Information API możesz zaktualizować co najmniej 1 pole lokalizacji za pomocą metody locations.patch.
Aby zmienić co najmniej 1 pole lokalizacji, użyj tych elementów:
Dodaj pola i zaktualizowane wartości za pomocą pola lokalizacji oraz użyj listy zaktualizowanych pól rozdzielonych przecinkami jako wartości fieldMask.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}