libpostal
Walla Walla
libpostalは、統計的NLPとオープンデータを使用して、世界中の通りのアドレスを解析/正規化するためのCライブラリです。このプロジェクトの目標は、あらゆる場所で、あらゆる言語の位置ベースの文字列を理解することです。 Libpostalの背後にある研究のより包括的な概要については、（長い）入門ブログ投稿を必ずチェックしてください。
?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??
住所とそれらが表す場所は、マップ（場所検索、交通機関、オンデマンド/配信サービス、チェックイン、レビュー）を扱うアプリケーションに不可欠です。しかし、最も単純なアドレスでさえ、ローカルの慣習、略語、コンテキストが詰め込まれているため、従来のフルテキスト検索エンジンで効果的にインデックス/クエリをすることは困難です。このライブラリは、人間が使用するフリーフォームアドレスを、機械比較とフルテキストインデックスに適した清潔な正規化されたフォームに変換するのに役立ちます。 Libpostal自体は完全なジオコーダーではありませんが、ジオコーディングアプリケーションをよりスマートでよりシンプルで、より一貫した国際的にするための前処理ステップとして使用できます。
?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??
コアライブラリは、Python、Ruby、Go、Java、PHP、およびNodejs用の純粋なC.言語バインディングで書かれています。
会社がLibpostalを使用している場合は、組織にプロジェクトのスポンサーを依頼することを検討してください。人間が場所を参照したときの意味を解釈することは解決された問題とはほど遠いものであり、スポンサーシップは地理空間NLPの新しいフロンティアを追求するのに役立ちます。スポンサーとして、あなたの会社のロゴは、サイトへのリンクとともに、GitHubレポのページに顕著に表示されます。スポンサーシップ情報
個々のユーザーは、毎月の寄付を行うことで、オープンGeo NLPの研究をサポートするのにも役立ちます。
インストールする前に、次の前提条件があることを確認してください。
ubuntu/debianで
sudo apt-get install curl autoconf automake libtool pkg-config
Centos/rhel
sudo yum install curl autoconf automake libtool pkgconfig
Mac OSXで
brew install curl autoconf automake libtool pkg-config
次に、Cライブラリをインストールします。
M1 Macを使用している場合は、 --disable-sse2 ./configureコマンドに追加します。これにより、パフォーマンスが低下しますが、ビルドは成功します。
git clone https://github.com/openvenues/libpostal
cd libpostal
./bootstrap.sh
./configure --datadir=[...some dir with a few GB of space...]
make -j4
sudo make install
# On Linux it's probably a good idea to run
sudo ldconfig
LibpostalはPKG-Configをサポートしているため、PKG-Configを使用して、プログラムをリンクするために必要なフラグを印刷できます。
pkg-config --cflags libpostal # print compiler flags
pkg-config --libs libpostal # print linker flags
pkg-config --cflags --libs libpostal # print both
たとえば、app.cというプログラムを作成した場合、次のようにコンパイルできます。
gcc app.c `pkg-config --cflags --libs libpostal`
msys2/mingw
Windowsの場合、ビルド手順には現在MSYS2とMINGWが必要です。これは、http：//msys2.orgからダウンロードできます。インストールについては、MSYS2 Webサイトの手順に従ってください。
MSYS2が実行されて最新であることを確認してください。
pacman -Syu
次の前提条件をインストールします。
pacman -S autoconf automake curl git make libtool gcc mingw-w64-x86_64-gcc
次に、Cライブラリを構築します。
git clone https://github.com/openvenues/libpostal
cd libpostal
cp -rf windows/* ./
./bootstrap.sh
./configure --datadir=[...some dir with a few GB of space...]
make -j4
make install
注：DataDirを設定すると、 C:ドライブが/cに入力されます。 Libpostal Build Scriptは、パスの終わりにlibpostal自動的に追加するため、「/C」はWindowsでC:libpostalになります。
コンパイルされた.dllはsrc/.libs/ディレクトリにあり、 libpostal-1.dllと呼ばれる必要があります。
これをアプリケーションにリンクするために.libインポートライブラリが必要な場合。 Visual Studio lib.exeツールとlibpostal.def定義ファイルを使用して生成できます。
lib.exe /def:libpostal.def /out:libpostal.lib /machine:x64
Libpostalでは、代替データモデルが利用できます。 Senzing Inc.によって作成され、米国、英国、シンガポールのアドレスを改善し、米国の農村ルートアドレス処理を改善しました。このadd MODEL=senzingを有効にするには：
./configure --datadir=[...some dir with a few GB of space...] MODEL=senzing
このモデルのデータは、OpenAddress、OpenStreetMap、および顧客フィードバック（数百の記録）に基づいてSenzingによって生成されたデータから得られます。 OpenStreetMapとOpenAddressからのデータは良好ですが、完全ではないため、データセットは、誤って形成されたアドレスをフィルタリングし、誤分類されたアドレストークンを修正し、これらの条件に遭遇した場合はアドレスに属さないトークンを削除することで変更されました。
Senzingは、モデルの品質をテストおよび検証するために使用する89か国から12950のアドレスのデータセットを作成しました。データセットは、OSMからのランダムアドレスを使用して生成されました。パルスが困難なアドレスは、サポートチームと顧客を介して、libpostal githubページから得られ、このセットに追加されました。このテストセットを使用して、上院モデルはデフォルトモデルよりも4.3％優れた解析結果を得ました。
このモデルのサイズは、デフォルトモデルの1.8GBと比較して約2.2GBであるため、Storagesスペースが重要な場合は、そのことに留意してください。
このデータモデルの詳細については、https：//github.com/senzing/libpostal-dataこのモデルの問題に遭遇した場合は、分割、インストール、またはその他の問題に遭遇する場合は、https：//github.com/senzing/libpostal-dataaで報告してください。
Libpostalの国際住所パーサーは、機械学習（条件付きランダムフィールド）を使用しており、地球上のすべての生息地で10億以上の住所で訓練されています。 OpenStreetMapとOpenAddressesを構造化されたアドレスのソースとして使用し、OpenCageアドレス形式のテンプレートをhttps://github.com/opencagedata/address-formattingでトレーニングデータを構築し、ポリゴンを含む、補足し、アパート/フロア数やポケスなどのサブビルディングコンポーネントを生成します。また、略語を追加し、コンポーネントをランダムにドロップアウトするなど、パーサーを乱雑な実際の入力に対してできるだけ堅牢にします。
これらの例の解析結果は、 make時にlibpostalで構築されるインタラクティブなaddress_parserプログラムから取得されます。パーサーは、コンマとコンマなし、およびさまざまなケーシングやコンポーネントの順列を処理できることに注意してください（入力が都市または都市/郵便番号のみである場合）。
パーサーは、保有データに対して非常に高い精度を達成しています。現在、99.45％の正しいフルパール（アドレス内のすべてのトークンを正しくするための分子の1を意味します）。
Pythonバインディングを使用したパーサーAPIの例を次に示します。
from postal . parser import parse_address
parse_address ( 'The Book Club 100-106 Leonard St Shoreditch London EC2A 4RH, United Kingdom' )C APIの例：
#include <stdio.h>
#include <stdlib.h>
#include <libpostal/libpostal.h>
int main ( int argc , char * * argv ) {
// Setup (only called once at the beginning of your program)
if (! libpostal_setup () || ! libpostal_setup_parser ()) {
exit ( EXIT_FAILURE );
}
libpostal_address_parser_options_t options = libpostal_get_address_parser_default_options ();
libpostal_address_parser_response_t * parsed = libpostal_parse_address ( "781 Franklin Ave Crown Heights Brooklyn NYC NY 11216 USA" , options );
for ( size_t i = 0 ; i < parsed -> num_components ; i ++ ) {
printf ( "%s: %sn" , parsed -> labels [ i ], parsed -> components [ i ]);
}
// Free parse result
libpostal_address_parser_response_destroy ( parsed );
// Teardown (only called once at the end of your program)
libpostal_teardown ();
libpostal_teardown_parser ();
}アドレスパーサーは、トレーニングデータで定義されている文字列ラベルを技術的に使用できますが、これらは、OpenCageのアドレス形成ライブラリで定義されているフィールドに基づいて現在定義されているものです。
Expand_Address APIは、乱雑な実世界のアドレスを検索インデックス、ハッシュなどに適した正規化された同等物に変換します。
これは、Pythonバインディングを使用したインタラクティブな例です。
Libpostalには、特定のアドレスで使用される言語を検出するためにOSMトレーニングを受けた言語分類器が含まれているため、適切な正常化を適用できます。必要な唯一の入力は、生のアドレス文字列です。これは、さまざまな言語での簡単な正常化の短いリストです。
| 入力 | 出力（libpostalで複数の場合があります） |
|---|---|
| 1000 e 96th st | 120 East 96th Street |
| c/ ocho、pi 4 | Calle 8PolígonoIndustrial 4 |
| v xx setembre、20 | 20セットテンブレ20経由 |
| Quatre Vingt Douze R. del'église | 92 rue de l eglise |
| 認本度準度acÅряジェ、д4、строение7 | it€aкаретныирядом4строение7 |
| 認本度準度acÅряジェ、д4、строение7 | Ulitsa Karetnyy Ryad dom 4 Stroyeniye 7 |
| Marktstraße14 | マークストラセス14 |
Libpostalは現在、これらのタイプの正常化を60以上の言語でサポートしており、さらに追加することができます（cを書く必要なく）。
さらに読み、いくつかの奇妙なアドレスのエッジケースについては、次のように参照してください：虚偽プログラマーは住所について信じています。
簡潔にするためにPythonバインディングを使用した例を以下に示します（高レベルの言語バインディングのほとんどは似ています）：
from postal . expand import expand_address
expansions = expand_address ( 'Quatre-vingt-douze Ave des Champs-Élysées' )
assert '92 avenue des champs-elysees' in set ( expansions )C API等価はさらにいくつかの行ですが、それでもかなり単純です。
#include <stdio.h>
#include <stdlib.h>
#include <libpostal/libpostal.h>
int main ( int argc , char * * argv ) {
// Setup (only called once at the beginning of your program)
if (! libpostal_setup () || ! libpostal_setup_language_classifier ()) {
exit ( EXIT_FAILURE );
}
size_t num_expansions ;
libpostal_normalize_options_t options = libpostal_get_default_options ();
char * * expansions = libpostal_expand_address ( "Quatre-vingt-douze Ave des Champs-Élysées" , options , & num_expansions );
for ( size_t i = 0 ; i < num_expansions ; i ++ ) {
printf ( "%sn" , expansions [ i ]);
}
// Free expansions
libpostal_expansion_array_destroy ( expansions , num_expansions );
// Teardown (only called once at the end of your program)
libpostal_teardown ();
libpostal_teardown_language_classifier ();
}libpostalを構築した後：
cd src/
./libpostal "Quatre vingt douze Ave des Champs-Élysées"
1行あたり1つのアドレスを持つテキストファイルまたはストリームがある場合、コマンドラインインターフェイスはstdinからの入力も受け入れます。
cat some_file | ./libpostal --json
libpostalを構築した後：
cd src/
./address_parser
address_parserはインタラクティブなシェルです。入力アドレスのみを使用すると、Libpostalがそれらを解析して結果を印刷します。
Libpostalは、高レベルの言語で使用するように設計されています。選択した言語が表示されていない場合、または言語の拘束力を書いている場合は、お知らせください！
正式にサポートされている言語バインディング
非公式の言語バインディング
データベース拡張機能
非公式のレストAPI
libpostal rest docker
Libpostal Zeromq Docker
Libpostalは、自動テストに最大を使用しています。テストを実行するには、使用してください。
make check
テストケースを追加するのは簡単です。たとえCが錆びていない/存在していない場合でも、貢献が大好きです。文字列出力に対する文字列入力をチェックする主に機能的なテストを使用します。
Libpostalはまた、OSM（クリーン）からの数百万のアドレスと、生産ジオコーダーからの匿名化されたクエリ（それほどきれいではない）で定期的に戦闘テストされています。このプロセス中に、Valgrindを使用して、メモリリークやその他のエラーを確認します。
libpostalは、S3からいくつかのデータファイルをダウンロードする必要があります。基本ファイルは、拡張を実行するために必要なデータ構造のディスク表現です。アドレス解析の場合、モデルトレーニングには数日かかるため、完全に訓練されたモデルをS3に公開し、OSM、OpenAddressesなどに新しいアドレスが追加されると自動的に更新されます。言語分類子モデルにも同じことが言えます。
データファイルは、実行時に自動的にダウンロードされます。新しいデータファイルをチェックしてダウンロードするには、 makeを実行するか、実行できます。
libpostal_data download all $YOUR_DATA_DIR/libpostal
$ your_data_dirを、インストール中に構成するために渡されたものをすべて置き換えます。
Libpostalには、拡張、言語分類器、およびパーサーに影響を与える多くの言語ごとの辞書が含まれています。辞書を探索したり、言語の略語/フレーズを提供するには、リソース/辞書を参照してください。
機械学習では、多くの場合、良い結果を得るために大量のトレーニングデータが不可欠です。多くのオープンソースの機械学習プロジェクトは、モデルコードのみをリリースします（Googleの場合にのみ再現可能な結果）、またはトレーニング条件が不明な事前焼きモデルのいずれかです。
Libpostalは、誰もが利用できるオープンデータでトレーニングされているため、少し異なります。そのため、トレーニングパイプライン（このリポジトリのGeodataパッケージ）と、インターネットアーカイブでの結果のトレーニングデータ自体をリリースしました。 100GB以上が解凍されます。
トレーニングデータは、作成された日付までにarchive.orgに保存されます。また、最近作成されたトレーニングセットの日付を保存するcurrent_parser_training_setと呼ばれるこのレポのメインディレクトリに保存されているファイルもあります。常に最新のデータを指すには、次のようなものを試してください： latest=$(cat current_parser_training_set)試し、日付の代わりにその変数を使用します。
すべてのファイルはhttps://archive.org/download/libpostal-parser-data-yyymmdd/$fileにありますlanguagetcountrytaddress
パーサーが特定のタイプのアドレスで期待していないように機能しない場合、最良の頼りはGREP/AWKを使用してトレーニングデータを調べ、キャプチャされていないアドレスのパターン/スタイルがあるかどうかを判断することです。
略語の拡張：例：「rd」=> "road"の拡大。 Libpostalは50を超える言語をサポートしており、新しい言語を簡単に追加したり、現在の辞書を拡張したりできます。表現文法言語（中国の白人で区切られていない）は、大通りの種類が弦の端に連結され、オプションで分離される可能性があるゲルマン語と同様に、ローゼンストラセとローゼンストラセが同等であるようにサポートされています。
国際住所の解析：「123メインストリートニューヨークニューヨーク」に{"house_number"：123、 "road"： "Main Street"、 "City"： "New York"、 "State"： "New York"}を解析する条件付きランダムフィールド。パーサーは、米国/英語だけでなく、さまざまな国と言語で働いています。このモデルは、OpenCageアドレスのフォーマットリポジトリのテンプレートを使用して、世界のすべての人に住むすべての国に対してフォーマットされたタグ付けされた交通例を構築するために、10億以上の住所と住所のような文字列でトレーニングされています。多くのタイプの正常化が実行され、トレーニングデータが実際の厄介なジオコーダー入力に可能な限り密接に似ています。
言語分類：すべてのOpenStreetMapの方法でトレーニングされた多項ロジスティック回帰トレーニング（FTRLプロシティメソッドを使用してスパースを誘導する）、ADDR：*タグ、トポニム、フォーマットアドレス。ラベルは、OSM諸国のポイントインポリゴンテストと、それぞれ国の公式/地域言語の両方のポイントインポリゴンテストを使用して導き出されます。したがって、たとえば、スペイン語はスペインのデフォルト言語ですが、バスク地域のガリシア、カタルーニャなどの地域では、それぞれの地域言語がデフォルトです。辞書ベースの曖昧性は、地域の言語がオクタンのウェールズ、ブレトン、たとえば非デフォルトである場合に採用されています。辞書は、「calle」=> "c/"などの標準的なフレーズを省略するためにも使用されます（言語分類器とアドレスパーサートレーニングセットの両方で実行されます）
数値式の解析（ "Twenty First" => 21st、 "quatre-vingt-douze" => 92、再びCLDRで提供されるデータを使用して）は、30の言語をサポートします。連結された式を持つ言語を処理する例：Milleottocento => 1800。多くの君主、教皇などの名前で発生する言語（ix => 9）に関係なく、オプションでローマ数字を正常化します。
高速で正確なトークン化 /レックス：1mを超えるトークン /秒でクロックされ、UTF8ワードセグメンテーションのTR-29仕様を実装し、東アジア語のクレクターを白人ではなくキャラクターでトークン化します。
UTF8の正規化：オプションでUTF8をNFD正規化フォームに分解し、アクセントマークなどをストリップします。
音訳：例えば、€eque or => ulicaまたはulitsa。 LibpostalはICUのすべてを引く必要はありませんが、すべてのCLDR変換を使用します。注：一部の言語、特にヘブライ語、アラビア語、タイ語には母音が含まれていない可能性があるため、人間が行った音訳とはしばしば一致しません。これらの言語のいくつかに統計的トララライターターを実装することが可能かもしれません。
スクリプト検出：特定の文字列が使用するスクリプトを検出します（たとえば、フリーフォームの香港またはマカオのアドレスが同じアドレスでHANとラテン語の両方のスクリプトを使用する場合があります）。音訳では、特定のUnicodeスクリプトに適用可能なすべての音楽師を使用できます（たとえば、ギリシャ語はギリシャ語ラティン、ギリシャ語 - ラチン-BGN、ギリシャ語ラチン環境で音訳することができます）。
Libpostalは、もともと、開会プロジェクトの一部として作成され、会場の拡張の問題を解決しました。 Openvenusには、一般的なクロールからのテラバイトのWebページから派生した数百万の場所のデータセットがあります。 Common Crawlは毎月公開されているため、2つのクロールの結果をマージしても重大な重複を生成します。
Dedupingは比較的よく研究されている分野であり、Webページ、アカデミックペーパーなどのテキストドキュメントの場合は、Minhashなどのかなりまともな近似類似性方法が存在します。
ただし、物理的な住所の場合、Road == RD、California == CA、またはニューヨーク市== NYCなどの従来の略語を頻繁に使用すると、少し複雑になります。 Minhashのような手法を使用していても、おおよその試合に適しており、2つのセットのJaccardの類似性と同等のテキストに相当するため、非常に短いテキストで作業する必要があります。また、2つの同等のアドレス（1つは完全に指定されたアドレス）がN-Gramセットの重複の点であまり密接に一致しないことがよくあります。ロシア語の住所とその音訳された同等物などの非ラチンスクリプトでは、同じ場所を参照する2つのアドレスが単一の文字にさえ一致しない可能性があると考えられます。
やる気のある例として、さまざまな慣習と程度の冗長性を備えた特定のマンハッタンの通りの住所を書くための次の2つの同等の方法を検討してください。
明らかに'30 W 26th St fl＃7！= '30 West Twenty-6th Street Floor Number Number 7 '"が文字列比較の意味で7'ですが、人間はこれらの2つのアドレスが同じ物理的位置を指していることを把握できます。
Libpostalは、コンポーネントに解析された正規化された地理的文字列を作成することを目的としています。そのため、2つのアドレスが実際にどれだけうまく一致し、自動化されたサーバー側の決定を行うかについてより効果的に推論できます。
上記がジオコーディングによく似ているように聞こえる場合は、それはある意味で、オープンベンズの場合にのみ、UIまたはユーザーなしでオートコンプリートドロップダウンで正しいアドレスを選択するためにジオコーディングする必要があります。 OpenAddressesやOpenStreetMap（または上記のすべて）などのソースアドレスのデータベースが与えられている場合、Libpostalを使用して、MapReduceやStream Processingなどの設定でのアドレスdedupingやサーバー側のバッチジオコーディングなどを実装できます。
現在、アドレス固有のコンベンションを、巨大な同義語ファイル、スクリプト、カスタムアナライザー、トークナイザーなどを使用してElasticSearchなどの従来のドキュメント検索エンジンに焼きようとするのではなく、ジオコーディングは次のようになります。
このようにして、libpostalは、データセットのサイズに比べて一定の時間でファジーアドレスマッチングを実行できます。
Libpostalは、3つの理由で（重要な順に）Cで書かれています。
移植性/普及：リブポッスターは、人々が実際に日々使用する高レベルの言語をターゲットにします：Python、Go、Ruby、nodejsなど。Cの美しさは、ほぼすべてのプログラミング言語がそれに結合し、Cコンパイラがどこにでもいるので、お気に入りを選んで、拘束力を発揮することができます。 Mac/Linux（Windowsは優先事項ではありませんが、パッチを受け入れることができます）をサポートし、データファイルの標準的なAutoToolsビルドとエンディアンネスに依存しないファイル形式を持っています。 Pythonバインディングは、トレーニングデータを構築するために必要であるため、このレポの一部として維持されます。
メモリ効率：Libpostalは、マシンの構成に応じて、プロセスごとに1GB未満のRAMに制限される可能性があるMapReduce設定で実行するように設計されています。可能な限りLibpostalは、連続したアレイを使用し、トライ（連続アレイの上に構築された）、ブルームフィルター、および圧縮されたスパースマトリックスを使用して、メモリの使用を低く保ちます。モデルが単一の国または少数の国で訓練されたモデルを備えたモバイルデバイスでLibpostalを使用することができます。
パフォーマンス：これは理由でリストの最後です。 Libpostalの最適化のほとんどは、パフォーマンスではなくメモリ使用に関するものです。 Libpostalは、それが行う作業の量を考えると非常に速いです。テストしたプラットフォーム上の単一のスレッド /プロセスで10〜30Kアドレス /秒を処理できます（OSM惑星のすべてのアドレスを1時間強で処理することを意味します）。環境とさまざまな種類の入力でテストするための簡単なベンチマークプログラムをチェックしてください。 MapReduceの設定では、すべてが並行して行われているため、コアごとのパフォーマンスはそれほど重要ではありませんが、Mapzenには、インプロセスを実行する必要があるストリーミング摂取アプリケーションがあります。
Libpostalは、現代的で読みやすいC99で書かれており、次の規則を使用しています。
Libpostal RepoのGeodata Pythonパッケージには、さまざまなGEOデータセットを前処理し、使用するCモデルのトレーニングデータを構築するためのパイプラインが含まれています。このパッケージは、ほとんどのユーザーには必要ではありませんが、新しいタイプのアドレスを生成したり、Libpostalのトレーニングデータを改善することに興味がある人には、これが見られる場所です。
保有されたテストデータ（モデルが以前に見たことのないラベルの付いた分割）では、アドレスパーサーは99.45％の完全な解析の精度を達成します。
名前付きエンティティ認識などのタスクでは、F1スコアやバリエーションなどを使用することが望ましいです。これは、主にクラスバイアスの問題があるためです（ほとんどの単語は非実体であり、すべてのトークンの非実現を単に予測するシステムは、精度の点でかなりうまくいくでしょう）。アドレス解析の場合はそうではありません。すべてのトークンにはラベルがあり、トレーニングデータには各クラスの数百万の例があります。そのため、パフォーマンスのクリーンでシンプルで直感的な尺度であるため、精度が好ましいです。
ここでは、完全な解析の精度を使用します。つまり、アドレス内のすべてのトークンが正しい場合は、分子にパーサーに1つの「ポイント」のみを与えます。それは、単に各トークンが正しかったかどうかを見るよりも良い尺度になるはずです。
現在のパーサーはほとんどの標準アドレスで非常にうまく機能しますが、特に使用するトレーニングデータが野生のアドレスにできるだけ近いことを確認するには、改善の余地がまだあります。アドレスパーサーをさらに改善することができる2つの主要な方法があります（難易度の順に）：
バグレポート、問題、プルリクエストは大歓迎です。問題、バグレポート、またはプルリクエストを送信する前に、寄稿ガイドをお読みください。
https://github.com/openvenues/libpostal/issuesで問題を送信します。
最初のWindowsビルドに @Benk10と、プロジェクトにシームレスに統合し、Appveyor Buildをセットアップしてくれた@aeroxukに感謝します。
このソフトウェアは、MITライセンスの条件の下でオープンソースとして利用できます。
