Autocomplete de Aeroportos

A API oferece endpoints para buscar aeroportos e cidades, ideal para implementar campos de autocomplete em formulários de busca de voos.

Busca Inteligente

O sistema busca por código IATA, nome do aeroporto, cidade, estado e país. Perfeito para autocomplete com busca rápida.

POST /api/flights/consulta-aereo/aeroportos

Lista aeroportos filtrados por texto de busca.

Request

POST /api/flights/consulta-aereo/aeroportos?filtro=sao%20paulo
Authorization: Bearer sua_chave_aqui

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`filtro`	string	Não	Texto para filtrar aeroportos (busca em nome, cidade, código IATA)

Response

{
  "Success": true,
  "Message": "Aeroportos encontrados com sucesso",
  "Data": [
    {
      "Iata": "GRU",
      "Aeroporto": "Aeroporto Internacional de São Paulo/Guarulhos",
      "Cidade": "São Paulo",
      "Estado": "SP",
      "Pais": "Brasil",
      "Latitude": -23.4356,
      "Longitude": -46.4731
    },
    {
      "Iata": "CGH",
      "Aeroporto": "Aeroporto de Congonhas",
      "Cidade": "São Paulo",
      "Estado": "SP",
      "Pais": "Brasil",
      "Latitude": -23.6261,
      "Longitude": -46.6564
    },
    {
      "Iata": "VCP",
      "Aeroporto": "Aeroporto Internacional de Viracopos",
      "Cidade": "Campinas",
      "Estado": "SP",
      "Pais": "Brasil",
      "Latitude": -23.0074,
      "Longitude": -47.1345
    }
  ]
}

Campos da Resposta

Campo	Tipo	Descrição
`Iata`	string	Código IATA do aeroporto (3 letras)
`Aeroporto`	string	Nome completo do aeroporto
`Cidade`	string	Cidade onde o aeroporto está localizado
`Estado`	string	Estado/província (quando aplicável)
`Pais`	string	País do aeroporto
`Latitude`	number	Coordenada de latitude
`Longitude`	number	Coordenada de longitude

POST /api/flights/consulta-aereo/pesquisar-aeroporto

Busca aeroportos específicos por códigos IATA.

Request

{
  "Iatas": ["GRU", "MIA", "CDG"],
  "PegarFotos": false
}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`Iatas`	array	Sim	Lista de códigos IATA para buscar
`PegarFotos`	boolean	Não	Se deve incluir URLs de fotos (padrão: false)

Response

{
  "Success": true,
  "Message": "Aeroportos encontrados",
  "Data": [
    {
      "Iata": "GRU",
      "Aeroporto": "Aeroporto Internacional de São Paulo/Guarulhos",
      "Cidade": "São Paulo",
      "Estado": "SP",
      "Pais": "Brasil",
      "Latitude": -23.4356,
      "Longitude": -46.4731,
      "FotoUrl": "https://..."
    },
    {
      "Iata": "MIA",
      "Aeroporto": "Miami International Airport",
      "Cidade": "Miami",
      "Estado": "FL",
      "Pais": "Estados Unidos",
      "Latitude": 25.7959,
      "Longitude": -80.2870,
      "FotoUrl": "https://..."
    }
  ]
}

Exemplos de Implementação

React com TypeScript

import { useState, useEffect } from 'react';

interface Airport {
  Iata: string;
  Aeroporto: string;
  Cidade: string;
  Estado: string;
  Pais: string;
}

