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.

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 precision for each record.

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:

GISDK

// 1. Copy the GISDK below in the immediate execution toolbox
 // 2. The result layer should have all records geocoded,
 // with one selection set: "Address Not Found" (19 records, located by ZIP Code or City)
 //
 // All other records have been located by street address.
// Use AddTables Class to open a table file
 folder = RunMacro("G30 Tutorial Folder")
 table_file = "ParcelInfo.bin"
 opts.TableName = folder + table_file
 obj = CreateObject("AddTables", opts)
 view = obj.TableView // "ParcelInfo"
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 ParcelInfo.BIN 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
// geocode by Postal field the records not found by address
 if not_found_set <> null and layer_name <> null then do
 address_field = GetFieldFullSpec(layer_name,"Address")
 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")
 input_fields = {postal_field}
 result = geo.LocateView("POSTAL_CODE",layer_name + "|" + not_found_set, id_field, input_fields, opts)
 end
not_found_set = result.NotFoundSet
 // Finally geocode by city any remaining not-found records
 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}, null)

Python

// Before running:
// 1. Open Maptitude manually
// 2. Open the ParcelInfo.bin table, located in the Tutorial folder "C:\Users\[USERNAME]\Documents\Caliper\Maptitude 2025\Tutorial\ParcelInfo.bin"
import caliperpy
def geocode_iterative_bakeries(dk):
try:
# Assume the view/table name is provided
view = "Bakeries_Int_ID.bin"
# Create a Data.Geocoder object and set the region
geo = dk.CreateGisdkObject("gis_ui", "Data.Geocoder")
geo.SetRegion()
region_name = geo.GetRegionName()
print(f"Locating view {view} in region {region_name}")
# Get field specifications for the input view
id_field = dk.GetFieldFullSpec(view, "ID")
address_field = dk.GetFieldFullSpec(view, "Address")
postal_field = dk.GetFieldFullSpec(view, "ZIP")
city_field = dk.GetFieldFullSpec(view, "City")
state_field = dk.GetFieldFullSpec(view, "State")
# Define geocoding options
opts = {
"new_layer_name": view + "_Layer",
"out_db": "c:\\temp\\" + view + "_Layer.dbd"
}
# First pass: geocode by ADDRESS method using address and postal code
result = geo.LocateView("ADDRESS", view + "|", id_field, [address_field, None, postal_field], opts)
layer_name = result["LayerName"]
not_found_set = result.get("NotFoundSet")
# Update field specs for the newly created layer
id_field = dk.GetFieldFullSpec(layer_name, "ID")
postal_field = dk.GetFieldFullSpec(layer_name, "ZIP")
city_field = dk.GetFieldFullSpec(layer_name, "City")
state_field = dk.GetFieldFullSpec(layer_name, "State")
# If some records were not found, try geocoding again by ADDRESS
if not_found_set is not None and layer_name is not None:
input_fields = [address_field, None, postal_field]
result = geo.LocateView("ADDRESS", view + "|", id_field, input_fields, opts)
# For any records still not found, try geocoding by CITY
not_found_set = result.get("NotFoundSet")
if not_found_set is not None and layer_name is not None:
result = geo.LocateView("CITY", layer_name + "|" + not_found_set, id_field, [city_field, state_field], None)
print("Iterative geocoding result:", result)
return result
except Exception as e:
print("Error during iterative geocoding:", e)
# Example usage:
if __name__ == "__main__":
dk = caliperpy.Gisdk("Maptitude")
geocode_iterative_bakeries(dk)

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 method "1" (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"})

Python

# This Python code creates geocoded layers for all three methods
# Before running:
# Open the ParcelInfo.bin table, located in the Tutorial folder "C:\Users\[USERNAME]\Documents\Caliper\Maptitude 2025\Tutorial\ParcelInfo.bin"
import caliperpy
def geocode_postal_code(dk):
 # Fetch the view and create geocoder object
 view = dk.GetView()
 geo = dk.CreateGisdkObject("gis_ui", "Data.Geocoder")
 geo.SetRegion()
# Define geocoding options
 opts = {
 "new_layer_name": "Centered",
 "out_db": "c:\\temp\\Centered.dbd"
 }
# First attempt: method "POSTAL_CODE|1"
 result_data = geo.LocateView("POSTAL_CODE|1", view + "|", view + ".ID", [view + ".ZIP"], opts)
# Second attempt: method "POSTAL_CODE|2"
 opts["out_db"] = "c:\\temp\\Scattered.dbd"
 opts["new_layer_name"] = "Scattered evenly"
 geo.LocateView("POSTAL_CODE|2", view + "|", view + ".ID", [view + ".ZIP"], opts)
# Third attempt: method "POSTAL_CODE|3"
 opts["out_db"] = "c:\\temp\\Scattered Within 1 mile.dbd"
 opts["new_layer_name"] = "Scattered within 1 mile"
 geo.LocateView("POSTAL_CODE|3", view + "|", view + ".ID", [view + ".ZIP"], opts)
return result_data
# Example usage:
 if __name__ == "__main__":
 dk = caliperpy.Gisdk("Maptitude")
 geocode_postal_code(dk)

Example 3

These examples show how to output the geocoding precision. In Maptitude open and import: C:\Users\[USERNAME]\Documents\Caliper\Maptitude 2025\Tutorial\ParcelInfo.bin before running this code.

GISDK

// This example creates a layer from an address table or view and outputs the corresponding geocoding precision.
// First, import 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")
view = GetView()
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)

