Listings APIListings API
Iniciar sesión
GET/api/v4/locations/{locationId}/listings/premium

Obtener fichas premium para una ubicación

Devuelve el estado de sincronización de cada directorio de las plataformas de publicación del plan de una ubicación.

Requiere una clave de API. Consulta Autenticación para conocer el formato del encabezado y la rotación de claves.

Parámetros

Ruta

NombreTipoObligatorioDescripción
locationIdstringobligatorioLocation to read. Accepts a base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID.

Respuestas

200Array of listings with per-directory sync status.
Response
{  "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.

Devuelve el estado de sincronización de cada directorio de las plataformas de publicación incluido en el plan de una ubicación. Cada registro asocia un site (metadatos del directorio) con un syncStatus y un displayStatus legible para las personas. El ejemplo anterior es una versión recortada de la respuesta real de Jenny Home (que devuelve más de 30 directorios) para mostrar un registro en cada uno de los estados habituales.

El nivel de la ficha forma parte de la ruta: /listings/premium devuelve los directorios premium del plan (que se muestran aquí) y /listings/additional devuelve las fichas adicionales/gratuitas. No existe ningún parámetro de consulta listingType; cualquier valor enviado en él se ignora.

Caso de uso: un panel del estado de las fichas

Obtén las fichas premium de una ubicación y agrúpalas por syncStatus para mostrar de un vistazo la cobertura y cuántos directorios están activos, en proceso o bloqueados. Muestra listingUrl en las filas con SYNCED para que los usuarios puedan hacer clic y acceder a la ficha publicada, y consulta displayStatus/syncIssue para todo lo que no esté sincronizado (e.g. Publisher requires website URL).

Caso de uso: mostrar los bloqueos de "conecta tu cuenta"

Filtra por actionRequired: true para crear la lista de tareas pendientes del propietario. En los datos reales, Google Maps, Facebook y Waze se devuelven con REQUIRING_ACTION y displayStatus: "Connect your account to sync the listing"; necesitan una conexión OAuth para poder sincronizarse. Dirige al propietario al flujo de conexión correspondiente y, después, vuelve a consultar periódicamente este endpoint para observar cómo avanza el estado.

Valores de syncStatus: AVAILABLE (listo para sincronizar, sin iniciar), IN_PROGRESS (enviado al socio, a la espera de respuesta), PENDING_APPROVAL (a la espera de la aprobación del socio), SYNCED / COMPLETED (publicado; listingUrl contiene un valor), REQUIRING_ACTION (se requiere una acción del propietario, consulta displayStatus), FAILED (la sincronización ha fallado; consulta syncIssue), CANNOT_SUBMIT (el envío no es posible).

Esta lista corresponde a una ubicación y está sujeta al límite de solicitudes de la cuenta; si recibes 429, vuelve a intentarlo una vez transcurrido el tiempo indicado en la cabecera Retry-After, en lugar de volver a consultar inmediatamente.

Request
curl -X GET 'https://listingsapi.com/api/v4/locations/<locationId>/listings/premium' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground