Listings APIListings API
Se connecter

Vérifiez le statut des fiches et obtenez leurs liens

Par établissement : synchro des plateformes de publication, liens actifs, couverture, assistants vocaux et webhooks sans interrogation périodique.

Dès qu'un établissement existe, une fiche est soumise automatiquement à chaque plateforme de publication comprise dans votre forfait. Ce guide explique comment consulter l'état de chacune, récupérer les URL des fiches en ligne et arrêter les interrogations périodiques une fois les webhooks configurés.

1. Récupérer les fiches premium d'un établissement

GET /locations/{locationId}/listings/premium renvoie un enregistrement par plateforme de publication premium comprise dans le forfait. Il s'agit d'un simple tableau, et non d'une liste paginée. La route associée /listings/additional renvoie les annuaires gratuits avec la même structure ; il n'existe aucun paramètre de requête 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"      }    ]  }}

Chaque ligne associe un site à un syncStatus exploitable par une machine et à un displayStatus lisible par une personne. lastUpdate indique la date de dernière modification de la ligne, ce qui permet de repérer une soumission qui ne progresse plus.

2. Consulter le statut de chaque plateforme de publication

syncStatus est le champ à utiliser pour déterminer le traitement à appliquer. displayStatus est le texte à afficher à une personne, et syncIssue contient le motif fourni par la plateforme de publication lorsqu'il y en a un.

syncStatusSignificationAction à effectuer
AVAILABLEPrêt pour la soumission, pas encore commencé.Rien. Le traitement se poursuit automatiquement.
IN_PROGRESSSoumis à la plateforme de publication, en attente d'une réponse.Patientez. Vérifiez lastUpdate si cela fait plusieurs semaines.
PENDING_APPROVALLa plateforme de publication l'a reçu et l'examine.Patientez.
SYNCED ou COMPLETEDEn ligne. listingUrl est renseigné.Récupérez le lien (étape 3).
REQUIRING_ACTIONBloqué dans l'attente de votre intervention. actionRequired vaut true.Consultez displayStatus, puis reportez-vous à Repérer et corriger les erreurs de fiche.
FAILEDLa plateforme de publication l'a rejeté ou n'a pas pu le traiter.Consultez syncIssue, corrigez l'établissement, puis interrogez à nouveau l'API.
CANNOT_SUBMITCette plateforme de publication ne peut pas du tout prendre en charge cet établissement.Il s'agit généralement d'un pays ou d'une catégorie que la plateforme de publication ne prend pas en charge.

Google Maps et Facebook restent au statut REQUIRING_ACTION tant que le compte de la plateforme de publication concernée n'est pas connecté : un Google Business Profile pour Google Maps et une page Facebook pour Facebook. C'est normal pour un nouvel établissement, ce n'est pas une anomalie.

Apple Maps ne nécessite pas de connexion. Si le propriétaire n'a pas connecté de compte d'organisation Apple Business vérifié, ListingsAPI soumet l'établissement via son propre compte Apple Business Connect, et Apple vérifie la soumission avant de la publier. Consultez Connecter Apple Business Connect.

listingUrl n'est renseigné que pour les lignes correspondant à des fiches en ligne. Filtrez sur SYNCED (et COMPLETED) et conservez l'URL avec le nom du site afin de pouvoir afficher une liste « voir en ligne » ou l'enregistrer dans votre propre enregistrement.

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

Une ligne SYNCED peut avoir un listingUrl à null : certains annuaires ne fournissent pas d'URL de page publique. Considérez le statut comme faisant foi et le lien comme facultatif.

4. Créer un résumé de la couverture

Compter les lignes par syncStatus donne un indicateur de santé en une ligne pour chaque établissement : le nombre de plateformes de publication sur lesquelles la fiche est en ligne, le nombre de celles pour lesquelles le traitement est encore en cours et le nombre de celles pour lesquelles il est bloqué. C'est le chiffre à afficher sur un tableau de bord.

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

Exécutez cette opération sur de nombreux établissements en parcourant les pages de GET /locations et en appelant l'endpoint premium une fois par établissement. Chaque appel est décompté de votre limite de débit ; espacez donc les appels et respectez Retry-After lors d'une réponse 429. Repérer et corriger les erreurs de fiche présente cette boucle sous la forme d'un parcours de l'ensemble d'un compte.

5. Vérifiez les assistants vocaux

Les assistants vocaux (Google Assistant, Alexa, Siri, Cortana, Bixby) disposent de leur propre endpoint, GET /locations/{locationId}/voice-assistants, avec un ensemble de statuts plus restreint. Google Assistant dépend de la connexion Google ; un établissement qui n'en dispose pas nécessite donc également votre attention ici. Les résultats de Siri proviennent de la fiche Apple Maps de l'établissement.

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": []      }    ]  }}
syncStatusSignification
NOT_SUBMITTEDPas encore envoyé à l'assistant.
IN_PROGRESSEnvoi en cours.
REQUIRING_ACTIONBloqué dans l'attente de votre intervention ; lisez syncIssue.
LIVEPublié.

Il n'existe pas de lien vers une fiche en ligne pour un assistant vocal ; LIVE est l'état final.

6. Recevez des événements webhook au lieu d'effectuer des interrogations périodiques

Si vous avez configuré une URL de webhook à /dashboard/webhooks, l'événement listing.submission se déclenche chaque fois qu'un envoi à une plateforme de publication pour un établissement atteint un état terminal. Il contient status (success, incomplete ou canceled), le site et, en cas de succès, live_link, qui correspond à l'URL que vous avez récupérée à l'étape 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"))

Répondez avec 200 dans un délai de 5 secondes et effectuez le traitement ensuite ; aucune nouvelle tentative n'est effectuée. Pour le squelette du récepteur et la vérification de la signature, consultez Réagir aux événements avec des webhooks.

Étapes suivantes