API complémentaires

API complémentaires : exemples cURL, Python et Node, pays et États pris en charge, sous-catégories et plateformes de publication de votre forfait.

Les endpoints complémentaires fournissent les trois catalogues de référence utilisés par le reste de l’API pour valider les données : les pays et États pris en charge, les catégories d’activité existantes et les annuaires des plateformes de publication couverts par votre forfait. Tous les trois sont en lecture seule, sans pagination, et renvoient un ensemble complet de résultats : une clé Read (lecture) suffit donc, et la mise en cache compte davantage que la pagination.

Aperçu des endpoints

Méthode	Chemin	Fonction	Référence
`GET`	`/countries`	Tous les pays pris en charge, avec leurs États et leurs codes ISO.	Lister les pays et États pris en charge
`GET`	`/sub-categories`	Le catalogue complet des catégories d’activité, soit environ 6 000 entrées.	Lister les sous-catégories
`GET`	`/plan-sites`	Tous les annuaires des plateformes de publication inclus dans votre forfait.	Lister les sites du forfait

Lister les pays et États pris en charge

GET /countries

Renvoie le catalogue complet sous data.supportedCountries. Chaque pays contient un code ISO, un id en base64, un databaseId numérique, un tableau states dont les entrées possèdent leurs propres codes ISO, ainsi que trois indicateurs relatifs à l’adresse : hasCity (ville obligatoire), stateRequired (État obligatoire et vérifié par rapport à states) et hasPostalCode (le pays utilise des codes postaux). Un pays sans subdivisions renvoie un tableau states vide.

Paramètres

Cet endpoint n’en accepte aucun. Il renvoie toujours l’ensemble complet des résultats.

Countries

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

JSON

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "hasCity": true,        "id": "Q291bnRyeToxMw==",        "iso": "AU",        "name": "Australia",        "states": [          { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" },          { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "hasCity": true,        "id": "Q291bnRyeToxNw==",        "iso": "BE",        "name": "Belgium",        "states": []      }    ]  }}

Les deux champs iso contiennent les valeurs dont vous avez besoin. Le iso d’un pays devient countryIso lors de la création et de la mise à jour, et le iso d’un État devient stateIso. Valider les deux à l’aide de cette liste avant une écriture permet de remplacer un 400 côté serveur par un message clair dans votre propre formulaire.

Lister les sous-catégories

GET /sub-categories

Renvoie environ 6 000 enregistrements de catégories sous data.subcategories dans un seul tableau sans pagination. Cette table de correspondance permet de convertir un type d’activité que vous connaissez sous forme de texte libre en l’id numérique requis pour une écriture sur un établissement.

Paramètres

Aucun. Le catalogue entier est renvoyé à chaque appel.

Subcategories

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

JSON

{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

Chaque enregistrement contient cinq champs, et celui que vous utilisez dépend de sa destination.

Champ	Utilisation
`databaseId`	L’entier à transmettre comme `subCategoryId` et dans `additionalCategoryIds`.
`id`	L’identifiant en base64 du même enregistrement.
`key`	Un slug du nom adapté aux URL.
`name`	Le libellé à afficher à une personne.
`primary`	Indique si la catégorie peut être la sous-catégorie principale d’un établissement.

Un établissement accepte une catégorie principale dans subCategoryId et jusqu’à 9 catégories supplémentaires dans additionalCategoryIds.

Lister les sites du forfait

GET /plan-sites

Renvoie sous data.planSites tous les annuaires des plateformes de publication inclus dans le forfait de votre compte. Il s’agit de la liste de référence des id numériques des sites, et seuls les id qui y figurent sont valides ailleurs dans l’API.

Paramètres

Aucun. La réponse se limite au forfait de votre compte.

Plan sites

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

JSON

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

Les deux tableaux de pays répondent à des questions différentes. supportedCountries indique dans quels pays le site accepte une fiche : filtrez donc les résultats selon le countryIso de votre établissement avant de proposer une plateforme de publication. hideAddressSupportedCountries indique dans quels pays le site respecte le masquage de l’adresse, ce dont une entreprise desservant une zone géographique a besoin. Les deux tableaux peuvent contenir 50 codes ou plus ; l’exemple ci-dessus est abrégé.

Les id des sites sont stables et utiles à connaître : 1 correspond à Google Maps et 184 à Facebook, les deux plateformes de publication visées par la plupart des parcours de connexion.

Liens d’action pour les établissements

Il ne s’agit pas d’un point de terminaison distinct. Les liens d’action pour les établissements correspondent aux boutons Google tels que Order online (commander en ligne), Reserve a table (réserver une table) et Book an appointment (prendre rendez-vous), et la plateforme les gère comme un champ de l’établissement plutôt que comme une ressource distincte. Vous les définissez dans le tableau placeActionLinks lors de la création et de la mise à jour, et vous les récupérez depuis n’importe quel point de terminaison de lecture d’un établissement.

Chaque entrée nécessite un placeActionType et un uri, accepte un indicateur facultatif isPreferred avec au maximum un lien préféré par type, et accepte un action valant add ou delete lors d’une mise à jour. Les types valides, les règles de suppression et le comportement de synchronisation sont tous décrits dans Liens d’action pour les établissements.

Erreurs que vous rencontrerez

Code ou statut	Signification	Solution
`401`	Clé manquante ou non valide.	Envoyez `Authorization: API <YOUR_API_KEY>`.
`429` avec `Retry-After`	Ces catalogues partagent la limite de requêtes de votre compte.	Mettez le résultat en cache. Consultez Limites de requêtes.
`500` pour les pays	Défaillance côté serveur, et non requête incorrecte.	Réessayez en augmentant progressivement le délai entre les tentatives ; il n’y a rien à corriger dans l’appel.

Aucun de ces points de terminaison n’effectue d’écriture ; ils ne renvoient donc jamais SY90016 ici avec une clé Read. La liste complète figure dans Codes d’erreur.

Étapes suivantes

Rechercher des pays et des catégories : le guide pratique, avec une explication étape par étape de la transition vers la création d’un établissement.
Ajouter un établissement : où countryIso et subCategoryId sont utilisés.
Détecter et corriger les erreurs de fiche : utilise les sites du forfait pour distinguer une plateforme de publication manquante d’une plateforme de publication en échec.
Référence des API complémentaires pour la liste complète des champs des trois points de terminaison.