Data.Finder Class

Geocodes an address.

Methods

SetRegion(string region_file)

Sets the region to use to find locations with this instance of the Data.Finder. You must call this method at least once before calling any other methods.

If you have installed more than one country package, you can set the region by calling this method.

Parameter

Type

Description

region_file

String

Data catalog file for the desired country package.

A data catalog file is stored in the corresponding country data folder and has the name [Country name].region.js.

ShowDialogBox()

Displays the Edit-Find dialog box over the current map window.

If a location is found, this method returns an options array with the values below. If a location is not found or the user closes the dialog box, this method returns null.

The returned options array has the following entries:

Option	Type	Description
Coord	Coord	A GISDK coordinate object
Scope	Scope	A GISDK Scope object (center,width,height)
Label	String	The text label for the found location
LocationType	String	The type of location found (e.g. "ADDRESS", "POSTAL_CODE", "CITY")

FindAddress(option_array args)

You can specify one or more of the following elements in the input options array:

Option	Type	Description
address	String	Input address string, e.g.: "1172 Beacon Street". Required
postal_code	String	Input postal code in the format required by the current region
postal_codes	Array	Input array of postal codes in the format required by the current region
city	String	Input "city, state" or "city, province" string as expected by the current region
on_screen	Boolean	If True (integer value 1) then, if no postal code and no city are specified, try to use the postal codes included for the current map location
silent	Boolean	If True (integer value 1) then run silently, avoiding displaying error messages. Default is False (null or missing)

The following elements are in the output result options array:

Option	Type	Description
Error	Boolean	True (integer value 1) if the address cannot be found, otherwise False (missing)
Message	String	A message describing the error, if the address cannot be found
Coord	Coord	A GISDK coordinate object if the address can be found, otherwise missing
StreetLayer	String	The name of the street layer database used for finding the address
RegionName	String	The country package used for finding the address
CountryCode	String	The 2-letter country code
Address	String	The street address found

Find(string type,array or string args)

Locates a point using one of the types available for the current region.

The list of available types for the current region is specified in the [Country name].region.js file in the country data folder, in the section called "locating". For most (but not all) countries, the type can be one of: "POSTAL_CODE", "CITY", "LANDMARK", "STATE" or "PROVINCE."

You store the input value n the array args. Here are some typical contents for the args array:

If input type is...	Then args should be...
"ADDRESS"	An options array with the format required by FindAddress(). The result will be an options array as returned by FindAddress().
"POSTAL_CODE"	A string postal code in the format required by the current region (e.g., "02461")
"CITY"	A "city, state" or "city, province" string in the format required by the current region (e.g. "Newton, MA"). You can also specify an array of two strings: { "city-name", "state-name" }
"STATE" or "PROVINCE"	A state name, province name, or abbreviation in the format required by the current region
"LANDMARK"	An array of the two elements { "landmark name" , "city, state" }

Both the FindAddress() and Find() methods return an options array.

If the location cannot be found, either the method returns null or the options array contains an option called Error and another one called Message:

Option	Type	Description
Error	Boolean	True (integer value 1)
Message	String	A message with the reason why the location cannot be found

If the location can be found and the input type is "ADDRESS," then the options array will contain the items Coord, StreetLayer, and RegionName.

For all other types, if N locations can be found to match the input arguments, then the options array will contain a sorted list of N rows in the database used to find the data you requested.

The general format of the result options array is:

Option	Type	Description
Message	String	"OK"
Error	Boolean	False (missing)
Type	String	The requested type, e.g., "POSTAL_CODE" or "LANDMARK"
Input	String	The standardized input string
Region	String	The name of the region used to find the location
Score	String	An internal geocoding score
Query	String	The query used to find the location in the database
Rows	Array	An array of the N records found; for each row, the first element is the row ID, the second element is the row name or label, and the other elements specify the record location (city, state)
Labels	Array	An array of N string labels that can be used to identify each record found
Scopes	Array	An array of N GISDK Scope objects, one for each record found (a Scope contains a coordinate, and a width and a height in current map units)
Layer	String	The geographic database layer name used to find the location

