등록 정보

모든 등록 정보 엔드포인트와 각 엔드포인트의 cURL, Python 및 Node 예제: 프리미엄 동기화 상태, 음성 비서, 사업장별 및 계정별 중복 탐지, 중복 등록 정보 노출 중단을 다룹니다.

등록 정보는 하나의 게시 플랫폼 디렉터리에 등록된 한 사업장의 항목입니다. 사업장을 생성하면 요금제에 포함된 게시 플랫폼마다 등록 정보가 대기열에 추가되며, 등록 정보 엔드포인트에서는 각 등록 정보의 진행 상태를 조회하고, 탐지된 중복 항목을 나열하고, 해당 항목을 중복으로 확인하거나 중복이 아닌 것으로 처리합니다. GET 엔드포인트 4개는 Read(읽기) 키로 사용할 수 있으며, POST 엔드포인트 2개에는 Write(쓰기) 키가 필요합니다.

엔드포인트 한눈에 보기

프리미엄 등록 정보 상태 조회

GET /locations/{locationId}/listings/premium

사업장의 요금제에 포함된 프리미엄 게시 플랫폼마다 레코드 1개를 data.listingsForLocation 아래에 반환합니다. 페이지가 나뉜 목록이 아닌 일반 배열입니다. 같은 수준의 경로인 /listings/additional은 무료 디렉터리를 동일한 구조로 반환하며, listingType 쿼리 매개변수는 없으므로 해당 매개변수로 전달한 값은 무시됩니다.

매개변수

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

