Achtung: Version 4.8 der API wurde veröffentlicht. Hier finden Sie das Änderungsprotokoll. Beiträge mit einem Bezug zur Coronakrise sind für Handelsketten weiterhin vorübergehend zulässig.

Mit Standortdaten arbeiten

In dieser Anleitung erfahren Sie, wie Sie Standortdaten erstellen und bearbeiten. Die Google My Business API bietet Ihnen folgende Möglichkeiten:

Standorte können in Anzeigen verwendet werden, müssen aber bestätigt werden, damit sie in der Google-Suche und auf Google Maps erscheinen können. Für Standortdaten werden die Felder von v4.accounts.locations verwendet.

Hinweis

Sie können die Google My Business API erst verwenden, nachdem Sie Ihre Anwendung registriert und OAuth 2.0-Anmeldedaten abgerufen haben. Weitere Informationen zu den ersten Schritten mit der Google My Business API finden Sie unter Grundlegende Einrichtung.

Einen oder mehrere Standorte abrufen

Wenn Sie ein Unternehmen mit einem oder mehreren Standorten haben, sollten Sie alle Standorte bestätigen, die mit Ihrem Konto verknüpft sind. Mit der accounts.locations.batchGet API können Sie alle Standorte auflisten, die einem Nutzer zugeordnet sind.

Verwenden Sie folgenden Code, um alle Standorte für einen authentifizierten Nutzer aufzulisten:

HTTP
POST
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations:batchGet

{
  "locationNames": [
    "accounts/{accountId}/locations/{locationId}",
    "accounts/{accountId}/locations/{locationId}"
  ],
}
Java

Diese Funktion verwendet einen ArrayList<String> mit Standortnamen und gibt eine GetLocationsResponse-Instanz zurück, aus der Sie die Liste der accounts.locations abrufen können.

/*
 * Returns the specified locations for a given account.
 * @param accountName Name (resource path) of the account to get locations from.
 * @param nameList List of location names to return.
 * @return GetLocationsRequest Data model class containing results.
 * @throws IOException.
 */
private static List<Location> batchGetLocations(String accountName, ArrayList<String> nameList) throws IOException {
  GetLocationsRequest getLocationsRequest = new GetLocationsRequest();
  getLocationsRequest.setLocationNames(nameList);

  Mybusiness.Accounts.Locations.BatchGet locations =
      mybusiness.accounts().locations().batchGet(accountName, getLocationsRequest);

  GetLocationsResponse response = locations.execute();

  return response.getLocations();
}

Zusätzliche Daten

Die Java API bietet Zugriff auf zusätzliche Felddaten für Standortinstanzen. Verwenden Sie die folgenden Methoden, um zusätzliche Daten zum Konto abzurufen:

  • getAdditionalCategories()
  • getAddress()
  • getBusinessHours()
  • getLabels()
  • getLocationKey()
  • getLocationName()
  • getName()
  • getPrimaryCategory()
  • getPrimaryPhone()
  • getServiceArea()
  • getStoreCode()
  • getWebsiteUrl()

Standort erstellen

Anhand von accounts.locations.create können Sie mit der API einen neuen Standort für ein Unternehmen erstellen.

Verwenden Sie folgenden Code, um einen Standort zu erstellen:

HTTP
POST
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False

{
    "storeCode": "GOOG-SYD",
    "languageCode": "en-AU",
    "locationName": "Google Sydney",
    "primaryPhone": "02 9374 4000",
    "address": {
      "addressLines": [
        "Level 5",
        "48 Pirrama Road"
      ],
      "locality": "Pyrmont",
      "postalCode": "2009",
      "administrativeArea": "NSW",
      "regionCode": "AU"
    },
    "websiteUrl": "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"
        }
      ]
    },
    "primaryCategory": {
      "categoryId": "gcid:software_company"
    }
}
Java

Mit dieser Funktion wird ein neuer Beispielstandort für Google Sydney erstellt.

/**
 * Creates a new location.
 * @param accountName The name (resource path) of the account to create a
 *   location for.
 * @return Location The data for the new location.
 * @throws Exception
 */

