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

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

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

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

Фильтр передаётся сервису в рамках любой команды, подразумевающей обработку почтового адреса или группы адресов, с помощью опционального параметра 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" 
}

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

  • code – строка, задающая АБР-код объекта. Если данный элемент присутствует в описании объекта, считается, что объект задается с помощью АБР-кода. В этом случае остальные JSON-элементы в описании объекта игнорируются.
  • address – строка, задающая почтовый адрес объекта. Данный элемент предназначен для использования текстового описания объекта, а также для описания объекта в виде ссылки на запись классификатора. Для классификатора ФИАС ссылка на объект записывается в виде текста в формате ФИАС-гуида с префиксом fias:, например, fias:0c5b2444-70a0-4932-980c-b4dc0d3f02b5
  • level – строка, содержащая имя уровня адресного объекта. Может принимать одно из значений, описанных по следующей ссылке cleanse/address#JSON-level. Данный элемент является необязательным, он позволяет подсказать сервису, какому уровню принадлежит адресный объект, текстовое описание которого приведено в элементе address. Использование данного элемента полезно, когда текстовое описание формируется на основании исходных данных сомнительного качества, так что заданному в address текстовому описанию могут соответствовать разные адресные объекты, размещённые на разных уровнях. Например, текстовому описанию Москва соответствует город-регион Москва и деревня Москва. Если мы заранее знаем, что здесь подразумевается первый вариант, то для повышения достоверности такого фильтра можно указать в описании объекта "level": "Region". Это позволит сервису осуществить более точный переход от текстового описания к его АБР-коду.

Пример передачи фильтра в формате JSON

В качестве примера рассмотрим передачу фильтра в рамках команды стандартизации одного адреса cleanse/address. Для простоты возьмём следующий фильтр, состоящий только из одного приоритетного правила, отдающего приоритет адресам города Москвы.

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

Данный фильтр содержит только один объект – город Москву, при этом используется способ описания объекта с помощью АБР-кода. Поле "address": "Москва" приведено в описании фильтра для наглядности, при реальном использовании фильтра оно будет игнорироваться, поскольку у объекта явно задан АБР-код "code": "77".

Теперь, имея данный фильтр, с помощью команды cleanse/address можно обработать адрес ул Ткацкая, дом 5, в котором явно опущено название города. Для этого необходимо передать JSON-описание фильтра в рамках параметра afilter следующим образом.

https://ahunter.ru/site/cleanse/address?user=demotoken;output=json;query=ул Ткацкая, дом 5;afilter={ "priority": [ { "code": "77", "address": "Москва" } ] }

Для наглядности в данном запросе мы не стали преобразовывать в URL-encoding строку запроса query и тело фильтра в параметре afilter. Для реальной обработки данного запроса также следует указать в параметре user настоящий API-токен вашей учётной записи.

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

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

  <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>

Описание каждого из трех правил фильтра: приоритетного, обязующего и режекторного выполняется с помощью дочерних XML-элементов priority, required и rejector соответственно. Они в свою очередь содержат списки дочерних XML-элементов item, каждый из которых содержит описание одного из адресных объектов фильтра. Описание этих объектов приведено в следующем подразделе.

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

Адресные объекты, как и в случае с JSON-представлением, могут задаваться несколькими способами: с помощью АБР-кода, посредством текстового описания и в виде ссылки на объект классификатора. Примеры задания адресного объекта этими способами приведены ниже.

Описание объекта с помощью АБР-кода

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

Текстовое описание объекта

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

Описание в виде ФИАС-ссылки

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

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

  • code – задает АБР-код объекта. Если данный атрибут присутствует в описании объекта, считается, что объект задается первым способом - с помощью АБР-кода. В этом случае остальные атрибуты элемента item игнорируются. Данный атрибут эквивалентен JSON-элементу code, описанному выше в рамках JSON-представления фильтра.
  • address – задает почтовый адрес объекта при использовании текстового способа описания, либо описания в виде ФИАС-ссылки. Данный атрибут эквивалентен JSON-элементу address, описанному выше в рамках JSON-представления фильтра.
  • level – задает имя уровня адресного объекта. Атрибут не является обязательным, он позволяет подсказать сервису, какому уровню принадлежит адресный объект, текстовое описание которого приведено в атрибуте address. Данный атрибут эквивалентен JSON-элементу level, описанному выше в рамках JSON-представления фильтра.

Пример передачи фильтра в формате XML

По аналогии с примером для JSON-описания фильтра, в качестве примера рассмотрим передачу фильтра в рамках команды стандартизации одного адреса cleanse/address. Возьмём следующий фильтр, состоящий только из одного приоритетного правила, отдающего приоритет адресам города Москвы.

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

Данный фильтр содержит только один объект – город Москву, при этом используется способ описания объекта с помощью АБР-кода.

Имея данный фильтр, с помощью команды cleanse/address можно обработать адрес ул Ткацкая, дом 5, в котором явно опущено название города. Для этого необходимо передать XML-описание фильтра в рамках параметра afilter следующим образом.

https://ahunter.ru/site/cleanse/address?user=demotoken;output=json;query=ул Ткацкая, дом 5;afilter=<filters><priority><item code="77" address="г Москва"/></priority></filters>

Для наглядности в данном запросе мы не стали преобразовывать в URL-encoding строку запроса query и тело фильтра в параметре afilter. Для реальной обработки данного запроса также следует указать в параметре user настоящий API-токен вашей учётной записи.

Упрощённое текстовое описание фильтра почтовых адресов

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

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

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

Брянская обл | Ростовская обл

Как видно из этого примера, адресные объекты задаются в виде списка, в котором они отделены друг от друга вертикальной чертой.

Имея данный фильтр, с помощью команды cleanse/address можно обработать адрес Ивановка, ул Ленина, в котором явно опущено название региона. Для этого необходимо передать текстовое описание фильтра в рамках параметра afilter следующим образом.

https://ahunter.ru/site/cleanse/address?user=demotoken;output=json;query=Ивановка, ул Ленина;afilter=Брянская обл | Ростовская обл

Для наглядности в данном запросе мы не стали преобразовывать в URL-encoding строку запроса query и тело фильтра в параметре afilter. Для реальной обработки данного запроса также следует указать в параметре user настоящий API-токен вашей учётной записи.

В результате обработки такого запроса из всех адресов, соответствующих множеству деревень и посёлков с именем Ивановка, сервис вернёт только адреса, принадлежащие Брянской и Ростовской областям, поскольку именно они указаны в фильтре.

версия сервиса:
обработано за 7 (мс)