Dovodi_Backend/apps/geolocation_package

Geolocation Package

این پکیج شامل تمام فایل‌های مرتبط با 3 API زیر است که از پروژه اصلی استخراج شده‌اند:

API Endpoints

API	URL	View	Description
IP Geolocation	geolocation/	IPGeolocationAPIView	دریافت اطلاعات موقعیت مکانی بر اساس IP کاربر
Reverse Geolocation	geolocation/coordinates/	ReverseGeolocationAPIView	دریافت اطلاعات شهر/کشور بر اساس مختصات جغرافیایی
Region Info	auth/user/region/	RegionInfoView	دریافت اطلاعات منطقه کاربر (شامل browser detection)

---

📁 ساختار پوشه‌ها

geolocation_package/
├── __init__.py
├── README.md
├── views/
│   ├── __init__.py
│   ├── geolocation.py          # IPGeolocationAPIView, ReverseGeolocationAPIView
│   └── region_info.py          # RegionInfoView + detect_browser_from_user_agent
├── serializers/
│   ├── __init__.py
│   └── geolocation.py          # IPGeolocationSerializer, ReverseGeolocationSerializer, ReverseGeolocationResponseSerializer
├── models/
│   ├── __init__.py
│   └── geoNames.py             # GeoNamesCity model
├── utils/
│   ├── __init__.py
│   ├── city_detection_ip.py    # get_location_by_coordinates, get_location_by_ip
│   └── geo.py                  # توابع کمکی برای geocoding از API‌های مختلف
└── data/
    ├── GeoLite2-City.mmdb      # MaxMind GeoIP2 City database (61.5 MB)
    ├── GeoLite2-Country.mmdb   # MaxMind GeoIP2 Country database (9.2 MB)
    └── geonames_city.sqlite    # SQLite export of GeoNamesCity (628.6 MB, 5,115,708 records)

---

📋 فایل‌های استخراج شده

Views (ویوها)

فایل	مبدا	توضیحات
views/geolocation.py	apps/account/views/geolocation.py	شامل IPGeolocationAPIView و ReverseGeolocationAPIView
views/region_info.py	apps/account/views/location_history.py (lines 138-248)	شامل RegionInfoView و detect_browser_from_user_agent

Serializers (سریالایزرها)

فایل	مبدا	توضیحات
serializers/geolocation.py	apps/account/serializer/geolocation.py	شامل IPGeolocationSerializer, ReverseGeolocationSerializer, ReverseGeolocationResponseSerializer

Models (مدل‌ها)

فایل	مبدا	توضیحات
models/geoNames.py	apps/account/models/geoNames.py	مدل GeoNamesCity با 5,115,708 رکورد شهر از سراسر جهان

Utils (ابزارها)

فایل	مبدا	توضیحات
utils/city_detection_ip.py	city_detection_ip.py	شامل get_location_by_coordinates, get_location_by_ip, SPECIAL_COORDINATES
utils/geo.py	utils/geo.py	توابع fallback برای geocoding از API‌های مختلف (Nominatim, BigDataCloud, etc.)

Data Files (فایل‌های داده)

فایل	مبدا	سایز	توضیحات
data/GeoLite2-City.mmdb	utils/country_city_db/GeoLite2-City.mmdb	61.5 MB	دیتابیس MaxMind برای IP to City
data/GeoLite2-Country.mmdb	utils/country_city_db/GeoLite2-Country.mmdb	9.2 MB	دیتابیس MaxMind برای IP to Country
data/geonames_city.sqlite	از PostgreSQL (GeoNamesCity model)	628.6 MB	SQLite export با 5,115,708 رکورد

---

🔧 وابستگی‌ها (Dependencies)

geoip2>=4.0.0
djangorestframework>=3.14.0
drf-yasg>=1.21.0

---

💾 SQLite Database Schema

جدول geonames_city:

CREATE TABLE geonames_city (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    country_code TEXT NOT NULL,
    latitude REAL NOT NULL,
    longitude REAL NOT NULL,
    feature_class TEXT NOT NULL,
    population INTEGER
);

-- Indexes
CREATE INDEX idx_lat_lon ON geonames_city (latitude, longitude);
CREATE INDEX idx_country_code ON geonames_city (country_code);
CREATE INDEX idx_feature_class ON geonames_city (feature_class);
CREATE INDEX idx_feature_lat_lon ON geonames_city (feature_class, latitude, longitude);

---

🚀 نحوه استفاده در پروژه جدید

1. کپی فولدر به پروژه

cp -r geolocation_package /path/to/new_project/apps/

2. تنظیم urls.py

from apps.geolocation_package.views import (
    IPGeolocationAPIView,
    ReverseGeolocationAPIView,
    RegionInfoView
)

urlpatterns = [
    path('geolocation/', IPGeolocationAPIView.as_view(), name='ip-geolocation'),
    path('geolocation/coordinates/', ReverseGeolocationAPIView.as_view(), name='geolocation-by-coordinates'),
    path('auth/user/region/', RegionInfoView.as_view(), name='region-info'),
]

3. تنظیم مسیر دیتابیس

مسیر فایل‌های MMDB را در کد به محل جدید تغییر دهید:

# در views/geolocation.py و views/region_info.py
CITY_DB_PATH = Path("apps/geolocation_package/data/GeoLite2-City.mmdb")

4. استفاده از SQLite به جای PostgreSQL (اختیاری)

اگر نمی‌خواهید GeoNamesCity را در PostgreSQL نگه دارید، می‌توانید مستقیماً از SQLite استفاده کنید:

import sqlite3
from pathlib import Path

DB_PATH = Path("apps/geolocation_package/data/geonames_city.sqlite")

def get_city_by_coordinates(lat, lon):
    conn = sqlite3.connect(DB_PATH)
    cursor = conn.cursor()
    
    cursor.execute("""
        SELECT name, country_code FROM geonames_city
        WHERE feature_class = 'P'
          AND latitude BETWEEN ? AND ?
          AND longitude BETWEEN ? AND ?
        LIMIT 1
    """, (lat - 0.5, lat + 0.5, lon - 0.5, lon + 0.5))
    
    result = cursor.fetchone()
    conn.close()
    return result

---

📊 آمار دیتابیس

• تعداد رکوردها در GeoNamesCity: 5,115,708
• حجم SQLite: 628.59 MB
• حجم GeoLite2-City.mmdb: 61.50 MB
• حجم GeoLite2-Country.mmdb: 9.22 MB

---

📝 نکات مهم

1. دیتابیس اصلی حذف نشده است - فقط داده‌ها کپی شده‌اند
2. GeoLite2 License: فایل‌های MMDB از MaxMind هستند و نیاز به رعایت لایسنس دارند
3. آپدیت دیتابیس: برای آپدیت GeoNames از اسکریپت export_geonames_to_sqlite.py استفاده کنید

---

Generated on: 2026-01-27