Информация

Техническая документация по API поиска городов и аэропортов

1. Описание проекта

Данный проект представляет собой REST API, разработанный на Node.js с использованием Express. Он предназначен для быстрого поиска городов, аэропортов и железнодорожных вокзалов по фрагменту названия или IATA-коду. API используется, например, для автозаполнения поисковых форм. Оптимизация структуры базы данных и SQL-запросов позволила сократить время ответа с 1.1 секунды до 0.22 секунды.

2. Установка и развертывание

2.1. Зависимости и подготовка

Установка Node.js и зависимостей:
Убедитесь, что на сервере установлены Node.js и npm. Затем установите зависимости, выполнив в директории проекта:
```
npm install
```
Настройка переменных окружения:
Создайте файл .env в корне проекта и задайте следующие переменные:
```
DB_HOST=localhost
DB_USER=your_user
DB_PASSWORD=your_password
DB_NAME=your_database
PORT=3000
API_KEY=your_api_key
    
```
Исходный код:
Исходный код маршрутов (например, /api/v1/search и /api/v1/short) и скрипт автоматического обновления базы (scripts/updateData.js) доступны по ссылке в разделе:

"Документы и файлы"

Обратите внимание, что вам не требуется копировать весь репозиторий – достаточно получить доступ к актуальной версии исходного кода по указанной ссылке.

2.2. Настройка автоматического обновления базы данных

Обновление через cron:
Скрипт обновления данных (scripts/updateData.js) запускается ежедневно в 03:00 по МСК. Для его настройки отредактируйте crontab следующим образом:
```
0 3 * * * /usr/bin/node /path/to/project/scripts/updateData.js >> /path/to/project/logs/update.log 2>&1
    
```
Если сервер находится в другой временной зоне, установите переменную окружения TZ="Europe/Moscow" или скорректируйте время запуска.

3. Автоматическое обновление базы данных

3.1. Описание процесса обновления

Источник данных: Скрипт загружает JSON-файл с IATA-кодами из внешнего URL.
Проверка актуальности: Вычисляется MD5-хэш полученного JSON, который сравнивается с ранее сохранённым (файл last_hashes.json). Если данные изменились, выполняется обновление.
Обновление базы данных: Таблицы city, airports и railway очищаются и заполняются заново. В каждую таблицу добавлен столбец country_code, а поля country_ru и country_en заполняются полными наименованиями стран, полученными по двухсимвольному коду из таблиц country_ru и country_en.
Оптимизация производительности: После оптимизации запросов время ответа сократилось с 1.1 сек до 0.22 сек.

3.2. Пример кода обновления базы данных

Смотрите исходный код функции updateDatabase в проекте.

4. Структура базы данных

4.1. Таблица `city`

Поля:
- id – INT, AUTO_INCREMENT, PRIMARY KEY
- country_code – VARCHAR(2): двузначный код страны
- country_ru – VARCHAR(255): полное наименование страны на русском
- country_en – VARCHAR(255): полное наименование страны на английском
- city_ru – VARCHAR(255): название города на русском
- city_en – VARCHAR(255): название города на английском
- iata_city – CHAR(3): IATA-код города (если есть)
- time_zone, lat, lon – дополнительные данные
Индексы: На полях city_ru, city_en, iata_city.

4.2. Таблица `airports`

Поля:
- id – INT, AUTO_INCREMENT, PRIMARY KEY
- country_code – VARCHAR(2)
- country_ru – VARCHAR(255)
- country_en – VARCHAR(255)
- city_ru, city_en, iata_city – данные о городе
- iata_airport – CHAR(3): IATA-код аэропорта
- airport_name_ru, airport_name_en – названия аэропортов
- time_zone, lat, lon – дополнительные данные
Индексы: На полях iata_airport, airport_name_ru, airport_name_en.

4.3. Таблица `railway`

Поля:
- id – INT, AUTO_INCREMENT, PRIMARY KEY
- country_code – VARCHAR(2)
- country_ru – VARCHAR(255)
- country_en – VARCHAR(255)
- city_ru, city_en, iata_city – данные о городе
- iata_railway – CHAR(3): код вокзала
- railway_name_ru, railway_name_en – названия вокзалов
- time_zone, lat, lon – дополнительные данные
Индексы: На полях iata_railway, railway_name_ru, railway_name_en.

4.4. Таблицы `country_ru` и `country_en`

Поля:
- id – VARCHAR(2), PRIMARY KEY
- value – VARCHAR(255): полное наименование страны

4.5. Таблица `secret`

Поля:
- id – INT, AUTO_INCREMENT, PRIMARY KEY
- api-key – ключ API
- comments – комментарии (опционально)

5. API-маршруты

5.1. GET /api/v1/search

Описание: Полный поиск по городам, аэропортам и железнодорожным вокзалам с группировкой по городу.

Параметры запроса:

lang – язык поиска (ru или en).
query – строка поиска (минимум 3 символа) для совпадений по первым символам названий и IATA-кодов.
limit – (опционально) максимальное число возвращаемых записей.
apiKey – ключ API для доступа.

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

https://ai.kupi.com:3001/api/v1/search?lang=en&query=led&limit=10&apiKey=YourApiKey

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

