Address matching

Multi-line matching

Multi-line matching allows you to pass any six lines of address information to GeoStan to extract and standardize the address. To specify multi-line matching, use the following:

After processing GeoStan outputs address data in the normal address output fields. You can retrieve extraneous information from the lines that did not contain valid address data by using the appropriate multi-line enums for your language. GeoStan returns lines that contain valid address data as blank values (empty strings).

The following example uses the C language.

GeoStan takes the valid address components from GS_LINE2 and GS_LINE4 and outputs the invalid values in GS_LINE1 and GS_LINE3.

Preferences for multi-line addresses

If GeoStan finds a match, it returns the matched address as the first line (for example, GS_ADDRLINE) and returns the extraneous address information in the appropriate multi-line address line (for example, GS_LINE1).

If you do not specify a preference for a P.O. Box or a street address, GeoStan uses the value in the bottom-most address as the input address. For example, if the address is:

John Doe

123 Main St

P.O. Box 24

New York, NY

GeoStan returns P.O. Box 24.

For more information on setting these preferences see Specifying a preference for street name or P.O. Box.

Two-line matching

Two-line address matching allows you to pass two different address lines to GeoStan. GeoStan scans these two lines and extracts and standardizes a two-line address.

To specify two-line matching, use the following:

If a unit designator is present on one address line and a valid address appears on the other line, GeoStan appends the unit information to the address.

Preferences for two-line addresses

If GeoStan finds a match, it returns the matched address as the first line (for example, GS_ADDRLINE) and returns the extraneous address line as the second address (for example, GS_ADDR2).

If you do not specify a preference for a P.O. Box or a street address, GeoStan uses the value in the first line of the address as the preferred input. For more information on setting these preferences see Specifying a preference for street name or P.O. Box.

Matching dual addresses

GeoStan can process input that contains two addresses on the same address line. For example, GeoStan can process the following input address:

3138 HWY 371 PO BOX 120

PRESCOTT AR 71857

GeoStan does not recognize dual addresses where the two addresses are both street addresses. For example, GeoStan does NOT recognize 135 Main St 4750 Walnut St Ste 200.

GeoStan does recognize dual addresses where the two addresses are the same type of address but are not street addresses. For example, GeoStan does recognize PO BOX 12 PO BOX 2000.

After GeoStan parses the dual address, it searches for a match. GeoStan determines which address has preference for a match based on the processing mode. In CASS mode, GeoStan ignores the prefer PO Box and prefer street options, and attempts to find a match based on the following order: PO Box, Street, Rural Route, and General Delivery. In Relaxed or Interactive modes, GeoStan recognizes the prefer PO Box and prefer street options.

Singleline address matching

Singleline address matching allows you to pass a singleline of address information where the street address and lastline (city, state, and ZIP Code) are contained on one text line instead of the traditional two-line address. For example, GeoStan can process the following input address:

4750 WALNUT ST BOULDER CO 80301

GeoStan does not require an address component to execute geocoding. The minimum information required in the lastline component for geocoding is a ZIP Code or a valid city and state combination. If an address component is included in the input, it must precede the lastline component.

To specify singleline matching, use the following:

City name matching

Extended city name matching allows GeoStan to recognize a large number of city abbreviations.

City-only lastline matching

City-only lastline matching permits address matching with only a city in the input lastline. The input address should be provided using the two-line format (GS_ADDRLINE and GS_LASTLINE), rather than the format used in multi-line mode (GS_LINE1, GS_LINE2, GS_LINE3, etc.).

With city-only lastline input, GeoStan will search all of the states in which the input city exists. Therefore, there is the possibility of an increase in multi-matches (E023 and E030) when matching with city-only input instead of city+state lastline input.

Restrictions:

• City-only lastline input matching is not supported in CASS mode.

• City-only lastline is not supported when matching to User Dictionaries.

• When matching using city-only lastline, the GS_FIND_PREFER_ZIP_OVER_CITY setting is ignored.

• It is strongly recommended to not use city-only lastline matching in Relaxed mode to avoid the return of false-positive matches.

Match rate and performance

GeoStan's computational speed depends on a number of factors: input record quality, match mode, input address format, the number of data sets in use and the amount of requested return data. These are factors you will want to consider when:

• Determining your performance requirements and developing your design strategy;

• Analyzing and optimizing your application’s performance.

The following sections discuss these factors in more detail.

The table below illustrates the differences in match rates based on input address format and match mode. The input data comprised a set of ‘real-world’ input records that were not thoroughly cleansed and standardized.

Input record quality

The geocoding process executes more quickly and efficiently with input records that are free of misspellings and with all known address components.

Match mode

The match mode can affect match rates and performance. Assuming real-world data (imperfect input records), the match modes compare to one another as follows:

