POST/api/v4/locations

사업장 생성

계정에 새 사업장을 생성하고 등록 정보 제출 대기열에 추가합니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

본문

필수로 표시된 중첩 필드는 상위 필드를 보낼 때만 적용됩니다. 상위 필드가 선택 사항이고 이를 생략하면 필수 하위 필드도 적용되지 않습니다.

이름	유형	필수	설명
input.name	string	필수	Name of the business.
input.description	string	필수	Business description, minimum 200 characters (`SY10005` when missing or shorter). Publishers use it as the primary listing copy.
input.storeId	string	선택	Unique store code. Must be unique across the account.
input.street	string	필수	Street address, 5 to 100 characters (`SY10011`).
input.city	string	필수	City. Required where the country's `hasCity` is `true` (`SY10126`). Where it is `false`, a city you send is dropped.
input.stateIso	string	필수	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.postalCode	string	선택	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.countryIso	string	필수	Country ISO code. Must be a supported country (`SY10036`). See the countries and states endpoint for valid values.
input.phone	string	필수	Primary phone number, validated for the country (`SY10015`).
input.subCategoryId	integer	필수	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.bizUrl	string	필수	Business website URL. Published to directories as the location's website. Some publishers refuse a listing without one.
input.primaryGbpSiteCategoryId	string	선택	Primary Google Business Profile category, as a GCID (e.g. `gcid:restaurant`). Resolved against `countryIso`, so send the two together.
input.additionalGbpSiteCategoryIds	array of strings	선택	Additional Google Business Profile categories, as GCIDs. Also resolved against `countryIso`.
input.offeringsUrl	string	선택	URL of the menu, catalogue, or service list.
input.bookingUrl	string	선택	URL customers use to book an appointment.
input.reservationUrl	string	선택	URL customers use to make a reservation.
input.street1	string	선택	Second address line (suite, unit, floor).
input.latitude	string	선택	Latitude of the location, as a string. Send with `longitude`; publishers use it when the address alone is ambiguous.
input.longitude	string	선택	Longitude of the location, as a string. Send with `latitude`.
input.ownerEmail	string	선택	Email of the location owner. Used for listing claims and verification, not for login.
input.ownerName	string	선택	Name of the location owner.
input.facebookUrl	string	선택	URL of the location's Facebook page.
input.twitterUrl	string	선택	URL of the location's X (Twitter) profile.
input.linkedinUrl	string	선택	URL of the location's LinkedIn page.
input.instagramUrl	string	선택	URL of the location's Instagram profile.
input.youtubeUrl	string	선택	URL of the location's YouTube channel.
input.tiktokUrl	string	선택	URL of the location's TikTok profile.
input.pinterestUrl	string	선택	URL of the location's Pinterest profile.
input.tagline	string	선택	Short tagline for the business.
input.yearOfIncorporation	string	선택	Year the business was incorporated, e.g. `2014`.
input.googleAdsPhone	string	선택	Alternate phone shown on Google Ads location extensions instead of `phone`.
input.additionalPhones	array of strings	선택	Secondary phone numbers submitted to Google Business Profile.
input.videos	array of strings	선택	Video URLs for the location.
input.additionalCategoryIds	array of integers	선택	Secondary Listings API subcategory IDs, from the subcategories endpoint. Distinct from `additionalGbpSiteCategoryIds`, which takes Google GCIDs.
input.submissionDisabledSiteIds	array 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.hideAddress	boolean	선택	Set `true` for a service-area business. ListingsAPI stores the address you send but does not submit it to publishers.
input.temporarilyClosed	boolean	선택	Set `true` to stop publishing business hours while the location is temporarily closed.
input.serviceItems	array of objects	선택	Services offered, published to Google Business Profile.
input.customAttributes	array of objects	선택	Publisher-specific attributes for the location.
input.paymentMethods	array 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.businessHours	array 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[].day	string	필수	MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, or SPECIAL (a one-off override for the date in `specialDate`).
input.businessHours[].type	string	필수	`OPEN` or `CLOSED`.
input.businessHours[].specialDate	string	선택	Date of a one-off override, as `YYYY-MM-DD`. Set this only when `day` is `SPECIAL`.
input.businessHours[].slots	array of objects	선택	Open intervals for the day, each `{ start, end }`. Omit or leave empty when `type` is `CLOSED`.
input.businessHours[].slots[].start	string	필수	Opening time, e.g. `09:00am`.
input.businessHours[].slots[].end	string	필수	Closing time, e.g. `05:00pm`.
input.serviceArea	object	선택	Service-area definition for service-area businesses: `{ businessType, regionCode, placeInfos: [{ placeId, placeName }] }`.
input.placeActionLinks	array 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.enabledSiteIds	array 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.clientMutationId	string	선택	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 } 시간대가 포함된 항목을 하나씩 넣고, 휴무일에는 빈 slots 배열과 함께 type: "CLOSED"를 지정합니다. 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개 지정할 수 있습니다. 생성 직후 각 링크의 name 및 submissionStatus는 Google에 동기화될 때까지 null입니다. 나중에 링크를 추가, 수정 또는 삭제하려면 사업장 업데이트를 사용하며, 전체 모델은 장소 작업 링크 가이드를 참조합니다.

일반적인 오류(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