API villes : base de données des villes et codes

Transformez les codes de destination en lieux que les voyageurs reconnaissent. Consultez les noms de villes, les données de pays et d'État, les coordonnées et les fuseaux horaires, ou téléchargez le répertoire pour la recherche de destinations de votre produit de voyage.

Clé d'API de testVoir l'exemple
  • Recherche par code de ville et par nom
  • Destinations par pays
  • JSON, XML et CSV

Rechercher une ville par son code

Envoyez code=NYC pour obtenir New York et ses données de référence. Remplacez YOUR_API_KEY par votre clé d'API.

Description de l'endpoint

Obtenez les données géographiques et démographiques de villes précises, ou exportez toute la base de données des villes en JSON, XML ou CSV.

Endpoint
GET https://content.airhex.com/api/v3.7.10/cities/

Requête · cURL

curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'code=NYC'

Réponse · JSON

[
    {
        "airhex_id": "5333",
        "updated": "2025-10-23 05:47:19",
        "code": "NYC",
        "country_code": "US",
        "name": "New York City",
        "state_short": "NY",
        "state_full": "New York",
        "latitude": "40.7143528",
        "longitude": "-74.0059731",
        "city_photo": "https:\/\/content.airhex.com\/content\/city_photos\/5333.jpg",
        "timezone": "America\/New_York",
        "gmt": "-4",
        "population": "8992908",
        "popularity": "39128143"
    }
]

Réponse JSON complète. Faites défiler le cadre pour voir tous les champs. Des exemples détaillés en JSON et en XML figurent plus bas.

Paramètres de la requête

Indiquez au moins l'un des paramètres code, country_code, name ou dump=1. Avec dump=1, les autres paramètres de recherche sont ignorés.

Paramètre Obligatoire Valeur Type Par défaut Description
apikey Oui Tous String aucun Votre clé d'API. Obtenir une clé d'API de test gratuite.
code Conditionnel AAA-ZZZ String aucun Code IATA à trois lettres de la ville
country_code Conditionnel AA-ZZ String aucun Code pays à deux lettres selon ISO 3166-1 alpha-2
name Conditionnel Tous String aucun Nom de la ville ou partie du nom pour la recherche
dump Conditionnel 0 ou 1 Integer 0 Indiquez 1 pour exporter toute la base de données (ignore les autres paramètres conditionnels ci-dessus)
response_type Non JSON, XML ou CSV String JSON Format de la réponse : JSON, XML ou CSV (CSV lance le téléchargement d'un fichier)

Champs de la réponse

Obtenez les identifiants, les données géographiques, les images de destinations et les champs démographiques des villes. Les champs avec lien mènent à des guides avec des exemples et des conseils d'intégration.

Champ Exemple Description
airhex_id 5333 Identifiant unique et permanent de l'enregistrement
updated 2025-10-23 05:47:19 Date et heure de la dernière mise à jour de l'enregistrement
code NYC Code IATA à trois lettres de la ville
country_code US Code pays ISO 3166-1 alpha-2
name New York City Nom de la ville
state_short NY Abréviation de l'État ou de la province (villes des États-Unis, du Canada et d'Australie uniquement)
state_full New York Nom complet de l'État ou de la province (villes des États-Unis, du Canada et d'Australie uniquement)
latitude 40.7143528 Latitude géographique du centre-ville
longitude -74.0059731 Longitude géographique du centre-ville
city_photo https://content.airhex.com/content/city_photos/5333.jpg URL d'une image de la ville sous licence pour usage commercial
timezone America/New_York Identifiant de fuseau horaire de la ville
gmt -4 Décalage horaire de la ville par rapport à GMT
population 8992908 Population de la ville
popularity 39128143 Indice de popularité relatif (une valeur plus élevée indique une destination plus populaire)

Exemples de réponse complets

Ces exemples montrent l'enregistrement complet de New York en JSON et en XML. Choisissez le format de sortie avec response_type.

Réponse · JSON

[
    {
        "airhex_id": "5333",
        "updated": "2025-10-23 05:47:19",
        "code": "NYC",
        "country_code": "US",
        "name": "New York City",
        "state_short": "NY",
        "state_full": "New York",
        "latitude": "40.7143528",
        "longitude": "-74.0059731",
        "city_photo": "https:\/\/content.airhex.com\/content\/city_photos\/5333.jpg",
        "timezone": "America\/New_York",
        "gmt": "-4",
        "population": "8992908",
        "popularity": "39128143"
    }
]

Réponse · XML