public static Location createLocation(String accountName) throws Exception {
    System.out.println("Creating Location");

    // Street address
    List<String> addressLines = new ArrayList();
    addressLines.add("Level 5, 48 Pirrama Road");
    Address address = new Address()
        .setAddressLines(addressLines)
        .setLocality("Pyrmont")
        .setAdministrativeArea("NSW")
        .setCountry("AU")
        .setPostalCode("2009");

    // Business hours
    List<TimePeriod> periods = new ArrayList<>();
    List<String> days = Arrays.asList("Monday", "Tuesday", "Wednesday", "Thursday", "Friday");

    for (String day : days) {
      TimePeriod period = new TimePeriod()
          .setOpenDay(day)
          .setOpenTime("9:00")
          .setCloseTime("17:00")
          .setCloseDay(day);
      periods.add(period);
    }
    BusinessHours businessHours = new BusinessHours()
        .setPeriods(periods);
    Location location = new Location()
        .setAddress(address)
        .setRegularHours(businessHours)
        .setLocationName("Google Sydney")
        .setStoreCode("GOOG-SYD")
        .setPrimaryPhone("02 9374 4000")
        .setPrimaryCategory(new Category().setName("Software Company"))
        .setWebsiteUrl("https://www.google.com.au/");

    Mybusiness.Accounts.Locations.Create createLocation =
        mybusiness.accounts().locations().create(accountName, location);
    createLocation.setRequestId("1a84939c-ab7d-4581-8930-ee35af6fefac");
    createLocation.setLanguageCode("en-AU");

    Location createdLocation = createLocation.execute();

    System.out.printf("Created Location:\n%s", createdLocation);
    return createdLocation;
  }

Standort löschen

Sie können die API verwenden, um einen Standort mit accounts.locations.delete zu löschen.

Verwenden Sie folgenden Code, um einen Standort zu löschen:

HTTP
DELETE
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
{
  "account": {
    "accountName": "Anne Droyd"
  },
  "languageCode": "en",
  "validateOnly": "true"
}

Java
/**
 * Deletes the specified location.
 * @param locationName The name (resource path) of the location to delete.
 * @throws Exception
 */
public static void deleteLocation(String locationName) throws Exception {
  Location location = new Location();
  location.setName(locationName);
  Mybusiness.Accounts.Locations.Delete deleteLocation =
    mybusiness.accounts().locations().delete(locationName);
  deleteLocation.execute();
}

Standort anhand des Namens abrufen

Mit Ihrem Konto sind viele Unternehmen verknüpft? Dann möchten Sie unter Umständen einen bestimmten Standort abrufen. Sie können nach dem Namen des Unternehmens filtern, um einen bestimmten Standort mit accounts.locations.get abzurufen.

Verwenden Sie folgenden Code, um einen Standort anhand seines Namens abzurufen:

HTTP
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
Java

Diese Funktion verwendet eine Liste von Standorten und gibt die Daten für das angegebene Konto zurück, sofern vorhanden.

/*
 * Returns the specified location
 * @param locationName The name (resource path) of the location to retrieve.
 * @return Location The requested location.
 */
private static Location getLocationByName(String locationName) throws IOException {
    Mybusiness.Accounts.Locations.Get location =
        mybusiness.accounts().locations().get(locationName);

    Location response = location.execute();
    return response;
}

Zusätzliche Daten

Die Java API bietet Zugriff auf zusätzliche Felddaten für Standortinstanzen. Verwenden Sie die folgenden Methoden, um zusätzliche Daten zum Konto abzurufen:

  • getAdditionalCategories()
  • getAddress()
  • getBusinessHours()
  • getLabels()
  • getLocationKey()
  • getLocationName()
  • getName()
  • getPrimaryCategory()
  • getPrimaryPhone()
  • getServiceArea()
  • getStoreCode()
  • getWebsiteUrl()

Google Maps-Version zurückgeben

HTTP

Wenn Sie die Google Maps-Version eines Standorts zurückgeben möchten, hängen Sie googleUpdated an die Anfrage-URL an, wie im folgenden Beispiel gezeigt:

GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}:googleUpdated

Wenn keine Ergebnisse vorhanden sind, wird der HTTP-Statuscode 404 NOT FOUND zurückgegeben.

