// docs

KAYAK Flights Search

Extrai resultados de voos do KAYAK Brasil por aeroporto de origem/destino, datas e passageiros. A API usa o fluxo mobile do KAYAK, com sessão, replay e polling, retornando tarifas, segmentos, fornecedores e status da busca em JSON estruturado.

Tempo de resposta: Em algumas execuções, esta API pode levar até 1 minuto para responder. Isso é normal para este endpoint. Aguarde a conclusão da requisição e tenha paciência.

Nota importante: alguns campos podem retornar null em produção, dependendo da página de origem. Nesta documentação, os exemplos de output são preenchidos intencionalmente com valores não nulos para facilitar integração.

Quando a entidade consultada não existe na origem, o extract e a tool MCP retornam 200 com data: null e notFound: true. Esse caso é tratado como resposta concluída, não como erro de servidor.

Chamada HTTP

cURL
curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "kayak.com.br",
  "type": "plp",
  "from": "GRU",
  "to": "GIG",
  "departureDate": "2026-06-20",
  "returnDate": "2026-06-27",
  "numAdults": 1,
  "numChildren": 0,
  "numInfants": 0,
  "lang": "pt-BR",
  "currency": "BRL"
}'

Chamada MCP

A mesma seam também aparece no MCP hospedado como uma tool dedicada. Os argumentos reaproveitam os campos do extract, mas target e type já ficam fixos pela tool.

Ver guia completo do MCP

Endpoint

POST /v1/mcp

Tool name

kayak_com_br_plp

Auth

Bearer ou X-API-Key

kayak_com_br_plp tools/call
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "kayak_com_br_plp",
    "arguments": {
      "from": "GRU",
      "to": "GIG",
      "departureDate": "2026-06-20",
      "returnDate": "2026-06-27",
      "numAdults": 1,
      "numChildren": 0,
      "numInfants": 0,
      "lang": "pt-BR",
      "currency": "BRL",
      "executionId": "exec_example_123"
    }
  }
}

Possibilidades de input

Campos suportados nesta API do POST /v1/extract, com regras específicas de obrigatoriedade e condicionais.

Campo Tipo Status Regra Default Exemplo
url
URL alvo da extração. Para alguns PLPs pode ser omitida quando a API monta a URL a partir de outros campos.
string (URL) Opcional Opcional. Quando informado, deve ser uma URL publica do KAYAK Brasil em kayak.com.br com rota /flights/ORIGEM-DESTINO/YYYY-MM-DD[/YYYY-MM-DD]. Sem URL, envie from, to e departureDate. - https://www.mercadolivre.com.br/p/MLB123456
from
Codigo IATA do aeroporto de origem para busca PLP da Decolar, GOL, LATAM, KAYAK, MaxMilhas e 123Milhas.
string (IATA 3 letras) Obrigatório Codigo IATA do aeroporto de origem com 3 letras (ex: GRU). Obrigatorio quando url nao for enviada. - GRU
to
Codigo IATA do aeroporto de destino para busca PLP da Decolar, GOL, LATAM, KAYAK, MaxMilhas e 123Milhas.
string (IATA 3 letras) Obrigatório Codigo IATA do aeroporto de destino com 3 letras (ex: GIG). Obrigatorio quando url nao for enviada. - GIG
departureDate
Data de saida para busca PLP da ClickBus, Decolar, GOL, LATAM, KAYAK, MaxMilhas e 123Milhas.
string (YYYY-MM-DD) Obrigatório Data de ida no formato YYYY-MM-DD. Obrigatoria quando url nao for enviada. - 2026-05-17
returnDate
Data de retorno opcional para busca PLP da ClickBus, Decolar, GOL, LATAM, KAYAK, MaxMilhas e 123Milhas.
string (YYYY-MM-DD) Opcional Data de volta no formato YYYY-MM-DD. Deve ser maior ou igual a departureDate. - 2026-05-20
target
Fonte alvo da extração.
enum Obrigatório Sempre obrigatorio e deve ser kayak.com.br. - mercadolivre.com.br
type
Tipo da extração: pdp, idp, plp, quote, review ou places.
enum Obrigatório Sempre obrigatorio e deve ser plp. - pdp
page
Paginacao. Em PLP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0.
integer Opcional Numero da pagina de resultados, iniciando em 1. 1 2
numAdults
Quantidade de adultos para Booking, Airbnb, Hoteis.com, Decolar, GOL e LATAM.
integer (1-30) Opcional Quantidade de adultos. Deve ser inteiro entre 1 e 9. 1 2
numChildren
Quantidade de crianças para Booking, Hoteis.com, Decolar, GOL e LATAM.
integer (0-30) Opcional Quantidade de criancas. Deve ser inteiro entre 0 e 9. 0 0
numInfants
Quantidade de bebês para GOL e LATAM PLP. Deve ser menor ou igual à quantidade de adultos.
integer (0-9) Opcional Quantidade de bebes de colo. Deve ser inteiro entre 0 e 9 e menor ou igual a numAdults. 0 0
lang
Idioma para Booking (default no backend: pt-br).
string (ll ou ll-cc) Opcional Idioma aceito pelo KAYAK no formato ll ou ll-CC. O default da GeckoAPI para este endpoint e pt-BR. pt-BR pt-br
currency
Moeda para Booking (default no backend: BRL).
string (ISO 4217) Opcional Moeda com 3 letras. O default da GeckoAPI para este endpoint e BRL. BRL BRL