• Exact: Performs fastest with the lowest match rate.

• Close: Executes relatively fast with very good match rates.

• Relax: Performs slower than Close mode, but with higher match rates; however, there is a greater possibility that false-positive matches are returned in this mode.

• Interactive: Can only be used in singleline addressing; this mode is meant for mobile/web users.

Input address format

Geostan has multiple input address formats as follows:

• Multi-field: Each address element is input separately, e.g., address, city, state, ZIP. This yields the fastest speeds, but might have slightly lower match rates than the two-line address format.

• Two-line: The address line and lastline information are input separately. This is nearly as fast and might have slightly better match rates than the multi-field format.

• Singleline: All address elements reside on a single address line. This format is 2-3x slower than two-line, but has 1-3% better match rates.

• Multi-line: The address elements are separated into multiple lines designated as GS_LINE1, GS_LINE2, etc. This format requires more time to process and the match rate results are lower than the two-line input address format. It is not recommended to use this input format.

Data sets

The number of loaded data sets may impact performance: the more data sets in use could lengthen the geocoding processing time.

Output data

There are 100+ pieces of information that can be queried after performing a successful geocode operation, e.g., latitude, longitude, etc. The more queries performed for each record, the slower the overall geocoding rate.

Analyzing a match - Status return codes

GsDataGet can return a status code that defines the match. The match ratings are described in Status codes overview. This code defines exactly what elements of an input address were modified, or the reason a match was not made. The return value for the find method yields a high-level status match process.

Understanding Extended Match Codes

The Extended Match Codes property enables the return of additional information about any changes in the house number, unit number and unit type fields. In addition, it can indicate whether there was address information that was ignored. The Extended Match Code is only returned for address-level matches (match codes that begin with A, G, H, J, Q, R, S, T or U), in which case a 3rd hex digit is appended to the match code (see Match codes).

For information about the 3rd hex digit values for:

• Intersection matches, see Definitions for 1st-3rd hex digit match code values.

• Extended Match Codes, see Definitions for Extended Match Code (3rd hex digit) values.

"Address information ignored" is specified when any of the following conditions apply:

• The output address has a mail stop (GS_MAIL_STOP).

• The output address has a second address line (GS_ADDR2).

• The input address is a dual address (two complete addresses in the input address). For example, "4750 Walnut St. P.O Box 50".

• The input last line has extra information that is not a city, state or ZIP Code, and is ignored. For example, "Boulder, CO 80301 USA", where "USA" is ignored when matching.

The following table contains the description of the Extended Match Code 3rd hex digit return values:

To enable Extended Match Codes, use the information in the following table that is appropriate for your API:

Output ZIP Code Rule (CASS Cycle O)

CASS Cycle O has new rules about the output ZIP Code when the address does not match. A "single-ZIP city" is a city that has just one ZIP Code.

When a city and ZIP "correspond", it means they exist in the same USPS City State record. For example, BOULDER and 80301 correspond, but BOULDER and 80007 do not. 80007 is a ZIP for Arvada, CO, and Boulder is not a valid city name in 80007.

Address matching sample code

