🌍 Geocoding API

A FastAPI-based reverse geocoding service that integrates multiple providers, including Geoapify, HERE, and Nominatim. This API allows for dynamic and flexible geolocation queries, ensuring automated configuration based on the environment.

🔥 Key Features

Multi-provider support: Dynamically query different geocoding services.
Automated configuration: Detects and registers geocoders using environment variables.
Flexible provider selection: Choose any available provider or use the default ones.
High performance with FastAPI: Built with FastAPI for scalability and speed.

📝 Interactive Documentation with FastAPI

The project uses FastAPI to automatically generate interactive API documentation, following the OpenAPI standard. This makes it easy to explore, test, and consume the endpoints. The documentation includes descriptions of each endpoint, input parameters, and response models.

📦 Two-Level Cache Architecture

To optimize performance and reduce the costs of calls to external geocoding services, the project implements a two-level cache architecture:

Redis (L1 Cache - Speed): Used to store responses temporarily (24 hours) to serve the most recent queries quickly.
SQLite (L2 Cache - Persistence): Acts as a long-term cache. If a query is not found in Redis, it is searched in the SQLite database and, if found, is "promoted" back to Redis for future fast queries.

This strategy helps save tokens and minimize latencies in repeated queries.

⚙️ Installation

Clone the repository:
```
git clone https://github.com/xeland314/geocoding_api.git
cd geocoding_api
```
bash

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate

bash

Install dependencies:
```
pip install -r pyproject.toml
```
bash

🌍 Environment Configuration

Set up API keys using environment variables:

export GEOAPIFY_API_KEY="your_api_key"
export HERE_API_KEY="your_api_key"
export NOMINATIM_USER_AGENT="MyGeocoderApp/1.0"
export NOMINATIM_REVERSER_REPLICA_URL_1="http://127.0.0.1:8088/reverse"
export NOMINATIM_REVERSER_REPLICA_URL_2="http://127.0.0.1:8089/reverse"

bash

Alternatively, use the provided set_env.sh script:

source ./scripts/set_env.sh

bash

🚀 Running the API

Start the FastAPI server:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

bash

Interactive API documentation available at:
🔗 http://127.0.0.1:8000/docs

📡 API Endpoints

🔎 Reverse Geocoding

Perform reverse geocoding by specifying latitude, longitude, and an optional provider:

curl -X GET "http://127.0.0.1:8000/reverse-geocode?latitude=40.748817&longitude=-73.985428&platform=geoapify"

bash

Example response:

{
  "success": true,
  "data": [
    {
      "formatted_address": "Empire State Building, 350 5th Ave, New York, NY, USA",
      "postcode": "10118",
      "country": "US",
      "state": "New York",
      "district": "Manhattan",
      "settlement": "New York",
      "street": "5th Ave",
      "house": "350"
    }
  ],
  "error": null
}

json

📜 List Available Providers

Retrieve the list of dynamically registered geocoders:

curl -X GET "http://127.0.0.1:8000/geocoders"

bash

Example response:

{
  "geocoders": [
    {
      "name": "GEOAPIFY",
      "url": "https://api.geoapify.com/v1/geocode/reverse"
    },
    {
      "name": "HERE",
      "url": "https://revgeocode.search.hereapi.com/v1/revgeocode"
    },
    {
      "name": "NOMINATIM",
      "url": "https://nominatim.openstreetmap.org/reverse"
    },
    {
      "name": "NOMINATIM_REPLICA_1",
      "url": "http://127.0.0.1:8088/reverse"
    }
  ]
}

json

📄 License

This project is under the GNU General Public License v3 (GPLv3). You are free to use, modify, and distribute this project under the terms of the GPLv3 license.

See the LICENSE file for more details.

⚠️ Disclaimer

This project integrates third-party geocoding services (HERE, Geoapify, Nominatim). Users must comply with the terms of service and usage limits of each provider. The author of this project does not endorse or facilitate any violation of external API agreements.