Listings APIListings API
登录
POST/api/v4/locations

创建地点

在您的账户中创建一个新的商家地点，并将其加入商家信息提交队列。

需要 API 密钥。请求头格式和密钥轮换请参阅身份验证。

参数

请求体

标记为必填的嵌套字段仅在您发送其父字段时适用。如果父字段为可选且您省略了它，其必填子字段不适用。

名称类型必填描述
input.namestring必填Name of the business.
input.descriptionstring必填Business description, minimum 200 characters (`SY10005` when missing or shorter). Publishers use it as the primary listing copy.
input.storeIdstring可选Unique store code. Must be unique across the account.
input.streetstring必填Street address, 5 to 100 characters (`SY10011`).
input.citystring必填City. Required where the country's `hasCity` is `true` (`SY10126`). Where it is `false`, a city you send is dropped.
input.stateIsostring必填State ISO code. Required where the country's `stateRequired` is `true`, and must be one of that country's `states` (`SY10010`). Leave it out where `stateRequired` is `false`. See the countries and states endpoint for valid values.
input.postalCodestring可选Postal code. Optional, but send it wherever the country's `hasPostalCode` is `true`. A value you send must match the country's format (`SY10014`).
input.countryIsostring必填Country ISO code. Must be a supported country (`SY10036`). See the countries and states endpoint for valid values.
input.phonestring必填Primary phone number, validated for the country (`SY10015`).
input.subCategoryIdinteger必填Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.bizUrlstring必填Business website URL. Published to directories as the location's website. Some publishers refuse a listing without one.
input.primaryGbpSiteCategoryIdstring可选Primary Google Business Profile category, as a GCID (e.g. `gcid:restaurant`). Resolved against `countryIso`, so send the two together.
input.additionalGbpSiteCategoryIdsarray of strings可选Additional Google Business Profile categories, as GCIDs. Also resolved against `countryIso`.
input.offeringsUrlstring可选URL of the menu, catalogue, or service list.
input.bookingUrlstring可选URL customers use to book an appointment.
input.reservationUrlstring可选URL customers use to make a reservation.
input.street1string可选Second address line (suite, unit, floor).
input.latitudestring可选Latitude of the location, as a string. Send with `longitude`; publishers use it when the address alone is ambiguous.
input.longitudestring可选Longitude of the location, as a string. Send with `latitude`.
input.ownerEmailstring可选Email of the location owner. Used for listing claims and verification, not for login.
input.ownerNamestring可选Name of the location owner.
input.facebookUrlstring可选URL of the location's Facebook page.
input.twitterUrlstring可选URL of the location's X (Twitter) profile.
input.linkedinUrlstring可选URL of the location's LinkedIn page.
input.instagramUrlstring可选URL of the location's Instagram profile.
input.youtubeUrlstring可选URL of the location's YouTube channel.
input.tiktokUrlstring可选URL of the location's TikTok profile.
input.pinterestUrlstring可选URL of the location's Pinterest profile.
input.taglinestring可选Short tagline for the business.
input.yearOfIncorporationstring可选Year the business was incorporated, e.g. `2014`.
input.googleAdsPhonestring可选Alternate phone shown on Google Ads location extensions instead of `phone`.
input.additionalPhonesarray of strings可选Secondary phone numbers submitted to Google Business Profile.
input.videosarray of strings可选Video URLs for the location.
input.additionalCategoryIdsarray of integers可选Secondary Listings API subcategory IDs, from the subcategories endpoint. Distinct from `additionalGbpSiteCategoryIds`, which takes Google GCIDs.
input.submissionDisabledSiteIdsarray of integers可选Site IDs to exclude from submission. The inverse of `enabledSiteIds`, useful when you want every site in your plan except a few.
input.hideAddressboolean可选Set `true` for a service-area business. ListingsAPI stores the address you send but does not submit it to publishers.
input.temporarilyClosedboolean可选Set `true` to stop publishing business hours while the location is temporarily closed.
input.serviceItemsarray of objects可选Services offered, published to Google Business Profile.
input.customAttributesarray of objects可选Publisher-specific attributes for the location.
input.paymentMethodsarray of strings可选Payment methods accepted. One or more of `VISA`, `MASTERCARD`, `AMEX`, `CASH`, `CHEQUE`, `CRYPTO`, `DINERS_CLUB`, `DISCOVER`, `FINANCING`, `INVOICE`, `TRAVELERS_CHECK`, `APPLE_PAY`, `SAMSUNG_PAY`, `PAYPAL`, `ANDROID_PAY`.
input.businessHoursarray of objects可选Opening hours. Each entry is `{ day, type, slots }`, plus `specialDate` for a `SPECIAL` entry: `day` is an uppercase weekday enum (MONDAY–SUNDAY) or `SPECIAL`, `type` is `OPEN` or `CLOSED`, and `slots` is an array of `{ start, end }` time strings (e.g. `09:00am`, `05:00pm`). For a closed day use `type: "CLOSED"` with an empty `slots` array.
input.businessHours[].daystring必填MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, or SPECIAL (a one-off override for the date in `specialDate`).
input.businessHours[].typestring必填`OPEN` or `CLOSED`.
input.businessHours[].specialDatestring可选Date of a one-off override, as `YYYY-MM-DD`. Set this only when `day` is `SPECIAL`.
input.businessHours[].slotsarray of objects可选Open intervals for the day, each `{ start, end }`. Omit or leave empty when `type` is `CLOSED`.
input.businessHours[].slots[].startstring必填Opening time, e.g. `09:00am`.
input.businessHours[].slots[].endstring必填Closing time, e.g. `05:00pm`.
input.serviceAreaobject可选Service-area definition for service-area businesses: `{ businessType, regionCode, placeInfos: [{ placeId, placeName }] }`.
input.placeActionLinksarray of objects可选Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean). On create every link is new, so no `action` is needed. See the Place Action Links guide.
input.enabledSiteIdsarray of integers可选Site IDs to publish this location to, when you want a subset of your plan's sites. See the plan-sites endpoint for valid IDs. Omit to publish to every site in your plan.
input.clientMutationIdstring可选Optional correlation token returned unchanged in the response. It does not prevent duplicate writes: the server does not detect repeated calls that reuse the same value.

