The RNI plugin can match addresses returning a match score reflecting the similarity of two addresses.
As with name and date matching, the process is to create an index containing addresses, then query an address against the index.
Note
RNI is optimized for addresses in English. Non-English addresses in Latin script may also be matched; results will vary by language.
Addresses can be defined either as a set of address fields or as a single string. When defined as a string, the jpostal library is used to parse the address string into address fields.
When entered as a set of fields, the address may include any of the fields in Table 2, “Supported Address Fields” below. At least one field must be specified, but no specific fields are required.
RNI optimizes the matching algorithm to the field type. Named entity fields, such as street name, city, and state, are matched using a linguistic, statistically-based algorithm that handles name variations. Numeric and alphanumeric fields such as house number, postal code, and unit, are matched using numeric-based methods.
Table 2. Supported Address Fields
Field Name |
Description |
Example(s) |
house |
venue and building names |
"Brooklyn Academy of Music", "Empire State Building" |
houseNumber |
usually refers to the external (street-facing) building number |
"123" |
road |
street name(s) |
"Harrison Avenue" |
unit |
an apartment, unit, office, lot, or other secondary unit designator |
"Apt. 123" |
level |
expressions indicating a floor number |
"3rd Floor", "Ground Floor" |
staircase |
numbered/lettered staircase |
"2" |
entrance |
numbered/lettered entrance |
"front gate" |
suburb |
usually an unofficial neighborhood name |
"Harlem", "South Bronx", "Crown Heights" |
cityDistrict |
these are usually boroughs or districts within a city that serve some official purpose |
"Brooklyn", "Hackney", "Bratislava IV" |
city |
any human settlement including cities, towns, villages, hamlets, localities, etc. |
"Boston" |
island |
named islands |
"Maui" |
stateDistrict |
usually a second-level administrative division or county |
"Saratoga" |
state |
a first-level administrative division |
"Massachusetts" |
countryRegion |
informal subdivision of a country without any political status |
"South/Latin America" |
country |
sovereign nations and their dependent territories, anything with an ISO-3166 code |
"United States of America" |
worldRegion |
currently only used for appending "West Indies" after the country name, a pattern frequently used in the English-speaking Caribbean |
"Jamaica, West Indies" |
postCode |
postal codes used for mail sorting |
"02110" |
poBox |
post office box: typically found in non-physical (mail-only) addresses |
"28" |
-
Create an index.
curl -XPUT 'http://localhost:9200/rni-test'
-
Define a mapping for fields that will contain addresses. The type for each of these fields is "rni_address".
curl -XPUT 'http://localhost:9200/rni-test/_mapping' -H'Content-Type: application/json' -d '{
"properties" : {
"primary_name" : { "type" : "rni_name" },
"residence" : { "type" : "rni_address" }
}
}'
-
Index documents containing an address field.
curl -XPUT 'http://localhost:9200/rni-test/_doc/1' -H'Content-Type: application/json' -d '{
"primary_name" : "Joe Schmoe",
"residence" : {
"houseNumber" : "123",
"road" : "Main St",
"city" : "Boston",
"state" : "Massachusetts",
"postCode" : "02110"
}
}'
The address in the document can also be defined as a string.
curl -XPUT 'http://localhost:9200/rni-test/_doc/1' -H'Content-Type: application/json' -d '{
"primary_name" : "Joe Schmoe",
"residence" : "123 Main St, Boston, Massachusetts, 02110"
}'
RNI compares the fields in the query with the fields in the index, matching each non-blank field. Addresses do not have to contain all the same fields to be compared and matched.
As with other objects, the query for an address consists of two parts: the base query and the RNI pairwise address match rescore query.
Base Query. The base query is a standard query against the address field. Refer to Query the Index.
curl -XGET 'http://localhost:9200/rni-test/_search' -H'Content-Type: application/json' -d '{
"query" : {
"match" : {
"residence" : "{\"road\" : \"Main\", \"state\" : \"MA\"}"
}
}
}'
RNI Rescore with Addresses. Refer to Rescoring with RNI Pairwise Name Match.
curl -XGET 'http://localhost:9200/rni-test/_search' -H'Content-Type: application/json' -d '{
"query" : {
"match" : { "residence" : "{\"road\" : \"Main\", \"state\" : \"MA\"}" }
},
"rescore" : {
"query" : {
"rescore_query" : {
"function_score" : {
"address_score" : {
"field" : "residence",
"query_address" : {
"road" : "Main",
"state" : "MA"
}
}
}
},
"query_weight" : 0
}
}
}'
The query returns a hit with the RNI address match score.
"hits": {
"total" : 1,
"max_score" : 0.6057692,
"hits" : [
{
"_index" : "rni-test",
"_type" : "_doc",
"_id" : "1",
"_score" : 0.6057692,
"_source" : {
"primary_name" : "Joe Schmoe",
"residence" : {
"houseNumber" : "123",
"road" : "Main St",
"city" : "Boston",
"state" : "Massachusetts",
"postCode" : "02110"
}
}
}
]
}
The address match score is a measure of how similar the addresses are. Similar addresses have a stronger match and their address match score is closer to 1.
The address can be structured as a string for queries. The address structure for the query is independent of the format of the address in the original document. A string can be used in the query regardless of whether the indexed address was formatted with fields or as a string.
Base Query. The base query constructed with an address string.
curl -XGET 'http://localhost:9200/rni-test/_search' -H'Content-Type: application/json' -d '{
"query" : {
"match" : {"residence" : "Main, MA"}
}
}'
RNI Rescore with Addresses. The rescore query with an address string.
curl -XGET 'http://localhost:9200/rni-test/_search' -H'Content-Type: application/json' -d '{
"query" : {
"match" : { "residence" : "Main, MA" }},
"rescore" : {
"query" : {
"rescore_query" : {
"function_score" : {
"address_score" : {
"field" : "residence",
"query_address" : "Main, MA"
}
}
},
"query_weight" : 0
}
}
}'
The response displayed here returns the address as a string because the indexed document used in this example represented the address as strings. The response will return the address in the same format as the indexed document. The format of the query does not have to match the format of the indexed documents.
"hits" : {
"total" : {
"value" : 1,
"relation" : "eq"
},
"max_score" : 0.4552421,
"hits" : [
{
"_index" : "rni-test",
"_type" : "_doc",
"_id" : "1",
"_score" : 0.4552421,
"_source" : {
"primary_name" : "Joe Schmoe",
"residence" : "123 Main St, Boston, Massachusetts, 02110"
}
}
]
}
The address match score is a measure of how similar the addresses are. Similar addresses have a stronger match and their address match score is closer to 1.
Overriding Address Field Matches
RNI supports override files for address fields.
You can create or modify UTF-8 text files that specify the scores to be assigned for pairs of address fields. The files are located in plugins/rni/bt_root/rlpnc/data/addresses/ref/overrides and named for the field type, for example city.txt or state.txt. Each row in the file, with the exception of rows that begin with #, is a tab-delimited pair and optional score. The scores must be between 0 and 1.0, where 0 indicates no match, and 1.0 indicates a perfect match. If no score is provided, RNI will use the value of addressOverrideDefaultScore as set in plugins/rni/bt_root/rlpnc/data/etc/parameter_defs.yaml.
For example, the state.txt file contains entries
Alabama AL
Alabama Ala.
AL Ala.