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 項目時，請務必包含完整的 7 天 businessHours 每週營業時間；如需完整模型，請參閱更新端點的營業時間規則。

使用案例：發布至部分網站。傳入 enabledSiteIds（來自 plan-sites 端點的網站 ID），即可將地點發布至精選的部分目錄，而非方案中的所有目錄，這是代理商用來銷售分級網站涵蓋範圍的做法。

在建立時設定初始 Google 動作按鈕。傳入 placeActionLinks，即可在同一次呼叫中設定地點的 Google 動作按鈕（預約、線上訂購等）。有效的 placeActionType 值為 APPOINTMENT、ONLINE_APPOINTMENT、DINING_RESERVATION、FOOD_ORDERING、FOOD_DELIVERY、FOOD_TAKEOUT 和 SHOP_ONLINE，每種類型最多可有 1 個偏好連結。剛建立完成時，每個連結的 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