Data.Geocoder Class

Geocodes a view. See also Data.Finder class. Extends the Data.Finder Class

Every method of the Data.Finder class is available to an instance of the Data.Geocoder class, in particular SetRegion(), which should also be called first. The Data.Geocoder class adds two methods.

Methods

RunSilent()

Forces the geocoder to run silently, avoiding to display internal error messages.

LocateView(string type_and_method,string view_set,string id_field_spec,array input_field_specs,array options)

Geocodes your input view, adds or replaces the output geographic file, and opens a map with the geocoding results.

Argument	Type	Description
type_and_method	String	One of the types and methods specified in the locating_views section for the current region. For example: "ADDRESS", "POSTAL_CODE\|1", "POSTAL_CODE\|2 "CITY\|1", "CITY\|2" "STATE" or "COUNTY". If the method is omitted, the first method available for that type will be used. Types and methods are specified in the "locating_views" section in the file [country name].region.js for the current region.
view_set	String	An input "view\|set" specification for the input table and selection set to be geocoded.
id_field_spec	String	The input table ID field specification in the format returned by GetFieldFullSpec()
input_field_specs	Array	An array of input table field specifications in the format returned by GetFieldFullSpec(). If the type is "ADDRESS" then { address-field-1, address-field-2, postal-code-field , city-field , state-field }. Otherwise, an array of one or two fields, e.g., { postal-code-field } or { city-field, state-field }.
options	Array	An options array, required if the input table is not a geographic layer. See options below.

Option	Type	Description
new_layer_name	String	Desired output layer name
out_db	String	Desired output geographic file
ignore_errors	Boolean	Proceed without reporting errors to the user interface; default is False (null)

The method returns an options array with information that can be used to either report the result to the user or to continue geocoding the records not found with another method. The options LayerName and NotFoundSet can be used to create the input view_set for another round of LocateView() using another method. See example 3 on how to obtain the geocoding precission for each record.

Option	Type	Description
Error	Boolean	True (integer value 1) if an error occurred, otherwise False (null or missing)
Message	String	An error message, or the string "OK"
InputView	String	The input view name
InputSet	String	The input selection set name
NumRecords	String	The number of examined records
NumLocated	String	The number of records found
LayerName	String	The output layer name (if some records are found)
NotFoundSet	String	The output selection set storing records not found
GeocodingLayer	String	The name of the geographic layer used for geocoding your input table

Example 1

You can program iterative geocoding first by address, then by postal code, and finally by City, ending up with various "Not Found" selection sets in the output layer. If you know the "old" geocoding macros, it was quite complicated. Here is what you can do now:

// 1. Open the binary table Bakeries_Int_ID.bin

// 2. In the immediatate execution toolbox, type:

// SetLibrary("full_path\\to\\locate_bakeries_ui")

// result = RunMacro("Locate Bakeries",GetView())

// 3. The result layer should have all records geocoded,

// with two selection sets: "Address Not Found" (150 records, located by ZIP Code or City)

// and "ZIP Code Not Found" (11 records, located by City)

// Records in the "ZIP Code Not Found" set are located by City.

// Records in the "Address Not Found" set

// and *not* in the "ZIP Code Not Found" set are located by ZIP Code.

// All other records have been located by street address.

Macro "Locate Bakeries" (view)

//view = GetView() // "Bakeries_Int_ID.bin"

geo = CreateObject("Data.Geocoder").SetRegion()

region_name = geo.GetRegionName()

ShowMessage("Locating view " + view + " in region " + region_name)

id_field = GetFieldFullSpec(view,"ID") // You need an input table with an integer ID field to get started

address_field = GetFieldFullSpec(view, "Address") // These fields are in the Bakeries_Int_ID table

postal_field = GetFieldFullSpec(view, "ZIP")

city_field = GetFieldFullSpec(view, "City")

state_field = GetFieldFullSpec(view, "State")

opts = {}

opts.new_layer_name = view + "_Layer"

opts.out_db = "c:\\temp\\" + view + "_Layer.dbd"

result = geo.LocateView("ADDRESS",view + "|", id_field, {address_field, null, postal_field}, opts)

