Transforme códigos de destino em locais que os viajantes reconhecem. Obtenha nomes de cidades, dados de país e de estado, coordenadas e fusos horários, ou descarregue o diretório para alimentar a pesquisa de destinos no seu produto de viagens.
Envie code=NYC para obter Nova Iorque e os respetivos dados de referência. Substitua YOUR_API_KEY pela chave atribuída.
Obtenha dados geográficos e demográficos de cidades concretas ou exporte toda a base de dados de cidades em JSON, XML ou 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"
}
]Resposta JSON completa. Desloque-se dentro do painel para ver todos os campos. Mais abaixo encontra exemplos expandidos em JSON e XML.
Indique pelo menos um dos parâmetros code, country_code, name ou dump=1. Com dump=1, os restantes parâmetros de consulta são ignorados.
| Parâmetro | Obrigatório | Valor | Tipo | Predefinição | Descrição |
|---|---|---|---|---|---|
| apikey | Sim | Qualquer | String | Nenhum | A sua chave de API atribuída. Obter chave de API de teste gratuita. |
| code | Condicional | AAA-ZZZ | String | Nenhum | Código IATA de cidade de três letras |
| country_code | Condicional | AA-ZZ | String | Nenhum | Código de país de duas letras ISO 3166-1 Alpha-2 |
| name | Condicional | Qualquer | String | Nenhum | Nome da cidade ou parte do nome para a pesquisa |
| dump | Condicional | 0 ou 1 | Integer | 0 | Defina 1 para exportar toda a base de dados (ignora os outros parâmetros condicionais acima) |
| response_type | Não | JSON, XML ou CSV | String | JSON | Formato da resposta: JSON, XML ou CSV (CSV inicia a descarga de um ficheiro) |
Obtenha identidades de cidades, dados geográficos, imagens de destinos e campos demográficos. Os campos com ligação abrem guias específicos com exemplos e conselhos de integração.
| Campo | Exemplo | Descrição |
|---|---|---|
| airhex_id | 5333 | Identificador único e permanente do registo |
| updated | 2025-10-23 05:47:19 | Data e hora da última atualização do registo |
| code | NYC | Código IATA de três letras da cidade |
| country_code | US | Código de país ISO 3166-1 Alpha-2 |
| name | New York City | Nome da cidade |
| state_short | NY | Abreviatura do estado ou província (apenas cidades dos EUA, do Canadá e da Austrália) |
| state_full | New York | Nome completo do estado ou província (apenas cidades dos EUA, do Canadá e da Austrália) |
| latitude | 40.7143528 | Latitude geográfica do centro da cidade |
| longitude | -74.0059731 | Longitude geográfica do centro da cidade |
| city_photo | https://content.airhex.com/content/city_photos/5333.jpg | URL de uma imagem da cidade licenciada e de utilização comercial |
| timezone | America/New_York | Identificador de fuso horário da cidade |
| gmt | -4 | Desvio horário da cidade em relação ao GMT |
| population | 8992908 | Número de habitantes da cidade |
| popularity | 39128143 | Índice de popularidade relativa (um valor mais alto indica um destino mais popular) |
Estes exemplos mostram o registo completo de Nova Iorque em JSON e XML. Utilize response_type para escolher o formato de saída.
[
{
"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>
Exporte o conjunto de dados de cidades para um seletor de destinos local. Conserve airhex_id e updated juntamente com os códigos, os nomes e os dados de localização.
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.csvUtilize um código de país de duas letras para criar uma lista de cidades específica de um país.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'country_code=US'Uma pesquisa parcial por nome pode devolver várias cidades. Compare o país e os dados de estado disponíveis antes de escolher um destino.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'name=New York'Utilize nomes de cidades, contexto de país e valores de popularidade para ordenar as sugestões na sua própria pesquisa de destinos.
Utilize as fotografias de cidades licenciadas disponíveis para ilustrar cartões de destinos e guias.
Ofereça pesquisas ao nível da cidade a par de aeroportos individuais, com uma etiqueta clara para cada opção.
Sim. Utilize popularity como sinal relativo de ordenação na sua aplicação; valores mais altos indicam um destino mais popular. Combine-o com a sua própria correspondência de texto e com o contexto de localização. O campo não fornece recomendações personalizadas nem um algoritmo completo de preenchimento automático.
O campo city_photo disponibiliza os URLs das imagens de destinos licenciadas existentes, para utilização comercial no âmbito da sua licença GEO Essentials. A cobertura não é universal: verifique se existe um URL preenchido e preveja uma alternativa para as cidades sem imagem. Utilize as imagens dentro dos direitos de utilização acordados para o seu produto.
A Airhex agrega e verifica dados geográficos de várias fontes e revê-os diariamente. Ao importar registos de cidades, conserve airhex_id e updated e atualize periodicamente o seu diretório local. A revisão diária não significa que todos os campos de cada cidade mudem todos os dias.
Sim, com uma licença GEO Essentials adequada. Utilize dump=1 e response_type para exportar em JSON, XML ou CSV. Conserve airhex_id e updated e atualize periodicamente os seus registos locais.
Não. Utilize a API de aeroportos com city_code para obter os registos de aeroportos associados. Confirme como o seu fornecedor de voos trata as pesquisas ao nível da cidade antes de oferecer a opção “todos os aeroportos”.
As pesquisas por nome admitem correspondências parciais. Compare name, country_code e os campos de estado disponíveis, em vez de selecionar automaticamente o primeiro resultado.
state_short e state_full aplicam-se a cidades dos Estados Unidos, do Canadá e da Austrália. Trate os valores vazios e utilize o nome da cidade e o país como contexto de apresentação básico.
Utilize code, por exemplo code=NYC. A API de cidades não utiliza iata como parâmetro de consulta.
Utilize timezone com a data e hora em causa e as regras de fuso horário em vigor. Não trate o desvio GMT como um desvio fixo para todas as datas.
O diretório fornece dados de referência de destinos. Não determina a cobertura de rotas, as tarifas nem a disponibilidade; obtenha essas informações junto do seu fornecedor de reservas.
Crie sugestões de destinos mais claras e apresentações de cidades mais ricas com códigos de cidade, dados de popularidade e fotografias licenciadas disponíveis.