Praca z danymi o lokalizacji

Z tego samouczka dowiesz się, jak tworzyć i edytować dane o lokalizacji. My Business Business Information API umożliwia:

• Utwórz nową lokalizację.
• Usuwanie lokalizacji
• Pobieranie lokalizacji według nazwy zasobu
• Wyświetlanie listy wszystkich lokalizacji na koncie
• Zaktualizuj co najmniej jedno pole lokalizacji.

Lokalizacje mogą być używane w reklamach, 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 My Business Business Information API, musisz zarejestrować aplikację i uzyskać dane logowania OAuth 2.0. Szczegółowe informacje o tym, jak zacząć korzystać z interfejsu My Business Business Information API, znajdziesz w artykule Konfiguracja podstawowa.

Tworzenie lokalizacji

Za pomocą interfejsu My Business Business Information API możesz utworzyć nową lokalizację firmy, używając metody accounts.locations.create.

Aby utworzyć lokalizację, użyj tych informacji:

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

Możesz użyć interfejsu My Business Business Information API, aby usunąć lokalizację za pomocą metody locations.delete.

Aby usunąć lokalizację, użyj tych metod:

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ć informacje o jednej lokalizacji. Możesz filtrować według nazwy firmy, aby uzyskać konkretną lokalizację za pomocą metody locations.get.

Aby uzyskać lokalizację według nazwy, użyj tych informacji. Aby pobrać określone pola, musisz podać readMask. :

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

Zwracanie wersji Map Google

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.

Zwracanie rozszerzonych danych o lokalizacji i stanu edycji (v1alpha)

Aby w ramach jednego wywołania pobrać dane o lokalizacji podane przez sprzedawcę i dane o lokalizacji przeznaczone dla użytkowników, a także etapy cyklu życia edycji poszczególnych pól (np. EDIT_LIFECYCLE_STAGE_PENDING lub EDIT_LIFECYCLE_STAGE_REJECTED), źródło edycji (SOURCE_API lub SOURCE_UI) i przyczyny naruszenia zasad, użyj locations.getExtended w v1alpha:

GET
https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}:getExtended

Pełne przykłady odpowiedzi i szczegółowe informacje o interpretowaniu stanu zmian w poszczególnych polach i naruszeń zasad znajdziesz w artykule Sprawdzanie stanu zmian w lokalizacjach i atrybutach.

Wyświetlenie listy lokalizacji

Jeśli zarządzasz co najmniej jedną lokalizacją, możesz wyświetlić listę wszystkich lokalizacji powiązanych 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órych właścicielem lub menedżerem jest uwierzytelniony użytkownik, użyj:

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

Aby uwzględnić oferty, które należą do Ciebie pośrednio (czyli należą do grupy lub są przez nią zarządzane), użyj w adresie URL żądania symbolu wieloznacznego '-' dla konta:

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

Filtrowanie wyników podczas wyświetlania listy lokalizacji

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 zaznaczono inaczej, wszystkie porównania są porównaniami tokenów, w których wielkość liter nie jest rozróżniana. 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 OR wszystkie ograniczenia muszą dotyczyć tego samego pola. Na przykład: locationName=A LUB 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ś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

Poniższy 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}

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 filtrów

Poniżej znajdziesz pełną listę wszystkich pól, których można używać do filtrowania:

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 znaków orderBy, jak w tym przykładzie:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

Zaktualizuj lokalizację

Użyj interfejsu My Business Business Information API, aby zaktualizować co najmniej jedno pole lokalizacji za pomocą metody locations.patch.

Aby zmienić co najmniej jedno pole lokalizacji, użyj tych opcji:

PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
    "title": "Google Shoes"
}