Listagens

Endpoints de listagens: cURL, Python e Node; status de sincronização premium, assistentes de voz, detecção por local/conta e supressão de duplicatas.

Uma listagem é o registro de um local em um diretório de uma plataforma de publicação. Ao criar um local, uma listagem é colocada na fila para cada plataforma de publicação do seu plano, e os endpoints de listagens consultam o estado de cada uma, listam as duplicatas encontradas pela detecção e permitem confirmá-las ou descartá-las. Os quatro endpoints GET funcionam com uma chave Read (leitura); os dois endpoints POST precisam de uma chave Write (escrita).

Visão geral dos endpoints

Consultar o status das listagens premium

GET /locations/{locationId}/listings/premium

Retorna em data.listingsForLocation um registro por plataforma de publicação premium incluída no plano do local. É um array simples, não uma lista paginada. O caminho equivalente /listings/additional retorna os diretórios gratuitos no mesmo formato; não existe parâmetro de consulta listingType, e qualquer valor enviado nele é ignorado.

Parâmetros

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"      }    ]  }}

Defina o fluxo com base em syncStatus. Exiba displayStatus para uma pessoa, consulte syncIssue para saber o motivo informado pela plataforma de publicação e use lastUpdate para identificar um envio que parou de progredir. listingUrl só é definido nas linhas de listagens publicadas.

Google Maps, Facebook e Waze permanecem em REQUIRING_ACTION com displayStatus: "Connect your account to sync the listing" até que a conta correspondente seja conectada. Isso é esperado para um novo local.

Consultar o status dos assistentes de voz

GET /locations/{locationId}/voice-assistants

Retorna em data.voiceAssistantsForLocation um registro por assistente de voz: Google Assistant, Amazon Alexa, Apple Siri, Microsoft Cortana e Samsung Bixby. É um array simples com um conjunto de status menor que o do endpoint premium.

Parâmetros

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": []      }    ]  }}

Sinalize todas as linhas em que actionRequired seja true ou syncIssue esteja definido. errors contém mensagens de erro da plataforma de publicação, e connectedAccountId identifica a conta conectada responsável pela sincronização, quando aplicável. Os resultados do Google Assistant vêm da conexão com o Google Business Profile, portanto, a ausência de uma conexão com o Google é o motivo mais comum para o assistente precisar de atenção. Os resultados da Siri vêm da listagem do local no Apple Maps.

Consolide as duplicatas de toda a conta

GET /locations/listings/duplicates

Retorna todas as duplicatas detectadas às quais a chave tem acesso, em todos os locais e plataformas de publicação, em data.duplicateListingsRollup. É uma página com paginação por deslocamento: recebe page e perPage e retorna records[] mais pageInfo.totalRecords, pageInfo.totalPages e pageInfo.hasNextPage. Os filtros são parâmetros de consulta simples, não JSON. Quando nada é fornecido, status assume o valor padrão POTENTIAL e tag assume all, portanto uma chamada sem parâmetros retorna as duplicatas em aberto da conta.

Parâmetros

Os wrappers de Python e Node expõem apenas tag e page. Para filtrar por status ou siteId, ou definir perPage, chame a rota diretamente, conforme mostrado em Gerenciar listagens duplicadas.

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"        }      ]    }  }}

A consolidação informa onde estão as duplicatas: cada registro identifica locationId e siteName. duplicateProcessingState é o mesmo status do ciclo de vida que o endpoint por local informa como status. Percorra uma página por vez até que hasNextPage seja false; um loop sem intervalos é a maneira mais rápida de receber 429.

Liste as duplicatas de um local

GET /locations/{locationId}/listings/duplicates

Retorna todas as duplicatas detectadas de um único local em data.duplicateListingsForLocation, agrupadas por site da plataforma de publicação. É um array simples. Cada grupo é um site (name, url) com um array listings, e cada entrada contém o listingItemId que ambos os endpoints de marcação recebem. Um array vazio significa que nada foi detectado.

Parâmetros

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"          }        ]      }    ]  }}

Abra liveLink para examinar a entrada e, em seguida, guarde listingItemId. No Node SDK, o d.id da estrutura sem aninhamento é o valor a ser passado adiante. status usa os mesmos quatro valores da consolidação da conta acima.

Confirme itens de listagem como duplicatas

POST /locations/listings/mark-as-duplicate

Marca itens de listagem como duplicatas confirmadas para que possam ser suprimidos junto à plataforma de publicação. Envie os valores de listingItemId em input e agrupe todos os itens confirmados de um local em uma única chamada, em vez de fazer uma chamada por item. Esta é uma operação de escrita e exige uma chave Write (escrita).

Parâmetros

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 significa que os itens foram aceitos e passam para PROCESSING. Uma resposta 200 com success: false, ou uma resposta 400, vem com um array errors cujas entradas contêm code, message e path; a causa habitual é um id desconhecido ou malformado. O Python SDK retorna o payload; o Node SDK lança ValidationError em vez disso, portanto uma promise resolvida significa que a operação foi bem-sucedida.

Descarte itens de listagem como não duplicados

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

Descarta possíveis duplicatas como falsos positivos. A detecção é conservadora e sinalizará outra unidade da mesma franquia, um segundo perfil legítimo ou um local renomeado. Depois de descartados, os itens deixam de aparecer em ambos os endpoints de duplicatas. Esse endpoint recebe um corpo idêntico ao do endpoint acima e também permite reverter a marcação de um item sinalizado por engano.

Parâmetros

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    }  }}

A resposta é data.markAsNotDuplicate com os mesmos campos success e errors da chamada de marcação como duplicata. Um item descartado é registrado como não duplicado confirmado e não volta a aparecer na próxima execução da detecção.

Erros que você verá

Todos os códigos estão listados na referência de erros.

Próximos passos

• Verifique o status das listagens e os links ativos: transforme os endpoints premium e voice em um painel de cobertura.
• Encontre e corrija erros de listagem: analise e resolva as linhas de REQUIRING_ACTION e FAILED.
• Lide com listagens duplicadas: o ciclo de avaliação nos quatro endpoints de duplicatas, incluindo o acompanhamento de status.
• Conecte o Google e importe locais: conecte o Google Business Profile que o Google Maps e o Google Assistant usam.
• Conecte o Apple Business Connect: publique no Apple Maps por meio da conta verificada do proprietário no Apple Business.
• Página inicial do recurso: Listagens. Referências dos SDKs: Listagens em Python, Listagens em Node.