Python

# This example creates a layer from an address table or view and outputs the corresponding geocoding precision.
# Before running:
# Open the ParcelInfo.bin table, located in the Tutorial folder "C:\Users\[USERNAME]\Documents\Caliper\Maptitude 2025\Tutorial\ParcelInfo.bin"
import caliperpy
 def geocode_with_precision(dk):
 try:
 # Get the current view (this might return the current active table/view name)
 view = dk.GetView()
 # Optionally, retrieve field information from the view
 field_data = dk.GetFields(view, "All") # Returns (fieldNames, fieldSpecs)
 geo = dk.CreateGisdkObject("gis_ui", "Data.Geocoder")
 geo.SetRegion()
 region_name = geo.GetRegionName()
 print(f"Geocoding view {view} in region {region_name}")
 # Get field specifications for the geocoding process
 id_field = dk.GetFieldFullSpec(view, "ID")
 address_field = dk.GetFieldFullSpec(view, "Address")
 postal_field = dk.GetFieldFullSpec(view, "ZIP")
 city_field = dk.GetFieldFullSpec(view, "City")
 state_field = dk.GetFieldFullSpec(view, "State")
 # Set geocoding options, including the best_match flag and method preferences
 opts = {
 "best_match": 1, # Ensures the "Geocoding Precision" field is populated
 "try_methods": [1, 1, 1, 1, 1, 1], # Methods ordered from most to least accurate
 "new_layer_name": view + " Layer",
 "out_db": "c:\\temp\\" + view + " Layer.dbd"
 }
 # Input field specifications for the best match geocoder:
 # Order: address, address2, city, state, postal_code
 input_field_specs = [address_field, None, city_field, state_field, postal_field]
 result = geo.LocateView("ADDRESS_WIZARD", view + "|", id_field, input_field_specs, opts)
 print("Geocoding with precision result:", result)
 return result
 except Exception as e:
 print("Error during geocoding with precision:", e)
 # Example usage:
 if __name__ == "__main__":
 dk = caliperpy.Gisdk("Maptitude")
 geocode_with_precision(dk)

.NET

Please, follow this link for a C# example: Using the CaliperForm.Connection.Gisdk Class: Geocode_Table()

For information about programming Maptitude in .NET, please refer to Accessing Maptitude from .NET

VBA

' This example creates a layer from an address table or view and outputs the corresponding geocoding precision.
' Before running:
' Open the ParcelInfo.bin table, located in the Tutorial folder
' "C:\Users\[USERNAME]\Documents\Caliper\Maptitude 2025\Tutorial\ParcelInfo.bin"
Sub GeocodeWithPrecision()
On Error GoTo ErrorHandler
Dim dk As Object
Set dk = CreateObject("Maptitude.AutomationServer")
' Get the current view
Dim view As String
view = dk.Function("GetView")
' Optionally get fields
Dim fieldData As Variant
fieldData = dk.Function("GetFields", view, "All")
' Create Geocoder object
Dim geo
Set geo = dk.CreateObject("Data.Geocoder", "")
' Set region
Dim SetRegion
Set SetRegion = geo.Method("SetRegion")
' Get field full specs
Dim idField As String
Dim addressField As String
Dim postalField As String
Dim cityField As String
Dim stateField As String
idField = dk.Function("GetFieldFullSpec", view, "Customer ID")
addressField = dk.Function("GetFieldFullSpec", view, "Street Address")
postalField = dk.Function("GetFieldFullSpec", view, "ZIP Code")
cityField = dk.Function("GetFieldFullSpec", view, "City")
stateField = dk.Function("GetFieldFullSpec", view, "State")
Set PathRep = CreateObject("Scripting.Dictionary")
PathRep.Add "best_match", 1
PathRep.Add "try_methods", Array(1, 1, 1, 1, 1, 1)
PathRep.Add "new_layer_name", view + " Layer"
PathRep.Add "out_db", "c:\\temp\\" + view + " Layer.dbd"
opts = CreateOptFromDictionary(PathRep)
' Input field spec array
Dim inputFields
inputFields = Array(addressField, "", cityField, stateField, postalField)
' Run LocateView
result = geo.Method("LocateView", "ADDRESS_WIZARD", view & "|", idField, inputFields, opts)
Exit Sub
ErrorHandler:
MsgBox "Error during geocoding with precision: " & Err.Description
End Sub
Function CreateOptFromDictionary(dict) As Variant
Dim nItems, i As Integer
Dim Key, items
Dim options
nItems = dict.Count
i = 0
ReDim options(nItems - 1, 1)
For Each Key In dict.Keys()
options(i, 0) = Key
If TypeOf dict(Key) Is Object Then
Set options(i, 1) = dict(Key)
Else
options(i, 1) = dict(Key)
End If
i = i + 1
Next
CreateOptFromDictionary = options
End Function

See Also:

AddLayerDB

AddTables

Calculate Tables

Caliper.Charts

CC.ModifyTableOperations

CC.Table

Clustering

Data.Finder

Data.Geocoder

PostgreSQL Connect

PostgreSQL Command

Routing.Bands

Routing.Path

Routing.Router

Table

Utilities.Mail