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

Cities Guide

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

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

  • Показывает все города из локальной базы SQLite на странице index.php.
  • Позволяет искать города по названию, стране и региону.
  • Позволяет сортировать список по населению и имени.
  • Даёт JSON API для быстрого поиска через search.php.
  • Позволяет заново собрать SQLite-индекс из файла cities.json через build_index.php.

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

index.php

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

info.php

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

search.php

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

build_index.php

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

cities.json

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

cities.sqlite

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

cities.sqlite-wal и cities.sqlite-shm

Служебные файлы SQLite в режиме WAL. Они могут появляться рядом с базой автоматически, когда база открыта на запись или чтение.

default.php

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

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

Параметр Что делает Пример
q Ищет по названию города, ASCII-имени, стране и региону. ./index.php?q=serbia
sort Сортировка: population_desc, population_asc, name_asc. ./index.php?sort=population_desc
page Номер страницы списка. ./index.php?page=2
./index.php?q=belgrade&sort=population_desc&page=1

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

Параметр Что делает Пример
q Поисковая строка. Минимум 2 символа. ./search.php?q=moscow
limit Ограничивает число результатов от 1 до 50. ./search.php?q=moscow&limit=5
{ "items": [ { "city": "Moscow", "country": "Russia", ... } ] }

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

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

php build_index.php cities.json cities.sqlite
После пересборки index.php и search.php автоматически начнут читать новые данные из обновлённого cities.sqlite.