Rechercher les pays, les États et les catégories

Avant de créer un établissement : pays et codes d’États pris en charge, ID numérique de catégorie et plateformes de publication de votre forfait.

La création d'un établissement nécessite trois valeurs qui doivent provenir de l'API : un countryIso et un stateIso acceptés par l'API, un subCategoryId numérique et, si vous souhaitez limiter les plateformes de publication, les identifiants des sites inclus dans votre forfait. Trois endpoints de catalogue les fournissent. Tous trois renvoient un simple tableau sans pagination.

1. Lister les pays et les codes des États

GET /countries renvoie chaque pays pris en charge avec son code ISO, un indicateur hasCity et un tableau states. Les valeurs iso servent à renseigner countryIso et stateIso lors de la création et de la mise à jour. Le Python SDK expose cette fonctionnalité via client.countries() et le Node SDK via client.fetchCountries().

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

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

hasCity: true signifie que city est obligatoire lors de la création ; avec false, la ville que vous envoyez est ignorée. stateRequired: true signifie que stateIso est obligatoire et doit correspondre à l'un des states du pays ; avec false, omettez ce champ. hasPostalCode: true signifie que le pays utilise des codes postaux ; envoyez donc postalCode avec l'adresse. L'endpoint des pays explique chaque indicateur.

2. Trouver un identifiant de catégorie

GET /sub-categories renvoie le catalogue complet des catégories. La valeur à envoyer dans subCategoryId est databaseId, l'entier, et non id en base64. Par exemple, la catégorie Restaurants correspond à 1432. Filtrez la liste par nom dans votre propre code ; il n'existe aucun paramètre de recherche côté serveur.

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'

{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}

3. Consulter les plateformes de publication incluses dans votre forfait

GET /plan-sites liste toutes les plateformes de publication incluses dans votre forfait avec un id numérique, un url, les pays qu'elles acceptent et les pays dans lesquels elles prennent en compte hideAddress. Ces identifiants sont les seules valeurs valides pour enabledSiteIds lors de la création et submissionDisabledSiteIds lors de la mise à jour. Filtrez par pays de l'établissement pour ne proposer que les plateformes de publication qui l'accepteront.

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

Les deux tableaux de pays sont tronqués ici ; la réponse réelle peut contenir 50 codes ou plus par site. Pour une entreprise desservant une zone géographique, vérifiez également hideAddressSupportedCountries, car une plateforme de publication qui accepte le pays peut tout de même refuser une fiche sans adresse postale.

4. Mettre ces données de référence en cache

Les trois catalogues changent rarement et aucun n'utilise de pagination ; récupérez donc chacun une fois au démarrage, conservez-le en mémoire ou dans une petite table et actualisez-le à intervalles réguliers. Les appeler à chaque création consomme votre quota de requêtes sans renvoyer de nouvelles données ; avec le forfait Launch, cela représente 3 de vos 10 requêtes par minute.

Créez une table de correspondance de name en minuscules vers databaseId pour les sous-catégories, et une table de correspondance de countryIso vers states pour les pays. Validez l'adresse à l'aide du cache avant d'appeler l'opération de création, afin qu'un countryIso non pris en charge (SY10036) ou un city manquant (SY10126) soit détecté dans votre application avant l'envoi de la requête.

Étapes suivantes

• Ajouter un établissement : utilisez les subCategoryId, countryIso et identifiants de site que vous venez de rechercher.
• Mettre à jour un établissement : modifiez les catégories ou excluez des plateformes de publication avec submissionDisabledSiteIds.
• Lister les pays et États pris en charge, Lister les sous-catégories et Lister les sites du forfait : les pages de référence.