{  "data": {    "listingsForLocation": [      {        "id": "TGlzdGluZzoxMDQ0Njg3MjM=",        "site": { "databaseId": "1", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3Mjc=",        "site": { "databaseId": "387", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3MDk=",        "site": { "databaseId": "301", "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "listingUrl": null,        "syncIssue": "Publisher requires website URL",        "lastUpdate": "2026-07-06T18:34:03Z"      }    ]  }}

syncStatus에 따라 분기합니다. 사용자에게는 displayStatus를 표시하고, 게시 플랫폼이 제시한 사유는 syncIssue에서 확인하며, 진행이 멈춘 제출 건은 lastUpdate를 사용해 찾습니다. listingUrl은 실제 게시된 행에만 설정됩니다.

Google Maps, Facebook, Waze는 해당 계정이 연결될 때까지 displayStatus: "Connect your account to sync the listing"과 함께 REQUIRING_ACTION 상태를 유지합니다. 새 사업장에서는 정상적인 상태입니다.

음성 비서 상태 조회

GET /locations/{locationId}/voice-assistants

Google Assistant, Amazon Alexa, Apple Siri, Microsoft Cortana, Samsung Bixby 등 각 음성 비서의 레코드 1개를 data.voiceAssistantsForLocation 아래에 반환합니다. 일반 배열이며, 프리미엄 엔드포인트보다 상태의 종류가 적습니다.

매개변수

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

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

actionRequired가 true이거나 syncIssue가 설정된 행은 모두 따로 표시합니다. errors에는 게시 플랫폼 측 오류 문자열이 포함되며, 해당하는 경우 connectedAccountId는 동기화에 사용되는 연결된 계정을 가리킵니다. Google Assistant 결과는 Google Business Profile 연결에서 가져오므로, 주의가 필요한 가장 흔한 이유는 Google 연결이 없는 것입니다. Siri 결과는 해당 사업장의 Apple Maps 등록 정보에서 가져옵니다.

계정 전체의 중복 항목 집계

GET /locations/listings/duplicates

모든 사업장과 게시 플랫폼에서 감지된 중복 항목 중 키로 조회할 수 있는 모든 항목을 data.duplicateListingsRollup에 반환합니다. 오프셋 기반 페이지 형식으로, page와 perPage를 입력받고 records[]와 함께 pageInfo.totalRecords, pageInfo.totalPages, pageInfo.hasNextPage를 반환합니다. 필터는 JSON이 아니라 개별 쿼리 매개변수로 전달합니다. 아무 값도 지정하지 않으면 status의 기본값은 POTENTIAL이고 tag의 기본값은 all이므로, 매개변수 없이 호출하면 계정의 미처리 중복 항목을 반환합니다.

매개변수

Python 및 Node 래퍼는 tag와 page만 제공합니다. status 또는 siteId로 필터링하거나 perPage를 설정하려면 중복 등록 정보 처리에 나온 대로 라우트를 직접 호출합니다.

curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=POTENTIAL&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "duplicateListingsRollup": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false,        "totalPages": 34,        "totalRecords": 1673      },      "records": [        {          "id": "3329229",          "name": "Woodbury Train Station",          "nameValid": false,          "duplicateProcessingState": "POTENTIAL",          "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",          "locationId": "73451",          "siteName": "City Squares",          "siteUrl": "citysquares.com"        }      ]    }  }}

집계 결과는 중복 항목이 어디에 있는지 알려 주며, 각 레코드에는 locationId와 siteName이 명시되어 있습니다. duplicateProcessingState는 사업장별 엔드포인트가 status로 보고하는 것과 동일한 수명 주기 상태입니다. hasNextPage가 false가 될 때까지 한 번에 한 페이지씩 조회합니다. 간격 없이 반복 호출하면 금방 429 오류가 발생합니다.

단일 사업장의 중복 항목 조회

GET /locations/{locationId}/listings/duplicates

단일 사업장에서 감지된 모든 중복 항목을 게시 플랫폼 사이트별로 그룹화하여 data.duplicateListingsForLocation에 반환합니다. 단순 배열 형식입니다. 각 그룹은 listings 배열이 있는 사이트(name, url)이며, 각 항목에는 두 표시 엔드포인트가 모두 입력받는 listingItemId가 포함됩니다. 빈 배열은 감지된 항목이 없음을 의미합니다.

매개변수

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

{  "data": {    "duplicateListingsForLocation": [      {        "id": "U2l0ZToxNTA=",        "name": "City Squares",        "url": "citysquares.com",        "listings": [          {            "id": "RHVwbGljYXRlOjIzNTk4NDUw",            "listingItemId": "TGlzdGluZ0l0ZW06MjM1OTg0NTA=",            "name": "Woodbury Train Station",            "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",            "status": "POTENTIAL"          }        ]      }    ]  }}

liveLink를 열어 항목을 검토한 다음 listingItemId를 보관합니다. Node SDK에서는 평탄화된 d.id가 이후 전달할 값입니다. status는 위의 계정 집계와 동일한 4가지 값을 사용합니다.

등록 정보 항목을 중복으로 확인

POST /locations/listings/mark-as-duplicate

게시 플랫폼에서 노출을 중단할 수 있도록 등록 정보 항목을 확인된 중복으로 표시합니다. listingItemId 값을 input에 담아 전송하고, 항목마다 호출하는 대신 한 사업장에서 중복으로 확인된 모든 항목을 한 번의 호출로 일괄 처리합니다. 이 작업은 쓰기 작업이며 Write(쓰기) 키가 필요합니다.

매개변수

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

{  "data": {    "markAsDuplicate": {      "success": true,      "errors": null    }  }}

success: true는 항목이 수락되어 PROCESSING 상태로 이동함을 의미합니다. success: false인 200 응답이나 400 응답에는 각 항목에 code, message, path가 포함된 errors 배열이 함께 반환되며, 일반적인 원인은 알 수 없거나 형식이 잘못된 id입니다. Python SDK는 페이로드를 반환하지만 Node SDK는 대신 ValidationError를 발생시키므로, promise가 정상적으로 이행되면 성공한 것입니다.

등록 정보 항목을 중복이 아닌 것으로 제외

POST /locations/listings/mark-as-not-duplicate

잠재적 중복 항목을 오탐으로 판단하여 제외합니다. 감지는 보수적으로 수행되므로 같은 프랜차이즈의 다른 지점, 별도로 존재하는 유효한 두 번째 프로필 또는 이름이 변경된 사업장도 표시됩니다. 제외된 항목은 두 중복 항목 엔드포인트 모두에 더 이상 나타나지 않습니다. 위 엔드포인트와 동일한 본문을 입력받으며, 잘못 표시된 항목을 되돌릴 때도 사용합니다.

매개변수

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-not-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

{  "data": {    "markAsNotDuplicate": {      "success": true,      "errors": null    }  }}

응답은 data.markAsNotDuplicate이며, 중복으로 표시하는 호출과 동일한 success 및 errors 필드를 포함합니다. 제외된 항목은 중복이 아닌 것으로 확인되어 기록되며, 다음 감지 실행 시 다시 나타나지 않습니다.

발생할 수 있는 오류

모든 코드는 오류 참조 문서에 나열되어 있습니다.

다음 단계

• 등록 정보 상태 및 공개 URL 확인: premium 및 voice 엔드포인트로 게시 현황 대시보드를 만듭니다.
• 등록 정보 오류 찾기 및 수정: REQUIRING_ACTION 및 FAILED 행을 차례로 처리합니다.
• 중복 등록 정보 처리: 상태 추적을 포함해 중복 엔드포인트 4개로 진행하는 검토 절차입니다.
• Google 연결 및 사업장 가져오기: Google Maps와 Google Assistant에서 사용하는 Google Business Profile을 연결합니다.
• Apple Business Connect 연결: 소유자의 인증된 Apple Business 계정을 통해 Apple Maps에 게시합니다.
• 리소스 안내 페이지: 등록 정보. SDK 참조 문서: Python listings, Node listings.