Listings APIListings API
Se connecter
GET/api/v4/countries

Répertorier les pays et les États pris en charge

Pays couverts par Listings API, États/provinces, codes ISO pour créer/modifier un établissement et champs d’adresse requis ou vérifiés par pays.

Nécessite une clé API. Consultez Authentification pour le format de l’en-tête et la rotation des clés.

Paramètres

Cet endpoint ne prend aucun paramètre.

Réponses

200List of supported countries, each with its states and ISO codes. The live response is trimmed here to the United States, with three of its states.
Response
{  "data": {    "supportedCountries": [      {        "databaseId": 233,        "hasCity": true,        "id": "Q291bnRyeToyMzM=",        "iso": "US",        "name": "United States",        "hasPostalCode": true,        "stateRequired": true,        "states": [          { "countryId": 233, "id": "3542", "iso": "CA", "name": "California" },          { "countryId": 233, "id": "3537", "iso": "NY", "name": "New York" },          { "countryId": 233, "id": "3524", "iso": "TX", "name": "Texas" }        ]      }    ]  }}
401Unauthenticated, missing or invalid API key.
500Internal server error.

Renvoie le catalogue complet des pays et de leurs subdivisions (États, provinces, territoires) pris en charge par Listings API pour les données des établissements. Chaque entrée de pays contient son code ISO (iso), un id Relay, un databaseId numérique, un tableau states et trois indicateurs précisant comment l’adresse d’un établissement est vérifiée dans ce pays. Chaque État possède son propre iso et un id numérique. Pour les pays que Listings API ne subdivise pas, le tableau states renvoyé est vide.

Règles relatives aux adresses par pays

Indicateurtruefalse
hasCitycity est obligatoire lors de la création (SY10126).Le système d’adressage du pays ne comporte pas de niveau correspondant à la ville. Toute valeur city que vous envoyez est supprimée.
stateRequiredstateIso est obligatoire et doit correspondre à l’une des valeurs states du pays (SY10010).N’incluez pas stateIso. Certains de ces pays répertorient tout de même des valeurs states ; toute valeur que vous envoyez est enregistrée sans être vérifiée.
hasPostalCodeLe pays utilise des codes postaux. Envoyez postalCode avec l’adresse.Le pays ne dispose pas de système de codes postaux. N’incluez pas postalCode.

postalCode est facultatif dans tous les pays, mais envoyez-le chaque fois que hasPostalCode vaut true : certaines plateformes de publication en ont besoin pour positionner le repère sur la carte. Toute valeur que vous envoyez est vérifiée par rapport au format du pays (SY10014). Lorsque hideAddress: true est défini sur l’établissement, les vérifications de la ville et de l’État sont ignorées.

Cas d’utilisation : remplir les listes déroulantes d’adresse. Récupérez ces données une seule fois au démarrage de l’application et mettez-les en cache. Affichez le sélecteur de pays à partir de name/iso et, lorsqu’un pays est sélectionné, remplissez le sélecteur d’État à partir de son tableau states. Les valeurs iso alimentent directement les champs countryIso et stateIso des endpoints create-location et update-location.

Cas d’utilisation : valider une adresse avant de l’envoyer. Avant d’appeler create-location, vérifiez que le countryIso cible existe dans cette liste, que stateIso figure sous ce pays lorsque stateRequired vaut true et que city est renseigné lorsque hasCity vaut true. Détecter un code non pris en charge à cette étape permet d’afficher un message clair côté client plutôt que de recevoir un 400 lors de l’appel de création. La réponse complète est volumineuse (elle comprend tous les pays pris en charge) ; l’exemple ci-dessus est limité à une seule entrée. Il n’y a aucun paramètre de requête ; l’endpoint renvoie toujours l’ensemble complet.

Request
curl -X GET 'https://listingsapi.com/api/v4/countries' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground