Listings APIListings API
Se connecter

Effectuez votre premier appel API

Authentifiez-vous, listez vos établissements, lisez la structure de la réponse, parcourez les résultats paginés et comprenez le fonctionnement des ID.

Ce guide suppose que vous disposez d’un compte et d’une clé API obtenus en suivant Premiers pas. Chaque requête utilise l’API de production à l’adresse https://listingsapi.com ; un appel en écriture avec une clé API standard modifie donc des données réelles. Pour essayer l’API sans interagir avec de véritables plateformes de publication, utilisez l’accès gratuit à la journée à l’environnement de test.

1. Définissez votre clé API

Copiez la clé depuis Clés API dans le tableau de bord et exportez-la une seule fois dans votre shell :

bash
export LISTINGSAPI_KEY="your-api-key"

Chaque clé possède un niveau d’accès. Une clé Read (lecture) permet d’effectuer toutes les consultations et de générer tous les rapports présentés dans ces guides. Toute création ou modification, toute réponse à un avis et toute publication d’un contenu nécessitent une clé Write (écriture). Si vous envoyez une clé Read à un endpoint d’écriture, celui-ci renvoie le statut HTTP 400 avec le code d’erreur SY90016.

2. Listez vos établissements

Les autres endpoints font référence à un établissement par son identifiant ; commencez donc par lister vos établissements. L’en-tête REST Authorization utilise le schéma API, suivi d’un espace et de votre clé API : Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. Lisez la réponse

L’API REST renvoie une réponse imbriquée plutôt qu’un simple tableau. Le nom de l’opération se trouve sous data, les résultats des listes sont renvoyés sous forme d’une connexion de edges, et chaque arête contient un node :

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

Le Python SDK renvoie une page d’objets que vous pouvez parcourir par itération. Le Node SDK renvoie locations et pageInfo. Lorsque vous appelez directement l’API REST, lisez data.allLocations.edges[].node.

4. Parcourez les pages de résultats

Les endpoints qui listent les établissements et les avis utilisent une pagination par curseur. Demandez une page avec first, puis transmettez pageInfo.endCursor comme valeur de after pour récupérer la page suivante. Les SDK peuvent lire toutes les pages pour vous.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

Tous les endpoints n’utilisent pas cette méthode de pagination. Les comptes connectés, les regroupements de doublons et les publications utilisent page et perPage avec un tableau records. Chaque guide précise le format de pagination utilisé par ses endpoints.

5. Deux types d’identifiants

Chaque enregistrement possède deux identifiants. id est une chaîne en base64, telle que TG9jYXRpb246MTgwMDI4OQ==, qui donne Location:1800289 une fois décodée. databaseId est le nombre brut, 1800289.

Conservez id en base64. Tous les endpoints d’écriture exigent des identifiants encodés en base64, et ce sont ces valeurs qui sont renvoyées dans les charges utiles des webhooks. De nombreux endpoints de lecture dont le chemin contient un établissement acceptent aussi le nombre brut, et les deux SDK acceptent les deux formes et effectuent l’encodage pour vous.

6. Erreurs et limites de débit

En cas d’échec, les réponses renvoient le statut HTTP correspondant avec un tableau errors. Le message est précédé d’un code d’erreur SY, répertorié dans Codes d’erreur :

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

Les limites de débit dépendent de l’offre, et les requêtes sont comptées par minute, par heure et par jour. L’offre Launch autorise 10 requêtes par minute. Lorsque vous dépassez une limite, l’API renvoie 429 avec un en-tête Retry-After ; attendez le nombre de secondes indiqué avant de réessayer. Les SDK lèvent l’exception RateLimitError et exposent la même valeur. Vous trouverez tous les détails dans Limites de débit.

Étapes suivantes