Использование фильтров при стандартизации почтовых адресов

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

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

Способы передачи фильтра

Фильтр передаётся сервису в рамках любой команды, подразумевающей обработку почтового адреса или группы адресов, с помощью опционального параметра afilter. Этот параметр может принимать одно из следующих значений:

• JSON или XML текст, содержащий описание фильтра в явном виде. Формат этого описания будет детально рассмотрен ниже в данной статье. Данный способ целесообразно использовать, если ваше приложение перед отправкой запроса располагает всей необходимой информацией для включения в тело фильтра. Например:

    afilter={ "priority": [ { "address": "Красноярский край" } ] }
  

• Упрощённое текстовое описание фильтра без использования полноценного JSON/XML представления. Фильтр, заданный таким способом, представляет собой простую текстовую строку, в которой передаётся название одного или нескольких адресных объектов, которым потенциально может принадлежать обрабатываемый адрес. Например:

    afilter=Московская область
  

  или

    afilter=Владимирская область, город Владимир
  

  Далее в данной статье этот способ описания фильтра будет разобран более подробно.
• Числовой идентификатор фильтра, созданного с помощью конструктора фильтров в личном кабинете и сохранённого там в разделе "Фильтры адресов". Этот способ подразумевает, что все фильтры, которые потенциально могут вам понадобиться, вы конструируете и заполняете вручную с помощью конструктора фильтров в личном кабинете сервиса. Когда очередной такой фильтр создаётся и сохраняется в личном кабинете, ему присваивается уникальный числовой идентификатор. Именно этот идентификатор можно передать сервису с помощью параметра afilter при отправке запроса, чтобы сообщить, что при обработке данного запроса должен использоваться данный фильтр. Например:

    afilter=12
  

  Подробнее о том, как конструировать и сохранять фильтры в личном кабинете можно ознакомиться по следующей ссылке: doc/pua/filters

Структура фильтра

Как бы не задавался фильтр, всегда подразумевается, что его описание представляет собой структуру из трёх правил priority, required и rejector. Каждое из этих правил соответствует своему критерию фильтрации, который применяется к обрабатываемому почтовому адресу. Любое из этих правил может быть опущено, в этом случае соответствующий критерий фильтрации применяться не будет.

Каждое из трёх указанных правил представляет собой простое перечисление достаточно крупных адресных объектов (например, городов или регионов), которым должен принадлежать почтовый адрес, для того чтобы в отношении этого адреса сработал соответствующий правилу критерий фильтрации. Как именно следует оформлять такое перечисление, зависит от используемого формата описания фильтра: JSON, XML или простой текст, каждый из которых будет рассмотрен далее. Здесь же рассмотрим критерии фильтрации, соответствующие каждому из указанных трёх правил.

• priority (приоритетное правило) – данное правило наделяет перечисленные в нём адресные объекты повышенными приоритетами. Критерий фильтрации, соответствующий данному правилу, срабатывает, если в результате распознавания почтового адреса возникло несколько вариантов, один из которых принадлежит какому-то объекту, указанному в тексте правила. В этом случае, согласно данному критерию, остальные варианты распознавания почтового адреса удаляются из результата обработки. Пример работы такого фильтра можно посмотреть по следующей ссылке: filters/priority.
• required (обязующее правило) – данное правило задаёт список объектов, которым должны принадлежать распознанные почтовые адреса в обязательном порядке. В результате работы критерия фильтрации, соответствующего данному правилу, среди вариантов распознавания адреса остаются только те из них, которые гарантированно принадлежат одному из объектов, заданных данным правилом фильтра. Если ни один из вариантов распознавания почтового адреса не принадлежит объектам, заданным в правиле фильтра, то такой почтовый адрес будет отбракован и сервис выдаст по нему пустой результат, снабдив его статусом FilteredByUser. Пример работы такого фильтра можно посмотреть здесь: filters/required.
• rejector (режекторное правило) – данное правило задаёт перечень объектов, которым обрабатываемые почтовые адреса НЕ должны принадлежать. В результате работы данного критерия фильтрации среди вариантов распознавания адреса удаляются те из них, которые принадлежат одному из объектов, перечисленных в правиле. Если в результате обработки адреса окажется, что все варианты распознавания почтового адреса принадлежат объектам, перечисленным в данном правиле фильтра, то такой почтовый адрес будет отбракован и сервис выдаст по нему пустой результат, снабдив его статусом FilteredByUser. Пример работы такого фильтра можно посмотреть по следующей ссылке: filters/rejector.

В общем случае все три правила priority, required и rejector могут присутствовать в описании фильтра, однако чаще всего на практике достаточно использовать какой-то один из них.

