Find with Location Index

Summary

Finds an address using a Location index.

Syntax

result_array = RunMacro("GISDK Find With Location Index", integer index_handle, string address, integer default_street_number, string|int|array postal_codes, string city, string layer_name, integer get_zips_from_map, integer interactive)

Argument Contents
index_handle A handle for a Location index, returned by theGet Location Indexmacro
address The address to find
default_street_number A default street number to use if it is missing from address, or null to assign a street number by parsing it from address
postal_codes An optional list of postal codes, which can be an integer, a string, or an array of string or integer values; if null or the wildcard string "*", search for any postal code
city An optional city name
layer_name The name of the layer corresponding to the geographic file used to create the index file
get_zips_from_map If not null or 0 (the default), try to use the U.S. ZIP Codes contained in the current map window
interactive If not null or 0 (the default), and there are multiple matching street segments, display the Please Choose A Matching Record dialog box so the user can choose the right one

Return Value

A 12 element array:

Element Type Contents
1 String Null if address was found; otherwise, the error message "Not Found"
2 Coord A coord compound variable, or null if element 1 is not null
3 String The actual street name found
4 String The actual postal code found
5 Integer The ID of the matching street feature
6 Integer The matching score, where:0 = Address not found1 = A perfect matchN+1 = A match with N errors
7 Integer The parsed input street number
8-12 N/A Reserved for future uses

Notes

  • In Caliper Script, you must set the Geocode UI to be the alternate interface by calling SetAlternateInterface("geocode") before running this macro. When calling these macros from VBScript, add "geocode" after the macro name and before the first argument.

  • The geocoding layer can be a point, line or area layer. It must be present in the workspace or in a map for this macro to succeed.

  • The get_zips_from_map option is available only if the address is in the United States, the current map window is centered somewhere in the United States, and the street speed-up files altzip.* and cityzip.* are installed.

  • The Please Choose A Matching Record dialog box contains a scroll list of the possible matches. The user can zoom to each match and choose the right one. The macro will then return the result_array corresponding to the user’s choice.

  • When developing web applications, interactive should be set to 0 or null.

  • When the matching score indicates errors, each error can be:

    • A substitution, insertion, or deletion of a character in the street name

    • A mismatch in the street address range

    • A mismatch in the postal code

  • The matching score can be used to decide whether to accept or reject the match. It is suggested that a score of 1 be reported without warnings, a score of 2, 3, or 4 be reported with a warning message, and a score of 4 or more be treated as if no matching address was found. You should determine how to use the matching score experimentally, with a specific street layer and with specific, realistic input addresses.

Example

// Before running this example, open a map with HARTFORD.CDF and make sure that
// the Location index HARTFORD.IDX exists, both in the Tutorial folder.
folder = RunMacro("G30 Tutorial Folder")
index_file = folder + "hartford.idx"
layer_name = "Hartford Streets"
SetAlternateInterface("geocode")
index_properties = RunMacro("GISDK Get Location Index Properties",index_file)
index_handle = RunMacro("GISDK Get Location Index", index_file, layer_name,
index_properties, 25, "Feet")
result_array = RunMacro("GISDK Find With Location Index", index_handle,
"1450 Asylum Ave", , "06105", , layer_name, , 1)
ShowArray(result_array)