등록 정보 상태 확인 및 공개 URL 가져오기

사업장의 모든 게시 플랫폼별 동기화 상태를 조회하고, 공개된 등록 정보의 URL을 수집하고, 게시 현황을 요약하고, 음성 비서를 확인하고, 폴링 대신 웹훅으로 알림을 받습니다.

사업장이 생성되면 요금제에 포함된 게시 플랫폼마다 등록 정보가 1개씩 자동으로 제출됩니다. 이 가이드에서는 각 등록 정보의 현재 상태를 조회하고, 공개된 등록 정보의 URL을 가져오고, 웹훅 설정 후 폴링을 중단하는 방법을 설명합니다.

1. 사업장의 프리미엄 등록 정보 가져오기

GET /locations/{locationId}/listings/premium은 요금제에 포함된 프리미엄 게시 플랫폼마다 레코드 1개를 반환합니다. 페이지로 나뉜 목록이 아닌 일반 배열입니다. 관련 경로인 /listings/additional은 동일한 구조로 무료 디렉터리를 반환하며, listingType 쿼리 매개변수는 없습니다.

Premium listings

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "listingUrl": null,        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:28Z"      },      {        "site": { "name": "BeLocalFocussed", "url": "belocalfocussed.com" },        "syncStatus": "SYNCED",        "displayStatus": "Synced",        "actionRequired": false,        "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e",        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:30Z"      }    ]  }}

각 행에는 site와 함께 기계가 읽을 수 있는 syncStatus 및 사람이 읽을 수 있는 displayStatus가 포함됩니다. lastUpdate는 행이 마지막으로 변경된 시점을 나타내므로, 제출 후 처리가 정체된 항목을 파악하는 데 유용합니다.

2. 각 게시 플랫폼의 상태 조회하기

syncStatus는 분기 처리의 기준으로 사용할 필드입니다. displayStatus는 사용자에게 표시할 텍스트이며, 게시 플랫폼이 사유를 제공한 경우 syncIssue에 해당 사유가 포함됩니다.

`syncStatus`	의미	수행할 작업
`AVAILABLE`	제출할 준비가 되었지만, 아직 시작되지 않았습니다.	아무 작업도 필요하지 않습니다. 자동으로 진행됩니다.
`IN_PROGRESS`	게시 플랫폼에 제출되었으며, 응답을 기다리고 있습니다.	기다립니다. 몇 주가 지났다면 `lastUpdate`를 확인합니다.
`PENDING_APPROVAL`	게시 플랫폼이 제출 내용을 수신하여 검토하고 있습니다.	기다립니다.
`SYNCED` 또는 `COMPLETED`	공개되었습니다. `listingUrl`에 값이 입력되어 있습니다.	링크를 수집합니다(3단계).
`REQUIRING_ACTION`	사용자의 조치가 필요하여 진행이 차단되었습니다. `actionRequired`는 `true`입니다.	`displayStatus`를 읽은 다음 등록 정보 오류 찾기 및 수정을 참조합니다.
`FAILED`	게시 플랫폼이 제출을 거부했거나 처리하지 못했습니다.	`syncIssue`를 읽고, 사업장 정보를 수정한 다음, 다시 폴링합니다.
`CANNOT_SUBMIT`	이 게시 플랫폼은 이 사업장을 전혀 수락할 수 없습니다.	일반적으로 게시 플랫폼이 지원하지 않는 국가 또는 카테고리에 해당합니다.

Google Maps와 Facebook은 해당 게시 플랫폼의 계정이 연결될 때까지 REQUIRING_ACTION 상태를 유지하며, Google Maps에는 Google Business Profile을, Facebook에는 Facebook Page를 연결해야 합니다. 이는 새 사업장에서 예상되는 상태이며, 오류가 아닙니다.

Apple Maps는 연결이 필요하지 않습니다. 소유자가 인증된 Apple Business 조직 계정을 연결하지 않은 경우, ListingsAPI는 자체 Apple Business Connect 계정을 통해 사업장을 제출하며, Apple은 게시 전에 제출 내용을 검증합니다. Apple Business Connect 연결을 참조합니다.

3. 공개 URL 수집하기

listingUrl은 공개된 행에만 설정됩니다. SYNCED(및 COMPLETED)로 필터링하고 URL을 사이트 이름과 함께 보관하면, "공개된 등록 정보 보기" 목록을 표시하거나 자체 레코드에 연결하여 저장할 수 있습니다.

