W tym samouczku pokazujemy, jak tworzyć i edytować dane o lokalizacji. Interfejs My Business Information API umożliwia Ci:
- Utwórz nową lokalizację.
- Usuwanie lokalizacji
- Uzyskaj lokalizację według nazwy zasobu.
- Lista wszystkich lokalizacji powiązanych z kontem.
- Aktualizowanie co najmniej jednego pola lokalizacji.
Lokalizacje mogą być używane w Google Ads, ale muszą zostać zweryfikowane, aby mogły się wyświetlać w wyszukiwarce i Mapach. Dane o lokalizacji są reprezentowane przez kolekcję accounts.locations.
Zanim zaczniesz
Zanim zaczniesz korzystać z interfejsu My Business Information API, musisz zarejestrować swoją aplikację i uzyskać dane uwierzytelniające OAuth 2.0. Szczegółowe informacje o tym, jak zacząć korzystać z interfejsu My Business Information API, znajdziesz w artykule Podstawowa konfiguracja.
Tworzenie lokalizacji
Nową lokalizację firmy możesz utworzyć za pomocą interfejsu My Business Information API (accounts.locations.create).
Aby utworzyć lokalizację, skorzystaj z tych opcji:
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 Information API możesz usunąć lokalizację za pomocą polecenia locations.delete.
Aby usunąć lokalizację, wykonaj te czynności:
DELETE https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Uzyskiwanie lokalizacji według nazwy
Jeśli ze swoim kontem masz powiązanych wiele firm, lepiej wybrać jedną lokalizację. Korzystając z metody locations.get, możesz filtrować wyniki według nazwy firmy, aby znaleźć konkretną lokalizację.
Aby uzyskać lokalizację według nazwy, użyj tych opcji. Aby pobrać określone pola, musisz określić parametr readMask. :
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Zwracanie wersji Map Google
Aby wyświetlić lokalizację w wersji z Map Google, dołącz do adresu URL żądania ciąg googleUpdated
, jak w tym przykładzie:
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
W przypadku braku 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 jedną lokalizacją lub większą ich liczbą, możesz wyświetlić wszystkie lokalizacje powiązane z Twoim kontem. Za pomocą interfejsu API accounts.locations.list możesz wyświetlić listę wszystkich lokalizacji powiązanych z użytkownikiem.
Aby wyświetlić wszystkie lokalizacje należące bezpośrednio do uwierzytelnionego użytkownika lub przez niego zarządzane, użyj tych opcji:
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
Użyj symbolu wieloznacznego '-'
dla konta w adresie URL żądania, aby uwzględnić wizytówki należące pośrednio (należące do grupy lub zarządzane przez grupę):
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrowanie wyników przy wyświetlaniu listy lokalizacji
Za pomocą filtrów możesz ograniczyć wyniki wyświetlane, gdy wywołujesz funkcję accounts.locations.list. Aby filtrować żądanie, dołącz wyrażenie filtra do podstawowego adresu URL, jak 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 zapytania
Ograniczenie ma taką 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
(zobacz tabelę poniżej).
Cudzysłowy są kodowane jako „%22”, a spacje są znakami plusa (+).
O ile nie wskazano inaczej, w porównaniach nie rozróżnia się wielkości liter. Na przykład „4 dysk” będzie pasować do „4, Privet Drive”.
Łączenie wielu pól w zapytaniu filtra
Interfejs API pozwala łączyć wszystkie ograniczenia pól za pomocą operatora ORAZ. Jednak w przypadku słowa kluczowego LUB wszystkie ograniczenia odnoszą się do tego samego pola. np.: locationName=A
OR labels=B
nie jest dozwolone.
Przykład
Poniższy przykład pokazuje wyrażenie filtra, które zwraca wszystkie lokalizacje o nazwie „Pepé Le Pew”. Wyświetlane są kategorie „restauracja_francuska” i „european_restauracja” oraz etykieta „nowo otwarte”.
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
Szukaj według odległości lub konta
Z przykładu poniżej dowiesz się, jak wyszukiwać lokalizacje znajdujące się 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 1000 mil od Boulder w Kolorado (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 wyczerpująca lista wszystkich pól, których można używać do filtrowania:
Pola | Opis i przykład |
---|---|
Pola pasujące do ciągu znaków | |
title |
Rzeczywista nazwa firmy
|
categories |
Kombinacja kategorii podstawowej i kategorii dodatkowych. Pamiętaj, że parametr „gcid:” musisz pominąć. Jeśli masz wiele kategorii, ten filtr będzie pasować, jeśli co najmniej jedna z nich pasuje do wzorca.
|
phone_numbers.primary_phone |
Główny numer telefonu w formacie E.164 (na przykład: „+441234567890”).
|
storefront_address.region_code |
Kod regionu CLDR kraju lub regionu adresu
|
storefront_address.administrative_area |
Najwyższy podział administracyjny używany w przypadku adresów pocztowych w kraju lub regionie.
|
storefront_address.locality |
Miasto (miejscowość) adresu
|
storefront_address.postal_code |
Kod pocztowy adresu.
|
metadata.place_id |
Jeśli ta lokalizacja została zweryfikowana, jest powiązana z Mapami Google lub się z nią wyświetla, to pole jest takie samo jak identyfikator miejsca powiązany z tą lokalizacją.
|
openInfo.status |
Wskazuje, czy lokalizacja jest obecnie otwarta dla firm (
|
labels |
Zbiór dowolnych ciągów tekstowych, które umożliwiają tagowanie firmy. W przeciwieństwie do wszystkich innych pól ta wartość musi dokładnie odpowiadać pełnej etykiecie, włącznie z wielkością liter, a nie tylko tokenem. Na przykład jeśli etykieta to „XX YY”, ani „XX” ani „xx yy” nie będzie pasować.
|
storeCode |
Zewnętrzny identyfikator tej lokalizacji, który musi być unikalny w obrębie danego konta.
|
Funkcje | |
distance |
Umożliwia filtrowanie według odległości od lokalizacji od punktu geograficznego.
|
Sortuj według pola zapytania
Możesz posortować wyniki według nazwy firmy lub kodu sklepu w kolejności rosnącej lub malejącej. Jeśli w ciągu znaków orderBy
jest wiele kryteriów sortowania, rozdziel je przecinkami jak w tym przykładzie:
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Naprawianie lokalizacji
Zaktualizuj jedno lub więcej pól lokalizacji za pomocą interfejsu My Business Information API za pomocą parametru locations.patch.
Aby zmienić jedno lub więcej pól lokalizacji, skorzystaj z tych opcji:
Dodaj pola i zaktualizowane wartości o pole lokalizacji i użyj oddzielonej przecinkami listy zaktualizowanych pól jako wartości w polu fieldMask
.
PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title { "title": "Google Shoes" }