Exemplos de request

Busca KAYAK - ida e volta

Busca round-trip no KAYAK Brasil com defaults pt-BR e BRL.

Busca KAYAK - ida e volta
{
  "target": "kayak.com.br",
  "type": "plp",
  "from": "GRU",
  "to": "GIG",
  "departureDate": "2026-06-20",
  "returnDate": "2026-06-27",
  "numAdults": 1,
  "numChildren": 0,
  "numInfants": 0,
  "lang": "pt-BR",
  "currency": "BRL"
}

Busca KAYAK por URL

Busca usando uma URL publica de flights do KAYAK Brasil.

Busca KAYAK por URL
{
  "target": "kayak.com.br",
  "type": "plp",
  "url": "https://www.kayak.com.br/flights/GRU-GIG/2026-06-20/2026-06-27",
  "lang": "pt-BR",
  "currency": "BRL"
}

Schema de response (leaf paths)

Mapa de paths de saída com tipo esperado para esta API.

responseSchema
{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "data.source": "string",
  "data.type": "string",
  "data.parser": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.pollUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.searchType": "string (ONE_WAY | ROUND_TRIP)",
  "data.from": "string",
  "data.to": "string",
  "data.departureDate": "string (YYYY-MM-DD)",
  "data.returnDate": "string | null",
  "data.numAdults": "number",
  "data.numChildren": "number",
  "data.numInfants": "number",
  "data.lang": "string",
  "data.currency": "string",
  "data.searchId": "string | null",
  "data.status": "string | null",
  "data.success": "boolean",
  "data.complete": "boolean",
  "data.totalResults": "number",
  "data.listedResults": "number",
  "data.filteredCount": "number | null",
  "data.page": "number",
  "data.pageSize": "number",
  "data.pollsPerformed": "number",
  "data.cheapestPrice.currency": "string | null",
  "data.cheapestPrice.amount": "number | null",
  "data.cheapestPrice.localizedPrice": "string | null",
  "data.airports[].code": "string",
  "data.airlines[].code": "string",
  "data.airlines[].name": "string | null",
  "data.providers[].code": "string",
  "data.providers[].displayName": "string | null",
  "data.items[].position": "number",
  "data.items[].resultId": "string | null",
  "data.items[].price.amount": "number | null",
  "data.items[].price.localizedPrice": "string | null",
  "data.items[].legs[].origin": "string | null",
  "data.items[].legs[].destination": "string | null",
  "data.items[].legs[].durationMinutes": "number | null",
  "data.items[].legs[].stops": "number | null",
  "data.items[].legs[].segments[].flightNumber": "string | null",
  "data.items[].bookingOptions[].providerName": "string | null",
  "data.items[].bookingOptions[].totalPrice.localizedPrice": "string | null"
}

Exemplo de response

