Listings APIListings API
Entrar

Verifique o status das listagens e obtenha links ativos

Por local, veja sincronização por plataforma de publicação, URLs de listagens ativas, cobertura e assistentes de voz. Receba webhooks sem consultas.

Assim que um local existe, uma listagem por plataforma de publicação do seu plano é enviada automaticamente. Este guia mostra como consultar o andamento de cada uma, obter as URLs das listagens publicadas e parar de fazer consultas periódicas depois que os webhooks estiverem configurados.

1. Busque as listagens premium de um local

GET /locations/{locationId}/listings/premium retorna um registro por plataforma de publicação premium do plano. É um array simples, não uma lista paginada. A rota correspondente /listings/additional retorna os diretórios gratuitos com a mesma estrutura; não há parâmetro de consulta 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"      }    ]  }}

Cada linha associa um site a um syncStatus legível por máquina e a um displayStatus legível por pessoas. lastUpdate informa quando a linha foi alterada pela última vez, o que é útil para identificar um envio que parou de avançar.

2. Consulte o status de cada plataforma de publicação

syncStatus é o campo a usar para definir os caminhos da lógica condicional. displayStatus é o texto a exibir para uma pessoa, e syncIssue contém o motivo informado pela plataforma de publicação, quando houver.

syncStatusSignificadoO que fazer
AVAILABLEPronta para envio, ainda não iniciado.Nada. O processo avança automaticamente.
IN_PROGRESSEnviada à plataforma de publicação, aguardando uma resposta.Aguarde. Verifique lastUpdate se já tiverem passado semanas.
PENDING_APPROVALA plataforma de publicação recebeu a listagem e está analisando-a.Aguarde.
SYNCED ou COMPLETEDPublicada. listingUrl está preenchido.Obtenha o link (etapa 3).
REQUIRING_ACTIONBloqueada, depende de uma ação sua. actionRequired é true.Leia displayStatus e consulte Encontre e corrija erros nas listagens.
FAILEDA plataforma de publicação rejeitou a listagem ou não conseguiu processá-la.Leia syncIssue, corrija o local e consulte novamente.
CANNOT_SUBMITEsta plataforma de publicação não pode aceitar este local de forma alguma.Geralmente, trata-se de um país ou de uma categoria que a plataforma de publicação não atende.

Google Maps e Facebook permanecem em REQUIRING_ACTION até que a conta da respectiva plataforma de publicação seja conectada: um Google Business Profile para o Google Maps e uma Página do Facebook para o Facebook. Isso é esperado para um novo local, não é uma falha.

O Apple Maps não exige uma conexão. Se o proprietário não tiver conectado uma conta verificada de organização do Apple Business, o ListingsAPI envia o local por meio de sua própria conta do Apple Business Connect, e a Apple verifica o envio antes de publicá-lo. Consulte Conecte o Apple Business Connect.

listingUrl só é definido nas linhas de listagens publicadas. Filtre por SYNCED (e COMPLETED) e guarde a URL junto com o nome do site para que você possa exibir uma lista de links para visualizar as listagens publicadas ou armazenar a URL no seu próprio registro.

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

Uma linha SYNCED com listingUrl definido como null pode ocorrer: alguns diretórios não disponibilizam uma URL de página pública. Considere o status como a informação definitiva e o link como opcional.

4. Crie um resumo de cobertura

Contar as linhas por syncStatus fornece um indicador da situação de cada local em uma única linha: quantas plataformas de publicação têm listagens publicadas, quantas ainda estão em andamento e quantas estão bloqueadas. Esse é o número a exibir em um painel.

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

Execute esse processo para vários locais percorrendo as páginas de GET /locations e chamando o endpoint premium uma vez por local. Cada chamada conta para o seu limite de requisições, então deixe um intervalo entre elas e respeite Retry-After ao receber 429. Encontre e corrija erros nas listagens mostra esse loop como uma varredura de toda a conta.

5. Verifique os assistentes de voz

Os assistentes de voz (Google Assistant, Alexa, Siri, Cortana, Bixby) têm seu próprio endpoint, GET /locations/{locationId}/voice-assistants, com um conjunto menor de status. O Google Assistant depende da conexão com o Google, portanto, um local sem essa conexão também precisa de atenção aqui. Os resultados da Siri vêm da listagem do local no 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": []      }    ]  }}
syncStatusSignificado
NOT_SUBMITTEDAinda não enviado ao assistente.
IN_PROGRESSEnvio em andamento.
REQUIRING_ACTIONBloqueado à espera de uma ação sua; leia syncIssue.
LIVEPublicado.

Não há um link ativo para um assistente de voz; LIVE é o estado final.

6. Receba eventos de webhook em vez de fazer consultas periódicas

Se você tiver uma URL de webhook configurada em /dashboard/webhooks, o evento listing.submission será disparado sempre que um envio de um local para uma plataforma de publicação atingir um estado terminal. Ele contém status (success, incomplete ou canceled), o site e, em caso de sucesso, live_link, que é a mesma URL que você coletou na etapa 3.

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"))

Responda com 200 em até 5 segundos e faça o processamento depois; não há novas tentativas. Para ver a estrutura básica do receptor e a verificação de assinatura, consulte Reaja a eventos com webhooks.

Próximas etapas