{
    "results": [
      {
        "city": {
          "id": 7278,
          "country_code": "RU",
          "country_ru": "Россия",
          "country_en": "Russia",
          "city_ru": "Санкт-Петербург",
          "city_en": "Saint Petersburg",
          "iata_city": "LED",
          "time_zone": "Europe/Moscow",
          "lat": "59.939039",
          "lon": "30.315785"
        },
        "airports": [
          {
            "id": 3837,
            "country_code": "RU",
            "country_ru": "Россия",
            "country_en": "Russia",
            "city_ru": "Санкт-Петербург",
            "city_en": "Saint Petersburg",
            "iata_city": "LED",
            "iata_airport": "LED",
            "airport_name_ru": "Пулково",
            "airport_name_en": "Pulkovo Airport",
            "time_zone": "Europe/Moscow",
            "lat": "59.806084",
            "lon": "30.308300"
          }
        ],
        "railway": [
          {
            "id": 276,
            "country_code": "RU",
            "country_ru": "Россия",
            "country_en": "Russia",
            "city_ru": "Санкт-Петербург",
            "city_en": "Saint Petersburg",
            "iata_city": "LED",
            "iata_railway": "ZLK",
            "railway_name_ru": "Московский Вокзал",
            "railway_name_en": "St Petersburg Moskovsky Railway Station",
            "time_zone": "Europe/Moscow",
            "lat": "59.939039",
            "lon": "30.315785"
          },
          {
            "id": 601,
            "country_code": "RU",
            "country_ru": "Россия",
            "country_en": "Russia",
            "city_ru": "Санкт-Петербург",
            "city_en": "Saint Petersburg",
            "iata_city": "LED",
            "iata_railway": "FVS",
            "railway_name_ru": "Финляндский вокзал",
            "railway_name_en": "Finland Station",
            "time_zone": "Europe/Moscow",
            "lat": "59.955556",
            "lon": "30.356667"
          }
        ]
      }
    ],
    "total": 1
  }

5.2. GET /api/v1/short

Описание: Облегчённый поиск, который возвращает данные только для городов и аэропортов, без железнодорожных вокзалов, а также с сокращённой структурой – из объекта города исключаются поля id, time_zone, lat и lon, а из аэропортов – поля id, country_code, country_ru, country_en, city_ru, city_en, iata_city, time_zone, lat и lon.

Параметры запроса:

lang – ru или en.
query – строка поиска (минимум 3 символа).
apiKey – ключ API.

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

https://ai.kupi.com:3001/api/v1/short?lang=ru&query=петер&apiKey=YourApiKey

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

    {
      "results": [
        {
          "city": {
            "country_code": "US",
            "country_ru": "Соединенные Штаты",
            "country_en": "United States",
            "city_ru": "Колорадо-Спрингс",
            "city_en": "Colorado Springs",
            "iata_city": "COS"
          },
          "airports": [
            {
              "iata_airport": "COS",
              "airport_name_ru": "Петерсон-Филд",
              "airport_name_en": "Colorado Springs Airport"
            }
          ]
        }
      ],
      "total": 1
    }

6. Примечания

Производительность: Оптимизированные SQL-запросы и индексы позволили снизить время ответа с 1.1 сек до 0.22 сек.
Безопасность: Доступ к API ограничен проверкой API-ключа. Запросы без корректного ключа отклоняются.
CORS: Для обеспечения кросс-доменного доступа настроен CORS через middleware Express (пакет cors).
Логирование: Все запросы и ошибки логируются. Рекомендуется использовать продвинутые логгеры (например, winston) в продакшене.
Первый запуск: Перед началом эксплуатации выполните ручной запуск скрипта обновления, чтобы заполнить таблицы (city, airports, railway) и убедиться в корректном заполнении справочников стран (country_ru и country_en).

Заключение

Данная документация описывает развертывание, обновление базы данных и работу API для поиска городов, аэропортов и железнодорожных вокзалов по IATA-кодам. Клиенты могут использовать маршруты /api/v1/search (полный ответ) и /api/v1/short (сокращённый ответ) для получения данных. Оптимизация запросов и структур базы позволила добиться значительного улучшения производительности – время ответа сократилось с 1.1 сек до 0.22 сек.

Сохраните этот документ в формате Word, скопировав и вставив данный HTML-код.

TAN (Tiker Avia Name) API

Демонстрация API поиска

Ответ в формате JSON

Данные в табличном виде

TAN (Tiker Avia Name) API

Информация

Техническая документация по API поиска городов и аэропортов

1. Описание проекта

2. Установка и развертывание

2.1. Зависимости и подготовка

2.2. Настройка автоматического обновления базы данных

3. Автоматическое обновление базы данных

3.1. Описание процесса обновления

3.2. Пример кода обновления базы данных

4. Структура базы данных

4.1. Таблица city

4.2. Таблица airports

4.3. Таблица railway

4.4. Таблицы country_ru и country_en

4.5. Таблица secret

5. API-маршруты

5.1. GET /api/v1/search

5.2. GET /api/v1/short

6. Примечания

Заключение

Комментарии (0) Комментировать📝

Документы и файлы

TAN (Tiker Avia Name) API

Демонстрация API поиска

Ответ в формате JSON

Данные в табличном виде

Удалить комментарий?

4.1. Таблица `city`

4.2. Таблица `airports`

4.3. Таблица `railway`

4.4. Таблицы `country_ru` и `country_en`

4.5. Таблица `secret`