2GIS Parser API

🚀 Мощный FastAPI сервер для парсинга данных с 2GIS

Этот проект предоставляет REST API для поиска и извлечения информации об организациях с карт 2GIS, используя библиотеку parser-2gis.

✨ Особенности

• 🎯 Поиск по координатам - находите организации вокруг указанной точки
• 🏙️ Поиск по городам - ищите бизнесы в любом городе России
• 📊 JSON API - получайте структурированные данные
• 📄 CSV экспорт - скачивайте результаты в виде файлов
• 🐳 Docker Ready - легкое развертывание в контейнерах
• 📚 Автодокументация - встроенная Swagger UI
• ⚡ Высокая производительность - асинхронная обработка запросов

🚀 Быстрый старт

1. Установка зависимостей

pip install -r requirements.txt

2. Запуск сервера

py main.py

Сервер будет доступен по адресу: http://localhost:8000

3. Документация API

Откройте в браузере: http://localhost:8000/docs

📋 API Эндпоинты

🎯 Поиск около точки (JSON)

POST /search-near-point-json

Пример запроса:

{
  "name": "аптека",
  "lat": 55.7517,
  "lon": 37.6178,
  "limit": 5
}

Пример ответа:

{
  "success": true,
  "message": "Найдено 5 организаций",
  "total_results": 5,
  "data": [
    {
      "Наименование": "Аптека №1",
      "Адрес": "Москва, ул. Примерная, 123",
      "Телефон": "+7 (495) 123-45-67",
      "Широта": 55.7520,
      "Долгота": 37.6180,
      "Рейтинг": "4.5",
      "2GIS URL": "https://2gis.ru/moscow/firm/..."
    }
  ]
}

🏙️ Поиск по городу

POST /search-business

Пример запроса:

{
  "name": "пиццерия", 
  "city": "moscow",
  "format": "json"
}

📄 CSV экспорт

GET /search-business-csv?name=кафе&city=spb

Возвращает CSV файл для скачивания.

❤️ Проверка здоровья

GET /health

🐳 Docker

Запуск с Docker Compose

docker-compose up

Сборка образа

docker build -t 2gis-api .
docker run -p 8000:8000 2gis-api

🧪 Тестирование

Запуск тестов

py test_api.py          # Полный набор тестов
py test_json_api.py     # Тесты JSON API

Быстрая проверка

curl http://localhost:8000/health

📁 Структура проекта

twogis/
├── main.py              # FastAPI сервер
├── Twogis.py            # Основная логика парсинга
├── requirements.txt     # Зависимости Python
├── docker-compose.yml   # Docker Compose конфигурация
├── Dockerfile          # Docker образ
├── healthcheck.py      # Проверка здоровья для Docker
├── test_api.py         # Тесты API
├── test_json_api.py    # Тесты JSON
├── API_EXAMPLES.md     # Примеры использования
└── API_JSON_GUIDE.md   # Руководство по JSON API

⚙️ Конфигурация

Переменные окружения

• PARSER_2GIS_CHROME_PATH - путь к Chrome/Chromium (опционально)

Параметры парсинга

• limit - максимальное количество результатов (по умолчанию: 10)
• format - формат вывода: csv, xlsx, json (по умолчанию: json)

🔧 Разработка

Установка для разработки

pip install -r requirements.txt

Запуск в режиме разработки

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

📚 Документация

• API Examples - подробные примеры использования
• JSON API Guide - руководство по JSON API
• Swagger UI - интерактивная документация

🛠️ Технологии

• FastAPI - современный веб-фреймворк
• parser-2gis - библиотека для парсинга 2GIS
• Pandas - обработка данных
• Uvicorn - ASGI сервер
• Docker - контейнеризация
• Pydantic - валидация данных

📄 Лицензия

Этот проект создан для образовательных целей.

🤝 Поддержка

При возникновении проблем:

1. Проверьте логи сервера
2. Убедитесь, что Chrome/Chromium установлен
3. Проверьте доступность 2GIS

---

Сделано с ❤️ для эффективного парсинга 2GIS