Стандартизация телефонного номера

Команда по стандартизации телефонного номера предназначена для проверки телефонного номера на существование, приведения номера к стандартному виду с выделением кода зоны и определения его географической принадлежности.

Стандартизация телефонного номера сопровождается его обогащением информацией об операторе связи, обслуживающем данный номер.

Пример простого запроса по обработке телефона

Приведенный ниже запрос отсылает сервису на обработку телефонный номер "4991663050". При этом используется минимальное количество параметров и опций.

В данном запросе используются следующие параметры.

• user=demotoken - сообщает сервису API-токен пользователя. При отправке реального запроса вместо значения demotoken нужно подставить токен из личного кабинета.
• output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
• query=4991663050 - закодированный с использованием URL-encoding исходный телефонный номер "4991663050", подлежащий обработке. Поскольку данный запрос кроме цифр не содержит других символов, результат его преобразования в URL-encoding совпадает с исходной записью.

Рассмотрим более подробно все параметры, которые сервис может получать в рамках данной команды.

Параметры команды

Обязательные параметры для выполнения запроса.

• https://ahunter.ru/site/cleanse/phone - URL-команды.
• user=API-токен - API-токен пользователя из личного кабинета.
• output=json или output=xml - формат, в котором требуется вернуть результат обработки.
• query=строка запроса - строка, содержащая обрабатываемый телефонный номер.

Опциональные параметры.

• output=pretty - опция применима только в случае использования JSON формата ответа сервиса. Данная опция требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON текста, расставив в нем переносы строк, отступы и пробельное прореживание. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
• output=cp1251 - опция применима только в случае использования XML формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251.
• input=utf8 или input=cp1251 - кодировка UTF-8 или windows-1251, в которой представлены входные данные в параметре query.
• phonelim=число - лимит на число возвращаемых вариантов распознавания телефонного номера, в случае если телефон в исходном запросе подразумевает многозначное толкование. Если в запросе данный лимит не установлен, то в качестве лимита будет выступать значение параметра "Максимальное количество вариантов для неоднозначных телефонов", указанное в разделе "Профиль" личного кабинета пользователя.
• output=timezone – опция сообщает сервису, что при обработке телефона нужно определить его часовую зону и вернуть эту информацию в ответе сервиса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о часовой зоне адреса/телефона".

Пример запроса по обработке телефона с дополнительными опциями

Приведенный ниже запрос отсылает сервису на обработку телефонный номер "1663050" с дополнительными параметрами.

В данном запросе используются следующие параметры.

• user=demotoken - сообщает сервису API-токен пользователя.
• output=json|pretty - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво".
• phonelim=1 - сообщает сервису, что в случае многозначного распознавания телефона следует вернуть только один вариант, наиболее соответствующий исходной строке.
• query=1663050 - закодированный с использованием URL-encoding исходный телефонный номер "1663050", подлежащий обработке.

Результат запроса: стандартизованный телефон в формате JSON

Ниже приведен ответ сервиса с результатом обработки телефонного номера "301-304-99-01". Результирующий JSON-ответ получен с использованием опции output=json|pretty, позволяющей выполнить "красивое" форматирование JSON-текста.

    {
      "check_info" : {
        "alts" : 1,
        "query" : "301-304-99-01",
        "time" : 0
      },
      "phones" : [
        {
          "canon_phone_number" : "3049901",
          "first_in_range" : "3049000",
          "geo_items" : [
            {
              "address" : {
                "fields" : [
                  {
                    "c" : "3",
                    "level" : "Region",
                    "name" : "Бурятия",
                    "type" : "Респ"
                  },
                  {
                    "c" : "17",
                    "level" : "District",
                    "name" : "Северо-Байкальский",
                    "type" : "р-н"
                  },
                  {
                    "c" : "11",
                    "level" : "Place",
                    "name" : "Новый Уоян",
                    "type" : "пгт"
                  },
                  {
                    "level" : "Zip",
                    "name" : "671000",
                    "type" : "Индекс"
                  }
                ]
              },
              "rel" : 100
            }
          ],
          "is_mobile" : false,
          "last_in_range" : "3049999",
          "operator_name" : "ООО Байкал Диалог",
          "zone_of_range" : "301",
          "time_zone" : {
            "msk_zone" : "MSK+5",
            "name" : "Иркутское время",
            "utc_zone" : "UTC+8"
          }
        }
      ],
      "request_process_time" : 0
    }

