Fichas

Endpoints con cURL, Python y Node: estado de sincronización prémium, asistentes de voz, detección de duplicados por ubicación/cuenta y supresión.

Una ficha es la entrada de una ubicación en el directorio de una plataforma de publicación. Al crear una ubicación, se pone en cola una ficha por cada plataforma de publicación de tu plan, y los endpoints de fichas consultan el estado de cada una, enumeran los duplicados que se han detectado y permiten confirmarlos o descartarlos. Los cuatro endpoints GET funcionan con una clave Read (lectura); los dos endpoints POST necesitan una clave Write (escritura).

Endpoints de un vistazo

Consultar el estado de las fichas prémium

GET /locations/{locationId}/listings/premium

Devuelve en data.listingsForLocation un registro por cada plataforma de publicación prémium del plan de la ubicación. Es un array simple, no una lista paginada. La ruta paralela /listings/additional devuelve los directorios gratuitos con la misma estructura; no existe el parámetro de consulta listingType y cualquier valor enviado en él se ignora.

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

Elige la lógica que se ejecuta según syncStatus. Muestra displayStatus a una persona, lee syncIssue para conocer el motivo indicado por la plataforma de publicación y usa lastUpdate para detectar un envío que se haya estancado. listingUrl solo tiene un valor en las filas de fichas publicadas.

Google Maps, Facebook y Waze permanecen en REQUIRING_ACTION con displayStatus: "Connect your account to sync the listing" hasta que se conecte la cuenta correspondiente. Es lo esperado para una ubicación nueva.

Consultar el estado de los asistentes de voz

GET /locations/{locationId}/voice-assistants

Devuelve en data.voiceAssistantsForLocation un registro por cada asistente de voz: Google Assistant, Amazon Alexa, Apple Siri, Microsoft Cortana y Samsung Bixby. Es un array simple con un conjunto de estados más reducido que el del endpoint prémium.

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

Marca todas las filas en las que actionRequired sea true o syncIssue tenga un valor. errors contiene las cadenas de error de la plataforma de publicación, y connectedAccountId indica el nombre de la cuenta conectada que realiza la sincronización cuando corresponde. Los resultados de Google Assistant proceden de la conexión con Google Business Profile, por lo que la ausencia de una conexión con Google es el motivo más habitual por el que requiere atención. Los resultados de Siri proceden de la ficha de la ubicación en Apple Maps.

Consolida los duplicados de toda la cuenta

GET /locations/listings/duplicates

Devuelve todos los duplicados detectados que la clave puede ver, en todas las ubicaciones y plataformas de publicación, en data.duplicateListingsRollup. Es una página basada en desplazamiento: recibe page y perPage y devuelve records[] junto con pageInfo.totalRecords, pageInfo.totalPages y pageInfo.hasNextPage. Los filtros son parámetros de consulta planos, no JSON. Si no se proporciona nada, status toma el valor predeterminado POTENTIAL y tag toma el valor all, por lo que una llamada sin parámetros devuelve los duplicados abiertos de la cuenta.

Parámetros

Los wrappers de Python y Node solo exponen tag y page. Para filtrar por status o siteId, o para establecer perPage, llama a la ruta directamente como se muestra en Gestionar fichas 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"        }      ]    }  }}

El consolidado te indica dónde están los duplicados: cada registro identifica el locationId y el siteName. duplicateProcessingState es el mismo estado del ciclo de vida que el endpoint por ubicación devuelve como status. Recorre las páginas hasta que hasNextPage sea false, de una en una; un bucle sin pausas es la forma más rápida de obtener un 429.

Enumera los duplicados de una ubicación

GET /locations/{locationId}/listings/duplicates

Devuelve todos los duplicados detectados para una sola ubicación en data.duplicateListingsForLocation, agrupados por sitio de la plataforma de publicación. Es un array simple. Cada grupo es un sitio (name, url) con un array listings, y cada entrada incluye el listingItemId que aceptan ambos endpoints de marcado. Un array vacío significa que no se detectó nada.

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

Abre liveLink para revisar la entrada y, después, guarda listingItemId. En el Node SDK, el d.id aplanado es el valor que debes pasar. status usa los mismos cuatro valores que el consolidado de la cuenta anterior.

Confirma elementos de fichas como duplicados

POST /locations/listings/mark-as-duplicate

Marca elementos de fichas como duplicados confirmados para que se pueda gestionar su supresión con la plataforma de publicación. Envía los valores de listingItemId en input y agrupa todos los elementos confirmados de una ubicación en una sola llamada en lugar de realizar una llamada por elemento. Esta es una operación de escritura y requiere una clave Write (escritura).

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 los elementos se aceptaron y pasan a PROCESSING. Un 200 con success: false, o un 400, viene acompañado de un array errors cuyas entradas incluyen code, message y path; la causa habitual es un id desconocido o mal formado. El Python SDK devuelve el contenido de la respuesta; el Node SDK lanza ValidationError en su lugar, por lo que una promesa resuelta significa que la operación se completó correctamente.

Descarta elementos de fichas por no ser duplicados

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

Descarta posibles duplicados como falsos positivos. La detección es conservadora y marcará otra ubicación de la misma franquicia, un segundo perfil legítimo o una ubicación cuyo nombre haya cambiado. Una vez descartados, los elementos dejan de aparecer en ambos endpoints de duplicados. Acepta el mismo cuerpo que el endpoint anterior y también permite revertir el marcado de un elemento señalado por error.

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

La respuesta es data.markAsNotDuplicate con los mismos campos success y errors que la llamada para marcar como duplicado. Un elemento descartado se registra como confirmado que no es un duplicado y no vuelve a aparecer en la siguiente ejecución de la detección.

Errores que verás

Todos los códigos figuran en la referencia de errores.

Próximos pasos

• Comprueba el estado de las fichas y los enlaces activos: convierte los endpoints premium y voice en un panel de cobertura.
• Busca y corrige errores en las fichas: revisa las filas de REQUIRING_ACTION y FAILED.
• Gestiona las fichas duplicadas: el ciclo de revisión en los cuatro endpoints de duplicados, incluido el seguimiento del estado.
• Conecta Google e importa ubicaciones: conecta el Google Business Profile que usan Google Maps y Google Assistant.
• Conecta Apple Business Connect: publica en Apple Maps a través de la cuenta verificada de Apple Business del propietario.
• Página principal del recurso: Fichas. Referencias de los SDK: Fichas en Python, Fichas en Node.