function AirportAutocomplete() {
  const [query, setQuery] = useState('');
  const [airports, setAirports] = useState<Airport[]>([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (query.length < 2) {
      setAirports([]);
      return;
    }

    const timer = setTimeout(async () => {
      setLoading(true);
      try {
        const response = await fetch(
          `/api/flights/consulta-aereo/aeroportos?filtro=${encodeURIComponent(query)}`,
          {
            method: 'POST',
            headers: {
              'Authorization': `Bearer ${process.env.API_KEY}`
            }
          }
        );
        
        const data = await response.json();
        if (data.Success) {
          setAirports(data.Data);
        }
      } catch (error) {
        console.error('Erro ao buscar aeroportos:', error);
      } finally {
        setLoading(false);
      }
    }, 300); // Debounce de 300ms

    return () => clearTimeout(timer);
  }, [query]);

  return (
    <div className="relative">
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Digite cidade ou aeroporto..."
        className="w-full px-4 py-2 border rounded"
      />
      
      {loading && (
        <div className="absolute top-full mt-1 w-full p-2 bg-white border rounded">
          Buscando...
        </div>
      )}
      
      {airports.length > 0 && (
        <ul className="absolute top-full mt-1 w-full bg-white border rounded shadow-lg max-h-60 overflow-auto">
          {airports.map((airport) => (
            <li
              key={airport.Iata}
              className="px-4 py-2 hover:bg-gray-100 cursor-pointer"
              onClick={() => {
                setQuery(`${airport.Iata} - ${airport.Cidade}`);
                setAirports([]);
              }}
            >
              <div className="font-semibold">
                {airport.Iata} - {airport.Cidade}
              </div>
              <div className="text-sm text-gray-600">
                {airport.Aeroporto}
              </div>
              <div className="text-xs text-gray-500">
                {airport.Estado && `${airport.Estado}, `}{airport.Pais}
              </div>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

JavaScript Vanilla

class AirportSearch {
  constructor(inputElement, apiKey) {
    this.input = inputElement;
    this.apiKey = apiKey;
    this.debounceTimer = null;
    this.resultsContainer = this.createResultsContainer();
    
    this.input.addEventListener('input', (e) => this.handleInput(e));
  }
  
  createResultsContainer() {
    const container = document.createElement('div');
    container.className = 'airport-results';
    container.style.cssText = `
      position: absolute;
      background: white;
      border: 1px solid #ccc;
      border-radius: 4px;
      max-height: 300px;
      overflow-y: auto;
      display: none;
    `;
    this.input.parentElement.appendChild(container);
    return container;
  }
  
  handleInput(event) {
    const query = event.target.value;
    
    clearTimeout(this.debounceTimer);
    
    if (query.length < 2) {
      this.hideResults();
      return;
    }
    
    this.debounceTimer = setTimeout(() => {
      this.searchAirports(query);
    }, 300);
  }
  
  async searchAirports(query) {
    try {
      const response = await fetch(
        `/api/flights/consulta-aereo/aeroportos?filtro=${encodeURIComponent(query)}`,
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${this.apiKey}`
          }
        }
      );
      
      const data = await response.json();
      
      if (data.Success && data.Data.length > 0) {
        this.showResults(data.Data);
      } else {
        this.hideResults();
      }
    } catch (error) {
      console.error('Erro ao buscar aeroportos:', error);
      this.hideResults();
    }
  }
  
  showResults(airports) {
    this.resultsContainer.innerHTML = airports.map(airport => `
      <div class="airport-item" data-iata="${airport.Iata}" style="padding: 10px; cursor: pointer;">
        <div style="font-weight: bold;">${airport.Iata} - ${airport.Cidade}</div>
        <div style="font-size: 0.9em; color: #666;">${airport.Aeroporto}</div>
        <div style="font-size: 0.8em; color: #999;">
          ${airport.Estado ? airport.Estado + ', ' : ''}${airport.Pais}
        </div>
      </div>
    `).join('');
    
    this.resultsContainer.style.display = 'block';
    
    // Adicionar event listeners
    this.resultsContainer.querySelectorAll('.airport-item').forEach(item => {
      item.addEventListener('click', () => {
        this.selectAirport(item.dataset.iata);
      });
    });
  }
  
  hideResults() {
    this.resultsContainer.style.display = 'none';
  }
  
  selectAirport(iata) {
    this.input.value = iata;
    this.hideResults();
    // Disparar evento customizado
    this.input.dispatchEvent(new CustomEvent('airportSelected', {
      detail: { iata }
    }));
  }
}

// Uso:
const searchInput = document.getElementById('airport-search');
const airportSearch = new AirportSearch(searchInput, 'sua_api_key');

searchInput.addEventListener('airportSelected', (e) => {
  console.log('Aeroporto selecionado:', e.detail.iata);
});

Dicas de UX

Melhores Práticas

Use debounce de 300ms para evitar requisições excessivas
Exiba resultados a partir de 2 caracteres digitados
Mostre código IATA, cidade e nome do aeroporto
Adicione loading state durante a busca
Feche os resultados ao clicar fora do componente

Exemplo de Exibição

┌─────────────────────────────────────────┐
│ GRU - São Paulo                         │
│ Aeroporto Internacional de SP/Guarulhos │
│ SP, Brasil                              │
├─────────────────────────────────────────┤
│ CGH - São Paulo                         │
│ Aeroporto de Congonhas                  │
│ SP, Brasil                              │
├─────────────────────────────────────────┤
│ VCP - Campinas                          │
│ Aeroporto Internacional de Viracopos    │
│ SP, Brasil                              │
└─────────────────────────────────────────┘

Principais Aeroportos Brasileiros

Para referência rápida:

IATA	Aeroporto	Cidade
GRU	Guarulhos	São Paulo
CGH	Congonhas	São Paulo
GIG	Galeão	Rio de Janeiro
SDU	Santos Dumont	Rio de Janeiro
BSB	Presidente Juscelino Kubitschek	Brasília
CNF	Tancredo Neves	Belo Horizonte
SSA	Deputado Luís Eduardo Magalhães	Salvador
REC	Guararapes	Recife
FOR	Pinto Martins	Fortaleza
CWB	Afonso Pena	Curitiba
POA	Salgado Filho	Porto Alegre
FLN	Hercílio Luz	Florianópolis

Erros Comuns

Código	Erro	Solução
`401`	`Unauthorized`	Verifique sua API key
`400`	`Invalid IATA code`	Use códigos IATA de 3 letras
`404`	`Airport not found`	Código IATA não existe
`429`	`Rate limit exceeded`	Reduza frequência de requisições

Performance

Latência típica: 50-200ms
Cache recomendado: 24 horas (dados de aeroportos mudam raramente)
Rate limit: Compartilhado com outros endpoints (conforme seu plano)

Autocomplete de Aeroportos

On this page