Listings APIListings API
Se connecter

Premiers pas

Créez votre compte, ajoutez un moyen de paiement, obtenez votre clé API et effectuez votre premier appel à la Listings API.

Ce guide explique comment créer un compte, obtenir votre première clé API et envoyer une requête à la Listings API.

1. Créez votre compte

Choisissez une offre sur la page des tarifs pour ouvrir le formulaire d'inscription, puis saisissez votre first name (prénom), votre last name (nom), votre work email (adresse e-mail professionnelle) et votre company (entreprise). Vous avez déjà un compte ? Connectez-vous plutôt.

2. Ajoutez un moyen de paiement

Après l'envoi du formulaire, nous vous redirigeons vers notre prestataire de paiement pour ajouter une carte. Votre essai gratuit commence immédiatement et se transforme en abonnement à l'offre choisie à la fin de l'essai ; annulez donc avant cette échéance si vous ne souhaitez pas être facturé. La FAQ sur les tarifs indique la durée actuelle de l'essai et les limites des offres.

3. Définissez votre mot de passe et connectez-vous

Une fois la procédure de paiement terminée, nous vous envoyons par e-mail un lien pour définir votre mot de passe et activer votre compte. Après avoir défini votre mot de passe, connectez-vous avec votre adresse e-mail et votre mot de passe, ou choisissez Email me a sign-in link (M'envoyer un lien de connexion par e-mail) pour recevoir à la place un lien de connexion à usage unique.

4. Obtenez votre clé API

Votre première clé API est générée automatiquement lors de la création de votre compte ; retrouvez-la dans le tableau de bord, sous API Keys. Pour en créer une autre, choisissez New key (Nouvelle clé), donnez-lui un nom et sélectionnez son niveau d'accès (Read (Lecture) ou Write (Écriture)).

5. Effectuez votre première requête

Authentifiez chaque requête avec un en-tête Authorization dont la valeur est la chaîne littérale API (notez l'espace final), suivie de votre clé :

Shell
curl https://listingsapi.com/api/v4/locations \  -H "Authorization: API $LISTINGSAPI_KEY"

La réponse utilise une structure imbriquée plutôt qu'un simple tableau : les résultats se trouvent sous data.allLocations, chaque enregistrement est un edges[].node, et pageInfo contient le curseur de pagination et les totaux.

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "countryIso": "US"          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "total": 1      }    }  }}

Pour passer à la page suivante, renvoyez pageInfo.endCursor comme valeur de ?after=… tant que pageInfo.hasNextPage vaut true, et arrêtez-vous également si une page renvoie un tableau edges vide. Chaque edge contient aussi son propre cursor, et le cursor du dernier edge correspond au endCursor de cette page ; l'une ou l'autre de ces valeurs peut donc être utilisée comme ?after=.

Tous les endpoints de liste n'utilisent pas le même mode de pagination

La structure edges / node / pageInfo ci-dessus correspond à la pagination par curseur de type Relay, qui n'est que l'un des trois modes disponibles :

  • Pagination par curseur (first, after → edges[].node plus pageInfo avec endCursor / hasNextPage) : établissements, recherche d'établissements et endpoints d'avis (interactions par établissement et synthèse à l'échelle du compte).
  • Pagination par décalage (page, perPage → un tableau records plus pageInfo avec totalRecords, totalPages, hasNextPage, hasPreviousPage) : comptes connectés, suggestions de connexion, publications pour un établissement, publications en masse pour un établissement et synthèse des fiches en double à l'échelle du compte.
  • Tableaux simples, sans aucune pagination : les endpoints du catalogue (sous-catégories, pays et États, sites du forfait) et les photos d'un établissement.

Consultez l'exemple de réponse sur la page de l'endpoint concerné avant d'écrire une boucle de pagination ; une boucle par curseur appliquée à un endpoint paginé par décalage tente de lire une clé edges qui n'est jamais présente.

Étapes suivantes