Результатом стандартизации телефонного номера является JSON-объект со следующими элементами.

• phones - массив с вариантами распознавания телефонного номера. Если телефон подразумевает неоднозначное толкование, то данный массив будет содержать более одного элемента.
• check_info - объект со сводной информацией о результате обработки. Структура и назначение данного объекта аналогичны одноименному JSON-объекту, возвращаемому в результате стандартизации почтового адреса с помощью команды cleanse/address. Описание данного элемента доступно по следующей ссылке: cleanse/address#JSON-check_info.
• request_process_time - время обработки всего запроса в целом в миллисекундах.

Ниже приведено детальное описание этих элементов.

JSON-массив phones: варианты стандартизации телефона

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

Каждый элемент массива phones представляет собой JSON-объект со следующими элементами.

• is_mobile - элемент булевского типа, принимает значение true, если обработанный телефонный номер является мобильным. Значение false указывает на то, что телефон является стационарным.
• is_verified - элемент булевского типа, выводится только в случае, когда телефон обрабатывается совместно с почтовым адресом, например, в рамках команды cleanse/record или cleanse/chunk. Значение true данного флага говорит о том, что телефонный номер прошел успешную перекрестную проверку с почтовым адресом, так что его географическая принадлежность соответствует почтовому адресу.
• restored_zone - элемент булевского типа, выводится в случае, когда у телефонного номера выполнено восстановление кода зоны. Восстановление кода зоны у номера происходит в случае, если в исходном запросе у номера не была указана зона или она была приведена не полностью. Например, номер "991663050" будет приведен к стандартному виду "(499)166-30-50", при этом он будет снабжен элементом restored_zone, указывающим на то, что код зоны был восстановлен.
• canon_phone_number - строка, содержащая каноническую запись номера телефона без кода зоны.
• zone_of_range - строка с кодом зоны диапазона номеров, которому принадлежит распознанный номер. Поскольку элемент canon_phone_number содержит информацию без кода зоны, то совместно со значением zone_of_range они образуют полный целевой телефонный номер.
• first_in_range - строка с первым телефонным номером диапазона номеров, которому принадлежит обработанный телефон. Данная информация возвращается в справочных целях.
• last_in_range - строка с последним телефонным номером диапазона номеров, которому принадлежит обработанный телефон. Данная информация возвращается в справочных целях.
• operator_name - строка, содержащая название оператора связи, обслуживающего распознанный номер.
• geo_items - JSON-массив, в котором каждый элемент описывает вариант географической принадлежности распознанного номера. Телефонный номер может принадлежать диапазону номеров, обслуживаемых на территории двух соседних регионов. Поэтому в общем случае у распознанного номера может быть несколько вариантов географической принадлежности. Каждый такой вариант возвращается сервисом в виде отдельного элемента JSON-массива geo_items. Подробное описание объектов, являющихся элементами данного массива, приведено далее в соответствующем подразделе.
• time_zone – JSON-объект, содержащий информацию о часовой зоне, которой принадлежит телефонный номер. Данный объект возвращается, если в запросе указан параметр output=timezone, либо если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах информацию о часовой зоне адреса/телефона". Описание состава элементов этого объекта и их назначение приведено здесь.

JSON-массив geo_items: географическая принадлежность телефона

Данный массив является элементом JSON-объекта, соответствующего одному варианту распознавания телефонного номера в рамках JSON-массива phones. Каждому элементу массива geo_items соответствует один вариант географической принадлежности распознанного телефонного номера. Чаще всего массив geo_items содержит только один элемент, как это проиллюстрировано в примере выше. Однако в общем случае телефон может быть привязан к диапазону номеров, обслуживаемому на территории двух соседних административных районов или регионов. Еще одной причиной множественности географической принадлежности является тот факт, что информация о телефонных диапазонах попадает в базу данных сервиса из нескольких открытых источников, каждый из которых может содержать информацию о принадлежности номера разным адресным объектам. В этих случаях массив geo_items будет содержать несколько элементов по числу географических объектов, которым принадлежит распознанный номер.