Live links

curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.listingUrl != null)       | {site: .site.name, url: .listingUrl}]'

listingUrl이 null인 SYNCED 행이 나타나는 경우도 있으며, 이는 일부 디렉터리가 공개 페이지 URL을 제공하지 않기 때문입니다. 상태를 확정적인 기준으로 삼고 링크는 선택 사항으로 취급합니다.

4. 게시 현황 요약 만들기

syncStatus별로 행 수를 세면 사업장마다 등록 정보가 공개된 게시 플랫폼 수, 아직 처리 중인 게시 플랫폼 수, 진행이 차단된 게시 플랫폼 수를 한 줄의 상태 지표로 확인할 수 있습니다. 이 수치를 대시보드에 표시합니다.

Coverage

curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.listingsForLocation      | group_by(.syncStatus)      | map({status: .[0].syncStatus, count: length})'

여러 사업장에 대해 실행하려면 GET /locations를 페이지별로 조회하고 각 사업장에 대해 프리미엄 엔드포인트를 1번씩 호출합니다. 각 호출은 요청 빈도 제한에 포함되므로 호출 사이에 간격을 두고, 429가 반환되면 Retry-After를 준수합니다. 등록 정보 오류 찾기 및 수정에서는 이 반복 처리를 한 계정 내 전체 사업장을 점검하는 방식으로 설명합니다.

5. 음성 비서 확인

음성 비서(Google Assistant, Alexa, Siri, Cortana, Bixby)에는 자체 엔드포인트인 GET /locations/{locationId}/voice-assistants가 있으며, 사용하는 상태의 종류가 더 적습니다. Google Assistant는 Google 연결에 의존하므로, Google 연결이 없는 사업장은 여기에서도 조치가 필요합니다. Siri 결과는 해당 사업장의 Apple Maps 등록 정보에서 가져옵니다.

Voice assistants

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "voiceAssistantsForLocation": [      {        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "voiceIdentifier": "SIRI",        "name": "Siri",        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}

`syncStatus`	의미
`NOT_SUBMITTED`	아직 음성 비서에 전송되지 않았습니다.
`IN_PROGRESS`	제출이 진행 중입니다.
`REQUIRING_ACTION`	사용자 조치가 필요하여 차단되었습니다. `syncIssue`를 확인합니다.
`LIVE`	게시되었습니다.

음성 비서에는 실제 게시된 페이지의 링크가 없으며, LIVE가 최종 상태입니다.

6. 폴링 대신 웹훅 이벤트 수신

/dashboard/webhooks에 웹훅 URL이 설정되어 있으면, 한 사업장의 게시 플랫폼 제출이 최종 상태에 도달할 때마다 listing.submission 이벤트가 발생합니다. 이 이벤트에는 status(success, incomplete 또는 canceled)와 사이트가 포함되며, 성공 시에는 3단계에서 수집한 것과 동일한 URL인 live_link도 포함됩니다.

Route listing.submission

import base64 def handle(payload: dict) -> None:  if payload["event"] != "listing.submission":      return   data = payload["data"]  # "TG9jYXRpb246Mjc5Mzgx" -> "Location:279381"  global_id = base64.b64decode(data["location_id"]).decode()  database_id = int(global_id.split(":")[1])   site = data["site"]["name"]  status = payload["status"]   if status == "success":      live_link = payload.get("live_link")      save_live_link(database_id, site, live_link)  elif status == "incomplete":      flag_for_review(database_id, site, payload.get("error_message"))

5초 이내에 200으로 응답하고 실제 처리는 그 후에 수행합니다. 재전송은 없습니다. 수신기 기본 구조와 서명 확인에 대해서는 웹훅으로 이벤트에 대응하기를 참조합니다.

다음 단계

등록 정보 오류 찾기 및 수정: REQUIRING_ACTION 및 FAILED 행을 바탕으로 문제를 수정합니다.
Google 연결 및 사업장 가져오기: Google Maps와 Google Assistant가 사용하는 Google Business Profile을 연결합니다.
Apple Business Connect 연결: 소유자의 인증된 Apple Business 계정을 통해 Apple Maps에 게시합니다.
중복 등록 정보 찾기 및 표시 제한: 등록 정보 상태 관리의 나머지 부분입니다.
참조: 프리미엄 등록 정보 가져오기, 음성 비서 등록 정보 가져오기, 이벤트 참조.