#define GEOSTAN_PROPERTIES
/* Geostan include files */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "geostan.h"
int main (int argc, char **argv)
{
 GsId gs;
 int iNumMatched = 0;
 int iNumFailed = 0;
 intl count;
 char buffer[GS_MAX_STR_LEN];
 char buffer2[GS_MAX_STR_LEN];
 char address[GS_ADDRLINE_LENGTH], 
 lastline[GS_LASTLINE_LENGTH], 
 longitude[GS_LON_LENGTH],
 latitude[GS_LAT_LENGTH], 
 matchcode[GS_MATCH_CODE_LENGTH],
 loccode[GS_LOC_CODE_LENGTH];
 /* Add addresses to this N-row, 2-column array to cause them to 
 * be processed */
 char* addresses[][2] = 
 {{"PO BOX 880066", "SAN FRANCISCO CA 94188"}, 
 {"4750 WALNUT ST STE 200", "BOULDER CO"}, 
 {"275 SKYLANE DR", "ERIE CO 80516"}, 
 {"1110 W 7th St", "Loveland CO"}, 
 {"2604 GRANDVIEW", "PLANO TX 75075"}};
 int i;
 int numAddresses = sizeof(addresses) / sizeof(*addresses);
 /* property lists for initialization and finding */
 qbool bVal;
 long lVal;
 PropList initProps;
 PropList statusProps;
 PropList findProps;
 GsPropListCreate( &initProps, GS_INIT_PROP_LIST_TYPE );
 GsPropListCreate( &statusProps, GS_STATUS_PROP_LIST_TYPE );
 GsPropListCreate( &findProps, GS_FIND_PROP_LIST_TYPE );
 /* This version strictly uses properties only */
 /* First the GeoStan properties */
 GsPropSetStr( &initProps, GS_INIT_LICFILENAME,
 "S:\\Geostan\\Java\\test\\data\\licenses\\all.lic"); 
 GsPropSetStr( &initProps, GS_INIT_DATAPATH, 
 "\\\\cog1nas1\\current\\DVDTomTom" ); 
 GsPropSetStr( &initProps, GS_INIT_Z4FILE, 
 "\\\\cog1nas1\\current\\DVDTomTom\\us.z9" ); 
 GsPropSetLong( &initProps, GS_INIT_PASSWORD, 22222222 ); 
 GsPropSetLong( &initProps, GS_INIT_GSVERSION, GS_GEOSTAN_VERSION ); 

 GsPropSetBool( &initProps, GS_INIT_OPTIONS_ADDR_CODE, TRUE ); 
 GsPropSetBool( &initProps, GS_INIT_OPTIONS_Z9_CODE, TRUE ); 
 GsPropSetBool( &initProps, GS_INIT_OPTIONS_SPATIAL_QUERY, TRUE ); 
GsPropSetLong( &initProps, GS_INIT_CACHESIZE, 0 ); 
 /* DPV properties */
 GsPropSetBool( &initProps, GS_INIT_DPV, TRUE ); 
 GsPropSetLong( &initProps, GS_INIT_DPV_DATA_ACCESS, 
 DPV_DATA_FULL_FILEIO );
 GsPropSetStr( &initProps, GS_INIT_DPV_DIRECTORY, 
 "\\\\cog1nas1\\Current\\LinkDPV" ); 
 GsPropSetStr( &initProps, GS_INIT_DPV_SECURITYKEY, 
 "C51F-02Z7-7906-Q9BG" ); 
 /* LACS properties */
 GsPropSetBool( &initProps, GS_INIT_LACSLINK, TRUE ); 
 GsPropSetStr( &initProps, GS_INIT_LACSLINK_DIRECTORY, 
 "\\\\cog1nas1\\Current\\LinkLACSLink" ); 
 GsPropSetStr( &initProps, GS_INIT_LACSLINK_SECURITY_KEY, 
 "740F-05L2-A791-51D7" ); 
 /* exercise the clearing of the lists */
 GsPropListGetCount( &initProps, &count );
 if ( count != 22 ) {
 printf( "Unexpected number of properties in initlist\n");
 exit( 1 );
 }
 /* initialize the GeoStan library */
 gs = GsInitWithProps( &initProps, &statusProps );
 GsPropListWrite( &initProps, "stdout", NULL, 0 );
 GsPropListWrite( &statusProps, "stdout", NULL, 0 );
 /* Demonstrate that the old GsInitStruct status bitfield is accessible. 
*/
 GsPropGetLong( &statusProps, GS_STATUS_STATUS_BITFIELD, &lVal );
 if ( lVal & GS_FILE_LICENSE )
 printf("Loaded GeoStan license file.\n");
 if ( lVal & GS_FILE_CITY_DIR )
 printf("Loaded GeoStan Ctyst.dir file.\n");
 /* test GeoStan status */
 if ( gs == 0 ) {
 printf("GeoStan did not initialize.\n");
 exit( 1 );
 }
 /* Now get properties from output status property list */
 GsPropGetBool( &statusProps, GS_STATUS_FILE_LICENSE, &bVal );
 if ( !bVal ) {
 printf("GeoStan license invalid.\n");
 exit( 1 );
 }
 GsPropGetBool( &statusProps, GS_STATUS_FILE_CITY_DIR, &bVal );
 if ( !bVal ) {
 printf("GeoStan citystate file could not be loaded.\n");
 exit( 1 );

 }
 GsPropGetBool( &statusProps, GS_STATUS_FILE_EXPIRED, &bVal );
 if ( bVal ) {
 printf("One or more GeoStan files have expired.\n");
 exit( 1 );
 }
 GsPropGetLong( &statusProps, GS_STATUS_FILE_MEMORY_USED, &lVal);
 printf("File Memory Used so far <%lu> megabytes.\n", lVal );
 
 GsPropGetBool( &statusProps, GS_STATUS_DPV_FILE_SECURITY, &bVal );
 if ( !bVal ) {
 printf("DPV security key failed to verify.\n");
 exit( 1 );
 }
 GsPropGetBool( &statusProps, GS_STATUS_DPV_FILE_ALL, &bVal );
 if ( !bVal ) {
 printf("DPV data failed to initialize.\n");
 exit( 1 );
 }
 
 GsPropGetBool( &statusProps, GS_STATUS_LACSLINK_FILE_SECUR, &bVal );
 if ( !bVal ) {
 printf("LacLink security key failed to verify.\n");
 exit( 1 );
 }
 
 GsPropGetBool( &statusProps, GS_STATUS_LACSLINK_FILE_ALL, &bVal );
 if ( !bVal ) {
 printf("LacsLink data failed to initialize.\n");
 exit( 1 );
 }
 if (gs == 0) {
 /* GeoStan did not initialize */
 fprintf(stderr, "GsInit failed\n" );
 GsPropListWrite( &statusProps, "c:\\temp\\out.txt", NULL, 0 );
 while (GsErrorHas(gs)) {
 GsErrorGetEx (gs, buffer, buffer2);
 printf ("%s\n%s\n", buffer, buffer2);
 }
 } else {
 /* Set find flags using properties */
 GsPropSetLong( &findProps, GS_FIND_MATCH_MODE, GS_MODE_CASS );
 GsPropSetLong( &findProps, GS_FIND_STREET_OFFSET, 50 ); 
 GsPropSetLong( &findProps, GS_FIND_CENTERLINE_OFFSET, 0 ); 
 GsPropSetStr ( &findProps, GS_FIND_CLIENT_CRS, "NAD83" ); 
 GsPropSetBool( &findProps, GS_FIND_ADDRCODE, TRUE ); 
 GsPropSetBool( &findProps, GS_FIND_Z9_CODE, TRUE ); 
 GsPropSetBool( &findProps, GS_FIND_FINANCE_SEARCH, TRUE ); 
 GsPropSetBool( &findProps, GS_FIND_MIXED_CASE, TRUE ); 
 GsPropSetBool( &findProps, GS_FIND_Z_CODE, TRUE );
 GsPropSetBool( &findProps, GS_FIND_Z5_CODE, FALSE ); 
 GsPropListWrite( &findProps, "stdout", NULL, 0 );
 /* Look up the input addresses, using the same find options 
 * each time */
 for ( i = 0; i < numAddresses; i++ ) {
 GsClear(gs);
 GsDataSet(gs, GS_ADDRLINE, addresses[i][0]);
 GsDataSet(gs, GS_LASTLINE, addresses[i][1]);
 /* this version uses the new style find */
 switch(GsFindWithProps( gs, &findProps )) {
 /* Get standardized address and geocode information */
 case GS_SUCCESS:
 /* Output the results */
 iNumMatched++;
 GsDataGet(gs, GS_OUTPUT, GS_ADDRLINE, address, 
 sizeof(address));
 GsDataGet(gs, GS_OUTPUT, GS_LASTLINE, lastline, 
 sizeof(lastline));
 GsDataGet(gs, GS_OUTPUT, GS_MATCH_CODE, matchcode, 
 sizeof(matchcode));
 GsDataGet(gs, GS_OUTPUT, GS_LOC_CODE, loccode, 
 sizeof(loccode));
 GsDataGet(gs, GS_OUTPUT, GS_LON, longitude, 
 sizeof(longitude));
 GsDataGet(gs, GS_OUTPUT, GS_LAT, latitude, sizeof(latitude));
 
printf("\n***********************************************\n");
 printf("match code: %s\nlocation code: %s\naddress: 
%s\nlastline: %s\nlongitude: %lf\nlatitude: %lf", 
 matchcode, loccode, address, lastline, 
 (double)(atof(longitude)/1000000.0), 
 (double)(atof(latitude)/1000000.0));
 printf(
 "\n***********************************************\n\n");
 fflush(stdout);
 break;
 case GS_ERROR:/* Each error can be handled */
 case GS_ADDRESS_NOT_FOUND:
 case GS_ADDRESS_NOT_RESOLVED:
 case GS_LASTLINE_NOT_FOUND:
 default: /* or just the default */
 iNumFailed++;
 fprintf(stderr, "Error geocoding address.\n");
 }
 }
 /* Terminate GeoStan */
 GsTerm (gs);
 } 
 
 /* Regardless of success or failure of GeoStan initialization, clean 
up */
 /* exercise the clearing of the lists */
 GsPropListReset( &initProps );
 GsPropListGetCount( &initProps, &count );
 if ( count != 1 ) {
 printf( "Unexpected number of properties in initlist\n");
 exit( 1 );
 }
 
 /* delete the lists */
 GsPropListDestroy( &initProps );
 GsPropListDestroy( &statusProps );
 GsPropListDestroy( &findProps );
 /* summary report */
 printf( "\nSummary of matches: \n");
 printf( " Total addresses: %d\n", numAddresses );
 printf( " Matched: %d\n", iNumMatched );
 printf( " Failed: %d\n\n", iNumFailed );
 return 0;
}