장소 작업 링크

Listings API를 통해 사업장의 Google 작업 버튼(주문, 배달, 포장, 테이블 예약, 방문 예약)을 관리합니다.

장소 작업 링크는 Google이 비즈니스 프로필에 표시하는 온라인 주문, 배달 주문, 테이블 예약, 방문 예약 등의 작업 버튼입니다. Listings API는 이러한 링크를 사업장의 일부로 관리하므로, 기존에 사용하던 생성 및 업데이트 엔드포인트를 통해 설정하고 모든 사업장 조회 엔드포인트에서 다시 조회할 수 있습니다.

`placeActionLinks` 필드

생성과 업데이트 모두 input에서 placeActionLinks 배열을 받습니다. 각 요소는 다음과 같습니다.

필드	타입	필수 여부	설명
`placeActionType`	enum	예	아래의 유효한 타입 중 하나입니다.
`uri`	string	예	대상 URL입니다.
`isPreferred`	boolean	아니요	이 링크를 해당 타입의 우선 링크로 지정합니다. 타입별로 우선 링크는 최대 1개입니다.
`action`	string	아니요	`add`(기본값) 또는 `delete`입니다. 업데이트 시에만 사용합니다.
`name`	string	아니요	링크의 식별자로, 링크가 Google에 동기화되면 조회 엔드포인트에서 반환됩니다. 쓰기 시 선택 사항이며, 식별자가 있으면 특정 저장된 링크를 가장 정확하게 지정할 수 있도록 포함합니다.

유효한 placeActionType 값:

Code

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

링크 매칭 방식(수정 / 삭제 시): name이 있으면 이를 기준으로, 없으면 placeActionType + uri를 기준으로 매칭합니다. 조회를 통해 얻은 name이 있으면 가장 정확하게 매칭할 수 있도록 포함합니다. 새로 추가되어 아직 Google에 동기화되지 않은 링크에는 name이 없으므로, placeActionType + uri를 기준으로 매칭합니다.

작업

쓰기 모델은 교체가 아닌 append/upsert입니다. 업데이트 시에는 지정한 링크에만 영향을 주며, 포함하지 않은 링크는 변경되지 않습니다.

작업	목적	매칭 기준
`add`	새 링크를 추가하거나, 저장된 링크의 `uri` / `isPreferred`를 해당 링크에서 업데이트합니다.	`name`이 있으면 이를 사용하고, 없으면 `placeActionType` + `uri`를 사용합니다.
`delete`	저장된 링크를 삭제하고 Google에서의 삭제를 대기열에 추가합니다.	`name`이 있으면 이를 사용하고, 없으면 `placeActionType` + `uri`를 사용합니다.

링크의 URL을 변경하려면 동일한 요청에서 기존 링크를 삭제하고 새 링크를 추가합니다(링크 URL 변경 참조).

권장 흐름

사업장의 장소 작업 링크를 채우고 Google과 동기화된 상태로 유지하는 방법은 2가지입니다.

흐름 1: Google에서 먼저 생성한 후 연결

사업자가 자신의 Google Business Profile에서 직접 장소 작업 링크를 설정합니다.
해당 Google Business Profile 사업장을 Listings API에 연결합니다.
연결 시 Listings API가 Google의 현재 링크를 가져와 사업장의 관리 대상 집합에 포함합니다. API를 통해 다시 입력할 필요가 없습니다.

흐름 2: Listings API에서 먼저 생성한 후 연결

Listings API에서 장소 작업 링크를 포함하여 사업장을 생성하거나(사업장 생성), 나중에 링크를 추가합니다(사업장 업데이트).
Google Business Profile에 연결하면 Listings API가 현재 링크를 가져와 관리 대상 집합과 병합합니다:
- 명확하게 매칭되는 링크는 관리 대상 집합에 포함됩니다.
- Google에 있는 링크 중 자동으로 병합할 수 없거나 아직 관리 대상 집합에 없는 링크는 검토할 수 있도록 discoveredPlaceActionLinks에 표시됩니다.
Listings API는 Google에 제출할 때마다 현재 링크를 다시 확인합니다. Google Business Profile에서 직접 발견된 새 링크 중 Listings API가 관리하지 않는 링크는 모두 discoveredPlaceActionLinks에 추가됩니다.

발견된 링크

발견된 링크는 업체의 Google 프로필에 존재하지만 Listings API에서 관리하지 않는 장소 작업 링크입니다. 이러한 링크는 위의 흐름을 통해 가져오며(연결 시 발견된 추가 링크 또는 이후 제출 시 발견된 새 링크), 모든 조회 엔드포인트(목록 조회, ID로 조회, 매장 코드로 조회, 검색)에서 관리 중인 링크와 별도로 discoveredPlaceActionLinks(placeActionLinks와 동일한 구조)에 반환됩니다.

JSON

{  "id": "TG9jYXRpb246MTgwMTAyMQ==",  "placeActionLinks": [ /* links you already manage */ ],  "discoveredPlaceActionLinks": [    {      "placeActionType": "APPOINTMENT",      "uri": "https://book.example.com",      "isPreferred": false,      "name": "locations/1944.../placeActionLinks/abc123",      "providerType": "MERCHANT",      "isEditable": true    }  ]}

발견된 링크를 관리 대상으로 추가

발견된 링크의 관리를 시작하려면 다른 링크를 추가할 때와 동일하게(placeActionType + uri로 식별) action: "add"를 포함하여 해당 링크를 사업장 업데이트로 전송합니다. 다른 링크는 변경되지 않습니다.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "action": "add" }      ]    }  }'

이후 해당 링크는 placeActionLinks에 표시되고 discoveredPlaceActionLinks에서 제거됩니다. 관리 대상으로 추가하지 않은 발견된 링크는 목록에 그대로 유지되며(나중에 Google에서 사라지면 목록에서도 자동으로 제거됩니다), 별도의 조치는 필요하지 않습니다.

예시

모든 업데이트는 해당 사업장의 현재 전체 placeActionLinks 집합을 반환하며, 변경 사항이 반영되어 있습니다. 쓰기 직후에는 링크의 name과 submissionStatus가 null이며, 링크가 Google에 동기화되면 값이 채워집니다.

링크 추가

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

링크 URL 변경

URL 변경은 동일한 요청에서 기존 링크를 제거하고 새 링크를 추가하는 방식으로 이루어집니다. 기존 링크가 Google에 동기화된 경우 가장 정확하게 일치하는 링크를 찾을 수 있도록 delete에 해당 링크의 name을 포함하며, 그렇지 않은 경우에는 placeActionType + uri가 사용됩니다.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "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" }      ]    }  }'

URL은 그대로 두고 isPreferred만 변경하려면 action: "add"와 새 값을 포함하여 링크를 다시 전송합니다.

링크 제거

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_DELIVERY", "uri": "https://deliver.example.com", "name": "<link-name-if-synced>", "action": "delete" }      ]    }  }'

링크를 포함한 사업장 생성

생성 시에는 모든 링크가 새 링크이므로 action의 기본값은 add입니다.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Dental",      "description": "<business description, minimum 200 characters>",      "countryIso": "US",      "city": "New York",      "subCategoryId": 1432,      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },        { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }      ]    }  }'

참고 사항

타입별 우선 링크는 최대 1개입니다.
링크의 submissionStatus는 Google과의 마지막 동기화 상태(success, failed 등)를 나타내며, 사람이 읽을 수 있는 submissionMessage가 함께 제공됩니다.
Google은 인증된 사업장에만 장소 작업 링크를 적용합니다.