Choisir votre mode d’intégration

Comparez l’API REST, les SDK Python et Node, le serveur MCP et les webhooks selon l’architecture et les besoins d’intégration de votre application.

Toutes les méthodes d’intégration utilisent la même clé API et la même URL de base : https://listingsapi.com/api/v4. Vous pouvez utiliser l’API REST ou un SDK pour les requêtes API, les webhooks pour les mises à jour déclenchées par des événements et le serveur MCP pour réaliser l’intégration avec l’aide d’un agent IA.

1. Choisissez comment appeler l’API

API REST. Utilisez l’API REST pour accéder directement à tous les endpoints via HTTP. Votre application doit analyser la réponse, gérer les deux méthodes de pagination et examiner le tableau errors[] pour détecter les erreurs de l’API.

Python SDK. Installez le Python SDK avec pip install listingsapi. Le SDK fournit des classes de ressources via des interfaces telles que client.locations et client.reviews. Il gère la pagination par curseur avec auto_paging_iter(), réessaie les requêtes qui renvoient des réponses 429 ou 5xx et valide les données des établissements dans locations.add() avant d’envoyer la requête API. Consultez Python SDK.

Node SDK. Installez le Node SDK avec npm install listingsapi-js. Il nécessite Node.js 18 ou une version ultérieure, inclut les définitions de types TypeScript et ne comporte aucune dépendance d’exécution. Les méthodes du SDK sont exposées directement sur l’instance du client, par exemple client.fetchAllLocations(). Définissez fetchAll: true pour récupérer tous les résultats paginés dans une seule réponse. Les identifiants numériques sont automatiquement encodés en Base64 avant l’envoi des requêtes API. Consultez Node SDK.

Serveur MCP. Connectez des clients IA tels que Claude, ChatGPT, Cursor et Gemini au serveur MCP de ListingsAPI à l’adresse https://listingsapi.com/mcp via Streamable HTTP. Aucune installation locale du serveur MCP n’est requise. Le serveur expose des outils permettant de rechercher dans la documentation de ListingsAPI, de découvrir les endpoints REST et d’exécuter les opérations API prises en charge. L’authentification utilise une clé API ou OAuth. Ouvrez /dashboard/mcp pour consulter la configuration des clients, les outils MCP disponibles et le niveau d’autorisation de la clé API requis pour chaque outil. Connecter un agent IA avec MCP.

Webhooks. Utilisez les webhooks avec l’API REST, les SDK ou le serveur MCP pour recevoir des mises à jour déclenchées par des événements. Lorsqu’un établissement, une fiche, un avis ou une publication est modifié, ListingsAPI envoie une requête HTTP POST à l’URL de webhook configurée pour votre compte. Cela permet à votre application de traiter les modifications sans interroger régulièrement l’API pour obtenir les mises à jour. Consultez Présentation des webhooks.

2. Comprenez le modèle d’authentification

L’API REST et les SDK authentifient les requêtes à l’aide d’une clé API. Transmettez la clé dans l’en-tête de requête HTTP Authorization en utilisant le schéma d’authentification API :

Authorization: API <YOUR_API_KEY>

Les clés API disposent d’un accès Read (lecture) ou Write (écriture). Une clé Read permet d’accéder aux opérations de lecture, notamment aux recherches et aux rapports. Une clé Write est requise pour les opérations qui créent ou mettent à jour des ressources. Lorsqu’une clé Read est envoyée à un endpoint d’écriture, celui-ci renvoie le statut HTTP 400 avec le code d’erreur SY90016.

La portée des clés API est limitée à un compte. Les requêtes effectuées avec des clés du même compte consomment le même quota de limitation du débit défini au niveau du compte.

Le serveur MCP prend également en charge l’authentification OAuth. Les clients MCP peuvent s’authentifier dans le navigateur via OAuth au lieu de fournir une clé API. Les requêtes de l’API REST et des SDK s’authentifient à l’aide de l’en-tête Authorization. Consultez la documentation Authentification pour obtenir les détails de configuration.

3. Comprendre les modèles de pagination

Les points de terminaison REST qui renvoient des listes utilisent une pagination par curseur ou par décalage. Les SDK gèrent ces modèles de pagination pour vous.

Les points de terminaison utilisant la pagination par curseur acceptent first et after. Les résultats sont renvoyés via edges[].node, et pageInfo.endCursor fournit le curseur pour la requête suivante.

Les points de terminaison utilisant la pagination par décalage acceptent page et perPage. Les résultats sont renvoyés dans records[], et pageInfo.totalRecords indique le nombre total d'enregistrements disponibles.

Les exemples suivants effectuent la même opération de récupération de la liste des établissements à l'aide de trois méthodes d'intégration. L'implémentation cURL nécessite que l'application analyse directement la structure de la réponse de l'API.

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

Pour toutes les méthodes d'intégration, les erreurs de l'API sont renvoyées dans le tableau errors[], chaque message d'erreur étant précédé d'un code d'erreur SY. Les requêtes d'écriture peuvent renvoyer un statut HTTP 200 avec success: false ; vous devez donc vérifier le corps de la réponse avant de considérer l'opération comme réussie.

Lorsque le compte dépasse sa limite de requêtes, l'API renvoie un statut HTTP 429 avec un en-tête Retry-After. Le forfait Launch autorise jusqu'à 10 requêtes par minute. Consultez la documentation sur les Codes d'erreur et les Limites de requêtes pour en savoir plus.

4. Choisir entre les webhooks et l'interrogation périodique

Utilisez l'interrogation périodique lorsque votre application a besoin de connaître l'état des ressources selon un calendrier défini, par exemple pour une synchronisation nocturne de tous les établissements, ou lorsque l'événement requis n'est pas pris en charge par les webhooks. Utilisez les webhooks lorsque votre application doit traiter les changements au moment où ils se produisent, comme la réception d'un nouvel avis, un changement de statut d'une fiche ou le rejet d'une publication Google.

Configurez une URL de webhook par compte à l'adresse /dashboard/webhooks. Chaque requête de webhook inclut un en-tête X-ListingsAPI-Signature au format suivant :

X-ListingsAPI-Signature: sha256=<base64 HMAC>

Le point de terminaison du webhook doit renvoyer une réponse 2xx dans un délai de 5 secondes. Les tentatives de livraison ayant échoué ne sont pas renouvelées.

Utilisez l'événement du webhook pour déclencher la récupération de l'état actuel de la ressource depuis l'API. Puisque les tentatives de livraison des webhooks ne sont pas renouvelées, exécutez un processus de rapprochement planifié pour détecter les mises à jour qui auraient pu être manquées. Consultez Réagir aux événements avec les webhooks pour un exemple d'implémentation.

5. Comparer en un coup d'œil

Étapes suivantes

• Ajouter un établissement : votre premier appel d'écriture, quelle que soit l'option choisie.
• Réagir aux événements avec les webhooks : mettez en place un récepteur qui vérifie les signatures.
• Python SDK et Node SDK : installez-les, configurez-les et consultez les tableaux des méthodes.
• Authentification, Limites de requêtes et Codes d'erreur : les trois références communes à toutes ces options.