使用营业地点数据

本教程介绍了如何创建和修改营业地点数据。借助 My Business Business Information API,您可以执行以下操作:

营业地点可以在 Google Ads 中使用,但必须先通过验证才能在 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 为商家创建新的营业地点。

如需创建营业地点,请使用以下命令:

HTTP
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 删除营业地点。

如需删除营业地点,请使用以下命令:

HTTP
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

按名称获取营业地点

如果您的账号关联了多个商家,您可能希望获取其中某个营业地点。您可以通过 locations.get 按商家名称进行过滤,以获取特定的营业地点。

要按名称获取营业地点,请使用以下命令(您必须指定 readMask 才能检索具体字段):

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

返回 Google 地图版本

HTTP

要返回某个营业地点的 Google 地图版本,请在请求网址后附加 googleUpdated,如以下示例所示:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}

如果没有结果,会返回 404 NOT FOUND HTTP 状态代码。如需详细了解如何管理 Google 更新,请点击此处

列出营业地点

如果您管理一个或多个营业地点,那么您可能希望列出与您的账号关联的所有营业地点。您可以使用 accounts.locations.list API 列出与某个用户关联的所有营业地点。

要列出某个经过身份验证的用户直接拥有或管理的所有营业地点,请使用以下命令:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

在请求网址中为账号使用 '-' 通配符,以包含间接拥有的商家信息(通过群组拥有或管理):

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

过滤列出的营业地点结果

HTTP

您可以使用过滤条件来限制调用 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”类别,并带有“newly open”标签。

locationName=%22Pepé+Le+Pew%22+AND+
(categories=%22french_restaurant%22+OR+
categories=%22european_restaurant%22)+AND+
labels=%22newly+open%22

按距离或账号搜索

以下示例展示了如何搜索与某个具体位置的距离在特定范围内的营业地点:

HTTP
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

商家的实际名称

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title:"Bajis"(匹配任何包含子字符串“Bajis”的营业地点名称)

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title="Bajis"(匹配任何包含令牌/字词“Bajis”的营业地点名称)

categories

主要类别和其他类别的组合。请注意,必须省略“gcid:”。如果存在多个类别,则至少有一个类别与此模式匹配时,此过滤条件才会匹配。

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=categories="french_restaurant"

phone_numbers.primary_phone

以 E.164 格式表示的主要电话号码(例如:“+441234567890”)。

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=phone_numbers.primary_phone="+441234567890"

storefront_address.region_code

地址所在国家/地区的 CLDR 地区代码

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.region_code="US"

storefront_address.administrative_area

某个国家或地区的邮政地址中使用的最高行政区划

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.administrative_area="CA"

storefront_address.locality

地址的城市/乡镇部分

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.locality="New York"

storefront_address.postal_code

地址的邮政编码

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.postal_code="12345"

metadata.place_id

如果此营业地点已通过验证并已连接到 Google 地图/在 Google 地图上显示,则此字段等于该营业地点的地点 ID

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=metadata.place_id="12345"

openInfo.status

指明该营业地点目前是否营业(OPENCLOSED_PERMANENTLY

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="OPEN"

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="CLOSED_PERMANENTLY"

labels

一组任何形式的字符串,用于为自己的商家添加代码。与所有其他字段不同,此值必须与完整的标签完全匹配,包括大小写,而不仅仅是令牌。例如,如果标签为“XX YY”,则“XX”或“xx yy”都不匹配。

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=labels="newly open"

storeCode

此营业地点的外部标识符,该 ID 在指定账号中必须是唯一的

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storeCode="12345"

函数
distance

可让您根据营业地点与某地理位置之间的距离进行过滤。

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(1.0, -25.0))<1000.0

按查询字段排序

您可以按商家名称或实体店代码对结果进行升序或降序排序。如有多个排序条件,应在 orderBy 字符串中以英文逗号分隔,如以下示例所示:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

修补营业地点

使用 My Business Business Information API 通过 locations.patch 更新营业地点的一个或多个字段。

要更改某个营业地点的一个或多个字段,请使用以下命令:

HTTP

使用营业地点字段添加字段和更新后的值,并使用以英文逗号分隔的更新字段列表作为 fieldMask 的值。

PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
    "title": "Google Shoes"
}