Listings APIListings API
Iniciar sesión

Comprueba el estado de las fichas y obtén enlaces activos

Revisa sincronización, URL de fichas activas, cobertura y asistentes de voz por ubicación y plataforma de publicación; recibe webhooks sin sondeo.

Una vez que existe una ubicación, se envía automáticamente una ficha a cada plataforma de publicación de tu plan. Esta guía muestra cómo consultar el estado de cada una, obtener las URL de las fichas publicadas y dejar de realizar consultas periódicas una vez configurados los webhooks.

1. Obtén las fichas prémium de una ubicación

GET /locations/{locationId}/listings/premium devuelve un registro por cada plataforma de publicación prémium del plan. Es un array simple, no una lista paginada. La ruta equivalente /listings/additional devuelve los directorios gratuitos con la misma estructura; no hay ningún 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 fila combina un site con un syncStatus legible por máquinas y un displayStatus legible por personas. lastUpdate te indica cuándo cambió la fila por última vez, lo que resulta útil para detectar un envío que se ha estancado.

2. Consulta el estado de cada plataforma de publicación

syncStatus es el campo que debes usar para decidir qué rama de la lógica ejecutar. displayStatus es el texto que debes mostrar a una persona, y syncIssue contiene el motivo indicado por la plataforma de publicación cuando lo hay.

syncStatusSignificadoQué hacer
AVAILABLEListo para enviar; aún no se ha iniciado.Nada. Avanza automáticamente.
IN_PROGRESSEnviado a la plataforma de publicación, a la espera de una respuesta.Espera. Comprueba lastUpdate si han pasado semanas.
PENDING_APPROVALLa plataforma de publicación lo ha recibido y lo está revisando.Espera.
SYNCED o COMPLETEDPublicado. listingUrl tiene un valor.Recopila el enlace (paso 3).
REQUIRING_ACTIONBloqueado a la espera de una acción por tu parte. actionRequired es true.Lee displayStatus y luego consulta Detectar y corregir errores de las fichas.
FAILEDLa plataforma de publicación lo ha rechazado o no ha podido procesarlo.Lee syncIssue, corrige la ubicación y vuelve a consultar el estado.
CANNOT_SUBMITEsta plataforma de publicación no puede aceptar esta ubicación en ningún caso.Normalmente se debe a un país o una categoría que la plataforma de publicación no admite.

Google Maps y Facebook permanecen en REQUIRING_ACTION hasta que se conecta la cuenta de esa plataforma de publicación: un Google Business Profile para Google Maps y una página de Facebook para Facebook. Es lo esperado para una ubicación nueva, no un fallo.

Apple Maps no requiere una conexión. Si el propietario no ha conectado una cuenta de organización verificada de Apple Business, ListingsAPI envía la ubicación a través de su propia cuenta de Apple Business Connect, y Apple verifica el envío antes de publicarlo. Consulta Conectar Apple Business Connect.

listingUrl solo tiene un valor en las filas correspondientes a fichas publicadas. Filtra por SYNCED (y COMPLETED) y conserva la URL junto con el nombre del sitio para poder mostrar una lista de enlaces con el texto «ver ficha publicada» o guardarla en tu propio 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}]'

Puede haber una fila SYNCED con listingUrl igual a null: algunos directorios no proporcionan la URL de una página pública. Considera el estado como la fuente de referencia y el enlace como opcional.

4. Crea un resumen de cobertura

Contar las filas por syncStatus proporciona un indicador de estado en una sola línea por ubicación: cuántas plataformas de publicación tienen la ficha publicada, cuántas siguen en proceso y cuántas están bloqueadas. Esta es la cifra que debes mostrar en un panel.

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

Ejecuta este proceso para muchas ubicaciones recorriendo las páginas de GET /locations y llamando al endpoint prémium una vez por ubicación. Cada llamada cuenta para tu límite de solicitudes, así que deja un intervalo entre ellas y respeta Retry-After cuando recibas un 429. Detectar y corregir errores de las fichas muestra el bucle como un recorrido de todas las ubicaciones de una cuenta.

5. Comprueba los asistentes de voz

Los asistentes de voz (Google Assistant, Alexa, Siri, Cortana, Bixby) tienen su propio endpoint, GET /locations/{locationId}/voice-assistants, con un conjunto más reducido de estados. Google Assistant depende de la conexión con Google, por lo que una ubicación sin esa conexión también requiere atención aquí. Los resultados de Siri proceden de la ficha de la ubicación en 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_SUBMITTEDAún no se ha enviado al asistente.
IN_PROGRESSEnvío en curso.
REQUIRING_ACTIONBloqueado a la espera de que actúes; lee syncIssue.
LIVEPublicado.

No hay un enlace público para un asistente de voz; LIVE es el estado final.

6. Recibe eventos de webhook en lugar de realizar consultas periódicas

Si tienes una URL de webhook configurada en /dashboard/webhooks, el evento listing.submission se activa cada vez que un envío a una plataforma de publicación para una ubicación alcanza un estado terminal. Incluye status (success, incomplete o canceled), el sitio y, si el envío se completa correctamente, live_link, que es la misma URL que recopilaste en el paso 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"))

Responde con 200 en un plazo de 5 segundos y realiza el trabajo después; no hay reintentos. Para consultar la estructura básica del receptor y la verificación de la firma, ve a Reacciona a eventos con webhooks.

Próximos pasos