Trasforma i codici di destinazione in luoghi che i viaggiatori riconoscono. Consulta nomi delle città, dati su paese e stato, coordinate e fusi orari, oppure scarica l’elenco per alimentare la ricerca di destinazioni nel tuo prodotto di viaggio.
Invia code=NYC per ottenere New York e i suoi dati di riferimento. Sostituisci YOUR_API_KEY con la tua chiave API.
Ottieni dati geografici e demografici di singole città oppure esporta l’intero database delle città in formato JSON, XML o CSV.
EndpointGET https://content.airhex.com/api/v3.7.10/cities/
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'code=NYC'[
{
"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"
}
]Risposta JSON completa. Scorri all’interno del riquadro per vedere tutti i campi. Più sotto trovi esempi estesi in JSON e XML.
Indica almeno uno tra code, country_code, name o dump=1. Con dump=1 gli altri parametri di ricerca vengono ignorati.
| Parametro | Obbligatorio | Valore | Tipo | Predefinito | Descrizione |
|---|---|---|---|---|---|
| apikey | Sì | Qualsiasi | String | Nessuno | La tua chiave API. Richiedi una chiave API di prova gratuita. |
| code | Condizionale | AAA-ZZZ | String | Nessuno | Codice IATA di città a tre lettere |
| country_code | Condizionale | AA-ZZ | String | Nessuno | Codice paese ISO 3166-1 alfa-2 a due lettere |
| name | Condizionale | Qualsiasi | String | Nessuno | Nome della città o parte del nome per la ricerca |
| dump | Condizionale | 0 o 1 | Integer | 0 | Imposta 1 per esportare l’intero database (ignora gli altri parametri condizionali indicati sopra) |
| response_type | No | JSON, XML o CSV | String | JSON | Formato della risposta: JSON, XML o CSV (con CSV parte il download di un file) |
Ottieni identità delle città, dati geografici, immagini delle destinazioni e campi demografici. I campi con link rimandano a guide mirate con esempi e consigli di integrazione.
| Campo | Esempio | Descrizione |
|---|---|---|
| airhex_id | 5333 | Identificatore univoco e permanente del record |
| updated | 2025-10-23 05:47:19 | Data e ora dell’ultimo aggiornamento del record |
| code | NYC | Codice IATA della città a tre lettere |
| country_code | US | Codice paese ISO 3166-1 alfa-2 |
| name | New York City | Nome della città |
| state_short | NY | Abbreviazione dello stato o della provincia (solo città di US, CA e AU) |
| state_full | New York | Nome completo dello stato o della provincia (solo città di US, CA e AU) |
| latitude | 40.7143528 | Latitudine geografica del centro della città |
| longitude | -74.0059731 | Longitudine geografica del centro della città |
| city_photo | https://content.airhex.com/content/city_photos/5333.jpg | URL di un’immagine della città in licenza, utilizzabile a fini commerciali |
| timezone | America/New_York | Identificatore del fuso orario della città |
| gmt | -4 | Scostamento orario della città rispetto a GMT |
| population | 8992908 | Numero di abitanti della città |
| popularity | 39128143 | Indice relativo di popolarità (un valore più alto indica una destinazione più popolare) |
Gli esempi mostrano il record completo di New York in JSON e XML. Scegli il formato di output con response_type.
[
{
"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"
}
]<?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>
Esporta il set di dati delle città per un selettore di destinazioni locale. Conserva airhex_id e updated insieme a codici, nomi e dati di posizione.
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.csvUsa un codice paese a due lettere per creare un elenco di città di un paese specifico.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'country_code=US'Una ricerca per nome parziale può restituire più città. Confronta paese e dati dello stato disponibili prima di scegliere una destinazione.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'name=New York'Usa i nomi delle città, il contesto del paese e i valori di popolarità per ordinare i suggerimenti nella tua ricerca di destinazioni.
Usa le foto in licenza disponibili per le città per illustrare schede e guide delle destinazioni.
Supporta le ricerche a livello di città insieme ai singoli aeroporti, con un’etichetta chiara per ogni opzione.
Sì. Usa popularity come segnale relativo di ordinamento nella tua applicazione: valori più alti indicano una destinazione più popolare. Combinalo con la tua corrispondenza testuale e con il contesto di posizione. Il campo non fornisce raccomandazioni personalizzate né un algoritmo completo di autocompletamento.
Il campo city_photo fornisce gli URL delle immagini di destinazione in licenza disponibili, per uso commerciale nell’ambito della tua licenza GEO Essentials. La copertura non è totale: verifica che l’URL sia valorizzato e prevedi un’immagine di riserva per le città senza foto. Usa le immagini nei limiti dei diritti d’uso concordati per il tuo prodotto.
Airhex raccoglie e verifica dati geografici da più fonti e li controlla ogni giorno. Quando importi i record delle città, conserva airhex_id e updated e aggiorna periodicamente il tuo elenco locale. Il controllo quotidiano non significa che ogni campo di ogni città cambi ogni giorno.
Sì, con una licenza GEO Essentials adeguata. Usa dump=1 e response_type per esportare in JSON, XML o CSV. Conserva airhex_id e updated e aggiorna periodicamente i tuoi record locali.
No. Usa l’API aeroporti con city_code per ottenere i record degli aeroporti associati. Verifica come il tuo fornitore di voli gestisce le ricerche a livello di città prima di offrire l’opzione “Tutti gli aeroporti”.
La ricerca per nome supporta la corrispondenza parziale. Confronta name, country_code e i campi dello stato disponibili invece di scegliere automaticamente il primo risultato.
state_short e state_full valgono per le città degli Stati Uniti, del Canada e dell’Australia. Gestisci i valori vuoti e usa il nome della città e il paese come contesto di visualizzazione di base.
Usa code, ad esempio code=NYC. L’API città non usa iata come parametro di ricerca.
Usa timezone insieme al timestamp pertinente e alle regole dei fusi orari in vigore. Non trattare lo scostamento gmt come uno scostamento fisso valido per ogni data.
L’elenco fornisce dati di riferimento sulle destinazioni. Non indica copertura delle rotte, tariffe o disponibilità: questi dati vanno richiesti al tuo fornitore di prenotazioni.
Crea suggerimenti di destinazione più chiari e schede città più ricche con codici città, dati di popolarità e le foto in licenza disponibili.