JSON-описание фильтра почтовых адресов

Ниже приведён пример описания фильтра в формате JSON. Для наглядности у данного фильтра заданы все три правила priority, required и rejector.

{
  "priority": 
  [ 
    { "address": "Москва", "level": "Region" } 
  ],
  
  "required": 
  [ 
    { "code": "77", "address": "г Москва" },
    { "code": "24", "address": "Красноярский край" },
    { "address": "обл Иркутская" },
    { "address": "Тюменская", "level": "Region" }
  ],
  
  "rejector":
  [
    { "address": "Тюменская область", "level": "Region" },
    { "address": "Иркутская", "level": "Region" }
  ]
}

Сам фильтр описывается с помощью JSON-объекта, в рамках которого с помощью дочерних JSON-элементов описываются три правила priority, required и rejector. А именно:

• priority – JSON-массив, задающий перечень адресных объектов приоритетного правила.
• required - JSON-массив, задающий перечень адресных объектов обязующего правила.
• rejector - JSON-массив, задающий перечень адресных объектов режекторного правила.

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

Фильтр, описанный выше, действует следующим образом. Среди всех вариантов распознавания адреса сохраняются только те, которые принадлежат четырем регионам обязующего фильтра (см. элемент required): городу Москве, Красноярскому краю, Иркутской области и Тюменской области.

Затем из оставшихся вариантов удаляются адреса, принадлежащие регионам режекторного фильтра (см. элемент rejector). В данном случае такими регионами являются Тюменская и Иркутская области.

Оставшиеся после срабатывания обязующего и режекторного фильтра варианты распознавания адреса обрабатываются приоритетным фильтром, который в нашем случае при прочих равных отдает приоритет адресам из города Москвы (см. элемент priority).

JSON-представление одного адресного объекта в рамках фильтра

Описание адресного объекта в рамках фильтра может быть выполнено двумя следующими способами.

• Описание с помощью АБР-кода объекта. В этом случае при описании объекта достаточно указать его код по внутреннему классификатору сервиса (АБР-классификатор). Такие коды можно заранее получить с помощью команды cleanse/address, если применить её к текстовому описанию объекта (более подробно о том, как получить АБР-код адресного объекта, можно узнать здесь). Например, для описания адресного объекта, соответствующего городу Екатеринбург, необходимо указать его АБР-код "66c1".
• Текстовое описание объекта. В этом случае объект описывается в виде строки, содержащей почтовый адрес объекта. Например, для описания адресного объекта, соответствующего городу Екатеринбург, необходимо указать его адрес следующим образом "обл Свердловская, г Екатеринбург". Текстовая форма записи адреса в общем случае может быть произвольной. Всякий раз, когда сервис получает в рамках фильтра описание адресного объекта в виде текста, выполняется его стандартизация и переход к АБР-коду. Данный способ является менее предпочтительным, поскольку для получения АБР-кода объекта сервис выполняет его распознавание, что приводит к замедлению обработки всего запроса в целом.
• Описание объекта в виде ссылки на запись в рамках какого-нибудь классификатора. Данная ссылка записывается в виде строки, содержащей идентификатор или код соответствующей записи классификатора. В настоящий момент поддерживается ссылка в виде ФИАС-идентификатора, указывающего на адресный объект в рамках ФИАС.

Примеры задания адресного объекта этими двумя способами приведены ниже.

{ 
  "code": "77" 
}

{ 
  "address": "Москва", 
  "level": "Region" 
}

{ 
  "address": "fias:0c5b2444-70a0-4932-980c-b4dc0d3f02b5" 
}

{
  "priority": 
  [ 
    { "code": "77", "address": "Москва" } 
  ]
}

  <filters>
    
    <!-- список регионов приоритетного правила -->
    <priority>
      <item address="г Москва" level="Region"/>
    </priority>

    <!-- список регионов обязующего правила -->
    <required>
      <item code="77" address="г Москва"/>
      <item address="Красноярский край"/>
      <item address="обл Иркутская"/>
      <item address="Тюменская" level="Region"/>
    </required>

    <!-- список регионов режекторного правила -->
    <rejector>
      <item address="Тюменская область" level="Region"/>
      <item address="Иркутская" level="Region"/>
    </rejector>

  </filters>

<item code="77" address="г Москва"/>

<item address="г Москва" level="Region"/>

<item address="fias:0c5b2444-70a0-4932-980c-b4dc0d3f02b5"/>

  <filters>
    <priority>
      <item code="77" address="г Москва"/>
    </priority>
  </filters>