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を参照します。

ユースケース：1つの実店舗を営業時間とともに登録する。 住所、phone、subCategoryId、およびbusinessHours配列を送信し、各曜日に1つのエントリを設けてtype: "OPEN"と{ start, end }の時間枠を指定するか、休業日にはtype: "CLOSED"と空のslots配列を指定します。storeIdに独自のキーを保存しておくと、Listings APIのIDを管理せずに、後から店舗コードによる取得で拠点を特定できます。

特別営業時間には通常営業時間が必要です。 特別営業時間（祝日やイベント時の営業時間を上書きするもので、day: "SPECIAL"、type: "OPEN"または"CLOSED"と、YYYY-MM-DD形式のspecialDateを含むbusinessHoursエントリとして送信します）は、拠点に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つです。作成直後は、各リンクがGoogleに同期されるまで、そのnameとsubmissionStatusはnullです。後からリンクを追加、編集、削除するには拠点を更新するを使用し、モデルの詳細はプレイスアクションリンクのガイドを参照してください。

よくあるエラー（400として返され、詳細はerrors[]に含まれます）：descriptionは200文字以上（SY10005）、countryIsoはサポート対象の国（SY10036）、住所に市区町村を使用する国ではcityが必須（SY10126）、州は有効なISOコード、郵便番号と電話番号はその国で有効な値、subCategoryIdは存在するID、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