Документация проекта post-API.ru

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

Общее описание

Проект реализует web-сервисы, которые могут использоваться при разработке Интернет-магазина с целью автоматизации: а) автозаполнения адресной информации, б) функций расчета стоимости и сроков доставки заказанных товаров клиенту в регионы России с помощью почтовых услуг компании ОАО "Почта России".

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

Поддерживаемые функции

Реализованные функции

  • Определение адреса по почтовому индексу с детализацией до дома (Край/Область/Республика -> Автономная область -> Район -> Город -> Улица -> Дом). Метод: ABI.
  • Определение массива индексов по полному или частичному имени населенного пункта. Метод: IBC.
  • Определение города по фрагменту имени для форм автозаполнения. Метод: CBP.
  • Определение улицы по фрагменту имени для форм автозаполнения. Метод: SBP.
  • Расчет стоимости доставки посылок в регионы России. Метод: delivcost.php.
  • Расчет стоимости услуг КиберДеньги. Метод: postdata.php.
  • Расчет срока доставки посылки по почтовому индексу. Метод: postdata.php.
  • Расчет удаленности города Московской области от центра Москвы и от МКАД: Методы: ABI, CBP.
  • Загрузка списка станций метро. Методы: LMS.

Планируемые функции

  • Набор AJAX-элементов для построения форм автозаполнения адресов
  • Поиск ближайшей станции метро
  • Валидатор почтовых адресов

Возможности и ограничения

Возможности:

  • Поддерживаемая география для методов поиска адресной информации - вся Россия
  • Поддерживаемая география для методов расчета сроков и стоимости - только Москва
  • Поддерживаемая география для списков станций метро - Москва и Санкт-Петербург
  • При расчете стоимости доставки "Ценной посылки" могут учитываться:
    • наземная или авиа-доставка;
    • труднодоступные районы;
    • страховка товаров;
    • вес и массогабаритные характеристики;
    • объявленная стоимость;
    • объявляемый признак "Осторожно!".
  • Срок доставки рассчитывается с разделением по этапам доставки (Москва, между областными центрами, внутри города, от областного центра в города области).
  • Расчет стоимости услуг по доставке наложенного платежа осуществляется по тарифам КиберДеньги.

Ограничения:

  • Для расчета сроков и стоимости доставки, отправителем может являться только Москва.
  • Не рассчитываются отправления 1-го класса.
  • Не рассчитываются международные отправления, в том числе в страны СНГ.

Обзор API

Символьная кодировка запросов и ответов

Проект использует кодировку utf-8

Методы API

API вызывается через отправку исходной информации в виде POST или GET запросов на специальные методы, расположенные по адресу http://post-api.ru/api (для версии 1), или http://post-api.ru/v2 (для версии 2).

Формат ответов

Вся возвращаемая API информация передается в массивах-ответах, которые идентифицируются 3-х буквенной аббревиатурой.

Формат ответа - JSON-структура.

Режим отладки

Для визуального просмотра возвращаемого результата необходимо в строку вызова метода добавить "&d=1".

Режим отладки: //post-api.ru/api/postdata.php?apikey=dev&index=656056&d=1

Рабочий режим: //post-api.ru/api/postdata.php?apikey=dev&index=656056

История проекта

v1 - версия 1

Первый вариант post-API.ru базируется на данных КЛАДР, но работает с адресными объектами до населенного пункта включительно. Первая версия не позволяет определять по индексу улицы/площади/проспекты и пр, а также дома. Скрипт city2index.php содержал критические ошибки.

v2 - версия 2

С апреля 2013 года начаты работы над версией 2 post-API.ru. В основе версии 2 лежит не данные КЛАДР, а данные новой Федеральной информационной автоматизированной системы (ФИАС). База данных post-API.ru обновляется автоматически примерно раз в неделю (+1-2 суток к моменту появления обновления ФИАС). Для данной версии более структурировано сформирована документация.

v3 - версия 3

В ноябре 2016 г. версия 2.0 была расширена адресами Республики Крым.

v4 - версия 4

В сентябре-октябре проходили работы над новой, коммерческой версией 4 post-API.ru. Основные задачи - внедрение технологии кеширования результатов, а также переработка форматов ответов на основе обратной связи от клиентов, сформированной по результатам опытной эксплуатации. Первыми методами, которые были сформированы для v4 стали ABI и OBG

Примеры

Наименование Версия Онлайн-демо Прямой вызов
1 Узнать адрес по почтовому индексу v3 [1] Вызов метода ABI
2 Найти индекс по названию города и улицы v2 [2] Вызов метода IBC
3 Найти индекс по названию города и улицы (устаревший) v1 [3] Вызов метода city2index.php
4 Найти город по почтовому индексу v1 [4] Вызов метода postdata.php
5 Узнать срок доставки посылки v1 [5] Вызов метода postdata.php
6 Узнать стоимость оправки посылки v1 [6] Вызов метода delivcost.php
7 Узнать стоимость наложенного платежа v1 [7] Вызов метода postdata.php
8 Найти город по фрагменту названия v2 нет Вызов метода CBP
9 Найти улицу по фрагменту названия v2 нет Вызов метода SBP
10 Загрузить список станций метро v2 нет Вызов метода LMS
11 Узнать адрес по почтовому индексу v4 Нет Вызов метода ABI
12 Узнать ближайшие объекты по географическим координатам v4 Нет Вызов метода OBG
13 Найти город по фрагменту названия v4 Нет Вызов метода CBP


Некоторые полезные ресурсы