Alle Standorte auflisten

Wenn viele Unternehmen mit Ihrem Konto verknüpft sind, sollten Sie alle Standorte bestätigen. Über die API können Sie alle Standorte mit accounts.locations.list abrufen.

Verwenden Sie folgenden Code, um alle Standorte abzurufen:

HTTP
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations
Java

Diese Funktion gibt eine Liste von Standorten für das angegebene Konto zurück.

/*
 * Returns all locations for the specified account.
 * @param accountName The account for which to return locations.
 * @return List<Location> A list of all locations for the specified account.
 */
public static List<Location> listLocations(String accountName) throws Exception {
  Mybusiness.Accounts.Locations.List locationsList =
      mybusiness.accounts().locations().list(accountName);
  ListLocationsResponse response = locationsList.execute();
  List<Location> locations = response.getLocations();

  if (locations != null) {
    for (Location location : locations) {
      System.out.println(location.toPrettyString());
    }
  } else {
    System.out.printf("Account '%s' has no locations.", accountName);
  }
  return locations;
}

Ergebnisse beim Auflisten von Standorten filtern

HTTP

Mithilfe von Filtern können Sie die Ergebnisse begrenzen, die zurückgegeben werden, indem Sie accounts.locations.list aufrufen. Zum Filtern einer Anfrage hängen Sie einen Filterausdruck an die Basis-URL an, wie in diesem Beispiel gezeigt:

GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter={FIELD_NAME}=%22{YOUR_QUERY}%22

Einfache Abfragesyntax

Einschränkungen haben die folgende Syntax: <field><operator><value>, wobei der Operator entweder EQUALS (=) oder HAS (:) lautet. Die Operatoren EQUALS (=) und HAS (:) bewirken in allen Feldern außer locationName das Gleiche (siehe Tabelle unten).

Anführungszeichen werden als „%22“ und Leerzeichen als Pluszeichen (+) codiert.

Sofern nicht anders angegeben, sind alle Vergleiche Tokenvergleiche, bei denen die Groß-/Kleinschreibung nicht berücksichtigt wird. So wird beispielsweise „4 drive“ als gleich mit „4, Privet Drive“ behandelt.

Mehrere Felder in einer Filterabfrage kombinieren

Über die API können alle Feldeinschränkungen mit UND verbunden werden. Bei OR müssen sich aber alle Einschränkungen auf dasselbe Feld beziehen. Zum Beispiel ist locationName=A OR labels=B nicht zulässig.

Beispiel

Im folgenden Beispiel sehen Sie einen Filterausdruck, der alle Standorte mit dem Namen „Pepé Le Pew“ zurückgibt. Es werden Kategorien für „french_restaurant“ oder „european_restaurant“ und das Label „newly open“ angezeigt.

locationName=%22Pepé+Le+Pew%22+AND+
(categories=%22french_restaurant%22+OR+
categories=%22european_restaurant%22)+AND+
labels=%22newly+open%22

Suche nach Entfernung oder Konto

Im folgenden Beispiel sehen Sie, wie Sie nach Standorten innerhalb einer bestimmten Entfernung von einem geografischen Punkt suchen können:

HTTP
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}

So rufen Sie alle Standorte in einem Umkreis von 1.000 Meilen um Boulder, Colorado, USA ab:

GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=distance(latlng, geopoint(40.01, -105.27))<1000.0

Liste aller unterstützten Filterfelder

Nachfolgend finden Sie eine vollständige Liste aller Felder, die zum Filtern verwendet werden können:

Felder Beschreibung und Beispiel
Felder für den Stringabgleich
locationName

Der tatsächliche Name des Unternehmens

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationName:"Bajis" (entspricht jedem Standortnamen mit „Bajis“ als Teilstring)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationName="Bajis" (entspricht jedem Standortnamen mit „Bajis“ als Token/Wort)

categories

Die Kombination aus der primären und den zusätzlichen Kategorien. „gcid:“ muss weggelassen werden. Sind mehrere Kategorien vorhanden, sind die Filterkriterien erfüllt, wenn mindestens eine Kategorie diesem Muster entspricht.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=categories="french_restaurant"

