API de países: base de dados de países e códigos

Mantenha a informação de países coerente em todo o seu produto de viagens. Associe os identificadores de país a nomes e dados geográficos, ou descarregue o diretório para filtros de destinos, formulários e relatórios.

Chave de API de testeVer exemplo
  • Consulta por código ISO Alpha-2, Alpha-3 e numérico
  • Registos individuais ou exportação completa
  • JSON, XML e CSV

Consultar um país pelo código

Envie code2=US para obter os Estados Unidos e os respetivos dados de referência. Substitua YOUR_API_KEY pela chave atribuída.

Descrição do endpoint

Este endpoint devolve os dados de um país ou exporta toda a base de dados de países num ficheiro JSON, XML ou CSV.

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

Pedido · cURL

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

Resposta · JSON

[
    {
        "airhex_id": "735",
        "updated": "2026-06-16 14:48:41",
        "iso": "840",
        "code2": "US",
        "code3": "USA",
        "name": "United States",
        "capital_code": "WAS",
        "currency_code": "USD",
        "region": "North America",
        "continent_code": "NA",
        "population": "310232863",
        "phone_code": "+1"
    }
]

Resposta JSON completa. Desloque-se dentro do painel para ver todos os campos. Mais abaixo encontra exemplos expandidos em JSON e XML.

Parâmetros do pedido

Indique pelo menos um dos parâmetros code2, code3, iso, 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.
code2 Condicional AA-ZZ String Nenhum Código de país de duas letras ISO 3166-1 Alpha-2
code3 Condicional AAA-ZZZ String Nenhum Código de país de três letras ISO 3166-1 Alpha-3
iso Condicional Qualquer Int Nenhum Código numérico de país ISO 3166-1
name Condicional Qualquer String Nenhum Nome do país 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)

Campos da resposta

Obtenha identificadores de país, nomes e dados geográficos de referência a partir do mesmo registo. Utilize os campos documentados para manter coerentes as associações de países nos seus sistemas.

Campo Exemplo Descrição
airhex_id 735 Identificador único e permanente do registo
updated 2026-06-16 14:48:41 Data e hora da última atualização do registo
iso 840 Código numérico de país ISO 3166-1
code2 US Código de país de duas letras ISO 3166-1 Alpha-2
code3 USA Código de país de três letras ISO 3166-1 Alpha-3
name United States Nome do país
capital_code WAS Código IATA de três letras da capital do país
currency_code USD Código ISO de moeda de três letras
region North America Região geográfica do país
continent_code NA Código de continente de duas letras
population 310232863 Número de habitantes do país
phone_code +1 Indicativo telefónico internacional do país

Exemplos de resposta completos

Estes exemplos mostram o registo completo dos Estados Unidos em JSON e XML. Utilize response_type para escolher o formato de saída.

Resposta · JSON

[
    {
        "airhex_id": "735",
        "updated": "2026-06-16 14:48:41",
        "iso": "840",
        "code2": "US",
        "code3": "USA",
        "name": "United States",
        "capital_code": "WAS",
        "currency_code": "USD",
        "region": "North America",
        "continent_code": "NA",
        "population": "310232863",
        "phone_code": "+1"
    }
]

Resposta · XML

<?xml version="1.0" encoding="UTF-8"?>
<countries>
 <country>
  <airhex_id>735</airhex_id>
  <updated>2026-06-16 14:48:41</updated>
  <iso>840</iso>
  <code2>US</code2>
  <code3>USA</code3>
  <name>United States</name>
  <capital_code>WAS</capital_code>
  <currency_code>USD</currency_code>
  <region>North America</region>
  <continent_code>NA</continent_code>
  <population>310232863</population>
  <phone_code>+1</phone_code>
 </country>
</countries>

Tarefas de implementação mais comuns

Descarregar o diretório de países

Exporte os países em CSV para os seus formulários locais e filtros de destinos. Conserve airhex_id e updated ao importar os registos.

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

Fazer corresponder um código de país de três letras

Utilize code3 quando um fornecedor enviar identificadores Alpha-3 e leia na resposta o valor code2 correspondente.

curl --get 'https://content.airhex.com/api/v3.7.10/countries/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'code3=USA'

Pesquisar pelo nome do país

Utilize name para pesquisar pelo nome completo ou parcial. Reveja as identidades devolvidas antes de escolher uma correspondência.

curl --get 'https://content.airhex.com/api/v3.7.10/countries/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'name=United States'

O que pode criar

Criar seletores de países coerentes

Utilize nomes de países reconhecíveis e identificadores normalizados em formulários e filtros de destinos.

Acrescentar contexto útil sobre o destino

Inclua a moeda e o indicativo telefónico em guias de países e em ecrãs de planeamento de viagens.

Ligar os dados geográficos em todo o produto

Associe países a registos de cidades, aeroportos e fornecedores para filtrar e elaborar relatórios de forma coerente.

Perguntas frequentes

Como se relacionam os dados de países com os de aeroportos e cidades?

As APIs de cidades e de aeroportos devolvem country_code como identificador ISO de duas letras. Faça corresponder esse valor a code2 na API de países para obter os nomes dos países e outros dados de referência. Conserve o airhex_id próprio de cada registo como identidade.

Que dados de país posso mostrar no meu produto de viagens?

Além dos nomes dos países e dos identificadores ISO, a resposta inclui currency_code, phone_code, capital_code, region, continent_code e population. Utilize-os para dar contexto ao destino e para o agrupamento geográfico. Os códigos de moeda são valores de referência, não taxas de câmbio; capital_code é um identificador, não um nome para apresentar.

Como são mantidos atualizados os dados de países?

A Airhex agrega e verifica dados geográficos de várias fontes e revê-os diariamente. 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 país mudem todos os dias.

Que formatos de código de país posso consultar?

Utilize code2 para os códigos ISO Alpha-2 de duas letras, code3 para os códigos Alpha-3 de três letras ou iso para os códigos numéricos ISO de país. A resposta inclui os identificadores correspondentes do país.

Posso encontrar um país pelo nome?

Sim. O parâmetro name admite correspondências parciais. Compare os nomes e os códigos de país devolvidos antes de escolher um registo.

Posso descarregar e guardar o diretório de países?

Sim, com uma licença GEO Essentials adequada. Defina dump=1 e escolha JSON, XML ou CSV com response_type. Conserve airhex_id e updated e atualize periodicamente a sua cópia local.

Esta API fornece requisitos de visto ou de entrada?

Não. Fornece dados de referência de países. Para consultar as regras de visto em vigor, os requisitos de entrada e as restrições de viagem, recorra a um especialista adequado ou a uma fonte oficial.

Informação de países coerente em cada viagem

Ligue filtros de destinos, formulários de viajantes e guias de países a códigos de país mantidos e a dados úteis sobre os destinos.

Chave de API de testePedir orçamento →