/api/v4/locations/{locationId}/listings/premiumObtenha listagens premium para um local
Retorna o status de sincronização de cada diretório de plataforma de publicação no plano de um local.
Parâmetros
Caminho
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| locationId | string | obrigatório | Location to read. Accepts a base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
Respostas
200Array of listings with per-directory sync status.
{ "data": { "listingsForLocation": [ { "id": "TGlzdGluZzoxMDQ0Njg3MjM=", "databaseId": "104468723", "site": { "id": "U2l0ZTox", "databaseId": "1", "name": "Google Maps", "url": "maps.google.com", "syScore": "100" }, "syncStatus": "REQUIRING_ACTION", "displayStatus": "Connect your account to sync the listing", "actionRequired": true, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:28Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MTQ=", "databaseId": "104468714", "site": { "id": "U2l0ZToxODA=", "databaseId": "180", "name": "Bing", "url": "www.bing.com", "syScore": "97" }, "syncStatus": "IN_PROGRESS", "displayStatus": "Information submitted to partner; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:35Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3Mjc=", "databaseId": "104468727", "site": { "id": "U2l0ZTozODc=", "databaseId": "387", "name": "BeLocalFocussed", "url": "belocalfocussed.com", "syScore": "80" }, "syncStatus": "SYNCED", "displayStatus": "Synced", "actionRequired": false, "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e", "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:30Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MDk=", "databaseId": "104468709", "site": { "id": "U2l0ZTozMDE=", "databaseId": "301", "name": "Local Mint", "url": "localmint.com", "syScore": "69" }, "syncStatus": "FAILED", "displayStatus": "Partner experiencing issues; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:34:03Z", "indexStatus": false, "syncIssue": "Publisher requires website URL", "verified": false } ] }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
Retorna o status de sincronização de cada diretório de plataforma de publicação incluído no plano de um local. Cada registro associa um site (metadados do diretório) a um syncStatus e a um displayStatus legível por humanos. O exemplo acima é um recorte da resposta real de Jenny Home (que retorna mais de 30 diretórios) para mostrar um registro em cada um dos estados comuns.
O nível da listagem faz parte do caminho: /listings/premium retorna os diretórios premium do plano (mostrados aqui) e /listings/additional retorna listagens adicionais/gratuitas. Não há parâmetro de consulta listingType; um valor enviado nesse parâmetro é ignorado.
Caso de uso: um painel de integridade das listagens
Busque as listagens premium de um local e agrupe por syncStatus para mostrar rapidamente a cobertura: quantos diretórios estão ativos, em andamento ou bloqueados. Exiba listingUrl nas linhas com SYNCED para que os usuários possam clicar e acessar a listagem ativa, e consulte displayStatus/syncIssue para tudo que não estiver sincronizado (e.g. Publisher requires website URL).
Caso de uso: mostre os bloqueios que exigem "conecte sua conta"
Filtre por actionRequired: true para montar a lista de tarefas do proprietário. Nos dados reais, Google Maps, Facebook e Waze são retornados com REQUIRING_ACTION e displayStatus: "Connect your account to sync the listing"; eles precisam de uma conexão OAuth antes de poderem sincronizar. Direcione o proprietário para o fluxo de conexão correspondente e consulte este endpoint novamente para acompanhar o avanço do status.
Valores de syncStatus: AVAILABLE (pronto para sincronizar, ainda não iniciado), IN_PROGRESS (enviado ao parceiro, aguardando resposta), PENDING_APPROVAL (aguardando aprovação do parceiro), SYNCED / COMPLETED (ativo; listingUrl preenchido), REQUIRING_ACTION (ação do proprietário necessária, consulte displayStatus), FAILED (falha na sincronização; consulte syncIssue), CANNOT_SUBMIT (envio não é possível).
Esta é uma lista por local sujeita ao limite de requisições da conta; ao receber 429, tente novamente após o intervalo indicado no cabeçalho Retry-After, em vez de consultar novamente de imediato.
curl -X GET 'https://listingsapi.com/api/v4/locations/<locationId>/listings/premium' \ -H "Authorization: API $LISTINGSAPI_KEY"