Skip to content

Kiwi Resilient SDK

What it is

The Kiwi Resilient SDK is a Python SDK and FastAPI sidecar service for searching flights via Kiwi.com's official GraphQL API. It provides both a programmatic Python client interface and a REST API wrapper, with built-in resilience features including:

  • Automatic retry with exponential backoff via tenacity
  • Response caching for development efficiency
  • Structured logging with structlog
  • Type-safe models using Pydantic
  • Browser-based token refresh using Playwright
  • Calendar price analysis with market stats and "greed scoring"

What it is not

This project does not perform web scraping, HTML parsing, or bypass rate limits. It communicates exclusively with Kiwi.com's official GraphQL API endpoint (https://api.skypicker.com/umbrella/v2/graphql) using proper API contracts. The browser automation component is used solely to obtain valid authentication headers for API requests.

Why this exists

Kiwi.com's GraphQL API requires authentication tokens that are generated by their frontend application, making direct API integration difficult for automated systems. This project provides a self-hosted solution that uses browser automation to legitimately obtain these tokens and expose a stable REST API interface. It enables developers to integrate flight search capabilities into local applications without relying on external SaaS services or managed APIs.

This tool is intended for developers building personal projects, prototypes, or internal tools who need programmatic access to flight search data with full control over the execution environment. It is not suitable for high-volume commercial applications, production travel booking systems, or use cases requiring guaranteed service level agreements—these scenarios should use Kiwi.com's official partner API instead.

Key features

  • Dual interface: Use as a Python SDK (KiwiClient) or run as a FastAPI sidecar service
  • Flexible search modes: Search (specific dates) and Explore (date ranges)
  • Return trip options: One-way, fixed return, flexible return, duration-based stays
  • Calendar analytics: Price graph data with market statistics and deal scoring
  • Token management: Background refresh loop with circuit breaker and persistent storage
  • Docker Compose ready: Includes browser service for headless Playwright execution

Quickstart

  1. Clone and install: bash git clone <repo-url> cd kiwi-resilient-sdk uv sync

  2. Run with Docker Compose: bash docker compose up --build

  3. Make your first request: bash curl -X POST http://localhost:8000/v1/flights/search \ -H "Content-Type: application/json" \ -d '{ "origin": "PRG", "destination": "LHR", "date": {"start": "2026-05-10", "type": "fixed"}, "return": {"type": "oneway"} }'

For detailed setup instructions, see the Getting Started guide.

  • API Reference: See API Documentation for full endpoint reference
  • Interactive docs: Swagger UI at http://localhost:8000/docs (when running)
  • ReDoc: Available at http://localhost:8000/redoc (when running)
  • OpenAPI Schema: /openapi.json endpoint (when running)
  • Architecture: See Architecture for component overview
  • Configuration: See Configuration for environment variables
  • Troubleshooting: See Troubleshooting for common issues