In dieser Anleitung erfahren Sie, wie Sie Standortdaten erstellen und bearbeiten. Die Google My Business API bietet Ihnen folgende Möglichkeiten:
- Einen oder mehrere Standorte abrufen
- Einen neuen Standort erstellen
- Einen Standort löschen
- Einen Standort anhand des Ressourcennamens abrufen
- Alle Standorte für ein Konto auflisten
- Ein oder mehrere Felder für einen Standort aktualisieren
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:
POST
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations:batchGet
{
"locationNames": [
"accounts/{accountId}/locations/{locationId}",
"accounts/{accountId}/locations/{locationId}"
],
}
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:
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"
}
}
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:
DELETE
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
{
"account": {
"accountName": "Anne Droyd"
},
"languageCode": "en",
"validateOnly": "true"
}
/**
* 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:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
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
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:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations
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
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:
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
|
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.
|
primaryPhone |
Die primäre Telefonnummer im E.164-Format (z. B. „+491234567890“).
|
address.regionCode |
Der CLDR-Regionscode des Landes/der Region der Adresse
|
address.administrativeArea |
Die größte Verwaltungseinheit, die für Postadressen eines Landes oder einer Region verwendet wird
|
address.locality |
Der Ort der Adresse
|
address.postalCode |
Die Postleitzahl der Adresse
|
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.
|
openInfo.status |
Gibt an, ob der Standort derzeit geöffnet ist (
|
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.
|
storeCode |
Externe Kennung für diesen Standort, die innerhalb eines bestimmten Kontos eindeutig sein muss
|
| Prädikate | |
locationState.isPublished |
Gibt an, ob der Standort auf Google Maps veröffentlicht wurde (
|
locationState.isGoogleUpdated |
Gibt an, ob die Place ID des Standorts aktualisiert wurde (
|
locationState.isSuspended |
Gibt an, ob der Standort gesperrt wurde (
|
locationState.isDuplicate |
Gibt an, ob der Standort ein Duplikat eines anderen Standorts ist (
|
| Funktionen | |
distance |
Damit können Sie anhand der Entfernung des Standorts von einem geografischen Punkt filtern.
|
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:
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:
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",
}
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);
}