responseExample
{
  "requestId": "99999999-1111-4111-8111-999999999999",
  "executionId": "99999999-2222-4222-8222-999999999999",
  "data": {
    "source": "kayak.com.br",
    "type": "plp",
    "parser": "kayak_android_poll",
    "url": "https://www.kayak.com.br/flights/GRU-GIG/2026-06-20/2026-06-27",
    "requestUrl": "https://www.kayak.com.br/flights/GRU-GIG/2026-06-20/2026-06-27",
    "pollUrl": "https://www.kayak.com.br/i/api/search/v2/flights/poll",
    "extractedAt": "2026-05-14T15:00:00.000Z",
    "searchType": "ROUND_TRIP",
    "from": "GRU",
    "to": "GIG",
    "departureDate": "2026-06-20",
    "returnDate": "2026-06-27",
    "numAdults": 1,
    "numChildren": 0,
    "numInfants": 0,
    "lang": "pt-BR",
    "currency": "BRL",
    "searchId": "kayak-search-id",
    "status": "complete",
    "success": true,
    "complete": true,
    "totalResults": 1111,
    "listedResults": 15,
    "filteredCount": 0,
    "page": 1,
    "pageSize": 15,
    "pollsPerformed": 2,
    "cheapestPrice": {
      "currency": "BRL",
      "amount": 372,
      "localizedPrice": "R$ 372"
    },
    "airports": [
      {
        "code": "GRU",
        "cityCode": "SAO",
        "cityName": "Sao Paulo",
        "displayName": "Guarulhos Intl",
        "fullDisplayName": "Sao Paulo Guarulhos Intl"
      }
    ],
    "airlines": [
      {
        "code": "G3",
        "name": "GOL",
        "logoUrl": "https://content.r9cdn.net/rimg/provider-logos/airlines/v/G3.png"
      }
    ],
    "providers": [
      {
        "code": "123milhas",
        "displayName": "123Milhas",
        "logoUrl": "https://content.r9cdn.net/rimg/provider-logos/airlines/v/123milhas.png"
      }
    ],
    "items": [
      {
        "position": 1,
        "resultId": "result-1",
        "tripId": "trip-1",
        "type": "core",
        "viewRank": 1,
        "shareableId": "share-1",
        "shareableUrl": "https://www.kayak.com.br/flights/GRU-GIG/2026-06-20/2026-06-27",
        "isBest": true,
        "isCheapest": true,
        "isCheapestDirect": true,
        "isFeatured": false,
        "hasHackerFares": false,
        "price": {
          "currency": "BRL",
          "amount": 372,
          "localizedPrice": "R$ 372"
        },
        "totalBookingOptions": 3,
        "totalDistinctFares": 1,
        "legs": [
          {
            "id": "leg-1",
            "origin": "GRU",
            "destination": "GIG",
            "departure": "2026-06-20T06:00:00",
            "arrival": "2026-06-20T07:05:00",
            "durationMinutes": 65,
            "stops": 0,
            "airlineCodes": [
              "G3"
            ],
            "segments": [
              {
                "id": "segment-1",
                "origin": "GRU",
                "destination": "GIG",
                "departure": "2026-06-20T06:00:00",
                "arrival": "2026-06-20T07:05:00",
                "durationMinutes": 65,
                "airlineCode": "G3",
                "airlineName": "GOL",
                "flightNumber": "1234",
                "equipmentTypeName": "Boeing 737",
                "cabinCode": "Y",
                "cabinDisplay": "Economy",
                "seatsRemaining": 3
              }
            ]
          }
        ],
        "bookingOptions": [
          {
            "bookingId": "booking-1",
            "providerCode": "123milhas",
            "providerName": "123Milhas",
            "price": {
              "currency": "BRL",
              "amount": 372,
              "localizedPrice": "R$ 372"
            },
            "totalPrice": {
              "currency": "BRL",
              "amount": 372,
              "localizedPrice": "R$ 372"
            },
            "basePrice": {
              "currency": "BRL",
              "amount": 372,
              "localizedPrice": "R$ 372"
            },
            "rawPrice": {
              "currency": "BRL",
              "amount": 372,
              "localizedPrice": "R$ 372"
            },
            "countryName": "Brasil",
            "bookingUrl": "https://www.kayak.com.br/book/flight",
            "universalLinkUrl": "kayak://book/flight",
            "isDirect": false
          }
        ]
      }
    ]
  }
}

Referência completa de campos