Examples

// Finding a Postal Code

finder = CreateObject("Data.Finder").SetRegion()

result = finder.Find("POSTAL_CODE","02461")

/* result ==

{ { "Message", "OK" },

{ "Error", null },

{ "Type", "POSTAL_CODE" },

{ "Input", "2461" },

{ "Region", "USA (Caliper) - 2012" },

{ "Query", "Select * where ZIP = 2461" },

{ "Labels", { "2461,Newton Highlands,MA" } },

{ "Scopes", { Scope(-71.208701 42.321417 5 5 Miles) } },

{ "Rows", { { 328297, 2461, "Newton Highlands", "MA" } } },

{ "Layer", "D:\\ccdata\\USA (Caliper) - 2012\\cczip5pt.cdf" } } */

// Finding a City

finder = CreateObject("Data.Finder").SetRegion()

result = finder.Find("CITY","Boston")

/* result ==

{ { "Message", "OK" },

{ "Error", null },

{ "Type", "CITY" },

{ "Input", "BOSTON" },

{ "Region", "USA (Caliper) - 2012" },

{ "Query", "Select * where LocateByCity like 'BOSTON*'" },

{ "Labels", { "Boston MA", "Bostonia CA", ... , "Boston Heights CA" } },

{ "Scopes", { Scope(-71.059773 42.358431 5 5 Miles) ,

...

Scope(-118.19535 34.059734 5 5 Miles) } },

{ "Rows", { { 1512873, "Boston MA" },

...

{ 70801, "Boston Heights CA" } } },

{ "Layer", "D:\\ccdata\\USA (Caliper) - 2012\\ccppl.cdf" } } */

// Finding an Address

finder = CreateObject("Data.Finder").SetRegion()

result = finder.Find("ADDRESS",{"address":"200 Beacon St","city":"Boston, MA","silent":true})

result = finder.FindAddress({"address":"200 Beacon St","city":"Boston, MA","silent":true})

/* result ==

{ { "Coord", Coord(-71.077761 42.354102) },

{ "Address", "200 Beacon St" },

{ "StreetLayer", "D:\\ccdata\\USA (Caliper) - 2015\\ccStreet.cdf" },

{ "RegionName", "USA (Caliper) - 2012" },

{ "CountryCode", "US" } } */

// Not Finding an Address

finder = CreateObject("Data.Finder").SetRegion()

result = finder.Find("ADDRESS",{"address":"200 Not Beacon St","city":"Boston, MA","silent":true})

/* result ==

{ { "Message", "Cannot find address 200 NOT BEACON ST BOSTON, MA..." },

{ "Error", 1 } } */

// Finding a Landmark by Name and City

finder = CreateObject("Data.Finder").SetRegion()

result = finder.Find("LANDMARK",{"target","boston ma"})

/* result ==

{ { "Message", "OK" },

{ "Type", "LANDMARK" },

{ "Input", "TARGET" },

{ "Region", "USA (HERE) - 2023 Quarter 4" },

{ "Query", "LocateByCityState = 'BOSTON MA' && LocateByName contains 'TARGET'" },

{ "Labels", { "SuperTarget,Boston,MA",

... ,

"Target Pizza & Subs,Boston,MA" } },

{ "Scopes", { Scope(-71.06274 42.32891 1 1 Miles) ,

... ,

Scope(-71.15695 42.26123 1 1 Miles) },

{ "Rows", { { 19409529, "SuperTarget", "Boston", "MA" }, ...

{ 19392529, "Target Pizza & Subs", "Boston", "MA" } } },

{ "Layer", "D:\\ccdata\\USA (HERE) - 2014 Quarter 4\\ntlandmark.cdf" } } */

See Also:

CC.ModifyTableOperations