本教學課程將說明如何建立及編輯位置資料。My Business Business Information API 可讓您執行下列操作：
地點可用於廣告，但必須經過驗證，才能在搜尋聯播網和地圖上顯示。位置資料由 accounts.locations 集合代表。
事前準備
使用「我的商家」商家資訊 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 更新，請參閱這篇文章。
列出位置
如果你管理一或多個地點，建議你列出與帳戶相關聯的所有地點。使用 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 (:)。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://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"
}