Praca z danymi o lokalizacji

W tym samouczku pokazujemy, jak tworzyć i edytować dane o lokalizacji. Interfejs My Business Information API umożliwia Ci:

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:

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"
      }
     }
}

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:

HTTP
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. :

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

Zwracanie wersji Map Google

HTTP

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:

HTTP
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ę):

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

Filtrowanie wyników przy wyświetlaniu listy lokalizacji

HTTP

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:

HTTP
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

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title:"Bajis" (dopasowuje dowolną nazwę lokalizacji do podłańcucha „Bajis”)

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title="Bajis" (dopasowuje dowolną nazwę lokalizacji do słowa „Bajis” jako tokena/słowa)

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.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=categories="french_restaurant"

phone_numbers.primary_phone

Główny numer telefonu w formacie E.164 (na przykład: „+441234567890”).

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=phone_numbers.primary_phone="+441234567890"

storefront_address.region_code

Kod regionu CLDR kraju lub regionu adresu

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.region_code="US"

storefront_address.administrative_area

Najwyższy podział administracyjny używany w przypadku adresów pocztowych w kraju lub regionie.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.administrative_area="CA"

storefront_address.locality

Miasto (miejscowość) adresu

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.locality="New York"

storefront_address.postal_code

Kod pocztowy adresu.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.postal_code="12345"

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ą.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=metadata.place_id="12345"

openInfo.status

Wskazuje, czy lokalizacja jest obecnie otwarta dla firm (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

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ć.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=labels="newly open"

storeCode

Zewnętrzny identyfikator tej lokalizacji, który musi być unikalny w obrębie danego konta.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storeCode="12345"

Funkcje
distance

Umożliwia filtrowanie według odległości od lokalizacji od punktu geograficznego.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(1.0, -25.0))<1000.0

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:

HTTP
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:

HTTP

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"
}