请求示例

可直接粘贴的请求体。请将占位 ID 和值替换为您自己的。

Request body
{  "input": {    "name": "Acme Kitchen",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",    "storeId": "ACME01",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "primaryGbpSiteCategoryId": "gcid:restaurant",    "additionalGbpSiteCategoryIds": ["gcid:pizza_restaurant"],    "businessHours": [      { "day": "MONDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY", "type": "CLOSED", "slots": [] }    ],    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true },      { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com" }    ]  }}

响应

200Location created successfully. Returns the new location as a summary object.
Response
{  "data": {    "createLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME01",        "name": "Acme Kitchen",        "street": "123 Jump Street",        "city": "New York",        "stateIso": "NY",        "postalCode": "10013",        "countryIso": "US",        "phone": "6443859313",        "status": "PENDING",        "primaryGbpSiteCategoryId": null,        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true, "name": null, "submissionStatus": null },          { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com", "isPreferred": false, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}
400Bad request, validation failure (see `errors[]`).
401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.

创建一个新的商家地点。创建成功后，该地点将加入提交队列，提交至其套餐中的每个发布平台（如果提供了 enabledSiteIds，则仅提交至指定站点）。必填字段：name、至少包含 200 个字符的 description、subCategoryId、countryIso，以及在采用城市级地址的国家／地区必填的 city。地点还需要有效的街道地址和电话号码才能实际发布，请在创建时提供这些信息，以免后续还需要更新。

返回的 id 经过 base64 编码（例如 TG9jYXRpb246MTgwMDI5MA==）；解码后即可查看内部的 Location:<databaseId> 格式。后续每次调用都引用此 base64 编码的 id。

使用场景：录入单个门店及其营业时间。 发送地址、phone、subCategoryId 和一个 businessHours 数组，其中一周中的每一天对应一个条目，包含 type: "OPEN" 和 { start, end } 时段；对于不营业的日期，则使用 type: "CLOSED" 并提供空的 slots 数组。将您自己的键存储在 storeId 中，以便稍后通过按门店代码获取来查找该地点，而无需跟踪 Listings API 的 ID。

设置特殊营业时间需要提供常规营业时间。 特殊营业时间（用于覆盖节假日或活动期间的营业时间，以 businessHours 条目发送，包含 day: "SPECIAL"、type: "OPEN" 或 "CLOSED"，以及采用 YYYY-MM-DD 格式的 specialDate）只有在地点同时包含常规的 MONDAY–SUNDAY 营业时间表时才会发布，Google 会拒绝仅提交特殊营业时间而未提供常规营业时间的地点。每当您设置 SPECIAL 条目时，请务必在 businessHours 中包含完整的一周 7 天营业时间；完整模型请参阅更新端点的营业时间规则。

使用场景：发布至部分站点。 传入 enabledSiteIds（来自 plan-sites 端点的站点 ID），即可将地点发布至选定的部分目录，而非套餐中的全部目录，这是代理机构销售分层站点覆盖服务时采用的方式。

在创建时设置 Google 操作按钮。 传入 placeActionLinks，即可在同一次调用中设置地点的 Google 操作按钮（预约、在线订购等）。有效的 placeActionType 值包括 APPOINTMENT、ONLINE_APPOINTMENT、DINING_RESERVATION、FOOD_ORDERING、FOOD_DELIVERY、FOOD_TAKEOUT 和 SHOP_ONLINE，每种类型最多只能有一个首选链接。创建完成后，每个链接的 name 和 submissionStatus 均为 null，直到该链接同步至 Google。若要稍后添加、编辑或移除链接，请使用更新地点；完整模型请参阅地点操作链接指南。

常见错误（返回 400，详情在 errors[] 中）：description 必须至少包含 200 个字符（SY10005），countryIso 必须是受支持的国家／地区（SY10036），对于采用城市级地址的国家／地区，city 为必填项（SY10126），state 必须是有效的 ISO 代码，邮政编码和电话号码必须在该国家／地区有效，subCategoryId 必须存在，且 storeId 必须在整个账户内唯一。无论使用哪个端点，每个请求都会消耗相同的速率限制配额，因此批量录入仅凭请求数量就会触发 429，请遵循 Retry-After 响应头，逐个创建，不要集中突发请求。

Request
curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Kitchen",      "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",      "storeId": "ACME01",      "street": "123 Jump Street",      "city": "New York",      "stateIso": "NY",      "postalCode": "10013",      "countryIso": "US",      "phone": "6443859313",      "bizUrl": "https://acmekitchen.example.com",      "subCategoryId": 1432,      "primaryGbpSiteCategoryId": "gcid:restaurant",      "additionalGbpSiteCategoryIds": [        "gcid:pizza_restaurant"      ],      "businessHours": [        {          "day": "MONDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "TUESDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "WEDNESDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "THURSDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "FRIDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "SATURDAY",          "type": "OPEN",          "slots": [            {              "start": "10:00am",              "end": "02:00pm"            }          ]        },        {          "day": "SUNDAY",          "type": "CLOSED",          "slots": []        }      ],      "placeActionLinks": [        {          "placeActionType": "FOOD_ORDERING",          "uri": "https://order.acmekitchen.example.com",          "isPreferred": true        },        {          "placeActionType": "FOOD_TAKEOUT",          "uri": "https://takeout.acmekitchen.example.com"        }      ]    }  }'
Run in playground