fias 0.0.2 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 74d2bb526b9c5ea3f360d6ac0dd82ffed3c16f6c
+  data.tar.gz: 5a902f0aea4bad5260a8502bd0276f5f62ba3113
+SHA512:
+  metadata.gz: 9d19fc34bb832abacd1579193db308d29e0278adeef76b62abd6a8c9b164a1eb7dd9d993a6bb650bd3dfa932e70488943ec25ebc0d6eff4d27121bf3c05e1ab4
+  data.tar.gz: f4bfabda5028093b5107cf98ca8e4d7a0ee7d7ff0f95e9df9a967386ec6398c8c2248bc4809a3455d6ee05adfd2bdad7f86fa2c954094e3f2ef62a9f2baf1fc9

data/.gitignore

@@ -1,22 +1,15 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-coverage
-InstalledFiles
-tmp
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-.yardoc
-_yardoc
-doc/
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+test.rb

data/.rubocop.yml

@@ -0,0 +1,7 @@
+AllCops:
+  Include:
+    - ./Gemfile
+  Exclude:
+    - config/**/*
+Documentation:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 2.1
+  - 2.2
+cache: bundler
+sudo: false
+
+addons:
+  code_climate:
+    repo_token: 11011732891441d394d80e3469bc3dc1c24e1766a1b017bf2c7680e90d4b9225

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in fias.gemspec
+# Specify your gem's dependencies in fias-import.gemspec
 gemspec

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 Victor Sokolov
+Copyright (c) 2015 Victor Sokolov
 
 MIT License
 
@@ -19,4 +19,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,213 +1,317 @@
-# Федеральная Информационная Адресная Система (ФИАС)
+# FIAS
 