Path Tipo Descrição Exemplo
data.airlines[].code string Codigo da companhia aerea. G3
data.airlines[].name string | null Nome da companhia aerea, quando informado. GOL
data.airports[].code string Codigo IATA do aeroporto referenciado. GRU
data.cheapestPrice.amount number | null Valor numerico da menor tarifa. 372
data.cheapestPrice.currency string | null Moeda da menor tarifa. BRL
data.cheapestPrice.localizedPrice string | null Texto de preco localizado da menor tarifa. R$ 372
data.complete boolean Indica se o KAYAK marcou a busca como concluida. true
data.currency string Moeda usada no header x-kayak-currency-code. BRL
data.departureDate string (YYYY-MM-DD) Data de ida em YYYY-MM-DD. 2026-06-20
data.extractedAt string (iso datetime) Momento da extracao em ISO 8601. 2026-05-14T15:00:00.000Z
data.filteredCount number | null Quantidade de resultados filtrados, quando o KAYAK informa esse dado. 0
data.from string Aeroporto IATA de origem. GRU
data.items[].bookingOptions[].providerName string | null Nome do fornecedor da opcao de compra. 123Milhas
data.items[].bookingOptions[].totalPrice.localizedPrice string | null Texto localizado do preco total da opcao de compra. R$ 372
data.items[].legs[].destination string | null Aeroporto de destino da perna. GIG
data.items[].legs[].durationMinutes number | null Duracao da perna em minutos. 65
data.items[].legs[].origin string | null Aeroporto de origem da perna. GRU
data.items[].legs[].segments[].flightNumber string | null Numero do voo no segmento. 1234
data.items[].legs[].stops number | null Quantidade de escalas da perna. 0
data.items[].position number Posicao do item na resposta normalizada. 1
data.items[].price.amount number | null Valor numerico do preco principal. 372
data.items[].price.localizedPrice string | null Texto localizado do preco principal. R$ 372
data.items[].resultId string | null Identificador do resultado no KAYAK. result-1
data.lang string Idioma usado nos headers e no app locale. pt-BR
data.listedResults number Quantidade de itens normalizados retornados no JSON. 15
data.numAdults number Quantidade de passageiros adultos. 1
data.numChildren number Quantidade de criancas. 0
data.numInfants number Quantidade de bebes de colo. 0
data.page number Pagina solicitada. 1
data.pageSize number Quantidade de resultados solicitados por pagina. 15
data.parser string Parser usado para estruturar a resposta. kayak_android_poll
data.pollsPerformed number Numero de chamadas de polling feitas ate obter resultados. 2
data.pollUrl string Endpoint mobile do KAYAK usado para polling dos resultados. https://www.kayak.com.br/i/api/search/v2/flights/poll
data.providers[].code string Codigo interno do fornecedor no KAYAK. 123milhas
data.providers[].displayName string | null Nome publico do fornecedor. 123Milhas
data.requestUrl string URL publica usada para representar a busca. https://www.kayak.com.br/flights/GRU-GIG/2026-06-20/2026-06-27
data.returnDate string | null Data de volta em YYYY-MM-DD ou null. 2026-06-27
data.searchId string | null Identificador da busca retornado pelo KAYAK para continuar o polling. kayak-search-id
data.searchType string (ONE_WAY | ROUND_TRIP) ONE_WAY quando nao ha returnDate; ROUND_TRIP quando ha volta. ROUND_TRIP
data.source string Fonte consultada. kayak.com.br
data.status string | null Status bruto do polling do KAYAK. complete
data.success boolean Indica se a busca retornou uma resposta utilizavel. true
data.to string Aeroporto IATA de destino. GIG
data.totalResults number Total de resultados reportado pelo KAYAK. 1111
data.type string Tipo da API executada. plp
data.url string URL publica canonica da busca KAYAK. https://www.kayak.com.br/flights/GRU-GIG/2026-06-20/2026-06-27
executionId string (uuid) Identificador idempotente da execucao. 99999999-2222-4222-8222-999999999999
requestId string (uuid) Identificador da requisicao no gateway da GeckoAPI. 99999999-1111-4111-8111-999999999999

Erros comuns

Respostas com notFound: true não entram nesta tabela, porque retornam sucesso HTTP 200.

Status errorCode Quando acontece
400 INVALID_PAYLOAD JSON inválido ou violação das regras de validação do payload.
401 UNAUTHORIZED Header Authorization ausente ou token/chave inválida.
402 INSUFFICIENT_CREDITS Saldo de créditos insuficiente para a API solicitada.
403 FORBIDDEN Usuário sem acesso ou API temporariamente desabilitada.
409 EXECUTION_CONFLICT executionId conflita com uma execução em estado incompatível.
429 RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS Limite de taxa ou limite de requisições em voo excedido.
5xx UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_INVOCATION_FAILED / WORKER_FUNCTION_ERROR / WORKER_INVALID_RESPONSE / INTERNAL_ERROR Falha de servidor no worker, provider/proxy ou gateway. Nesses casos os créditos são estornados automaticamente.