🏠 Addok

A blazing fast address search engine. Made for addresses, optimized for addresses, nothing but addresses.

Addok is a powerful geocoding engine that indexes your address data and exposes it through a clean HTTP API. Built with performance in mind, it handles typos, autocomplete, and filters with ease.

Requirements: Python 3.9–3.14 • Redis 7.2–8.0

✨ Features

• 🚀 Fast: Handles thousands of requests per second
• 🔍 Smart search: Fuzzy matching, typo-tolerant, autocomplete
• 🌍 Geocoding & Reverse geocoding: From text to coordinates and back
• 📦 Batch processing: Import and geocode CSV files
• 🔌 Extensible: Plugin system for custom needs
• 🎯 Filtered search: Query by postcode, city, region, or custom filters
• 🗺️ Geographic bias: Prioritize results near a location
• 🛠️ Debug shell: Interactive shell for testing and debugging
• 📊 GeoJSON output: Standard compliant API responses

🎬 Quick Example

Once installed and your data imported, searching for an address is as simple as:

curl "http://localhost:7878/search/?q=baker+street+221b"

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-0.158434, 51.523767]
      },
      "properties": {
        "label": "221B Baker Street, London NW1 6XE",
        "score": 0.95,
        "housenumber": "221B",
        "street": "Baker Street",
        "postcode": "NW1 6XE",
        "city": "London"
      }
    }
  ]
}

🚀 Getting Started

Installation

pip install addok

Import your data

addok batch your_addresses.ndjson
addok ngrams

Start the server

addok serve

Your API is now running at http://localhost:7878 🎉

Check out the full documentation for detailed instructions, configuration options, and advanced features.

🔌 Plugins

Extend Addok with plugins for your specific needs:

• addok-fr: French language support
• addok-csv: Batch CSV geocoding via HTTP
• addok-trigrams: Trigram-based indexing
• addok-sqlite-store: SQLite storage backend
• addok-psql: PostgreSQL storage backend

Discover all plugins

🌟 Production Ready

Addok powers the official French national address database with:

• 26+ million addresses indexed
• ~2000 searches/second throughput
• ~15 minutes full import time

👉 See it in action with the French address database demo

💡 Learn More

• 📖 Documentation
• 🎓 Tutorial
• 💬 Community Forum (French & English welcome)
• 🐛 Report an issue

📄 License

Addok is released under the MIT License. Free to use, modify, and distribute.