本教學課程說明如何建立及編輯位置資料。My Business Business Information API 可讓你執行下列操作：
地點可用於 Google Ads，但必須通過驗證，才能在 Google 搜尋和 Google 地圖上顯示。位置資料是以 accounts.locations 集合表示。
事前準備
使用 My Business Information API 前，您必須先註冊應用程式並取得 OAuth 2.0 憑證。如要進一步瞭解如何開始使用 My Business Business Information API，請參閱「基本設定」。
建立地點
您可以使用 My 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 雲端硬碟」的比對結果會與「4, Privet Drive」相符。
在篩選器查詢中合併多個欄位
API 允許 AND 連結所有欄位限制。不過，如果是 OR 關鍵字，所有限制都必須套用至同一個欄位。例如：不得使用 locationName=A 或 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
所有支援的篩選器欄位清單
以下完整列出可用於篩選的所有欄位：
| Fields | 說明和範例 |
|---|---|
| 字串比對欄位 | |
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 Information API，透過 locations.patch 更新地點的一或多個欄位。
如要變更某個地點的一或多個欄位，請使用下列方式：
根據位置欄位新增欄位和更新的值，並使用以半形逗號分隔的已更新欄位清單做為 fieldMask 的值。
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}