このチュートリアルでは、ビジネス情報を作成、編集する方法を説明します。Google My Business API では次のような操作を行えます。
ビジネス情報は Google 広告で使用できます。ただし、Google 検索や Google マップにビジネス情報を表示するには、オーナー確認の手続きが必要です。ビジネス情報は v4.accounts.locations コレクションで表されます。
準備
Google My Business API を使用するには、組み込み先のアプリケーションを事前に登録し、OAuth 2.0 の認証情報を取得する必要があります。Google My Business API の使用方法について詳しくは、基本設定をご覧ください。
ビジネス情報を取得する
ビジネス拠点をお持ちの場合は、アカウントに関連付けられているすべての拠点(ビジネス)について、オーナー確認を行うことをおすすめします。GMB API の accounts.locations.batchGet を使用すると、特定のユーザーに関連付けられているすべてのビジネスのリストを取得できます。
特定の認証済みユーザーに関連付けられたすべてのビジネス情報を取得するには、次のように記述します。
POST https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations:batchGet { "locationNames": [ "accounts/{accountId}/locations/{locationId}", "accounts/{accountId}/locations/{locationId}" ], }
この関数は、引数としてビジネス名の ArrayList<String> を取り、GetLocationsResponse
インスタンスを返します。このインスタンスから accounts.locations のリストを取得できます。
/* * 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(); }
追加データ
Java API を使用すると、ビジネス情報のインスタンスの追加フィールド データにアクセスできます。アカウントに関する追加データを返すには、次のメソッドを使用します。
getAdditionalCategories()
getAddress()
getBusinessHours()
getLabels()
getLocationKey()
getLocationName()
getName()
getPrimaryCategory()
getPrimaryPhone()
getServiceArea()
getStoreCode()
getWebsiteUrl()
ビジネス情報を作成する
GMB API では、accounts.locations.create を使用して新しいビジネス情報を作成できます。
ビジネス情報を作成するには、次のように記述します。
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" } }
この関数は、サンプルとして Google シドニー オフィスの新しいビジネス情報を作成します。
/** * 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; }
ビジネス情報を削除する
GMB API では、accounts.locations.delete を使ってビジネス情報を削除できます。
ビジネス情報を削除するには、次のように記述します。
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(); }
名前を指定してビジネス情報を取得する
アカウントに多くのビジネス情報が関連付けられており、その中の 1 つだけを取り出したい場合は、accounts.locations.get を使用し、ビジネス名でフィルタをかけると特定のビジネス情報を取得できます。
名前を指定してビジネス情報を取得するには、次のように記述します。
GET https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
この関数は引数としてビジネスのリストを取り、指定されたアカウントが存在すれば、そのデータを返します。
/* * 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; }
追加データ
Java API を使用すると、ビジネス情報のインスタンスの追加フィールド データにアクセスできます。アカウントに関する追加データを返すには、次のメソッドを使用します。
getAdditionalCategories()
getAddress()
getBusinessHours()
getLabels()
getLocationKey()
getLocationName()
getName()
getPrimaryCategory()
getPrimaryPhone()
getServiceArea()
getStoreCode()
getWebsiteUrl()
Google マップのバージョンを取得する
ビジネス情報の Google マップ バージョンを取得するには、次のように、リクエスト URL に googleUpdated
を付加します。
GET https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}:googleUpdated
該当する結果がない場合は、HTTP ステータス コード 404 NOT FOUND
が返されます。
ビジネスの一覧を取得する
アカウントに多数のビジネスが関連付けられている場合は、それらすべてのオーナー確認をまとめて行うことをおすすめします。GMB API では、accounts.locations.list を使ってすべてのビジネスを取得できます。
すべてのビジネスを取得するには、次のように記述します。
GET https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations
この関数は、指定するアカウントのビジネスの一覧を返します。
/* * 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; }
ビジネスのリスト結果を絞り込む
accounts.locations.listを呼び出す際、フィルタを使用して結果を絞り込むことができます。 リクエストにフィルタを適用するには、ベース URL にフィルタ式を付加します。次の例をご覧ください。
GET https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter={FIELD_NAME}=%22{YOUR_QUERY}%22
基本的なクエリ構文
限定条件の構文は <field><operator><value>
で、演算子(operator)は EQUALS(=)または HAS(:)です。EQUALS(=)と HAS(:)演算子は、locationName
以外のすべてのフィールド(下の表を参照)と同等です。
引用符は「%22」、スペースはプラス記号(+)としてエンコードされます。
特に明記されていない限り、すべての比較で大文字と小文字を区別しないトークン比較です。たとえば、「4 drive」は「4, Privet Drive」と一致します。
フィルタクエリで複数のフィールドを結合する
この API では、AND を使用してすべてのフィールド制限を結び付けることができますが、OR キーワードでは、すべての制限を同じフィールドに適用する必要があります。たとえば、locationName=A
OR labels=B
は許可されません。
例
次の例のフィルタ式は、名前が「Pepé Le Pew」、カテゴリが「french_restaurant」または「european_restaurant」、ラベルが「newly open」のビジネスをすべて返すものです。
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
距離またはアカウントで検索する
次の例は、ある地点から指定された距離内にあるビジネス拠点の検索方法を示すものです。
GET https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
米国のコロラド州ボルダーから 1,000 マイル圏内にあるビジネス拠点をフィルタリングするには:
GET https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=distance(latlng, geopoint(40.01, -105.27))<1000.0
サポートされているすべてのフィルタ フィールドのリスト
以下は、フィルタに使用できるすべてのフィールドの完全なリストです。
フィールド | 説明と例 |
---|---|
フィールドに一致する文字列 | |
locationName |
ビジネスの実際の名称
|
categories |
メインカテゴリと追加カテゴリの組み合わせ。 なお、「gcid:」は省略します。複数のカテゴリがある場合、少なくとも 1 つのカテゴリがこのパターンに一致すると、このフィルタは一致します。
|
primaryPhone |
E.164 形式のメインの電話番号(例: +441234567890)。
|
address.regionCode |
住所の国または地域を表す CLDR 地域コード
|
address.administrativeArea |
国または地域の住所で使われる最上位の行政区画
|
address.locality |
住所の市区町村の部分
|
address.postalCode |
住所の郵便番号
|
locationKey.placeId |
ビジネスのオーナー確認が済んでおり、Google マップに関連付けられているか表示されている場合は、このフィールドはそのビジネスのプレイス ID と同じになります。
|
openInfo.status |
ビジネスが現在営業しているかどうかを表します
(
|
labels |
ビジネスにタグを付けられるようにするための自由形式の文字列のコレクションです。他のすべてのフィールドとは異なり、この値はトークンだけでなく、ラベルと完全に一致する(大文字と小文字を含む)必要があります。たとえば、ラベルが「XX YY」の場合、「XX」も「xx yy」も一致しません。
|
storeCode |
このビジネスの外部識別子です。アカウント内で一意である必要があります
|
述語 | |
locationState.isPublished |
ビジネスが Google マップに公開されているかどうかを示します
(
|
locationState.isGoogleUpdated |
このビジネスに関連付けられているプレイス ID に変更があるかどうかを表します
(
|
locationState.isSuspended |
ビジネスが強制停止されているかどうかを表します
(
|
locationState.isDuplicate |
ビジネスが別のビジネスと重複しているかどうかを表します
(
|
関数 | |
distance |
特定の地点からのビジネス拠点までの距離に基づいてフィルタリングできます。
|
クエリ フィールドに基づいて並べ替える
出力結果はビジネス名や店舗コードに基づいて、昇順や降順に並べ替えられます。並べ替え基準が複数ある場合は、orderBy
に続けて、並べ替え基準をカンマで区切って指定します。次の例をご覧ください。
GET https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?orderBy=locationName,storeCode
ビジネス情報を修正する
GMB API では、accounts.locations.patch を使ってビジネス情報の項目を更新できます。
ビジネス情報の項目を変更するには、次のように記述します。
ビジネス情報の項目を指定して、項目と更新する値を追加します。更新する項目はカンマ区切りのリストにし、fieldMask
の値として指定します。
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", }
この関数は、ビジネス情報の locationName
項目を更新します。
/** * 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); }