POST/api/v4/locations/update

사업장 업데이트

기존 사업장에서 쓰기 가능한 필드를 업데이트합니다. 전송한 필드만 변경됩니다.

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

매개변수

본문

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

이름	유형	필수	설명
input.id	string	필수	The location's Base64-encoded Relay ID to update.
input.name	string	선택	Business name.
input.street	string	선택	Street address.
input.city	string	선택	City.
input.stateIso	string	선택	State/region ISO code.
input.postalCode	string	선택	Postal or ZIP code.
input.countryIso	string	선택	Two-letter country ISO code.
input.phone	string	선택	Primary phone number.
input.bizUrl	string	선택	Business website URL. Published to directories as the location's website.
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.description	string	선택	Business description. Published to Google Business Profile as the business description.
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.subCategoryId	integer	선택	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.storeId	string	선택	Unique store code. Must be unique across the account.
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.updateOnlySiteIds	array of integers	선택	Restrict this update to the given site IDs. Other sites keep their current published values.
input.contentPreferredLanguage	string	선택	Preferred language for the location's published content, e.g. `ENGLISH`.
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.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	선택	Hours. Each entry is `{ day, type, slots }`, plus `specialDate` for a `SPECIAL` entry. Send the full seven-day week when you set hours.
input.businessHours[].day	string	필수	One of 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 }` (e.g. `09:00am`, `05:00pm`). Use an empty array when `type` is `CLOSED`.
input.businessHours[].slots[].start	string	필수	Opening time for the interval, e.g. `09:00am`.
input.businessHours[].slots[].end	string	필수	Closing time for the interval, e.g. `05:00pm`.
input.moreHours	array of objects	선택	Additional hour sets (e.g. delivery, drive-through). Each entry is `{ hoursTypeId, moreHour }`, where `moreHour` is an array of `{ day, type, slots }` using the same shape as `businessHours` (minus `specialDate`).
input.serviceArea	object	선택	Service-area business config: `businessType`, `regionCode`, and a `placeInfos` array of `{ placeId, placeName }`.
input.customAttributes	array of objects	선택	Custom attribute values for the location. Each item is `{ slug, value }`, where `slug` identifies a custom attribute registered on your account and `value` is an array of strings. Sending a slug that is not registered returns `SY10035`. Registering a new custom attribute is not yet available through the API.
input.placeActionLinks	array of objects	선택	Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean), optional `action` (`add`, the default, or `delete`), optional `name` (the link identifier returned by read endpoints once synced to Google). Only the links you reference are affected; links you don't include are left unchanged. See the Place Action Links guide.

요청 예시

바로 붙여 넣을 수 있는 본문입니다. 예시 ID와 값을 실제 값으로 바꾸세요.

Request body

{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com",    "primaryGbpSiteCategoryId": "gcid: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": [] }    ]  }}

응답

200Location updated. `success` is true and the updated location summary is returned.

Response

{  "data": {    "updateLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "street": "600 Congress Ave, Suite 200",        "city": "Austin",        "stateIso": "TX",        "countryIso": "US",        "postalCode": "78701",        "phone": "5125550199",        "storeId": null,        "status": "APPROVED",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

401Unauthenticated, missing or invalid API key.

단일 사업장을 업데이트합니다. input에 포함된 필드만 수정되며, 생략한 모든 필드는 현재 값을 유지합니다. id만 필수 필드입니다.

사용 사례: 전화번호 수정. id와 phone만 전송하면 주소나 영업시간을 변경하지 않고 연락처 정보를 수정할 수 있습니다. 응답으로 업데이트된 사업장이 반환되므로 새 값이 반영되었는지 확인할 수 있습니다.

사용 사례: 전체 주간 일정 게시. 샘플 요청과 같이 7일분의 businessHours 배열을 전송하여 요일별 영업 시간대를 설정합니다. 휴무일은 { "day": "SUNDAY", "type": "CLOSED", "slots": [] }로 표시합니다.

영업시간 규칙.

7일을 모두 제공해야 하며, 일부 요일만 포함한 주간 일정은 거부됩니다.
시간은 각 slots 항목 내의 start/end를 사용하며(예: 09:00am, 05:00pm), 하루 내의 시간대는 서로 겹치면 안 됩니다.
공휴일과 행사용 예외 영업시간은 day: "SPECIAL"과 specialDate(YYYY-MM-DD)를 포함한 추가 항목으로 보냅니다. 7개의 요일별 항목을 대체하지 않고 항상 함께 전송합니다.
SPECIAL은 businessHours에서만 사용합니다. moreHours 항목에는 specialDate 필드가 없으므로, 해당 항목의 SPECIAL일에는 날짜가 포함되지 않습니다.
보조 일정(배달, 드라이브스루)에는 moreHours를 사용하고, hoursTypeId를 키로 지정합니다.

항상 전체 주간 일정을 전송해야 합니다. 게시 플랫폼은 완전한 MONDAY–SUNDAY 일정을 요구하므로, businessHours를 설정할 때마다 7개의 항목을 모두 전송하고, 영업하지 않는 날은 생략하지 말고 type: "CLOSED"를 사용하며 slots는 비워 둡니다.

주의 사항.

식별자 필드는 id이며, 모든 조회 엔드포인트에서 반환하는 Base64 Relay ID입니다.
유효성 검사에 실패해도 호출은 success: false와 값이 채워진 errors 배열을 포함하여 HTTP 200을 반환하므로, 상태 코드만 확인하지 말고 항상 success를 확인해야 합니다.

장소 작업 링크

placeActionLinks는 사업장의 Google 작업 버튼(주문, 배달, 포장 주문, 예약, 방문 예약)을 관리합니다. 쓰기 모델은 교체가 아닌 append/upsert 방식입니다:

action: "add"(기본값): 새 링크를 추가하거나 저장된 링크의 uri/isPreferred를 해당 링크에서 업데이트합니다.
action: "delete": 저장된 링크를 삭제하고 Google에서의 삭제 작업을 대기열에 추가합니다.
요청에서 참조하지 않은 링크는 변경되지 않으며, 링크를 생략해도 삭제되지 않습니다.

링크 일치 기준(수정/삭제 시): name이 있으면 이를 기준으로, 없으면 placeActionType + uri를 기준으로 일치하는 링크를 찾습니다. 가장 정확하게 일치하는 링크를 찾으려면 조회 엔드포인트에서 받은 name이 있을 경우 이를 포함해야 하며, 아직 Google에 동기화되지 않은 링크에는 name이 없으므로 placeActionType + uri를 기준으로 일치하는 링크를 찾습니다.

유효한 placeActionType 값: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE입니다. 타입별 우선 링크는 최대 1개입니다.

링크의 URL 변경 = 동일한 요청에서 기존 링크 삭제 + 새 링크 추가입니다:

JSON

{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },      { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }    ]  }}

쓰기 직후에는 링크의 name과 submissionStatus가 null이며, 링크가 Google에 동기화되면 값이 채워집니다. Google에서 직접 발견된 링크가 discoveredPlaceActionLinks 아래에 표시되는 방식을 포함한 전체 흐름은 장소 작업 링크 가이드를 참조합니다.

Request

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "TG9jYXRpb246MTgwMDI4OQ==",      "phone": "5125550199",      "bizUrl": "https://acmekitchen.example.com",      "primaryGbpSiteCategoryId": "gcid: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": []        }      ]    }  }'

Run in playground