<?xml version="1.0" encoding="UTF-8"?>
<cities>
 <city>
  <airhex_id>5333</airhex_id>
  <updated>2025-10-23 05:47:19</updated>
  <code>NYC</code>
  <country_code>US</country_code>
  <name>New York City</name>
  <state_short>NY</state_short>
  <state_full>New York</state_full>
  <latitude>40.7143528</latitude>
  <longitude>-74.0059731</longitude>
  <city_photo>https://content.airhex.com/content/city_photos/5333.jpg</city_photo>
  <timezone>America/New_York</timezone>
  <gmt>-4</gmt>
  <population>8992908</population>
  <popularity>39128143</popularity>
 </city>
</cities>

Tâches d'intégration courantes

Télécharger le répertoire des destinations

Exportez le jeu de données des villes pour un sélecteur de destinations local. Conservez airhex_id et updated avec les codes, les noms et les données de localisation.

curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'dump=1' \
  --data-urlencode 'response_type=CSV' \
  --output cities.csv

Trouver les destinations d'un pays

Constituez la liste des villes d'un pays donné à partir de son code pays à deux lettres.

curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'country_code=US'

Rechercher par nom de ville

Une recherche partielle par nom peut renvoyer plusieurs villes. Comparez le pays et les données d'État disponibles avant de choisir une destination.

curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'name=New York'

Ce que vous pouvez créer

Proposer des suggestions de destinations plus utiles

Classez les suggestions de votre propre recherche de destinations grâce aux noms de villes, au contexte du pays et aux valeurs de popularité.

Présenter les destinations de façon plus attrayante

Illustrez les fiches de destinations et les guides de voyage avec les photos de villes sous licence disponibles.

Relier villes et aéroports

Prenez en charge les recherches au niveau de la ville en plus des aéroports individuels, avec un libellé clair pour chaque option.

Questions fréquentes

Puis-je utiliser la popularité d'une ville pour classer les suggestions de destinations ?

Oui. Utilisez popularity comme signal de classement relatif dans votre application : plus la valeur est élevée, plus la destination est populaire. Combinez-la avec votre propre algorithme de correspondance textuelle et avec le contexte de localisation. Le champ ne fournit ni recommandations personnalisées ni algorithme de suggestion complet.

Les photos de destinations sont-elles incluses, et puis-je les utiliser à des fins commerciales ?

Le champ city_photo fournit les URL des photos de destinations sous licence lorsqu'elles existent, pour un usage commercial dans le cadre de votre licence GEO Essentials. Toutes les villes n'ont pas d'image : vérifiez que l'URL est renseignée et prévoyez une image de remplacement pour les villes sans photo. Utilisez les images dans la limite des droits d'usage convenus pour votre produit.

Comment les données des villes sont-elles tenues à jour ?

Airhex regroupe des données géographiques issues de plusieurs sources, les vérifie et les contrôle chaque jour. Lorsque vous importez des enregistrements de villes, conservez airhex_id et updated, et mettez régulièrement à jour votre répertoire local. Le contrôle quotidien ne signifie pas que chaque champ de chaque ville change tous les jours.

Puis-je stocker le répertoire des villes en local ?

Oui, avec une licence adaptée de GEO Essentials. Exportez avec dump=1 et response_type en JSON, XML ou CSV. Conservez airhex_id et updated, et mettez régulièrement à jour vos enregistrements locaux.

L'enregistrement d'une ville inclut-il tous ses aéroports ?

Non. Récupérez les enregistrements d'aéroports associés avec l'API aéroports et city_code. Vérifiez comment votre fournisseur de vols traite les recherches au niveau de la ville avant de proposer l'option « Tous les aéroports ».

Comment traiter les villes aux noms semblables ?

La recherche par nom accepte les correspondances partielles. Comparez name, country_code et les champs d'État disponibles plutôt que de retenir automatiquement le premier résultat.

Les données d'État sont-elles disponibles pour tous les pays ?

state_short et state_full s'appliquent aux villes des États-Unis, du Canada et d'Australie. Attendez-vous à des valeurs vides et utilisez le nom de la ville et le pays comme contexte d'affichage de base.

Quel paramètre accepte un code IATA de ville ?

Utilisez code, par exemple code=NYC. L'API villes n'utilise pas iata comme paramètre de recherche.

Comment utiliser les fuseaux horaires des villes ?

Utilisez timezone avec l'horodatage concerné et les règles de fuseau horaire en vigueur. Ne traitez pas le décalage gmt comme un décalage fixe valable pour n'importe quelle date.

Une ville de la liste a-t-elle des vols réservables ?

Le répertoire fournit des données de référence sur les destinations. Il n'indique ni la couverture des lignes, ni les prix, ni la disponibilité ; ces données viennent de votre fournisseur de réservations.

Aidez les voyageurs à découvrir leur prochaine destination

Proposez des suggestions de destinations plus claires et un affichage plus riche des villes grâce aux codes de ville, aux données de popularité et aux photos sous licence disponibles.

Clé d'API de testDemander un devis →