Описание API

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

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

Принципы взаимодействия с сервисом

Для обработки данных через API вашему приложению или веб-сайту необходимо отсылать сервису соответствующие HTTP-запросы. В ответ на эти запросы сервис возвращает HTTP-сообщения, в теле которых содержится сам результат обработки. Запросы можно отсылать методом GET или POST.

В простейшем случае запрос сервису содержит обычную строку, например с точным адресом погрузки, стандартизацию которого необходимо выполнить. При использовании метода GET обрабатываемые данные в большинстве команд передаются с помощью параметра query в рамках URL запроса. При использовании метода POST данные передаются с помощью того же параметра query, но уже в рамках тела HTTP-запроса.

Кодировка обрабатываемых данных

Передаваемые на обработку данные должны быть закодированы с использованием процентной схемы кодирования URL-encoding (http://en.wikipedia.org/wiki/Urlencode).

До преобразования в URL-encoding обрабатываемые данные должны быть представлены либо кодировкой UTF-8, либо кодировкой windows-1251. По умолчанию сервис полагает, что данные на обработку представлены в UTF-8. Чтобы сообщить сервису о том, что исходные данные представлены в windows-1251, необходимо использовать URL-параметр input со следующим значением input=cp1251.

Использование API-токена

Кроме обрабатываемых данных в запросе необходимо отсылать API-токен. С помощью этого токена сервис идентифицирует пользователя, от которого получен запрос. Если сервис получит некорректный API-токен, он не будет выполнять обработку запроса, а вместо этого вернет сообщение с соответствующей ошибкой.

API-токен представляет собой строку из латинских букв и цифр. Токен присваивается пользователю при регистрации на сервисе, его можно посмотреть в своем личном кабинете в разделе "Аккаунт".

При отправке запросов сервису API-токен должен передаваться в параметре user.

Формат и кодировка ответа сервиса

Возвращаемые сервисом результаты обработки могут быть представлены в формате JSON или в формате XML. Использование конкретного формата зависит от предпочтений пользователя и от технических возможностей, доступных в рамках его приложения или веб-сайта.

Для получения ответов от сервиса в формате JSON необходимо в исходном запросе использовать URL-параметр output=json. Для получения ответов в формате XML в рамках URL исходного запроса необходимо использовать параметр output=xml. Использование одного из двух указанных значений параметра output является обязательным. Сервис не сможет выполнить обработку полученных данных без явного указания одного из двух поддерживаемых форматов.

Сервис использует кодировку UTF-8 для представления результатов обработки данных. При использовании формата XML можно запросить ответ в кодировке windows-1251. Для этого используется параметр output со следующим значением: output=xml|cp1251. Здесь для разделения двух значений параметра output используется вертикальная черта.

При формировании ответа в формате JSON сервис по умолчанию не выполняет его форматирования, так что ответ представлен в виде одной сплошной строки без переносов строк, отступов и пробельного прореживания. Для удобства отладки и знакомства с ответами сервиса в формате JSON непосредственно в окне браузера можно попросить сервис выполнить форматирование и представить JSON-ответ в гуманном виде. Для этого необходимо использовать параметр output со следующим значением output=json|pretty.

Пример обработки адреса

Для иллюстрации использования API и всех изложенных выше параметров рассмотрим пример обработки одного расчета стоимости. Предположим, что требуется привести к стандартному виду город погрузки "Москва, Регион Москва и МО, Россия". В случае использования UTF-8 данная строка в схеме URL-encoding будет иметь следующий вид.

%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0%20%D1%83%D0%BB.%20%D1%82%D0%BA%D0%B0%D1%86%D0%BA%D0%B0%D1%8F,%20%D0%B4.%205

В случае использования windows-1251 данная строка в схеме URL-encoding будет иметь следующий вид.

%EC%EE%F1%EA%E2%E0%20%F3%EB.%20%F2%EA%E0%F6%EA%E0%FF,%20%E4.%205

Дальше будем полагать, что используется UTF-8 версия этого запроса. Для его обработки необходимо сформировать следующий URL-запрос нашему сервису.

https://1-81.ru/bitrix/admin/workflow_edit.php?user=ru&site=s2&fname=/api/calc.php

Данный запрос содержит следующие важные компоненты:

• SitiZagruzka – команда ввода города отгрузки, благодаря этой информации сервис понимает, что от него требуется выполнить обработку одного города отгрузки;
• user=demotoken – параметр user посредством которого сообщаем сервису наш API-токен. При отправке реального запроса вместо значения demotoken нужно подставить токен из вашего личного кабинета;
• output=json|pretty – параметр output указывает сервису, что результат стандартизации адреса необходимо вернуть в формате JSON, при этом требуется выполнить его форматирование для нужд отладки;
• query=длинная строка с кучей процентных символов "%" - параметр, в котором сервису передается почтовый адрес "Санкт-Петербург Комендантский пр. д 49...", который необходимо исправить и привести к стандартному виду. Адрес представлен в кодировке UTF-8 с использованием процентной схемы кодирования URL-encoding.

В качестве ответа на данный запрос сервис вернет стандартизованную версию данного адреса в формате JSON. Ответ будет выглядеть следующим образом.

{
  "addresses" : [
    {
      "fields" : [
        {
          "c" : "77",
          "level" : "Region",
          "name" : "Санкт-Петербург",
          "ns" : 1.00,
          "ts" : 0.00,
          "type" : "г"
        },
        {
          "level" : "District"
        },
        {
          "level" : "City"
        },
        {
          "level" : "Place"
        },
        {
          "level" : "Site"
        },
        {
          "c" : "2908",
          "level" : "Street",
          "name" : "Ткацкая",
          "ns" : 1.00,
          "ts" : 1.00,
          "type" : "ул"
        },
        {
          "c" : "1",
          "level" : "House",
          "name" : "5",
          "ns" : 1.00,
          "ts" : 0.00,
          "type" : "ДОМ"
        },
        {
          "level" : "Building"
        },
        {
          "level" : "Structure"
        },
        {
          "level" : "Flat"
        },
        {
          "level" : "Zip",
          "name" : "105318",
          "type" : "Индекс"
        }
      ]
    }
  ],
  "check_info" : {
    "alts" : 1,
    "query" : "москва ул. ткацкая, д. 5",
    "time" : 0
  },
  "request_process_time" : 3
}

Здесь сервис вернул JSON-объект, поле "addresses" которого содержит массив с вариантами стандартизации обработанного адреса. Если адрес распознан однозначно, то данный массив будет содержать один вариант стандартизации адреса, как это имеет место в приведенном примере. В массиве "fields" стандартизованного адреса приведены компоненты адреса с разбивкой на отдельные поля, начиная с региона и заканчивая почтовым индексом.

Кроме адресных полей сервис может возвращать дополнительную информацию об адресе: географические координаты адреса (GPS-координаты), коды по справочникам (например, код КЛАДР), показатели качества адреса, отражающие то, насколько правильно и корректно записаны исходные обработанные адресные данные, разметку исходной строки в рамках которой отмечены фрагменты исходной строки, использованные при распознавании адреса и др. Включить вывод всей этой дополнительной информации в ответ сервиса можно либо с помощью соответствующих дополнительных опций параметра output, либо с помощью настроек в личном кабинете пользователя в разделе "Профиль". Дополнительные опции параметра output изложены в описаниях для каждой команды API, ссылки на которые приведены в конце данной статьи.

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

https://ahunter.ru/site/cleanse/address?user=demotoken;output=xml;query=%D0%BC%D0%BE%D1%81%D0%BA%D0%...

В отличие от предыдущего примера в данном запросе параметр output имеет значение output=xml, в остальном данный запрос совпадает с запросом из предыдущего примера. Ответ сервиса на данный запрос будет выглядеть следующим образом.

    3
    1
  

Здесь по аналогии с JSON-ответом адрес разбит на отдельные компоненты, каждый из которых записан в отдельном XML-элементе Field, начиная с адресного поля региона и заканчивая полем с почтовым индексом.

Более подробно параметры и возможности команды API по стандартизации почтового адреса приведены по следующей ссылке: cleanse/address.

Детальное описание всех команд

API стандартизации

Подробное описание всех API-команд сервиса по стандартизации, исправлению и обогащению контактных данных приведено по следующим ссылкам:

• Команда адреса: cleanse/address
• Команда получения стоимости  cleanse/address
  

API подсказок

Подробное описание API-команд сервиса по формированию в реальном времени подсказок при вводе почтовых адресов и ФИО персон приведено по следующим ссылкам:

• Команда по формированию подсказок при вводе адреса одной строкой: suggest/address
• Команда по формированию подсказок при вводе веса груза: suggest/person/solid
• Команда подсказок при вводе объема груза: suggest/person/discret