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", "POSTAL_CODE|3", "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.jsfor the current region. See Example 2 for further description of POSTAL_CODE options.
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 byGetFieldFullSpec()
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)
best_match	Boolean	When set to True it adds a [Geocoding Precission] field to the table, with a description of the geocoding level achieved.
try_methods	Array	Array of six booleans that specify the geocoding methods to try, from most accurate to least accurate, as listed in the table below (see example 3 below)

 

try_methods Array Position	Geocoding Method	Geocoding Precission Label
1	By Address and ZIP Code	Address+ZIP Code
2	By Address and Nearby ZIP Code	Address+NearZIP
3	By Exact Address and City"	ExactAddress+City
4	By Address and City	Address+City
5	By ZIP Code	ZIP Code
6	By City/State	City

 

         Note:  The methods listed are valid for the USA country dataset.  Geocoding methods change for different countries.  Please, contact Caliper Support if you need help defining the geocoding methods for countries other than the USA

 

Returns

 

LocateView() 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 LayerName and NotFoundSet keys can be used to create the input view_set for another round of LocateView() using another method. The Summary key includes complete information about the geocoding results.  See example 3 on how to obtain the geocoding precision for each record. 

 

Option	Type	Description	Availability*
NumRecords	Integer	Total number of records examined	Always
InputView	String	Name of the view supplied to the first locate step	Always
InputSet	String	Selection set passed to the first locate step	Always
NotFoundSet	String	Selection set that contains all records left unmatched after the final step	Always
Summary	Array	Aggregate locate statistics (seeSummarytable)	Always
InputIDField	String	Field used as the unique record identifier	Always
NumLocated	Integer	Total records matched by all steps	Always
GeocodingLayer	String	Layer (data source) used by the last successful method	Always
Stats	Array	Internal statistics array (seeStatstable)	Always
LayerName	String	Working layer that receives matched points	Always
OutputLayer	String	Layer that stores the final matched records	Always
MethodNames	Array	Ordered list of locate methods executed	Only whenbest_matchis True
NotFoundSets	Array	Ordered list of not found sets created by each method inMethodNames	Only whenbest_matchis True
MethodResults	Array	Per-method diagnostics (seeMethodResultstable)	Only whenbest_matchis True
Message	String	OKon success or an error message	Always

          * Keys flagged “Only when best_match is True” are omitted when the parameter is False.

 

       Keys in  the Returned Summary Option

Key	Type	Description
Total Records Examined	Integer	Total records passed to the geocoder.
Located By Address and ZIP Code	Integer	Count matched in the first method.
Located By Address and Nearby ZIP Code	Integer	Count matched in the second method.
Located By Exact Address and City	Integer	Count matched in the third method.
Located By Address and City	Integer	Count matched in the fourth method.
Located By ZIP Code	Integer	Count matched in the fifth method.
Located By City/StateInteger	Integer	Count matched in the sixth method.
Records Located	Integer	Grand total matched across all enabled steps.
Records Not Located	Integer	Grand total not matched.

 

 

      Keys in the Returned MethodResults  Option

 

        For each method in the try_methods input option, the  returned MethodResults array includes an options array with the following keys

 

Key	Type	Description
InputView	String	Name of the view (layer) that supplies the candidate records to this locate step.
InputSet	String	Selection set that is processed by the step (for step 1 this field is omitted because the set is implied).
NotFoundSet	String	Set containing records that the current step could not match; becomes theInputSetfor the next step.
InputIDField	String	Field used as the unique record identifier for reporting statistics and building the output.
NumRecords	Integer	Total records examined in this step (size ofInputSet).
NumLocated	Integer	Number of records that this step successfully geocoded.
GeocodingLayer	String	Path to the reference layer or data file used to perform the match.
Stats	Array	Internal numeric statistics for quality-tier and status reporting (layout vendor-specific).
LayerName	String	Name of the working layer that receives the matched points for this step. Available
OutputLayer	String	Layer that stores the matched records after the step completes (usually identical toLayerName).
Message	String	Status text (e.g."OK"); present only when the step is executed through a built-in locate macro that returns a textual status.

 
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

 

Python

 

 

Example 2

 

The USA Country Data Catalog provides three methods for locating data by ZIP code in Maptitude, accessible under Tools > Locate > Locate by Postal Code. These methods are represented as checkboxes in the dialog box and include:

 

• 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 geocoding process by specifying which method to use in the LocateView macro. The method is selected by passing a first argument that defines the method to be executed.

 

To call a specific method, use:

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

• The method_name is always POSTAL_CODE.

• The method_number can be 1, 2, or 3, corresponding to the three methods listed above.

If no method_number is specified, Maptitude defaults to method 1 (Centered at the ZIP Code Point).

 

This GISDK code creates a geocoded layer with poitns scattered wihtin the ZIP codes.

 

GISDK

// This GISDK code creates a geocoded layer with poitns scattered wihtin the ZIP codes.

//  Before running:

//  Open the ParcelInfo.bin table, located in the Tutorial folder "C:\Users\[USERNAME]\Documents\Caliper\Maptitude 2025\Tutorial\ParcelInfo.bin"
 

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

view = GetView()

 

opts = {  "new_layer_name": view + "_Scattered", "out_db": "c:\\temp\\Scattered.dbd"}
result = geocoder.LocateView("POSTAL_CODE|2",  view + "|" ,view  + ".ID",{view  + ".ZIP"}, opts)

 

 

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.Maptitude.connect()
    geocode_postal_code(dk)
 

 

Example 3

This example shows 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 shows how to output the geocoding precision.

//  Before running:

//     Open the ParcelInfo.bin table, located in the Tutorial folder "C:\Users\[USERNAME]\Documents\Caliper\Maptitude 2025\Tutorial\ParcelInfo.bin"

view = GetView()

{ 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)

ShowArray(result)  // inspect the returned array

 

Python

 

#This example shows how to output the 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.Maptitude.connect()
    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 shows how to output the 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

PostgreSQLConnect

PostgreSQLCommand

Routing.Bands

Routing.Path

Routing.Router

Table

Utilities.Mail