Элементами массива geo_items являются JSON-объекты, каждый из которых соответствует одному варианту географической принадлежности номера. Пример одного такого JSON-объекта приведен ниже.

    {
      "address" : {
        "fields" : [
          {
            "c" : "3",
            "level" : "Region",
            "name" : "Бурятия",
            "type" : "Респ"
          },
          {
            "c" : "17",
            "level" : "District",
            "name" : "Северо-Байкальский",
            "type" : "р-н"
          },
          {
            "c" : "11",
            "level" : "Place",
            "name" : "Новый Уоян",
            "type" : "пгт"
          },
          {
            "level" : "Zip",
            "name" : "671000",
            "type" : "Индекс"
          }
        ]
      },
      "rel" : 100
    }

Объекты данного типа содержат следующие элементы.

• address - JSON-объект, описывающий адрес объекта, которому принадлежит диапазон номеров, в который попадает распознанный телефон. Содержимое данного объекта аналогично содержимому JSON-объекта, описывающего стандартизованный адрес, возвращаемый в результате выполнения команды cleanse/address. Разница заключатся лишь в том, что для компактности записи здесь в объект address выводятся только поля адреса. Это выполняется посредством JSON-массива fields, описание которого доступно по следующей ссылке cleanse/address#JSON-fields. Дополнительная информация об адресе (географические координаты, коды качества и др.) здесь не выводится. Также в рамках JSON-массива fields выводятся только заполненные адресные поля, пустые поля для сокращения записи в этот массив не выводятся.
• rel - число от 0 до 100. Данное число отражает степень достоверности информации о географической принадлежности, приведенной в JSON-объекте address. Сервис использует данные, полученные из различных открытых источников, некоторые из которых могут обладать не стопроцентной достоверностью. Для отражения данного факта предназначен данный элемент rel.

Результат запроса: стандартизованный телефон в формате XML

Здесь и далее приводится описание ответа сервиса в случае использования формата XML. По существу возвращаемые в XML-ответе элементы имеют аналогичное назначение JSON-элементам, описанным выше. Для получения ответа в формате XML необходимо в исходном запросе использовать значение параметра output=xml.

XML-ответ сервиса в результате обработки телефонного номера "382-493-21-01" имеет следующий вид.

<ProcessCheckResult>
  <Phone type="fixed">
    <Number value="(382) 4932101"/>
    <Range zone="382" first="4932100" last="4932199" 
           oper="ООО Т2 Мобайл"/>
    <GeoItem rel="100">
      <Address>
        <Field level="Region" name="Томская" type="обл" c="70"/>
        <Field level="District" name="Бакчарский" type="р-н" c="4"/>
        <Field level="Place" name="Бакчар" type="с" c="1"/>
        <Field level="Zip" name="636200" type="Индекс"/>
      </Address>
    </GeoItem>
    <TimeZone utc_zone="UTC+8" msk_zone="MSK+5" name="Иркутское время"/>
  </Phone>
  <CheckInfo>
    <String><![CDATA[382-493-21-01]]></String>
    <Time>0</Time>
    <Alts>1</Alts>
  </CheckInfo>
</ProcessCheckResult>

Результатом стандартизации телефонного номера является XML-документ со следующими дочерними элементами.

• Phone - данный XML-элемент соответствует одному из вариантов нормализации телефонного номера. Поскольку в результате обработки телефона может возникнуть несколько его вариантов распознавания, в XML-ответе может присутствовать несколько элементов Phone, каждый из которых соответствует одному из предложенных сервисом вариантов. Список из всех XML-элементов Phone является аналогом JSON-массива phones, возвращаемого в JSON-ответе сервиса.
• CheckInfo - данный XML-элемент содержит сводную информацию о результате обработки. Данный элемент является полным аналогом JSON-объекта check_info, возвращаемого в JSON-ответе сервиса. Аналогичный одноименный элемент возвращается в ответе сервиса при выполнении команды cleanse/address, его описание доступно по следующей ссылке cleanse/address#XML-CheckInfo.

Ниже приведено детальное описание этих XML-элементов.

XML-элемент Phone: вариант стандартизации телефона

Элемент Phone содержит информацию об одном варианте распознавания и интерпретации обработанного телефонного номера. Если исходный телефонный номер может быть интерпретирован неоднозначно, то в рамках ответа сервиса будет возвращено несколько дочерних элементов Phone. Список из всех XML-элементов Phone является аналогом JSON-массива phones, возвращаемого сервисом при использовании формата JSON. Количество возвращаемых элементов Phone может быть ограничено с помощью опционального параметра phonelim. Если в запросе данный лимит не установлен, то в качестве лимита будет выступать значение параметра "Максимальное количество вариантов для неоднозначных телефонов", указанное в разделе "Профиль" личного кабинета пользователя.