layer_name = result.LayerName

not_found_set = result.NotFoundSet

id_field = GetFieldFullSpec(layer_name,"ID") // ID, ZIP, and City are now fields in the output layer_name

postal_field = GetFieldFullSpec(layer_name,"ZIP")

city_field = GetFieldFullSpec(layer_name,"City")

state_field = GetFieldFullSpec(layer_name,"State")

geo_opts = null

if not_found_set <> null and layer_name <> null then do

// input_fields is the list of fields in the input view to use for geocoding

// in general:

// input_fields = { address_field , address_field_2 , postal_field ,

// city_field_or_value , state_field_or_value }

// in this case:

input_fields = {address_field, null, postal_field}

result = geo.LocateView("ADDRESS",view + "|", id_field, input_fields, opts)

end

not_found_set = result.NotFoundSet

if not_found_set <> null and layer_name <> null then

result = geo.LocateView("CITY", layer_name + "|" + not_found_set, id_field, {city_field, state_field}, geo_opts)

Return(result)

EndMacro

Example 2

The USA country data catalog has three methods for locating by ZIP Codes. In Maptitude they are listed as checkboxes in the dialog box under Tools>Locate>Locate by Postal Code:

Centered at the ZIP Code Point
Scattered Evenly inside the ZIP Code Area
Scattered within 1 Mile of the ZIP Code

You can program this step-by-step geocoding process by specifying which method to use in the "LocateView" macro, by passing a first argument that specifies which step to use:

result = geocoder.LocateView("method_name|method_number",...)

In this case, the method_name is “POSTAL_CODE” and the method_number is "1", "2" or "3". If you do not specify the method number, then Maptitude executes the first method in the list (Centered at the ZIP Code Point). Here is the GISDK code, in a nutshell:

geocoder = CreateObject("Data.Geocoder")

geocoder.SetRegion()

result = geocoder.LocateView("POSTAL_CODE|1","customers|",

"customers.ID",{"customers.ZIP_CODE"})

if TypeOf(result.NotFoundSet) = "string" then

result = geocoder.LocateView("POSTAL_CODE|2","customers|" + result.NotFoundSet ,"customers.ID",{"customers.ZIP_CODE"})

if TypeOf(result.NotFoundSet) = "string" then

result = geocoder.LocateView("POSTAL_CODE|3","customers|" + result.NotFoundSet ,"customers.ID",{"customers.ZIP_CODE"})

Example 3

This example shows how to output the geocoding precision.

view = GetView()

// First, inport the input table into a binary table, and modify the binary table

// by adding a string column named "Geocoding Precision"

// Insert code here to modify your table and add a "Geocoding Precision" field

// Second, geocode the table using the "ADDRESS_WIZARD" method for the current region

{ fieldNames , fieldSpecs } = GetFields(view,"All")

geo = CreateObject("Data.Geocoder").SetRegion()

region_name = geo.GetRegionName()

id_field = GetFieldFullSpec(view,"Customer ID") // You need an input table with an integer ID field to get started

address_field = GetFieldFullSpec(view, "Street Address") // These fields are in the Maptitude tutorial table

postal_field = GetFieldFullSpec(view, "ZIP Code")

city_field = GetFieldFullSpec(view, "City")

state_field = GetFieldFullSpec(view, "State")

// Geocoding options: output geographic file in Maptitude dbd format

opts = {}

opts.best_match = 1 // Important, otherwise [Geocoding Precision] will not be filled

opts.try_methods = { 1 , 1, 1, 1, 1, 1} // Which ADDRESS_WIZARD methods to try, from most accurate to least accurate

opts.new_layer_name = view + " Layer"

opts.out_db = "c:\\temp\\" + view + " Layer.dbd"

// input_field_specs must be an array of 5 elements in this order for the best

// match geocoder: { address , address2 , city , state , postal_code }

input_field_specs = { address_field , null , city_field , state_field , postal_field }

result = geo.LocateView("ADDRESS_WIZARD",view + "|", id_field, input_field_specs , opts)

See Also:

CC.ModifyTableOperations