CBP (метод)

Материал из post-API.ru
Перейти к: навигация, поиск

Данный метод (аббр. - Citys By Part) предназначен для получения списка городов и иных населенных пунктов, подходящих под введенный пользователем фрагмент названия.

Метод может быть использован следующим образом.

  • По мере ввода пользователем фрагмента города, под полем ввода появляется выпадающий список, в котором отображается список подходящих городов, с указанием района и области, в котором они расположены. При этом удовлетворяющий условию фрагмент - подсвечивается.

Версия API

 Версия 2.0

Вызов

 http://post-api.ru/api/v2/cbp.php?city=Сан&apikey=dev&d=1&limit=10&full=1&hl=1&ex=0&cf=1 

Параметры

Ключ Обязательный Описание
city О Фагмент наименования города. В зависимости от ключа full, по фразе "сан" будет осуществлен поиск как города "Санкт-Петербург", так и "Александров". Название города может вводиться без учета регистра.
limit Н Количество возвращаемых городов. По умолчанию 50. Рекомендуется не превышать значение 200 во избежании больших задержек.
full Н Если установлен в 0 (значение по умолчанию), то поиск осуществляется с первых символов (т.е. при маске "сан" - "Александров" найден не будет.
hl Н Если установлен в 1 (значение по умолчанию - 0), то в итоговом результате все вхождения поисковой строки будут обрамлены тегом .
ex Н Если установлен в 1 (значение по умолчанию - 0), то в итоговом результате будут отсекаться все объекты "низкого" уровня, такие как санатории, гаражные кооперативы и прочее.
cf Н Если установлен в 1 (значение по умолчанию - 0), то в итоговом результате, в сруктуре route будет всегда заполнено поле "city". Без этого флага структура заполняется в соответствии с иерархией адресных объектов. Например, "Москва" без флага cf будет находиться в массиве "region" структуры route, а с флагом cf - будет перенесена в массив "city" структуры route.
apikey О Ключ доступа к API.
d Н Отладочный режим.


Возвращаемое значение

С этим методом связаны следующие массивы-ответы: CBPv2_content, route, mkad.

При успешном выполнении запроса возвращается следующий массив-ответ.

   [id] => CBP                        // Тип результирующей структуры
   [api_ver] => 2.0                   // Входит в семейство методов версии 2.0
   [status] => ok                     // Результат вызова метода. Может быть error и ok
   [access] => active                 // Статус ключа доступа к post-API.ru
   [access_status] => ok              // Статус доступа с использованием ключа
   [executed_time] => 0.13            // Время исполнения скрипта (без учета сетевых задержек)
   [source] => Array                  // Исходные данные, передаваемый в базу данных (контроль)
       (
           [city] => сан
           [limit] => 10
           [highlight] => 1
           [full_search] => 1
       )
   [content] =>                       // структура CBPv2_content

При не успешном выполнении метода, возвращается массив-ответ с ошибкой.

   [id] => CBP
   [api_ver] => 2.0
   [access] => active
   [access_status] => ok
   [executed_time] => 0
   [status] => error
   [content] => Array
       (
           [msg] => Фрагмент имени города должен содержать не менее 2 символов
           [err] => cbp_fewchars
       )


Особенности

  • В отличие от метода IBC используется иной алгоритм, который не приводит к возникновению задержки в 1-5 секунд. Среднее время работы метода CBP 0,12 секунд для поиска города с первого символа (без ключа full). И примерно 0,16 секунд при установленном ключе full.
  • В возвращаемой структуре города отсортированы по важности, то есть первыми будут населенные пункты федерального и районного значения.
  • Фрагмент имени города/улицы может передаваться как текстом, так и в виде строки, закодированной urlencode (Например, "сан" - %D1%81%D0%B0%D0%BD). Настоятельно рекомендуется отправлть в API запрос именно в кодированном формате для гарантии корректной обработки символов "пробел", "кавычки" и прочие.
  • Фрагмент имени города должен содержать минимум два символа. В противном случае будет возвращена ошибка.
  • Если требуется иное оформление "подсветки" найденного населенного пункта, отличающееся просто от жирного начертания, то необходимо после получения результата заменить теги "" и "" на необходимые.

Обсуждение

 Форум для обсуждения метода CBP

Примеры использования

нет

Фрагменты кода

нет

История

  • 16.08.2013 - Добавлен флаг cf.
  • 12.08.2013 - Корректно стал отображаться в переменной order и print_screen республика. Например, "Республика Татарстан", но "Чеченская республика".
  • 09.08.2013 - Добавлен новый ключ "ex".
  • 09.08.2013 - Исправлена ошибка, при которой в качестве городов находились объекты, лежащие фактически в городской черте. Результатом являлось некорректное отображение таких объектов в структуре route.
  • 09.08.2013 - Исправлена ошибка с некорректной обработкой (игнорированием) параметра limit. Исправлена ошибка с выгрузкой нескольких одинаковых записей.
  • 01.06.2013 - Добавлен порядок вывода городов и улиц
  • 11.05.2013 - В результирующий массив-ответ теперь добавляется структура mkad, если в массив-ответ содержит меньше 5 (пяти).
  • 04.05.2013 - Метод создан