Fiches

Tous les endpoints : cURL/Python/Node, état de synchronisation premium, assistants vocaux, doublons par établissement/compte : détection et suppression.

Une fiche est l’entrée d’un établissement dans l’annuaire d’une plateforme de publication. La création d’un établissement met en file d’attente une fiche par plateforme de publication comprise dans votre forfait, et les endpoints de fiches permettent de consulter l’état de chacune, de répertorier les doublons détectés et de les confirmer ou de les écarter. Les quatre endpoints GET fonctionnent avec une clé Read (lecture) ; les deux endpoints POST nécessitent une clé Write (écriture).

Les endpoints en un coup d’œil

Consulter l’état des fiches premium

GET /locations/{locationId}/listings/premium

Renvoie, sous data.listingsForLocation, un enregistrement par plateforme de publication premium comprise dans le forfait de l’établissement. Il s’agit d’un simple tableau, et non d’une liste paginée. Le chemin parallèle /listings/additional renvoie les annuaires gratuits sous la même forme ; il n’existe aucun paramètre de requête listingType, et toute valeur transmise à ce titre est ignorée.

Paramètres

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

Adaptez le traitement selon syncStatus. Affichez displayStatus à une personne, consultez syncIssue pour connaître le motif fourni par la plateforme de publication, et utilisez lastUpdate pour repérer une soumission qui n’avance plus. listingUrl n’est renseigné que pour les lignes correspondant à des fiches en ligne.

Google Maps, Facebook et Waze restent à l’état REQUIRING_ACTION avec displayStatus: "Connect your account to sync the listing" tant que le compte correspondant n’est pas connecté. Ce comportement est normal pour un nouvel établissement.

Consulter l’état des assistants vocaux

GET /locations/{locationId}/voice-assistants

Renvoie un enregistrement par assistant vocal sous data.voiceAssistantsForLocation : Google Assistant, Amazon Alexa, Apple Siri, Microsoft Cortana et Samsung Bixby. Il s’agit d’un simple tableau dont l’ensemble des états possibles est plus restreint que celui de l’endpoint premium.

Paramètres

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

Signalez chaque ligne où actionRequired vaut true ou où syncIssue est renseigné. errors contient les chaînes d’erreur provenant de la plateforme de publication, et connectedAccountId identifie le compte connecté utilisé pour la synchronisation, le cas échéant. Les résultats de Google Assistant proviennent de la connexion à Google Business Profile ; l’absence de connexion à Google est donc la raison la plus fréquente pour laquelle Google Assistant nécessite votre attention. Les résultats de Siri proviennent de la fiche Apple Maps de l’établissement.

Regrouper les doublons à l’échelle du compte

GET /locations/listings/duplicates

Renvoie sous data.duplicateListingsRollup tous les doublons détectés auxquels la clé donne accès, pour l’ensemble des établissements et des plateformes de publication. La pagination repose sur un décalage : page et perPage en entrée, records[] ainsi que pageInfo.totalRecords, pageInfo.totalPages et pageInfo.hasNextPage en sortie. Les filtres sont des paramètres de requête à plat, et non du JSON. Si aucun paramètre n’est fourni, status prend par défaut la valeur POTENTIAL et tag la valeur all ; un appel sans paramètres renvoie donc les doublons ouverts du compte.

Paramètres

Les wrappers Python et Node exposent uniquement tag et page. Pour filtrer par status ou siteId, ou pour définir perPage, appelez directement la route comme indiqué dans Gérer les fiches en double.

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

Le regroupement vous indique où se trouvent les doublons : chaque enregistrement précise le locationId et le siteName. duplicateProcessingState correspond au même statut de cycle de vie que celui renvoyé par le point de terminaison par établissement sous le nom status. Parcourez les pages une à une jusqu’à ce que hasNextPage ait la valeur false ; une boucle sans pause est le moyen le plus rapide de provoquer une erreur 429.

Lister les doublons d’un établissement

GET /locations/{locationId}/listings/duplicates

Renvoie sous data.duplicateListingsForLocation tous les doublons détectés pour un seul établissement, regroupés par site de plateforme de publication. Il s’agit d’un simple tableau. Chaque groupe correspond à un site (name, url) avec un tableau listings, et chaque entrée contient le listingItemId accepté par les deux points de terminaison de marquage. Un tableau vide signifie qu’aucun doublon n’a été détecté.

Paramètres

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

Ouvrez liveLink pour examiner l’entrée, puis conservez listingItemId. Dans le Node SDK, le d.id aplati est la valeur à transmettre. status utilise les mêmes quatre valeurs que le regroupement à l’échelle du compte ci-dessus.

Confirmer des éléments de fiche comme doublons

POST /locations/listings/mark-as-duplicate

Marque des éléments de fiche comme doublons confirmés afin qu’ils puissent être supprimés auprès de la plateforme de publication. Envoyez les valeurs listingItemId sous input et regroupez tous les éléments confirmés d’un établissement dans un seul appel plutôt que d’effectuer un appel par élément. Il s’agit d’une opération d’écriture qui nécessite une clé Write (écriture).

Paramètres

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 signifie que les éléments ont été acceptés et passent au statut PROCESSING. Une réponse 200 avec success: false, ou une réponse 400, s’accompagne d’un tableau errors dont les entrées contiennent code, message et path ; un identifiant inconnu ou mal formé en est généralement la cause. Le Python SDK renvoie la charge utile ; le Node SDK lève à la place une exception ValidationError, donc une promesse résolue signifie que l’opération a réussi.

Écarter des éléments de fiche comme n’étant pas des doublons

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

Écarte des doublons potentiels en les classant comme faux positifs. La détection est prudente et signalera un autre établissement de la même franchise, un second profil légitime ou un établissement renommé. Une fois écartés, les éléments cessent d’apparaître dans les résultats des deux points de terminaison de doublons. Ce point de terminaison accepte un corps identique à celui du point de terminaison ci-dessus et permet également d’annuler le marquage d’un élément signalé par erreur.

Paramètres

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 réponse est data.markAsNotDuplicate, avec les mêmes champs success et errors que l’appel de marquage comme doublon. Un élément écarté est enregistré comme confirmé non doublon et ne réapparaît pas lors du prochain passage de détection.

Erreurs que vous rencontrerez

Chaque code figure dans la référence des erreurs.

Étapes suivantes

• Vérifier le statut des fiches et les liens actifs : transformez les endpoints premium et voice en tableau de bord de couverture.
• Détecter et corriger les erreurs des fiches : traitez les lignes REQUIRING_ACTION et FAILED.
• Gérer les fiches en double : le cycle de vérification utilisant les quatre endpoints de doublons, avec le suivi des statuts.
• Connecter Google et importer des établissements : connectez le profil Google Business Profile utilisé par Google Maps et Google Assistant.
• Connecter Apple Business Connect : publiez sur Apple Maps via le compte Apple Business vérifié du propriétaire.
• Page d’accueil de la ressource : Fiches. Références des SDK : Fiches Python, Fiches Node.