-Для работы с базой потребуются файлы полной БД ФИАС в формате DBF. Скачать их можно по адресу:
+[![Build Status](https://travis-ci.org/evilmartians/fias.svg)](http://travis-ci.org/evilmartians/fias)
+[![Code Climate](https://codeclimate.com/github/evilmartians/fias/badges/gpa.svg)](https://codeclimate.com/github/evilmartians/fias)
+[![Test Coverage](https://codeclimate.com/github/evilmartians/fias/badges/coverage.svg)](https://codeclimate.com/github/evilmartians/fias)
 
-    http://fias.nalog.ru/Public/DownloadPage.aspx
+Ruby wrapper for the Russian [ФИАС](http://fias.nalog.ru) database.
 
-Там же можно скачать описание структуры базы.
+Designed for usage with Ruby on Rails and a PostgreSQL backend.
 
-# Установка и подготовка базы
+<a href="https://evilmartians.com/?utm_source=fias-gem">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
+</a>
 
-1. Подключить гем
+Think twice before you decide to use a standalone copy of FIAS database in your project. [КЛАДР в облаке](https://kladr-api.ru/) could also be a solution.
 
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'fias'
 ```
-gem 'fias', git: 'https://github.com/evilmartians/kladr.git'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself:
+
+    $ gem install fias
+
+## Import into PostgreSQL
+
+    $ mkdir -p tmp/fias && cd tmp/fias
+    $ bundle exec rake fias:download | xargs wget
+    $ unrar e fias_dbf.rar
+    $ bundle exec rake fias:create_tables fias:import DATABASE_URL=postgres://localhost/fias
+
+The rake task accepts options through ENV variables:
+
+* `TABLES` to specify a comma-separated list of tables to import or create. See `Fias::Import::Dbf::TABLES` for the list of key names. Use `houses` as an alias for HOUSE* tables and `nordocs` for NORDOC* tables. In most cases you'll need only the  `address_objects` table.
+* `PREFIX` for database tables prefix ('fias_' by default).
+* `PATH` to specify DBF files location ('tmp/fias' by default).
+* `DATABASE_URL` to set database credentials (required explicitly even with a Ruby on Rails project).
+
+This gem uses `COPY FROM STDIN BINARY` to import data. At the moment it works with PostgreSQL only.
+
+## Notes about FIAS
+
+1. FIAS address objects table contains a lot of fields which are useless in most cases (tax office ID, legal document ID, etc.).
+2. Address objects table contains a lot of historical records (more than 50%, in fact), which are useless in most cases.
+3. Every record in the address object table could have multiple parents. For example, "Nevsky prospekt" in Saint Petersburg has two parents: Saint Petersburg (active) and Leningrad (historical name of the city, inactive). Most hierarchy libraries do accept just one parent for a record.
+4. Using UUID type field as a primary key as it used in FIAS is not a good idea if you want to use `ancestry` or `closure_tree` gems to navigate through record tree.
+5. Typical SQL production server settings are optimized for reading, so the import process in production environment could take a dramatically long time.
+
+## Notes on initial import workflow
+
+1. Use raw FIAS tables just as a temporary data source for creating/updating primary address objects table for your application.
+2. The only requirement is to keep AOGUID, PARENTGUID and AOID fields in target table. You will need them for updating.
+3. Keep your addressing object table immutable. This will give you an ability to work with huge amounts of addressing data locally. Send the result to production environment via a SQL dump.
+4. FIAS contains some duplicates. Duplicates are records which have different UUIDs but equal names, abbrevations and nesting level. It is up to you to decide on how to deal with it: completely remove them or just mark as hidden. Krasnodar city has a lot of equally named streets situated in different districts.
+5. [closure_tree](https://github.com/mceachen/closure_tree) works great as a hierarchy backend. Use [pg_closure_tree_rebuild](https://github.com/gzigzigzeo/pg_closure_tree_rebuild) to rebuild the hierarchy table from scratch.
+
+[See example](examples/create.rb).
+
+## Toponyms
+
+Every FIAS address object has two fields: `formalname`, which holds the toponym (the name of a geographical object) and `shortname`, which holds its type (street, city, etc.). FIAS contains the list of all available `shortname` values and their corresponding long forms in the `address_object_types` table (SOCRBASE.DBF).
+
+### Canonical forms
+
+In real life people use a lot of type name variations. For example, 'проспект' can be written as 'пр' or 'пр-кт'.
+
+You can convert any variation to a canonical form:
+
+```ruby
+Fias::Name::Canonical.canonical('поселок')
+# => [
+#  'поселок', # FIAS canonical full name
+#  'п',       # FIAS canonical short name (as in address_objects table)
+#  'п.',      # Short name with dot if needed
+#  'пос',     # Alias
+#  'посёлок'  # Alias
+# ]
 ```
 
-2. Скачать и распаковать базу ФИАС в tmp/fias (по умолчанию)
+See [fias.rb](lib/fias.rb) for a list of settings.
+
+### Append type to toponym
 
-# Импорт структуры данных
+Use `Fias::Name::Append` to build toponym names in conformity with the rules of grammar:
 
-Возможны два варианта:
+```ruby
+Fias::Name::Append.append('Санкт-Петербург', 'г')
+# => ['г. Санкт-Петербург', 'город Санкт-Петербург']
+
+Fias::Name::Append.append('Невский', 'пр')
+# => ['Невский пр-кт', 'Невский проспект']
+
+Fias::Name::Append.append('Чечня', 'республика')
+# => ['Респ. Чечня', 'Республика Чечня']
 
+Fias::Name::Append.append('Чеченская', 'республика')
+# => ['Чеченская Респ.', 'Чеченская Республика']
 ```
-rake fias:create_tables [DATABASE_URL=... PREFIX=... PATH=... ONLY=...]
+
+You can pass any form of type name: full, short, an alias, with or without the dot.
+
+### Extract a toponym
+
+Sometimes you need to extract a toponym and its type from a plain string:
+
+```ruby
+Fias::Name::Extract.extract('Город Санкт-Петербург')
+# => ['Санкт-Петербург', 'город', 'г', 'г.']
+
+Fias::Name::Extract.extract('ул. Казачий Вал')
+# => ['Казачий Вал', 'улица', 'ул', 'ул.']
 ```
 
-Либо:
+### Extract house number
+
+Sometimes street names come mixed up with house numbers, and you need to extract the house number from a string to clean it up for indexing:
 
+```ruby
+Fias::Name::HouseNumber.extract('Ново-Садовая ул,303а')
+# => ['Ново-Садовая ул', '303а']
+
+Fias::Name::HouseNumber.extract('пр.Энергетиков 72/2')
+# => ['пр.Энергетиков', '72/2']
 ```
-rails g fias:migration [--path=... --prefix=... --only=...]
+
+## Searching
+
+Given you have a set of structured addresses:
+
+```ruby
+[
+  { region: 'Еврейская АОбл', city: 'г. Биробиджан', street: 'Шолом-Алейхема' },
+  { city: 'Санкт-Петербург', street: 'Лермонтовский проспект' }
+]
 ```
 
-Первый вариант - для использования гема вне рельсов, либо для случая, когда
-актуальная база ФИАС будет использоваться только для локального мапинга, и
-на продакшн попасть не должна.
+You need to find a FIAS item for each address in set.
 
-В параметре only можно передать имена нужных таблиц, houses - все
-таблицы домов.
+Your project may use a full-text search engine (Sphinx, ElasticSearch) or just a SQL database. Search principles are the same, but the implementation would differ. This library contains helpful modules and base classes to facilitate searching.
 
-# Импорт данных
+### Indexing
 
-```
-rake fias:import PREFIX=fias PATH=tmp/fias ONLY=address_objects
-rake fias:import PREFIX=fias PATH=tmp/fias ONLY=houses
+Each toponym consists of words; some of them are considered "special". Said "special" words could have synonyms or different forms, they could be skipped by user or could be written differently in FIAS database itself.
+
+Examples:
+
+* "50 лет Октября" == "50-летия Октября"
+* "1-ая Советская" == "1 Советская" || "Советская 1-я"
+* "Большой Проспект П.С." == "Большой Проспект Петроградской"
+* "имени Максима Горького" == "им. Горького" || "Горького"
+* "ул. Цюрупы" == "Цурюпы" || "Цюрупа" || "Цорюпы" || "Цорупа" (that's my favorite!)
+
+You should trait them as equal when performing search.
+
+Note that we are talking about toponym names with types extracted (see type extraction above).
+
+#### Splitting the words
+
+Words are split according to a set of simple rules aimed to simplify disclosure of synonyms and determination of optional parts.
+
+```ruby
+Addressing::Name::Split.split("50 лет Октября")
+# => ["50 лет", "октября"]
+
+Addressing::Name::Split.split("Ю.Р.Г.Эрвье")
+# => ["ю.р.г.", "эрвье"]
 ```
 
-Первый пример импортирует только адресные объекты (без справочников),
-второй - только дома.
+#### Finding synonyms and optional words
 
-Поддерживается импорт в Postgres и SQLite (нужно для :memory: баз)
+Given we have a street named `им. академика И.П.Павлова` in FIAS, most people will reference it as just `Павлова` street, some will write it as `имени Павлова`, and some - `академика Павлова`. Basically, nobody except the FIAS database would reference it by the exact original name.
 
-# Импорт данных в память (для рейк тасок)
+```ruby
+Addressing::Name::Synonyms.expand('им. академика И.П.Павлова')
+
+# => [["им", "имени", "им.", ""],
+# ["ак.", "академика", ""],
+# ["и.п.", ""],
+# ["павлова"]]
+```
+
+Will return all possible forms for each word. Empty strings here mark optional words.
 
 ```ruby
-ActiveRecord::Base.configurations['fias'] = {
-  :adapter  => 'sqlite3',
-  :database => ':memory:'
-}
-Fias::AddressObject.establish_connection :fias
-
-fias = Fias::DbfWrapper.new('tmp/fias')
-importer = Fias::Importer.build(
-  adapter: 'sqlite3', connection: Fias::AddressObject.connection.raw_connection
-)
-tables = fias.tables(:address_objects)
+Addressing::Name::Synonyms.tokens('им. академика И.П.Павлова')
 
-# Мигрейт. В таком виде так как стандартный мигратор всегда открывает новое
-# соединение с БД, а в случае с SQLite это означает пересоздание базы :memory:.
-Fias::AddressObject.connection.instance_exec do
-  eval(importer.schema(tables))
-end
+# => ["им", "имени", "им.", "ак.", "академика", "и.п.", "павлова"]
+```
 
-importer.import(tables) do |name, record, index|
-  record[:aclevel] == 1 # Только активные
-end
+Will return flat array with all words.
+
+You can also calculate all possible name combinations:
 
-Fias::AddressObject.count # И дальше импорт
+```ruby
+Addressing::Name::Synonyms.forms('им. И.П.Павлова')
+# => [
+#   'и.п. им павлова',
+#   'им павлова',
+#   'и.п. имени павлова',
+#   'имени павлова',
+#   'и.п. им. павлова',
+#   'им. павлова',
+#   'и.п. павлова',
+#   'павлова'
+# ]
 ```
 
-# Некоторые замечания про ФИАС
+#### Generating search index
 
-1. ФИАС хранит историю изменений информации адресных объектов. Например,
-в ней есть и Ленинград и Санкт-Петербург. Исторические версии это
-двунаправленный список.
-2. Записи базы данных ФИАС имеют признак актуальности.
-3. Ленинград и Санкт-Петербург, хотя, и хранятся в разных записях базы данных,
-являются одним и тем же территориальным образованием. Код территориального
-образования хранится в поле AOGUID. Из внешних таблиц логично ссылаться
-на AOGUID, а не на AOID.
+In search index you need:
+* name tokens (result of `Fias::Name::Synonyms.tokens`)
+* name forms (result of `Fias::Name::Synonyms.forms`)
+* ancestor ids
 
-# Маппинг, он же итерирование
+See [indexing example](examples/generate_index.rb).
 
-Задачи:
+### Querying
 
-1. Сопоставить базу приложения с ФИАСом.
-2. Уведомлять приложение об изменениях в связанных объектах ФИАСа.
-3. Уведомлять приложения о новых данных в ФИАСе.
+Performing a search will execute these three steps:
 
-В таблице, с которой устанавливаются соответствия нужно создать поле для
-хранения UUID записи ФИАСа.
+1. Preparation: sanitizing request values, splitting toponym name and type, etc.
+2. Querying: finding possible candidates in addressing object tree.
+3. Decision: determining the most suitable result depending on similarity with request.
 
-На примере регионов:
+#### Defining an in-app query class
+
+We'll use the `sequel` gem in this example.
 
 ```ruby
-# Будем искать соответствия регионов приложения регионам в ФИАС
-scope = Region
-fias_scope = Fias::AddressObject.leveled(:region)
-
-# Обработчик событий итератора
-matcher = ->(action, record, *objects) {
-  match = objects.first
-
-  case action
-
-  # Появилась новая запись в ФИАСе
-  when :created
-    puts "Region #{match.abbrevated}"
-    Region.create!(
-      fias_reference: match.id,
-      title: match.abbrevated
-    )
-
-  # Элемент в ФИАСе обновлен, нужно (?) обновить базу приложения
-  when :updated
-    record.update_attributes(
-      title: match.abbrevated,
-      fias_reference: match.id
-    )
-    puts "#{record.title} became #{match.abbrevated}"
-
-  # Объект в ФИАСе был, но из актуального состояния перешел в неактуальное.
-  # Типа, Припять: умерший город.
-  # Скорее всего, такой элемент в базе приложения нужно скрыть.
-  when :deleted
-    raise NotImplementedError, "#{record.title} #{objects.first.abbrevated}"
-
-  # Элемент в ФИАСе разделился: например, поселение Черто-Полохово
-  # было преобразовано в две деревни: Чертово и Полохово
-  # В этом случае параметр objects содержит объекты ФИАСа, на которые
-  # разделился старый.
-  when :split
-    raise NotImplementedError
-
-  # Элемент в ФИАСе объединился
-  # Типа, присоединили Московскую область к Москве
-  # В этом случае objects.first это запись ФИАС о новом объекте, а остальные
-  # элементы objects - записи ФИАС объединившихся объектов.
-  when :joined
-    raise NotImplementedError
-
-  # Элементу базы приложения нет соответствия в ФИАСе. Пытаемся сопоставить
-  # и зафиксировать, если найшли соответствующий вариант.
-  when :match
-    match = objects.detect { |b| b.actual? || b.name == record.title }
-    if match.present?
-      record.update_attributes(
-        title: match.abbrevated,
-        fias_reference: match.id
-      )
-      puts "#{record.title} became #{match.abbrevated} (new)"
-    else
-      puts "Record not found #{record.title}"
-    end
-
-  else
-    raise 'Unknown action!'
-  end
-}
+class Query
+  include Fias::Query
 
-# Итерирует существующие в базе приложения элементы
-#   fias_reference - название колонки с UUID соответствующей региону записи
-#   ФИАСа
-#   title - название региона
-fias_scope.match_existing(scope, :fias_reference, :title, &matcher)
+  def find(tokens)
+    return [] if tokens.blank? # Empty array has no type, Sequel fails.
 
-# Итерирует отсутствующие в базе приложения, но имеющиеся в скоупе
-# ФИАСа адреса.
-fias_scope.actual.match_missing(scope, :fias_reference, &matcher)
-```
+    op = Sequel.pg_array_op(:tokens)
 
-Примечания:
+    DB[:address_objects]
+      .select(:id, :name, :abbr, :parent_id, :ancestry, :forms, :tokens)
+      .where(op.overlaps(tokens))
+      .to_a
+  end
+end
+```
 
-1. В случае неоднозначного совпадения ФИАС и приложения, нужно ставить поиск
-соответствия на модерацию.
-2. В случае :split, :joined - тоже на модерацию. Хотя, разделения происходят
-и нечасто, однако, в ФИАСе таких случаев больше полутора тысяч.
-3. При начальном импорте данных из ФИАСа, #match_missing лучше начать вызывать
-только после того как соответствия старой базы ФИАСу будут полностью разрулены.
+`#find` accepts splitted object name (a result of `Fias::Name::Split.split`). It searches all address objects with their tokens matching a given set of tokens. It returns an array of hashes with keys you can see above.
 
-# Работа с данными
+* `:abbr` - FIAS shortname value.
+* `:ancestry` - array of ancestor IDs.
+* `:forms` - object name forms (`Fias::Name::Synonyms.forms`)
+* `:tokens` - object name tokens (`Fias::Name::Synonyms.tokens`)
 
-Существующие регионы:
+#### Query params
 
 ```ruby
-Fias::AddressObject.actual.leveled(:region).all
+query = Query.new(
+  region: 'Еврейская АОбл', city: 'г. Биробиджан', street: 'Шолом-Алейхема'
+)
+
+query.params.sanitized
+# => {
+#   :region => ["Еврейская", "автономная область", "Аобл", "Аобл"],
+#   :city   => ["Биробиджан", "город", "г", "г."],
+#   :street => ["Шолом-Алейхема"]
+# }
 ```
 
-Подчиненные объекты в регионе (области, районы, столица региона):
+Allowed params are: `%i(region district city subcity street)`
+
+#### Result
 
 ```ruby
-region = Fias::AddressObject.actual.leveled(:region).first
-region.children.actual
+query.perform
+#
+# [[13213, {:id=>72344, :name=>"Шолом-Алейхема", :abbr=>"ул", :parent_id=>184027, :ancestry=>[184027, 12550], :forms=>["шолом-
+# алейхема"], :tokens=>["шолом-алейхема"], :key=>:street}]]
 ```
 
-# TODO
+Result is array.
+
+* Each element of array contains two values: factor of equality and found object.
+* If there are more then one row in array it means that query results are ambigous. All elements will have same factors.
+* Array is empty if nothing found.
+
+## Notes
+
+1. People make mistakes. Search requests can have mistakes. Our goal is to minimize mistake's impact. Everything above (name forms, synonyms, etc.) is made to better understand humans. Over 50K of different real addresses written by humans was used to collect type of mistakes and deduce that rules.
+2. That's why requests are slow.
+3. In real applications there could be a lot of similar queries. It's okay to cache request results in database to prevent repeated queries. Cached items do not need TTL because FIAS changes rarely.
+4. In many cases human can resolve ambigous results or try to find result manually. It could be wise to have some kind of admin interface in your app to do that.
+
+## Contributors
+
+* Victor Sokolov (@gzigzigzeo)
+* Vlad Bokov (@razum2um)
+
+Special thanks to @gazay.
+
+## Contributing
 
-1. Индексы. Индексы. ИНДЕКСЫ.
+1. Fork it ( https://github.com/evilmartians/fias/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
 
-# Полезные ссылки
+## License
 
-* http://fias.nalog.ru/Public/DownloadPage.aspx
-* http://wiki.gis-lab.info/w/%D0%A4%D0%98%D0%90%D0%A1#.D0.A2.D0.B5.D0.BA.D1.81.D1.82.D0.BE.D0.B2.D1.8B.D0.B5_.D1.8D.D0.BB.D0.B5.D0.BC.D0.B5.D0.BD.D1.82.D1.8B_.D0.B0.D0.B4.D1.80.D0.B5.D1.81.D0.B0
-* http://basicdata.ru
+The MIT License