Описание 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 и всех изложенных выше параметров рассмотрим пример обработки одного почтового адреса. Предположим, что требуется привести к стандартному виду адрес "москва ул. ткацкая, д. 5". В случае использования UTF-8 данная строка в схеме URL-encoding будет иметь следующий вид.

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

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

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

• cleanse/address – команда стандартизации почтового адреса, благодаря этой информации сервис понимает, что от него требуется выполнить обработку одного почтового адреса;
• user=demotoken – параметр user посредством которого сообщаем сервису наш API-токен. При отправке реального запроса вместо значения demotoken нужно подставить токен из вашего личного кабинета;
• output=json|pretty – параметр output указывает сервису, что результат стандартизации адреса необходимо вернуть в формате JSON, при этом требуется выполнить его форматирование для нужд отладки;
• query=длинная строка с кучей процентных символов "%" - параметр, в котором сервису передается почтовый адрес "москва ул. ткацкая, д. 5", который необходимо исправить и привести к стандартному виду. Адрес представлен в кодировке 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-запрос.

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

<ProcessCheckResult>
  <Address>
    <Field level="Region" name="Москва" type="г" 
           ns="1.00" ts="0.00" c="77"/>
    <Field level="District" name="" type=""/>
    <Field level="City" name="" type=""/>
    <Field level="Place" name="" type=""/>
    <Field level="Site" name="" type=""/>
    <Field level="Street" name="Ткацкая" type="ул" 
           ns="1.00" ts="1.00" c="2908"/>
    <Field level="House" name="5" type="ДОМ" ns="1.00" ts="0.00" c="1"/>
    <Field level="Building" name="" type=""/>
    <Field level="Structure" name="" type=""/>
    <Field level="Flat" name="" type=""/>
    <Field level="Zip" name="105318" type="Индекс"/>
  </Address>
  <CheckInfo>
    <String><![CDATA[москва ул. ткацкая, д. 5]]></String>
    <Time>3</Time>
    <Alts>1</Alts>
  </CheckInfo>
</ProcessCheckResult>

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

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

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

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

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

• Команда по стандартизации одного адреса: cleanse/address
• Команда по стандартизации одного телефона: cleanse/phone
• Команда по стандартизации фамилии, имени и отчества персоны: cleanse/person
• Команда по стандартизации записи из нескольких элементов разного типа: cleanse/record
• Команда по стандартизации пакета из нескольких записей: cleanse/chunk

API подсказок

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

• Команда по формированию подсказок при вводе почтового адреса одной строкой: suggest/address
• Команда по формированию подсказок при вводе ФИО одной строкой: suggest/person/solid
• Команда по стандартизации фамилии, имени и отчества персоны: suggest/person/discrete