Metadata-Version: 2.4
Name: addok
Version: 1.3.0rc1
Summary: Search engine for address. Only address.
Author-email: Yohan Boniface <yohan.boniface@data.gouv.fr>
License-Expression: MIT
Project-URL: Homepage, https://github.com/addok/addok
Keywords: address,openstreetmap,geocoding
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: falcon==4.0.2
Requires-Dist: hashids==1.3.1
Requires-Dist: editdistance==0.8.1
Requires-Dist: ngram==4.0.3
Requires-Dist: progressist==0.1.0
Requires-Dist: python-geohash==0.8.5
Requires-Dist: redis==6.4.0
Requires-Dist: unidecode==1.4.0
Requires-Dist: gnureadline==8.2.13; sys_platform == "darwin"
Provides-Extra: perf
Requires-Dist: hiredis==3.3.0; extra == "perf"
Provides-Extra: dev
Requires-Dist: pytest~=8.3; extra == "dev"
Requires-Dist: pytest-cov~=6.1; extra == "dev"
Requires-Dist: mkdocs==1.4.3; extra == "dev"
Requires-Dist: build~=1.2; extra == "dev"
Requires-Dist: twine==6.1.0; extra == "dev"
Requires-Dist: hiredis==3.3.0; extra == "dev"
Dynamic: license-file

# 🏠 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.

[![PyPi version](https://img.shields.io/pypi/v/addok.svg)](https://pypi.python.org/pypi/addok/)
[![Coverage Status](https://coveralls.io/repos/addok/addok/badge.svg?branch=main&service=github)](https://coveralls.io/github/addok/addok?branch=main)

**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:

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

```json
{
  "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

```bash
pip install addok
```

### Import your data

```bash
addok batch your_addresses.ndjson
addok ngrams
```

### Start the server

```bash
addok serve
```

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

Check out the [full documentation](http://addok.readthedocs.org/en/latest/) for detailed instructions, configuration options, and advanced features.

---

## 🔌 Plugins

Extend Addok with plugins for your specific needs:

- **[addok-fr](https://github.com/addok/addok-fr)**: French language support
- **[addok-csv](https://github.com/addok/addok-csv)**: Batch CSV geocoding via HTTP
- **[addok-trigrams](https://github.com/addok/addok-trigrams)**: Trigram-based indexing
- **[addok-sqlite-store](https://github.com/addok/addok-sqlite-store)**: SQLite storage backend
- **[addok-psql](https://github.com/addok/addok-psql)**: PostgreSQL storage backend

[Discover all plugins](http://addok.readthedocs.io/en/latest/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](http://adresse.data.gouv.fr/map) with the French address database demo

---

## 💡 Learn More

- 📖 [Documentation](http://addok.readthedocs.org/en/latest/)
- 🎓 [Tutorial](http://addok.readthedocs.org/en/latest/tutorial/)
- 💬 [Community Forum](https://forum.geocommuns.fr/c/adresses/addok-le-geocodeur/17) (French & English welcome)
- 🐛 [Report an issue](https://github.com/addok/addok/issues)

---

## 📄 License

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