primaryPhone

Die primäre Telefonnummer im E.164-Format (z. B. „+491234567890“).

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=primaryPhone="+441234567890"

address.regionCode

Der CLDR-Regionscode des Landes/der Region der Adresse

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.regionCode="US"

address.administrativeArea

Die größte Verwaltungseinheit, die für Postadressen eines Landes oder einer Region verwendet wird

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.administrativeArea="CA"

address.locality

Der Ort der Adresse

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.locality="New York"

address.postalCode

Die Postleitzahl der Adresse

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.postalCode="12345"

locationKey.placeId

Wenn dieser Standort bestätigt wurde und mit Google Maps verknüpft ist bzw. dort angezeigt wird, entspricht dieses Feld der Place ID des Standorts.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationKey.placeId="12345"

openInfo.status

Gibt an, ob der Standort derzeit geöffnet ist (OPEN, CLOSED_PERMANENTLY)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=openInfo.status="OPEN"

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=openInfo.status="CLOSED_PERMANENTLY"

labels

Eine Sammlung frei definierbarer Strings, mit denen Sie Ihr Unternehmen taggen können. Im Gegensatz zu allen anderen Feldern muss dieser Wert genau mit einem vollständigen Label (einschließlich Groß- und Kleinschreibung) und nicht nur mit einem Token übereinstimmen. Beispiel: Lautet das Label „XX YY“, stimmt weder „XX“ noch „xx yy“ überein.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=labels="newly open"

storeCode

Externe Kennung für diesen Standort, die innerhalb eines bestimmten Kontos eindeutig sein muss

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=storeCode="12345"

Prädikate
locationState.isPublished

Gibt an, ob der Standort auf Google Maps veröffentlicht wurde (TRUE, FALSE)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isPublished="TRUE"

locationState.isGoogleUpdated

Gibt an, ob die Place ID des Standorts aktualisiert wurde (TRUE, FALSE)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isGoogleUpdated="TRUE"

locationState.isSuspended

Gibt an, ob der Standort gesperrt wurde (TRUE, FALSE)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isSuspended="TRUE"

locationState.isDuplicate

Gibt an, ob der Standort ein Duplikat eines anderen Standorts ist (TRUE, FALSE)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isDuplicate="TRUE"

Funktionen
distance

Damit können Sie anhand der Entfernung des Standorts von einem geografischen Punkt filtern.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=distance(latlng, geopoint(1.0, -25.0))<1000.0

Nach Abfragefeld sortieren

Sie können die Ergebnisse in aufsteigender oder absteigender Reihenfolge nach Name des Unternehmens oder Geschäftscode sortieren. Mehrere Sortierungskriterien werden im orderBy-String durch Kommas getrennt, wie im folgenden Beispiel gezeigt:

HTTP
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?orderBy=locationName,storeCode

Standort korrigieren

Sie können die API verwenden, um ein oder mehrere Felder für einen Standort mit accounts.locations.patch zu aktualisieren.

Gehen Sie so vor, um ein oder mehrere Felder für einen Standort zu ändern:

HTTP

Geben Sie die Felder und aktualisierten Werte mit dem Feld „location“ an und verwenden Sie als Wert für fieldMask eine durch Kommas getrennte Liste aktualisierter Felder.

PATCH
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=FIELD_NAME
{
    "locationName": "Google Shoes",
    "primaryPhone": "(212) 553-5558",
}
Java

Diese Funktion aktualisiert das Feld locationName für einen Standort.

/**
 * Updates the specified fields in the specified location.
 * @param phone A string value for the location's primary phone.
 * @param name The name (resource path) for the location to update.
 * @throws Exception
 */
public static void updateLocation(String phone, String name) throws Exception {
    Location location = new Location()
        .setPrimaryPhone(phone);

    Mybusiness.Accounts.Locations.Patch updateLocation =
        mybusiness.accounts().locations().patch(name, location);
    updateLocation.setFieldMask("primary_phone");
    updateLocation.setLanguageCode("en-AU");
    Location updatedLocation = updateLocation.execute();

    System.out.printf("Updated Location:\n%s", updatedLocation);
  }