Назад к списку городов Открыть пример API

Cities Guide

Эта страница объясняет, какие файлы лежат в папке cities, как работает поиск, как открывать список городов и какие параметры можно передавать в URL.

Что умеет папка `cities`

  • Показывает все города из локальной базы SQLite на странице index.php.
  • Позволяет искать города по названию, стране и региону — на русском, английском, французском, немецком, испанском, итальянском, португальском и турецком (казань, kazan, Pékin, Moskau, Nueva York, Moskova). Акценты можно не вводить.
  • Показывает русские названия городов и стран, если они есть (поля city_ru и country_ru).
  • Если на index.php выбрать страну, города показываются на языке этой страны: Турция — İstanbul, Япония — 東京都, Сербия — Београд (поля city_local, country_local, local_lang).
  • Позволяет сортировать список по населению и имени.
  • Даёт JSON API для быстрого поиска через search.php, в том числе с фильтром по стране.
  • Даёт JSON API для автодополнения стран через countries.php.
  • Позволяет заново собрать SQLite-индекс из файла cities.json через build_index.php.

Какие файлы за что отвечают

index.php

Главная страница каталога. Показывает список городов в табличном виде, поддерживает поиск, пагинацию и сортировку.

info.php

Эта страница. Здесь собрана документация по всем основным возможностям папки cities.

search.php

JSON API для поиска. Возвращает массив items и лучше подходит для автокомплита, фронтенд-поиска и AJAX-запросов.

countries.php

JSON API для поиска стран: вводишь букву — получаешь список подходящих стран с кодами для фильтра country.

countries.json

Список стран (коды, названия на русском и английском, число городов). Собирается build_index.php, читается countries.php.

build_index.php

CLI-скрипт, который читает cities.json и пересобирает файл cities.sqlite, FTS-индекс для поиска и countries.json.

enrich_ru.py

Python-скрипт, который добавляет в cities.json русские названия city_ru и country_ru, а в keySearch — названия на других языках по данным GeoNames. На хостинге не нужен.

cities.json

Исходный JSON со всеми городами. Нужен как источник данных для построения SQLite-базы.

cities.sqlite

Рабочая база данных SQLite, из которой читают index.php и search.php.

cities.sqlite-wal и cities.sqlite-shm

Служебные файлы SQLite в режиме WAL. Могут появляться рядом с базой автоматически. При замене cities.sqlite на новую их нужно удалить.

default.php

Старый дефолтный файл страницы. Для списка городов и API он не нужен.

Как пользоваться `index.php`

Параметр Что делает Пример
q Ищет по началу слов в названии города, стране и регионе, на русском и латинице. Несколько слов — все должны совпасть. ./index.php?q=сербия
country Код страны ISO2. Показывает только города этой страны и выводит их названия на её языке. В интерфейсе — выпадающий список «Все страны». ./index.php?country=TR
sort Сортировка: population_desc, population_asc, name_asc. ./index.php?sort=population_desc
page Номер страницы списка. ./index.php?page=2
./index.php?q=белград&sort=population_desc&page=1

Как пользоваться `search.php`

Параметр Что делает Пример
q Поисковая строка на русском, английском, французском, немецком, испанском, итальянском, португальском или турецком. Минимум 2 символа. Можно не передавать, если указан country. ./search.php?q=казань
country Только города этой страны. Код ISO2/ISO3 (RU, RUS) или название на русском/английском (Россия, Russia), регистр не важен. ./search.php?q=каза&country=RU
limit Ограничивает число результатов от 1 до 50, по умолчанию 20. ./search.php?q=москва&limit=5

Порядок результатов: сначала города, чьё название совпадает с запросом (от 4 букв), потом те, чьё название начинается с запроса, потом остальные (например, совпала страна). Внутри — по населению, крупные первыми. Если страна не найдена, вернётся пустой items.

{ "items": [ { "city": "Kazan", "city_ru": "Казань", "country": "Russia", "country_ru": "Россия", "iso2": "RU", "population": 1243500, ... } ] }
Русское название есть не у всех городов. В приложении показывайте city_ru, а если его нет — city. Название на языке страны лежит в city_local (код языка — в local_lang, например tr, ja, ar), его тоже может не быть. По названиям на местных языках работает и поиск: 東京, القاهرة, Београд.

Как пользоваться `countries.php`

Параметр Что делает Пример
q Начало названия страны на русском или английском, можно с одной буквы. Ищет по началу любого слова: кор найдёт Южную и Северную Корею. Без q вернутся все страны. ./countries.php?q=р
limit Число результатов от 1 до 250, по умолчанию 20. ./countries.php?q=а&limit=5

Сначала идут страны, название которых начинается с запроса, внутри — от крупных к мелким (по населению городов в базе).

{ "items": [ { "iso2": "RU", "iso3": "RUS", "country": "Russia", "country_ru": "Россия", "cities_count": 1211 } ] }
Выбранную страну удобно передавать в search.php кодом: ./search.php?q=каза&country=RU — тогда вернутся только города этой страны.

Как пересобрать базу

Если меняется cities.json, можно заново собрать SQLite-базу и индекс полнотекстового поиска.

php build_index.php cities.json cities.sqlite

Русские названия уже лежат в cities.json. Если взять новый исходный JSON без них, сначала добавьте их скриптом enrich_ru.py (файлы GeoNames: cities500.txt, countryInfo.txt и строки из alternateNamesV2.txt: русские в ru_names.tsv, en/fr/de/es/it/pt/tr в lang_names.tsv, основные языки стран в local_names.tsv).

python3 enrich_ru.py cities.json cities.json --geonames cities500.txt --countries countryInfo.txt --ru ru_names.tsv --langs lang_names.tsv --local local_names.tsv
После пересборки index.php и search.php автоматически начнут читать новые данные из обновлённого cities.sqlite.