# Geolocation Diagnostic & Testing Tools

This guide explains how to use the custom scripts created to monitor, debug, and manage the geonames city database.

## 🚀 Migration Tool

### `migrate_geo_data.py`
Used to migrate 5.1 million city records from the reference SQLite file to your primary PostgreSQL database.

**Usage:**
```bash
python migrate_geo_data.py
```
*Note: This script uses high-speed `TRUNCATE` and batch processing (25k rows/batch) to ensure performance.*

---

## 🔍 Diagnostic Scripts

### 1. `test_geo_app_flow.py`
Monitors the **logical flow** of a reverse geolocation request. It helps you see if a coordinate is hitting a "Special Case" (placeholder), the cache, or the database.

**Usage:**
```bash
python test_geo_app_flow.py <latitude> <longitude>
```
**Example Output:**
- `[STEP 1] Checking Special Coordinates...`
- `[STEP 2] Checking Cache...`
- `[STEP 3] Executing Application Logic...`

### 2. `test_geo_raw_sql.py`
Dives into the **PostgreSQL database** to show exactly which cities are being considered as candidates and how they are scored.

**Usage:**
```bash
python test_geo_raw_sql.py <latitude> <longitude>
```
**What to look for:**
- **Distance**: How far the city is from the coordinates.
- **Population**: Used to weight the results.
- **Score**: The final value used to determine the winner (Higher is better).

### 3. `test_geo_search_integer.py`
A search tool to lookup records by their **integer part**. Useful for checking if data exists in a specific region without knowing exact decimals.

**Usage:**
```bash
# Search by Latitude integer
python test_geo_search_integer.py --lat 25

# Search by Longitude integer
python test_geo_search_integer.py --lon 59

# Combined search
python test_geo_search_integer.py --lat 25 --lon 55
```

---

## 🛠 Troubleshooting
If you receive a `ModuleNotFoundError`:
Ensure your virtual environment is active before running the scripts:
```powershell
.venv\Scripts\activate
```