本教學課程說明如何建立及編輯位置資料。My Business Business Information API 可讓您執行下列操作：
地點可用於廣告，但必須經過驗證，才能在 Google 搜尋和 Google 地圖上顯示。位置資料由 accounts.locations 集合表示。
事前準備
使用 My Business Business Information API 前，您必須先註冊應用程式並取得 OAuth 2.0 憑證。如要進一步瞭解如何開始使用 My Business Business Information API，請參閱「基本設定」。
建立位置
您可以使用 My Business Business Information API，透過 accounts.locations.create 為商家建立新地點。
如要建立位置，請使用下列指令：
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"
}
}
}
刪除位置
您可以使用 My Business Business Information API，透過 locations.delete 刪除地點。
如要刪除位置，請使用下列指令：
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
依名稱取得位置
如果帳戶與多個商家相關聯，建議您取得單一地點。您可以使用 locations.get，依商家名稱篩選，取得特定地點。
如要依名稱取得位置，請使用下列指令。您必須指定 readMask，才能擷取特定欄位。:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
傳回 Google 地圖版本
如要傳回 Google 地圖版的地點，請在要求網址中附加 googleUpdated，如以下範例所示：
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
如果沒有結果，系統會傳回 404 NOT FOUND HTTP 狀態碼。如要進一步瞭解如何管理 Google 資訊更新，請參閱「接受或拒絕更新」。
傳回擴充位置資料和編輯狀態 (v1alpha)
如要擷取商家提供的地點資料和消費者看到的地點資料，以及每個欄位的編輯生命週期階段 (例如 EDIT_LIFECYCLE_STAGE_PENDING 或 EDIT_LIFECYCLE_STAGE_REJECTED)、編輯來源 (SOURCE_API 或 SOURCE_UI) 和違反政策的原因，請在單一呼叫中使用 v1alpha 中的 locations.getExtended：
GET
https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}:getExtended
如需完整的回應範例，以及如何解讀各欄位編輯狀態和違反政策情形的詳細資訊，請參閱「查看地點和屬性的編輯狀態」。
列出位置
管理一或多個地點時，您可能需要列出與帳戶相關聯的所有地點。使用 accounts.locations.list API，列出與使用者相關聯的所有地點。
如要列出已驗證使用者直接擁有或管理的所有地點，請使用下列指令：
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
在要求網址中使用 '-' 萬用字元，即可納入間接擁有的商家資訊 (透過群組擁有或管理)：
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
列出地點時篩選結果
呼叫 accounts.locations.list 時，您可以使用篩選器限制傳回的結果。如要篩選要求，請在基準網址中附加篩選運算式，如以下範例所示：
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22
基本查詢語法
限制的語法如下：<field><operator><value>，其中運算子為 EQUALS (=) 或 HAS (:)。除了 locationName 之外，EQUALS (=) 和 HAS (:) 運算子在所有欄位中都等效 (請參閱下表)。
引號會編碼為「%22」，空格則會編碼為加號 (+)。
除非另有註明，否則所有比較都是不區分大小寫的權杖比較。例如，「4 drive」會比對出「4, Privet Drive」。
在篩選器查詢中合併多個欄位
API 允許使用 AND 連結所有欄位限制。不過，如果使用 OR 關鍵字，所有限制都必須套用至同一個欄位。例如：不允許使用 locationName=A OR labels=B。
範例
以下範例顯示的篩選運算式會傳回名稱為「Pepé Le Pew」的所有位置。其中顯示「french_restaurant」或「european_restaurant」類別，以及「新開幕」標籤。
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
依距離或帳戶搜尋
以下範例說明如何搜尋距離某個地理位置一定範圍內的地點：
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
如要篩選美國科羅拉多州波德市方圓 1000 英里內的地點，請按照下列步驟操作：
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0
所有支援的篩選器欄位清單
以下是可用於篩選的所有欄位完整清單：
| 欄位 | 說明與範例 |
|---|---|
| 字串比對欄位 | |
title |
商家的實際名稱
|
categories |
主要類別和其他類別的組合。 請注意，您必須省略「gcid:」。如果有多個類別，只要至少有一個類別符合這個模式，這項篩選器就會比對成功。
|
phone_numbers.primary_phone |
主要電話號碼，格式為 E.164 (例如「+441234567890」)。
|
storefront_address.region_code |
地址所在國家/地區的 CLDR 區域代碼
|
storefront_address.administrative_area |
國家/地區郵寄地址使用的最高行政區劃
|
storefront_address.locality |
地址中的城市/鄉鎮部分
|
storefront_address.postal_code |
地址的郵遞區號
|
metadata.place_id |
如果這個地點已通過驗證，且已連結/顯示在 Google 地圖上，這個欄位會等於該地點的地點 ID
|
openInfo.status |
指出地點目前是否營業 (
|
labels |
一組任意形式的字串，可用來標記商家。與所有其他欄位不同的是，這個值必須與完整標籤完全相符 (包括大小寫)，而不只是權杖。舉例來說，如果標籤為「XX YY」，則「XX」或「xx yy」都不會相符。
|
storeCode |
這個地點的外部 ID，在指定帳戶中不得重複
|
| 函式 | |
distance |
可根據地點與地理位置點的距離進行篩選。
|
依查詢欄位排序
您可以依商家名稱或商店代碼，以遞增或遞減順序排序結果。多個排序條件在 orderBy 字串中以半形逗號分隔，如以下範例所示：
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
修補位置
使用 My Business Business Information API，透過 locations.patch 更新營業地點的一或多個欄位。
如要變更地點的一或多個欄位，請使用下列方法：
新增欄位和更新後的值，以及位置欄位，並使用以逗號分隔的更新欄位清單做為 fieldMask 的值。
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}