Элемент Phone снабжается следующими атрибутами.

• type - принимает значение fixed, если телефонный номер является стационарным. Если номер является мобильным, то принимает значение mobile. В JSON-представлении аналогом данного атрибута является булевский элемент is_mobile.
• verified - данный атрибут возвращается только в том случае, если телефонный номер обрабатывается совместно с почтовым адресом, например, в рамках команды cleanse/record или cleanse/chunk. Наличие данного флага говорит о том, что телефонный номер прошел успешную перекрестную проверку с почтовым адресом, так что его географическая принадлежность соответствует почтовому адресу. В JSON-представлении аналогом данного атрибута является булевский элемент is_verified.

В рамках элемента Phone могут присутствовать следующие дочерние элементы.

• Number - элемент содержит распознанный телефонный номер в атрибуте value. Формат записи номера в данном атрибуте имеет вид (ZZZ) NNNNNNN, где ZZZ - код зоны номера, а NNNNNNN - семизначный номер телефона в рамках зоны. В случае если зона не указана в исходном запросе, либо если ее не удалось распознать, то значение (ZZZ) будет заполнено строкой (***). Семизначная часть номера NNNNNNN является аналогом JSON-элемента canon_phone_number, возвращаемого в ответе сервиса в формате JSON.
• Range - содержит информацию о диапазоне телефонных номеров, которому принадлежит распознанный номер. Данный элемент может содержать следующие атрибуты.
  • zone - содержит номер зоны, которой принадлежит диапазон номеров, в который попал распознанный номер. Данный атрибут является аналогом JSON-элемента zone_of_range.
  • first - содержит первый телефонный номер диапазона. Данный атрибут является аналогом JSON-элемента first_in_range.
  • last - содержит последний телефонный номер диапазона. Данный атрибут является аналогом JSON-элемента last_in_range.
  • oper - содержит название оператора связи, которому принадлежит данный диапазон телефонных номеров. Данный атрибут является аналогом JSON-элемента operator_name.
• GeoItem - содержит информацию о географической принадлежности распознанного телефонного номера. Поскольку номер может быть привязан к нескольким адресным объектам, элементов GeoItem может быть несколько по числу географических принадлежностей номера. Список всех XML-элементов GeoItem является аналогом JSON-массива geo_items.
• TimeZone - содержит информацию о часовой зоне телефонного номера. Данный элемент является аналогом JSON-объекта time_zone, возвращаемого в ответе сервиса в формате JSON. Описание состава элементов этого объекта и их назначение приведено здесь.

XML-элемент GeoItem: географическая принадлежность телефона

Данный элемент является дочерним по отношению к элементу Phone и содержит информацию о географической принадлежности распознанного телефонного номера.

Пример XML-элемента GeoItem приведен ниже.

<GeoItem rel="100">
  <Address>
    <Field level="Region" name="Томская" type="обл" c="70"/>
    <Field level="District" name="Бакчарский" type="р-н" c="4"/>
    <Field level="Place" name="Бакчар" type="с" c="1"/>
    <Field level="Zip" name="636200" type="Индекс"/>
  </Address>
</GeoItem>

Элемент GeoItem содержит следующие дочерние элементы.

• Address - элемент содержит почтовый адрес объекта, которому принадлежит диапазон телефонных номеров для распознанного телефона. Данный элемент аналогичен по структуре и содержанию одноименному XML-элементу, используемому в ответе сервиса, возвращаемому при выполнении команды стандартизации адреса cleanse/address. Описание этого элемента доступно по следующей ссылке cleanse/address#XML-Address. Разница заключатся лишь в том, что для компактности записи здесь выводятся дочерние элементы Field, соответствующие непустым полям адреса. Дополнительная информация об адресе (географические координаты, коды качества и др.) здесь не выводится.

Элемент GeoItem имеет атрибут rel содержащий число от 0 до 100. Данное число отражает степень достоверности информации о географической принадлежности, приведенной в дочернем элементе Address. Данный атрибут является аналогом JSON-элемента rel.