You can also use the Message component to override a service's default processing options. The default options for a service are set in Management Console. For example, the service ValidateAddress is capable of producing output in either mixed case or upper case. Let's say that in most instances, you need upper case output. However, one of your applications requires output in mixed case. In this situation, you would set the default for casing in the ValidateAddress service to upper case and override the default casing setting for that single application using the API. For those requests that should be handled according to the defaults you have specified, it is not necessary to provide any input options in your request.

The properties for Message include context properties, such as account ID, account password, service name, and service method; option properties, which are the service-specific runtime options; and error properties, which are the error class, error message, and error stacktrace.

DataTable

The DataTable component contains the records for your input and output data. Using the methods associated with this class, you define the column names for your output and add records to the data set.

The Reset and Next methods are used to iterate over the results that are returned in a response from the server.

API Guide 13

Supported Compilers

DataRow

The DataRow contains schema information and a list of data rows. Individual records reside in rows of data. For each output data row there are record-level qualifiers, field-level data, and field-level qualifiers.

Record-level qualifiers describe the processing of the record. Record-level qualifiers include status of the request (Success, Failure, or Error) and confidence in the accuracy of the output record.

Field-level data contains the validated, standardized, or enhanced record.

Field-level qualifiers include additional data about a given field. For example, the type of a Private Mailbox according to USPS categorization is a field-level qualifier.

Server

The Server component represents the Spectrum

™

Technology Platform server. Using a Server component, you connect, disconnect, or access a specific service from the server.

Service

The Service component is used to process the message you're sending (i.e., send the input message and get back the response). The Service component has just one method: Process message.

Supported Compilers

The Spectrum

™

Technology Platform Client SDK is supported with the following compiler and runtime minimum versions.

Java

Client SDK Package Directory: clientSDK/platforms/java

Client SDK requires the Java JDK, version 1.4 or higher. This is not installed with the Client SDK.

Windows

• JDK: 1.4

• C Compiler: MSVC 6.0 SP3, MSVC 2003, MSVC 2005

• C++ Compiler: MSVC 6.0 SP3, MSVC 2003, MSVC 2005

• C# .NET: Microsoft .NET Framework 1.1

• Visual Basic: MS Visual Basic 6.0

HP-UX RISC

• JDK: 1.4

• C Compiler: cc: HP92453-01 A.11.01.21 HP C (Bundled) Compiler

• C++ Compiler: aCC: HP aC++ B3910B A.03.30 HP aC++ B3910B A.03.27

The clientSDK 32 bit lib is linked to the following libraries:

• libpthread.1

• librt.2

• libnsl.1

• libxti.2

The clientSDK 64 bit lib is linked to the following libraries:

• libpthread.1

14 Spectrum

™

Technology Platform 9.0

Chapter 1: Getting Started

• libnsl.1

• librt.2

• libdl.1

• libc.2

• libxti.2

• libdl.1

HP-UX Itanium

• JDK: 1.4

• C Compiler: cc: HP aC++/ANSI C B3910B A.06.05

• C++ Compiler: aCC: HP aC++/ANSI C B3910B A.06.05

The clientSDK 32 bit lib is linked to the following libraries:

• libpthread.so.1

• libnsl.so.1

• librt.so.1

• libxti.so.1

• libdl.so.1

The clientSDK 64 bit lib is linked to the following libraries:

• libpthread.so.1

• libnsl.so.1

• librt.so.1

• libxti.so.1

• libdl.so.1

Red Hat (32 bit)

• Operating System: Red Hat Linux 2.4.9-e.65smp

• C Compiler: gcc version 2.96 (gcc 4.1 required for the Address Now Module)

• C++ Compiler: g++ version 2.96

The clientSDK lib is linked to the following libraries:

• libstdc++-libc6.2-2.so.3

• libm.so.6

• libc.so.6

• ld-linux.so.2

Red Hat (64 bit)

• Operating System: Red Hat Linux version 2.6.9-34.0.2.ELsmp

• C Compiler: gcc version 3.4.5

• C++ Compiler: g++ version 3.4.5

The clientSDK lib is linked to the following libraries:

• libstdc++.so.6

• libm.so.6

• libgcc_s.so.1

• libpthread.so.0

• libc.so.6

• ld-linux-x86-64.so.2

API Guide 15

Supported Compilers

SuSE

• Operating System: SuSE SLES 8 (powered by UnitedLinux 1.0) (i586)\nKernel 2.4.21-295-smp (0).

• C Compiler: gcc version 3.2.2

• C++ Compiler: g++ version 3.2.2

The clientSDK lib (32 bit) is linked to the following libraries:

• libstdc++.so.5

• libm.so.6

• libgcc_s.so.1

• libc.so.6

• ld-linux.so.2

Solaris

• Operating System: Solaris 5.8

• C Compiler: cc: Forte Developer 7 C 5.4 2002/03/09

• C++ Compiler: CC: Forte Developer 7 C++ 5.4 Patch 111715-16 2005/04/28

The clientSDK 32 bit lib is linked to the following libraries:

• libpthread.so.1

• libsocket.so.1

• libnsl.so.1

• librt.so.1

• libc.so.1

• libdl.so.1

• libmp.so.2

• libaio.so.1

• libc_psr.so.1

The clientSDK 64 bit lib is linked to the following libraries:

• libpthread.so.1

• libsocket.so.1

• libnsl.so.1

• librt.so.1

• libc.so.1

• libmp.so.2

• libmd5.so.1

• libscf.so.1

• libaio.so.1

• libdoor.so.1

• libuutil.so.1

• libm.so.2

• libc_psr.so.1

• libmd5_psr.so.1

AIX

• Operating System: AIX version 5.1.0.0

• C Compiler: xlc 6.0 Visual Age C 6.0

• C++ Compiler: xlC 6.0 Visual Age C++ 6.0

The clientSDK 32 bit and 64 bit lib are linked to the following libraries:

16 Spectrum

™

Technology Platform 9.0

Chapter 1: Getting Started

• libC.a

• libc_r.a

• libpthread.a

• librtl.a

Network Protocols and Ports

The API communicates with the Spectrum

™

SOCKET. Spectrum

™

Technology Platform server using HTTP, HTTPS, or

Technology Platform typically uses port 8080 to listen for HTTP requests and port

443 for HTTPS requests. Secure Socket Layer (SSL) and Proxy (HTTP, HTTPS) features are also supported in the C, C++, COM, Java, and .NET APIs. .Net, Java, and COM APIs support Unicode; C and C++ APIs support both ASCII and Unicode.

In addition to HTTP, Spectrum

™

Technology Platform supports a persistent SOCKET connection. The high-speed SOCKET connection provides much faster performance than traditional HTTP. Spectrum

™

Technology Platform typically uses port 10119 to listen for SOCKET requests.

Using the Sample Applications

The Client SDK includes sample applications for all supported languages. The sample applications call a sample service on the Spectrum

™

Technology Platform server which changes the casing of the input data to either upper case or lower case.

1. Copy the casing-<version>.car file from ClientAPI\common\lib to the server\app\deploy folder on the Spectrum

™

Technology Platform server.

The casing service used by the sample applications is now deployed on your Spectrum

™

Technology

Platform server.

2. In the ClientAPI\platforms folder, find the samples subfolder for your platform and open the readme.txt

file for further instructions on using the sample applications.

Note:

You can modify the sample application to use one of the services you have licensed, and recompile the sample to run.

Using SSL

This procedure describes how to use SSL communication between your application and the Spectrum

™

Technology Platform server.

1. Specify the root CA that will be used for communication between your application and the Spectrum

™

Technology Platform server by doing one of the following:

Option Description

If you do not know which root CA will be used

Copy the file ca-bundle.pem to your working directory. For C/C++ and

COM, and ASP, the .pem file is located in the following folder: platform\windows\c-c++\<32or64>\<version>\lib\openssl

For ASP, some examples of a working folder are:

API Guide 17

Increasing the Timeout Value

Option Description

• If you use Internet Information Services to run ASP, copy ca-bundle.pem

to the Windows system directory (for example,

C:\Windows\system32

• If you use Internet Explorer to run ASP, copy ca-bundle.pem to the

Internet Explorer default working directory (for example,

C:\Documents and Settings\<user>\Desktop

If you know which root

CA will be used

Specify the root CA certificate in your CA bundle file.

2. In your application, when you connect to the server set the connection type to HTTPS.

Increasing the Timeout Value

If you experience timeouts between the client and server, you can increase the timeout value for the client.

• Use the setConnectionProperty method to set the timeout value.

18 Spectrum

™

Technology Platform 9.0

The C API

In this section:

•

Introduction to the C API . . . . . . . . . . . . . . . . . . . . . . . . . .20

•

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

•

Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

•

Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

•

DataTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

•

DataRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Introduction to the C API

The C API consists of the following structures:

• Server

• Service

• Message

• DataTable

• DataRow

Note:

The C API is a C wrapper around the C++ code. On Unix you can use a C++ compiler to build your C application, which is the preferred approach. However, a C compiler can also be used directly on Linux, and Solaris. On HP-UX and AIX, you need to link all the C++ required libs when you use the C compiler. To do this, run "ldd ./batch" under ..../samples/batch/bin/ to get the list of all dependent libs and put them in the link section of your makefile.

Supported Libraries

Spectrum

™

Technology Platform provides an ASCII and Unicode version C API, while the Unicode version remains as compatible as possible with the original ASCII-version API design. Spectrum

™

Technology Platform applies International Components for Unicode (ICU) in the API to support the

Unicode feature. ICU is a mature, widely used set of C/C++ libraries for Unicode support and is developed by IBM.

The Unicode standard defines a default encoding based on 16-bit code units. This is supported in ICU by the definition of the UChar to be an unsigned 16-bit integer type(unsigned short *). This is the base type for character arrays for strings in ICU. Spectrum

™

Technology Platform uses UChar as the Unicode string representation in our C API.

Note:

Not all services support the full Unicode character set. For example, the ValidateAddress service supports the ISO 8859-1 character set for US inputs and International inputs and outputs and the CP 850 character set for Canadian inputs and outputs. However, the Unicode libraries should be used whenever your input data may contain any non-ASCII character, even if the underlying service does not support the full Unicode character set.

For detailed information about UChar, please refer to the following two sites:

• icu.sourceforge.net/userguide/

• www-306.ibm.com/software/globalization/icu/index.jsp

C Libraries Supported on Windows

Each API configuration produces library files with a common base name (g1client) but with a unique suffix and possibly prefix ("lib" in the case of static libraries). The library suffixes work like this:

<lib>g1client<S><U><D>.<lib|dll>

• lib—indicates a static library.

• dll—indiates a dynamic (shared) library.

• S—indicates a single-threaded build. If this is absent it indicates a multi-threaded build.

• U—indicates a UNICODE version build. If this is absent it indicates an ASCII build.

• D—indicates a debug build. If this suffix is absent it indicates an optimized release build.

To enable the UNICODE version, the LIB_UNICODE macro definition must be in your project.

To use the static C/C++ API library UNICODE version, you need to define U_STATIC_IMPLEMENTATION in your project.

20 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

To use the dynamic version, you need to define G1CLIENT_DLL in your project.

We also provide a file called "auto_link.h" in the header file directory and it automatically links to all the corresponding libraries according to the project settings.

To call 64-bit libraries in Windows, you need to define VER_64 in your project.

Static Library

Note:

The names provided in this section are for 32-bit libraries. For 64-bit libraries, replace "32" with

"64" in the library name.

Table 1: Single Threaded/Release

g1 openssl opentop icu

ASCII

libg1client_S.lib

otlibeay32.lib otlibssl32.lib

opentop.lib

Poco

Table 2: Single Threaded/Debug

PocoXML32.lib

Unicode

libg1client_SU.lib

otlibeay32.lib otlibssl32.lib

opentopw.lib

libicuuc.lib libicudt.lib libicuin.lib

libicuio.lib

PocoXML32w.lib

g1 openssl opentop icu

ASCII

libg1client_SD.lib

otlibeay32d.lib otlibssl32d.lib

opentopd.lib

Unicode

libg1client_SUD.lib

otlibeay32d.lib otlibssl32d.lib

opentopwd.lib

libicuucd.lib libicudtd.lib

libicuind.lib libicuiod.lib

PocoXML32wd.lib

Poco PocoXML32d.lib

Table 3: Multi/Release (using Multi-Threaded CRT)

g1 openssl opentop icu

Poco

ASCII Unicode

libg1client.lib

libg1client_U.lib

otlibeay32mt.lib otlibssl32mt.lib

opentopmt.lib

opentopmtw.lib

PocoXMLmt32.lib

libicuucmt.lib libicudtmt.lib

libicuinmt.lib libicuiomt.lib

PocoXML32mtw.lib

API Guide 21

Introduction to the C API

Table 4: Multi/Debug (using Multi-Threaded CRT)

g1 openssl opentop icu

Poco

ASCII Unicode

libg1client_D.lib

libg1client_UD.lib

otlibeay32mtd.lib otlibssl32mtd.lib

opentopmtd.lib

PocoXMLmt32d.lib

opentopmtwd.lib

libicuucmtd.lib libicudtmtd.lib

libicuinmtd.lib libicuiomtd.lib

PocoXML32mtwd.lib

Dynamic Library

Note:

The names provided in this section are for 32-bit libraries. For 64-bit libraries, replace "32" with

"64" in the library name.

Table 5: Multi/Release (using Multi-Threaded CRT)

g1 openssl opentop icu

ASCII Unicode

g1client.dll

g1client_U.dll

otlibeay32mts.dll otlibssl32mts.dll

opentopmts.dll

PocoXML32mts.dll

opentopmtws.dll

icuuc32.dll icuio32.dll icuin32.dll

icudt32.dll

PocoXML32mtws.dll

Poco

Table 6: Multi/Debug (using Multi-Threaded CRT)

g1 openssl opentop icu

Poco

ASCII

g1client_D.dll

otlibeay32mtds.dll

otlibssl32mtds.dll

opentopmtds.dll

PocoXML32mtds.dll

Unicode

g1client_UD.dll

otlibeay32mtds.dll

otlibssl32mtds.dll

opentopmtwds.dll

icuuc32d.dll icuio32d.dll

icuin32d.dll icudt32d.dll

PocoXML32mtwds.dll

C Libraries Supported on Unix

Each ClientSDK configuration produces library files with a common base name (libg1client ) but with a unique suffix. Spectrum

™

Technology Platform provides a multithread and release build for ASCII version and UNICODE version.

Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

The library suffixes work like this:libg1client<U>.<so|sl|a>

• U—indicates a UNICODE version build. If this is absent it indicates an ASCII build.

To use the UNICODE version, you need to define LIB_UNICODE in your project.

In UNICODE Version C++ API, the namespace for all classes is g1client.

Table 7: AIX

g1 openssl opentop icu

Poco

Table 8: HP-UX

ASCII

libg1client.so

libcrypto.so libssl.so

libopentop-xlCmt.so

libPocoXML.so

Unicode

libg1client_U.so

libcrypto.so libssl.so

libopentop-xlCmtw.so

libotxml-xlCmtw.so

libicudata34.a libicui18n34.a

libicuio34.a libicuuc34.a

g1 openssl opentop icu

Poco

Table 9: Itanium

ASCII Unicode

libg1client.sl

libcrypto.sl libssl.sl

libcrypto.sl.0.9.7 libssl.sl.0.9.7

libopentop-accmt.sl

libg1client_U.sl

libcrypto.sl libssl.sl

libcrypto.sl.0.9.7 libssl.sl.0.9.7

libopentop-accmtw.sl

libotxml-accmtw.sl

libicudata.sl libicudata.sl.34

libicui18n.sl libicui18n.sl.34

libicuio.sl libicuio.sl.34 libicuuc.sl

libicuuc.sl.34

libPocoXML.sl

g1 openssl opentop

ASCII

libg1client.sl

libcrypto.a libssl.a

libopentop-accmt.sl

Unicode

libg1client_U.sl

libcrypto.a

libssl.a

libopentop-accmtw.sl

libotxml-accmtw.sl

API Guide 23

Introduction to the C API

icu

ASCII Unicode

libicudata.sl libicudata.sl.34

libicudata.sl.34.0 libicui18n.sl

libicui18n.sl.34 libicui18n.sl.34.0

libicuio.sl libicuio.sl.34

libicuio.sl.34.0 libicuuc.sl

libicuuc.sl.34 libicuuc.sl.34.0

Poco

Table 10: Linux

libPocoXML.sl

g1 openssl opentop icu

ASCII

libg1client.so

libcrypto.so libcrypto.so.0.9.7

libssl.so libssl.so.0.9.7

libopentop-gccmt.so

Unicode

libg1client_U.so

libcrypto.so libcrypto.so.0.9.7

libssl.so libssl.so.0.9.7

libopentop-gccmtw.so

libotxml-gccmtw.so

libicudata.so libicudata.so.34

libicui18n.so libicui18n.so.34

libicuio.so libicuio.so.34

libicuuc.so libicuuc.so.34

libPocoXML.so

Poco

Table 11: Solaris

g1 openssl opentop icu

ASCII

libg1client.so

libcrypto.so libcrypto.so.0.9.7

libssl.so libssl.so.0.9.7

libopentop-fortemt.so

Unicode

libg1client_U.so

libcrypto.so libcrypto.so.0.9.7

libssl.so libssl.so.0.9.7

libopentop-fortemtw.so

libotxml-fortemtw.so

libicudata.so libicudata.so.34

libicui18n.so libicui18n.so.34

libicuio.so libicuio.so.34

libicuuc.so libicuuc.so.34

libPocoXML.so

Poco

Constants

The C API uses two sets of constants. The first set is for the Server component, described in the table below.

24 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Table 12: Constants for the Server Component

Constant Name Description/Default Example

SERVER_HOST

SERVER_PORT

String for server host name.

Default is "localhost".

65.89.200.89

String for server port. Default is

"8080".

10119

SERVER_ACCOUNT_ID String for server account ID. No default value.

user1

SERVER_ACCOUNT_PASSWORD String for server account password. No default value.

user1

SERVER_CONNECTION_TIMEOUT String for server connection timeout, in milliseconds. Default is "5000".

50000

SERVER_CONNECTION_TYPE String for server connection type.

Currently only supports HTTP,

HTTPS, or SOCKET. Default is

"HTTP".

HTTP(S)

SERVER_PROXY_HOST String for proxy server host name.

No default value.

192.168.1.77

8080 SERVER_PROXY_PORT String for proxy server port. No default value.

SERVER_PROXY_USER String for proxy server account

ID. No default value.

SERVER_PROXY_PASSWORD String for proxy server account password. No default value.

user1 user1

The second set of constants is for the Message component.

Table 13: Constants for the Message Component

Constant Name Description Example

MESSAGE_CONTEXT_ACCOUNT_ID String for message context account ID.

user1

MESSAGE_CONTEXT_ACCOUNT_PASSWORD String for message context account password.

user1

MESSAGE_CONTEXT_SERVICE_NAME String for message context service name.

echoservice

API Guide 25

Introduction to the C API

Error Messages

Some functions return a SUCCESSFUL_RETURN or 0 (zero) value if they are successful. If it is not successful, the function returns the corresponding error code. In order to retrieve error messages, call getErrorMessage(int errorCode). For example:

Server *server = NULL; int nRet;

//Create Server server = createServer();

//set the property to the server

...

//Connect to server printf("Making connection to the server...\n"); nRet = serverConnect(server); if(nRet != SUCCESSFUL_RETURN)

{

// ASCII Version-use the following code printf(getErrorMessage(nRet));

//Unicode Version -use the following code

UChar * error = getErrorMessage(nRet));

// more code to print out the error messageÂ….

return ;

}

The C API uses the following error messages:

• Error Messages for Passing Null structure:

• "Input null DataRow"

• "Input null DataTable"

• "Input null Message"

• "Input null Server"

• Error Messages for Connection

• "Connection type not supported"

• "Client timeout"

• "Blank connection property name"

• "Blank property name"

• Error Messages for Creating DataTable:

• "Blank column name"

• "Duplicated column name"

• Error Messages for MessagePackaging Exception

• "Input Message is null"

• "Failed to connect to Server"

• "Failed to disconnect from Server"

• "Failed to open Http Connection"

• "Failed to get Service"

• "Failed to package the message using Serializer and Encoding"

Example Application

The sample code shown below illustrates how to use the ASCII version C API.

// Declarations

Server *server = NULL;

Message *request = NULL;

DataTable *dataTable = NULL;

Message *reply = NULL;

Service *service = NULL;

26 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

int nRet;

DataRow *row1 = NULL;

DataRow *row2 = NULL;

DataTable *returnDataTable= NULL; char** columnNames;

DataRow** rows;

DataRow*dataRow; int i; int j; char* value;

//Create Server server = createServer();

//Set server connection properties nRet = setConnectionProperty(server, SERVER_HOST, "localhost"); nRet = setConnectionProperty(server, SERVER_PORT, "10119 "); nRet = setConnectionProperty(server, SERVER_CONNECTION_TYPE,"SOCKET"); nRet = setConnectionProperty(server, SERVER_ACCOUNT_ID,"guest"); nRet = setConnectionProperty(server, SERVER_ACCOUNT_PASSWORD,"");

//Connect to server nRet = serverConnect(server); if(nRet != SUCCESSFUL_RETURN)

{ printf( getErrorMessage(nRet));

// free memory if(server) nRet = deleteServer(server); return ;

}

//Get Service From Server service = getServiceFromServer(server,"ValidateAddress" );

//Create Input Message request = createMessage();

//Fill DataTable in the input message dataTable = getDataTable(request); nRet= addColumn( dataTable, "AddressLine1", &nRet); nRet= addColumn( dataTable, "City", &nRet); nRet= addColumn( dataTable, "StateProvince", &nRet); row1 = newRow( dataTable ); setByIndex (row1, 0 , "4200 Parliament Place"); setByIndex (row1, 1 ,"Lanham"); setByIndex (row1, 2 , "Maryland"); addRow( dataTable, row1); row2 = newRow( dataTable ); setByIndex (row2, 0 , "10535 Boyer Blvd"); setByIndex (row2, 1 ,"Austin"); setByIndex (row2, 2 , "Texas"); addRow( dataTable, row2);

//Set"option" Properties to the Input Message nRet = putOption(request, "OutputCasing","M"); nRet = putOption(request, "OutputRecordType","A");

//Process Input Message, return output Message nRet = processMessage(service, request, &reply); if(nRet != SUCCESSFUL_RETURN)

{ printf("Error Occurred, " ); printf(getErrorMessage(nRet));

// free memory if(request)

API Guide 27

Introduction to the C API

nRet = deleteMessage(request); if(reply) nRet = deleteMessage(reply); if(server) nRet = deleteServer(server); return ;

}

//Disconnect from server nRet = serverDisconnect(server);

//Get the result from the response message returnDataTable = getDataTable(reply ); columnNames = getColumnNames(returnDataTable); rows = getDataRows( returnDataTable); for( i=0; i < getRowCount( returnDataTable); i++)

{ dataRow = rows[i]; for(j=0; j < getColumnCount(returnDataTable); j++)

{ value = (char*)getByIndex( dataRow, j); printf(value); printf("\n");

}

//Free Memory if(request) nRet = deleteMessage(request); if(reply) nRet = deleteMessage(reply); if(server) nRet = deleteServer(server);

}

The sample code shown below illustrates how to use the Unicode version C API. The string here is represented by UChar*(or unsigned short*), which is 16-bit type to represent the Unicode string .ICU

provides a function called u_charsToUChars, which converts 8-bit string to 16-bit string. The example here shows how to call Unicode version C API. The input string are all ASCII, so that we use u_charsToUChars to convert to 16-bit string. You could also construct Unicode string to directly pass in

C API.

UChar* convertcharToUChar( char* name, UChar* value)

{ int lenName= strlen(name); u_charsToUChars(name, value, lenName ); value[ lenName]=0;

} return value;

// Declarations

Server *server = NULL;

Message *request = NULL;

DataTable *dataTable = NULL;

DataTable *returnDataTable= NULL;

Message *reply = NULL;

Service *service = NULL; int nRet;

DataRow* newDataRow;

UChar name[128];

UChar value[128];

UChar** columnNames;

DataRow** rows;

DataRow* dataRow;

28 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

int i, j;

UChar* columnValue;

UChar* errorMsg;

//Create Server server = createServer();

//Set server connection properties setConnectionProperty(server, convertcharToUChar( SERVER_HOST, name) , convertcharToUChar( "localhost", value)); setConnectionProperty(server, convertcharToUChar( SERVER_PORT, name) , convertcharToUChar( "10119", value)); setConnectionProperty(server, convertcharToUChar( SERVER_CONNECTION_TYPE, name) , convertcharToUChar( "SOCKET", value)); setConnectionProperty(server, convertcharToUChar( SERVER_ACCOUNT_ID, name) , convertcharToUChar( "guest", value)); setConnectionProperty(server, convertcharToUChar(

SERVER_ACCOUNT_PASSWORD, name) , convertcharToUChar( "", value));

//Connect to server nRet = serverConnect(server); if(nRet != SUCCESSFUL_RETURN)

{

// error handling errorMsg = getErrorMessage(nRet);

// free memory if(server) nRet = deleteServer(server); return ;

}

//Get Service From Server service = getServiceFromServer(server,convertcharToUChar(

"ValidateAddress", name));

//Create Input Message request = createMessage();

//Fill DataTable in the input message dataTable = getDataTable(request); addColumn( dataTable,convertcharToUChar( "AddressLine1", name), &nRet); addColumn( dataTable,convertcharToUChar( "City", name), &nRet); addColumn( dataTable,convertcharToUChar( "PostalCode", name), &nRet); addColumn( dataTable,convertcharToUChar( "StateProvince", name), &nRet); newDataRow = newRow( dataTable ); setByIndex (newDataRow, 0 , convertcharToUChar( "74, Rue Octave Bénard", name) ); setByIndex (newDataRow, 1 , convertcharToUChar( "Etang-Salé-les- Bains", name) ); setByIndex (newDataRow, 2 , convertcharToUChar( "97427", name) ); setByIndex (newDataRow, 3 , convertcharToUChar( "Reunion Island", name)

); addRow( dataTable, newDataRow);

//Set"option" Properties to the Input Message nRet = putOption(request, convertcharToUChar( "OutputCasing", name), convertcharToUChar( "M", value)); nRet = putOption(request, convertcharToUChar( "OutputRecordType", name), convertcharToUChar( "A", value));

//Process Input Message, return output Message nRet = processMessage(service, request, &reply); if(nRet != SUCCESSFUL_RETURN)

API Guide 29

Server

{

// error handling errorMsg = getErrorMessage(nRet);

// free memory if(request) nRet = deleteMessage(request); if(reply) nRet = deleteMessage(reply); if(server) nRet = deleteServer(server); return ;

}

//Disconnect from server nRet = serverDisconnect(server);

//Get the result from the response message returnDataTable = getDataTable(reply ); columnNames = getColumnNames(returnDataTable); rows = getDataRows( dataTable); for( i=0; i < getRowCount( dataTable); i++)

{ dataRow = rows[i]; for(j=0; j < getColumnCount(dataTable); j++)

{ columnValue = (UChar*)getByIndex( dataRow, j);

}

//Free Memory if(request) nRet = deleteMessage(request); if(reply) nRet = deleteMessage(reply); if(server) nRet = deleteServer(server);

Server

The Server structure is used to connect to server, disconnect from the server, and get the service from the server. The following table summarizes the functions performed in the Server structure.

Table 14: Server Functions Summary

Function

createServer deleteServer setConnectionProperty serverConnect serverDisconnect getServiceFromServer

Description

Creates a server.

Deletes the server.

Sets the configuration items for the connection to the server.

Connects to the server.

Disconnects from the server.

Gets the service from the server.

30 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

CreateServer

Creates the server.

Syntax

Server* createServer()

Parameters

None.

Result

The server is created.

Example

Server *server = NULL;

//Create Server server = createServer();

DeleteServer

Deletes the server.

Syntax

int deleteServer(Server* server)

Parameters

• Server— the server to be deleted.

Result

Returns 0 (if successful) or error code.

Example

int nRet; nRet = deleteServer(server);

SetConnectionProperty

Establishes the server connection configuration properties, such as host name and length of timeout.

Syntax

ASCII Version

int setConnectionProperty(Server* server, const char* name, const char* value)

API Guide 31

Server

Unicode Version

int setConnectionProperty(Server* server, const UChar* name, const UChar* value)

Parameters

• Server — the server to which the client connects

• Name — the name of the connection property, such as HOST

• Value — the value for the name of the connection property, such as "www.myhost.com"

Result

Returns 0 (if successful) or error code.

Example

ASCII Version

int nRet;

Server *server = NULL; nRet = createServer(&server); nRet = setConnectionProperty(server, SERVER_HOST,

"localhost");

Unicode Version

int nRet;

// construct 16-bit string

UChar serverHost[32]; char* SERVER_HOST= SERVER_HOST; u_charsToUChars(SERVER_HOST, serverHost, strlen(SERVER_HOST)); serverHost [ strlen(SERVER_HOST)]=0;

// construct 16-bit string

UChar hostValue [32]; char* value= "localhost"; u_charsToUChars(value, hostValue, strlen(value)); hostValue[ strlen(value)]=0; nRet = setConnectionProperty(server, serverHost , hostValue);

ServerConnect

Reads the properties to determine the configuration settings and makes a connection to the server.

Note:

C uses the HTTP, HTTPS, or SOCKET server connection protocol. HTTP and HTTPS logically establish a client connection but do not actually connect to the server until a GetService or

Process method is invoked. The SOCKET protocol establishes a connection to the server when

Connect is invoked.

Syntax

int serverConnect(Server* server)

Parameters

• Server—the server to which the client connects

Results

Returns 0 (if successful) or error code.

32 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Example

int nRet; nRet = serverConnect(server);

ServerDisconnect

Disconnects from the server.

Syntax

int serverDisconnect(Server* server)

Parameters

• Server—the server from which the client disconnects.

Results

Returns 0 (if successful) or error code.

Example

int nRet; nRet = serverDisconnect(server);

GetServiceFromServer

Gets the service from the server.

Note:

See the Component Reference section of this guide for a list of services that may be available to you.

Syntax

ASCII Version

Service* getServiceFromServer(Server* server,const char* serviceName )

Unicode Version

Service* getServiceFromServer(Server* server,const UChar* serviceName )

Parameters

• Server - server from which the client connects

• ServiceName - the name of service the client requests

Results

Service returned.

API Guide 33

Service

Example

ASCII Version

Server *server= NULL;

Service *service = NULL;

//Create Server server = createServer();

...

// get Service From Server service = getServiceFromServer(server,"ValidateAddress" );

Unicode Version

// construct 16-bit string

UChar serviceName[32]; char* sName="ValidateAddress"; u_charsToUChars(sName, serviceName, strlen(sName)); serviceName [ strlen(sName)]=0; service = getServiceFromServer(server , serviceName );

Service

The Service structure is used to process the message (in other words, it sends the message to the server and receives a response from the server). The following table summarizes the functions performed in the Service structure.

Table 15: Service Functions Summary

processMessage Processes the input message and retrieves the response message from the server.

ProcessMessage

Process the input message and returns the response message.

Note:

You will need to call DeleteMessage() to free memory when this returned message is no longer used.

Syntax

int processMessage (Service* service, Message* request, Message* returnVal)

Parameters

• Service—the service the client requests.

• Request—the input message which contains the "option" setting and the dataset.

• returnVal—returns the response message from the server.

Results

Returns 0 (if successful) or error code.

34 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Example

Message *request = NULL;

Message *reply = NULL; int nRet;

...

// Assume that service is given here

// Create Input Message request = createMessage();

... more code to fill dataTable information in request message

//Process Input Message, return output Message nRet = processMessage(service, request, &reply); if(nRet != SUCCESSFUL_RETURN)

{ printf("Error Occurred, " ); printf(getErrorMessage(nRet)); return ;

} if(request) nRet = deleteMessage(request); if(reply) nRet = deleteMessage(reply);

Message

The Message structure sends your input data and receives your output data from the service. The properties for Message include context properties, such as account ID, account password, service name, and service method; option properties, which are the service-specific runtime options; and error properties, which are the error class, error message and error stacktrace.

The following table summarizes the functions performed in the Message structure.

Table 16: Message Functions Summary

Function

createMessage deleteMessage getContext getContextMap putContext putContextMap setContextMap getOption

Description

Creates a message.

Deletes the message.

Gets the value of the context entity identified by the name in the context session of the message.

Gets the Map that contains all of the context entries.

Sets the value of the context entity identified by the name in the context session of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Adds the new context properties to the current context properties.

Overwrites the current context properties with the new context properties.

Gets the value of the option entity identified by the name in the option session of the message.

API Guide 35

Message

Function

getOptions putOption putOptions setOptions getError getDataTable

Description

Gets the Map that contains all of the option entries.

Sets the value of the option entity identified by the name in the option session of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Adds the new option properties to the current option properties.

Overwrites the current option properties with the new option properties.

Gets the error message.

Gets the DataTable from the message

These methods are discussed in more detail in the following sections.

CreateMessage

Creates a message.

Syntax

Message* createMessage()

Parameters

None.

Results

The message created.

Example

Message* request = NULL; request = createMessage();

DeleteMessage

Deletes the message.

Syntax

int deleteMessage(Message* message)

Parameters

• Message— the message to be deleted

36 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Results

Returns 0 if successful or error code.

Example

int nRet = deleteMessage(message);

GetContext

Gets the value of the context entity identified by the name in the context session of the message. "Context" entities include the following constants: account id, account password, service name, service method.

Syntax

ASCII Version

const char* getContext(Message* message,const char* name)

Unicode Version

const UChar * getContext(Message* message,const UChar* name)

Parameters

• Message - the message to which this function applies

• Name - the name whose associated value is to be returned

Result

Returns the value for the name in the context entity. If the name does not exist, the method returns empty string.

Example

ASCII Version

const char* value = getContext(message, "account.id");

Unicode Version

UChar* value;

// construct 16-bit string

UChar accountID[32]; char* account="account.id"; u_charsToUChars(account, accountID, strlen(account)); accountID[ strlen(account)]=0; value = getContext(message, accountID);

GetContextMap

Gets the Map that contains all of the context entries.

API Guide 37

Message

Syntax

ASCII Version

MAP_STRING**getContextMap(Message* message)

Where the MAP_STRING is defined by typedef struct map_string{ char* key; char* value;

}MAP_STRING;

Unicode Version

MAP_STRING**getContextMap(Message* message)

Where the MAP_STRING is defined by typedef struct map_string{

UChar* key;

UChar* value;

}MAP_STRING;

Parameters

• Message - the message to which this function applies

Results

Returns the array of MAP_STRING that contains all of the context entries.

Example

ASCII Version

int i; char* name; char* value;

MAP_STRING** mapping; mapping = getContextMap( message); i=0; while(mapping[i] != NULL)

{ name= mapping[i]->key; value = mapping[i]->value; i++;

}

Unicode Version

int i;

UChar* name;

UChar* value;

MAP_STRING** mapping; mapping = getContextMap( message); i=0; while(mapping[i] != NULL)

{ name= mapping[i]->key; value = mapping[i]->value; i++;

}

38 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

PutContext

Sets the value for given name in the "context" properties. If there is an existing value present for the entity identified by the name, it is replaced. Context properties include the following constants: account

ID, account password, service name, service key, and request ID.

Syntax

ASCII Version

int putContext(Message* message,const char* name, const char* value)

Unicode Version

int putContext(Message* message,const UChar* name, const UChar* value)

Parameters

• Message—message to which this function applies

• Name—name with which the specified value is to be associated

• Value—value to be associated with the specified name

Results

Returns 0 (if successful) or error code.

Example

ASCII Version

int nRet;

Message* message = createMessage(); nRet = putContext( message, "account.id", "user1") ;

Unicode Version

int nRet;

Message* message;

// construct 16-bit string

UChar accountID[32]; char* account="account.id";

UChar accountIDValue[32]; char* accountValue="user1"; u_charsToUChars(account, accountID, strlen(account)); accountID [ strlen(account)]=0; u_charsToUChars(accountValue, accountIDValue, strlen(accountValue)); accountIDValue [ strlen(accountValue)]=0; message = createMessage(); nRet = putContext( message, accountID, accountIDValue);

PutContextMap

Adds the new context properties to the current context properties.

Syntax

int putContextMap(Message* message, MAP_STRING** context)

API Guide 39

Message

Parameters

• Message - the message to which this function applies

• The new context map to be added to the current context map.

Results

Returns 0 (if successful) or error code.

Example

ASCII Version

MAP_STRING** mapping;

Message* message; message = createMessage(); int nRet; mapping = (MAP_STRING **)malloc(3 * sizeof(MAP_STRING *)); mapping[0] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[0]->key = "key1" ; mapping[0]->value = "value1" ; mapping[1] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[1]->key = "key2" ; mapping[1]->value = "value2" ; mapping[2] = NULL; nRet = putContextMap( message, mapping) ;

Unicode Version

MAP_STRING** mapping;

Message* message; int nRet;

UChar key1[32]; char* key1String="key1";

UChar value1[32]; char* value1String="value1"; u_charsToUChars(key1String, key1, strlen(key1String)); key1[ strlen(key1String)]=0; u_charsToUChars(value1String, value1, strlen(value1String)); value1[ strlen(value1String)]=0; message = createMessage(); mapping = (MAP_STRING **)malloc(2 * sizeof(MAP_STRING *)); mapping[0] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[0]->key = key1; mapping[0]->value = value1 ; mapping[1] = NULL; nRet = putContextMap( message, mapping) ;

SetContextMap

Overwrites the current context properties with the new context properties.

Syntax

int setContextMap(Message* message, MAP_STRING** context)

Parameters

• Message - the message to which this function applies

• The new context map to be used to replace the current context map.

40 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Results

Returns 0 (if successful) or error code.

Example

ASCII Version

MAP_STRING** mapping;

Message* message; int nRet; message = createMessage(); mapping = (MAP_STRING **)malloc(2 * sizeof(MAP_STRING *)); mapping[0] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[0]->key = "key1" ; mapping[0]->value = "value1" ; mapping[1] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[1]->key = "key2" ; mapping[1]->value = "value2" ; mapping[2] = NULL; nRet=setContextMap( message, mapping) ;

Unicode Version

MAP_STRING** mapping;

Message* message; int nRet;

UChar key1[32]; char* key1String="key1";

UChar value1[32]; char* value1String="value1"; u_charsToUChars(key1String, key1, strlen(key1String)); key1[ strlen(key1String)]=0; u_charsToUChars(value1String, value1, strlen(value1String)); value1[ strlen(value1String)]=0; message = createMessage(); mapping = (MAP_STRING **)malloc(2 * sizeof(MAP_STRING *)); mapping[0] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[0]->key = key1 ; mapping[0]->value = value1 ; mapping[1] = NULL; nRet=setContextMap( message, mapping) ;

GetOption

Gets the value of the option entity identified by the name in the option session of the message. "Options" entities include the service-specific runtime options, such as output casing, output data format, and so on.

Syntax

ASCII Version

const char* getOption(Message* message,const char* name)

Unicode Version

const Uchar* getOption(Message* message,const UChar* name)

Parameters

• Message - the message to which this function applies

• Name- the name whose associated value is to be returned

API Guide 41

Message

Results

Returns the value for the name in the "option" property in the message or an empty string if the name does not exist.

Example

ASCII Version

const char* value = getOption (message, " OutputCasing");

Unicode Version

UChar* value;

// construct 16-bit string

UChar option[32]; char* optionValue="OutputCasing"; u_charsToUChars(optionValue, option, strlen(optionValue)); option [ strlen(optionValue)]=0; value = getOption(message, option);

GetOptions

Gets the map that contains all of the option entries.

Syntax

MAP_STRING** getOptions(Message* message)

Parameters

• Message—the message to which this function applies

Results

Returns the array of MAP_STRING that contains all of the context entries.

Example

ASCII Version

int i; char* name; char* value;

MAP_STRING** mapping; mapping = getOptions( message); i=0; while(mapping[i] != NULL)

{ name= mapping[i]->key; value = mapping[i]->value; i++;

}

Unicode Version

int i;

UChar* name;

UChar* value;

MAP_STRING** mapping; mapping = getOptions( message); i=0;

42 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

while(mapping[i] != NULL)

{ name= mapping[i]->key; value = mapping[i]->value; i++;

}

PutOption

Sets the value for given name in the "option" properties. If there is an existing value present for the entity identified by the name, it is replaced. Option properties are the service-specific run-time options.

Syntax

ASCII Version

int putOption(Message* message,const char* name, const char* value)

Unicode Version

int putOption(Message* message,const UChar* name, const UChar* value)

Parameters

• Message - the message to which this function applies

• Name - with which the specified value is to be associated.

• Value - to be associated with the specified name.

Results

Returns 0 (if successful) or error code.

Example

ASCII Version

int nRet;

Message* message = createMessage(); nRet = putOption( message, "OutputCasing", "M");

Unicode Version

int nRet;

Message* message;

// construct 16-bit string

UChar option[32]; char* optionString="OutputCasing";

UChar optionValue[32]; char* optionValueString="M"; u_charsToUChars(optionString, option, strlen(optionString)); option[ strlen(optionString)]=0; u_charsToUChars(optionValueString, optionValue, strlen(optionValueString)); optionValue [ strlen(optionValueString)]=0; message = createMessage(); nRet = putOption( message, option, optionValue);

API Guide 43

Message

PutOptions

Adds the new option properties to the current option properties.

Syntax

int putOptions(Message* message, MAP_STRING** context)

Parameters

• Message - the message to which this function applies

• The new option map to be added to the current option properties

Results

Returns 0 if successful or error code.

Example

ASCII Version

MAP_STRING** mapping;

Unicode Version

MAP_STRING** mapping;

Message* message; int nRet;

UChar key1[32]; char* key1String="key1";

SetOptions

Overwrites the current option properties with the new option properties.

44 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Syntax

int setOptions(Message* message, MAP_STRING** context)

Parameters

• Message - the message to which this function applies

• The new option map to be used to replace the current option map

Results

Returns 0 if successful or error code.

Example

ASCII Version

MAP_STRING** mapping;

Message* message; int nRet; message = createMessage(); mapping = (MAP_STRING **)malloc(3 * sizeof(MAP_STRING *)); mapping[0] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[0]->key = "key1" ; mapping[0]->value = "value1" ; mapping[1] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[1]->key = "key2" ; mapping[1]->value = "value2" ; mapping[2] = NULL; nRet=setOptions( message, mapping) ;

Unicode Version

MAP_STRING** mapping;

Message* message; int nRet;

UChar key1[32]; char* key1String="key1";

UChar value1[32]; char* value1String="value1"; u_charsToUChars(key1String, key1, strlen(key1String)); key1[ strlen(key1String)]=0; u_charsToUChars(value1String, value1, strlen(value1String)); value1[ strlen(value1String)]=0; message = createMessage(); mapping = (MAP_STRING **)malloc(2 * sizeof(MAP_STRING *)); mapping[0] = (MAP_STRING *)malloc( sizeof(MAP_STRING)); mapping[0]->key = key1 ; mapping[0]->value = value1 ; mapping[1] = NULL; nRet= setOptions ( message, mapping) ;

GetError

Gets the error message from the message.

Syntax

ASCII Version

const char* getError(Message* message )

API Guide 45

DataTable

Unicode Version

const UChar* getError(Message* message )

Parameters

• Message - the message to which this function applies

Result

Returns the error message in message.

Example

ASCII Version

const char* error = getError(message );

Unicode Version

const UChar* error = getError(message );

GetDataTable

Gets the DataTable in the message.

Syntax

DataTable* getDataTable(Message* message )

Parameters

• Message - the message to which this function applies

Example

// Assume that message is given here

DataTable *dataTable ; dataTable = getDataTable( message );

DataTable

DataTable contains the records for the input and output data.

The following table summarizes the functions performed in the DataTable structure.

Table 17: DataTable Functions Summary

Function

createDataTable deleteDataTable

Description

Creates the DataTable.

Deletes the DataTable.

46 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Function

addColumn getColumnNames getColumnIndex getColumnCount clear getDataRows addRow newRow getRowCount mergeDataTable

Description

Adds the new column.

Gets all the column names.

Gets the corresponding column index.

Gets the number of columns.

Clears the data in DataTable.

Gets an array of all DataRows in the DataTable.

Adds a DataRow to the DataTable.

Creates a new DataRow in the DataTable.

Gets the number of the DataRows in this DataTable.

Merges the given DataTable and the current DataTable.

These methods are discussed in more detail in the following sections.

CreateDataTable

Create the DataTable.

Syntax

DataTable* createDataTable()

Results

Returns the DataTable created.

Example

DataTable* dataTable; dataTable = createDataTable();

DeleteDataTable

Deletes the DataTable.

Syntax

int deleteDataTable(DataTable* dataTable)

Parameters

• Datatable - the DataTable to be deleted

API Guide 47

DataTable

Example

DataTable* dataTable; dataTable = createDataTable();

...

if(dataTable) deleteDataTable(dataTable);

AddColumn

Adds the new column.

Syntax

ASCII Version

int addColumn(DataTable* dataTable, const char* columnName, int* indexReturn)

Unicode Version

int addColumn(DataTable* dataTable, const UChar* columnName, int* indexReturn)

Parameters

• Datatable - the DataTable to which this function applies

• Column name to be added to the DataTable

• Returns the corresponding index

Results

Returns 0 if successful or error code.

Exceptions

• Blank column name

• Duplicate column name

Example

ASCII Version

int nIndex; int nRet; nRet= addColumn( dataTable, "AddressLine1", &nIndex); nRet= addColumn( dataTable, "City",&nIndex); nRet= addColumn( dataTable, "State", &nIndex); if(nRet != SUCCESSFUL_RETURN)

{ printf(getErrorMessage(nRet)); return ;

}

Unicode Version

int nRet; int nIndex;

UChar* error;

UChar city[64]; char* cityString= "City" u_charsToUChars(cityString, city, strlen(cityString));

48 Spectrum

™

Technology Platform 9.0

city[ strlen(cityString)]=0; nRet= addColumn( dataTable, city,&nIndex); if(nRet != SUCCESSFUL_RETURN)

{ error = getErrorMessage(nRet);

//more code

}

GetColumnNames

Gets all the column names.

Syntax

ASCII Version

char** getColumnNames(dataTable )

Unicode Version

UChar** getColumnNames(dataTable )

Parameters

• Datatable - the DataTable to which this function applies

Results

Returns the array of column names.

Example

ASCII Version

char* value; char** columnNames; int i; columnNames =getColumnNames ( dataTable) ; for( i=0; i < getColumncount( dataTable); i++)

{ value = columnNames[i];

}

Unicode Version

UChar* value;

UChar** columnNames; int i; columnNames =getColumnNames ( dataTable) ; for( i=0; i < getColumncount( dataTable); i++)

{ value = columnNames[i];

}

GetColumnIndex

Gets the corresponding column index.

API Guide

Chapter 2: The C API

DataTable

Syntax

ASCII Version

int getColumnIndex(DataTable* dataTable ,const char* columnName)

Unicode Version

int getColumnIndex(DataTable* dataTable ,const UChar* columnName)

Parameters

• Datatable - the DataTable to which this function applies

• Column name

Results

Returns the corresponding column index.

Example

ASCII Version

int nIndex ; nIndex = getColumnIndex(dataTable ,"AddressLine1")

Unicode Version

int nIndex ;

UChar columnName[64]; char* columnNameStr= "AddressLine1" u_charsToUChars(columnNameStr, columnName, strlen(columnNameStr)); columnName [strlen(columnNameStr)]=0; nIndex = getColumnIndex(dataTable , columnName);

GetColumnCount

Gets the number of columns.

Syntax

int getColumnCount(DataTable* dataTable )

Parameters

• Datatable - the DataTable to which this function applies

Results

Returns the number of columns.

Example

// Assume that dataTable is given here int nColumnCount ; nColumnCount = getColumnCount( dataTable ) ;

50 Spectrum

™

Technology Platform 9.0

Clear

Clears the data in DataTable.

Syntax

int clear(DataTable* dataTable)

Parameters

• Datatable - the DataTable to which this function applies

Results

Returns 0 if successful or error code.

Example

// Assume that dataTable is given here clear(dataTable);

GetDataRows

Gets an array of all DataRows in the DataTable.

Syntax

DataRow** getDataRows(DataTable* dataTable)

Parameters

• Datatable - the DataTable to which this function applies

Results

Returns an array of DataRows.

Example

// Assume that dataTable is given here

DataRows** rows;

DataRow* dataRow; int i; int j; rows = getDataRows( dataTable); for( i=0; i < getRowCount( dataTable); i++)

{ dataRow = rows[i]; for(j=0; j < getColumnCount(dataTable); j++)

{ value = (char*)getByIndex( dataRow, j);

}

API Guide

Chapter 2: The C API

DataTable

AddRow

Adds a DataRow to the DataTable.

Syntax

int addRow(DataTable* dataTable, DataRow* dataRow)

Parameter

• Datatable - the DataTable to which this function applies

• Datarow to be added to the DataTable

Results

Returns 0 if successful or error code.

Example

// Assume that dataTable is given here DataRow* newDataRow; int nRet; newDataRow = newRow( dataTable ); setByIndex (newDataRow, 0 , "10535 Boyer Blvd"); setByIndex (newDataRow, 1 , "Austin"); setByIndex (newDataRow, 2 , "Texas"); nRet = addRow( dataTable, newDataRow);

NewRow

Creates a new DataRow in the DataTable.

Syntax

DataRow* newRow(DataTable* dataTable )

Parameter

• Datatable - the DataTable to which this function applies

Results

Returns the new created DataRow.

Example

// Assume that dataTable is given here

DataRow* newDataRow; int nRet; newDataRow = newRow( dataTable ); setByIndex (newDataRow, 0 , "10535 Boyer Blvd"); setByIndex (newDataRow, 1 , "Austin"); setByIndex (newDataRow, 2 , "Texas"); nRet = addRow( dataTable, newDataRow);

52 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

GetRowCount

Gets the number of the DataRows in this DataTable.

Syntax

int getRowCount(DataTable* dataTable)

Parameter

• Datatable - the DataTable to which this function applies

Results

Returns the number of the DataRows in this DataTable.

Example

// Assume that dataTable is given here int nRowCount ; nRowCount = getRowCount( dataTable);

MergeDataTable

Merges the given DataTable and the current DataTable.

Syntax

int mergeDataTable(DataTable* dataTable ,DataTable* other )

Parameter

• Datatable - the DataTable to which this function applies

• Other DataTable to be merged with the current DataTable

Results

Returns 0 if successful or error code.

Example

// Assume that dataTable and otherDataTable are given here mergeDataTable (dataTable ,otherDataTableDataRow)

DataRow

DataRow contains the record for the input and output data.

The following table summarizes the functions performed in the DataRow structure.

API Guide 53

DataRow

Table 18: DataRow Functions Summary

Function

createDataRow deleteDataRow getColumnNamesFromRow getColumnIndexFromRow getColumnCountFromRow getByIndex getByName mergeDataRow setByName setByIndex addChild getChildren listChildNames setChildren

Description

Creates the DataRow.

Deletes the DataRow.

Gets all the column names.

Gets the corresponding column index

Gets the number of columns.

Gets the value from the fields array by the column index in this DataRow.

Gets the value from the fields array by the column name in this DataRow.

Merges the given DataRow and the current

DataRow.

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Sets the value for the corresponding column for the DataRow. If the value for the index exists, the old value is replaced.

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied DataRow will be appended to the existing

DataRow Collection, otherwise a new Collection will be created with the supplied DataRow as its only element.

Retrieves the child rows from a named relationship.

Retrieves all of the names of the named parent/child relationships.

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

CreateDataRow

Creates the DataRow.

Syntax

DataRow* createDataRow()

Results

Returns the DataRow created.

54 Spectrum

™

Technology Platform 9.0

Example

DataRow* dataRow; dataRow = createDataRow();

DeleteDataRow

Deletes the DataRow.

Syntax

int deleteDataRow(DataRow* dataRow)

Parameter

• The DataRow to be deleted

Example

DataRow* dataRow; dataRow = createDataRow();

...

if(dataRow) deleteDataRow (dataRow);

GetColumnNamesFromRow

Gets all the column names.

Syntax

ASCII Version

char** getColumnNamesFromRow(DataRow* dataRow)

Unicode Version

UChar** getColumnNamesFromRow(DataRow* dataRow)

Parameter

• Datarow - the DataRow to which this function applies

Results

Returns the array of column names.

Example

ASCII Version

char* value; char** columnNames; int i; columnNames = getColumnNamesFromRow (dataRow) ; for( i=0; i < getColumnCountFromRow (dataRow); i++)

{

API Guide

Chapter 2: The C API

DataRow

} value = columnNames[i];

Unicode Version

UChar* value;

UChar** columnNames; int i; columnNames = getColumnNamesFromRow (dataRow) ; for( i=0; i < getColumnCountFromRow (dataRow); i++)

{

} value = columnNames[i];

GetColumnIndexFromRow

Gets the corresponding column index.

Syntax

ASCII Version

int getColumnIndexFromRow(DataRow* dataRow, const char* name)

Unicode Version

int getColumnIndexFromRow(DataRow* dataRow, const UChar* name)

Parameter

• Datarow - the DataRow to which this function applies

• Column name

Results

Returns the corresponding column index.

Example

ASCII Version

int nIndex nIndex = getColumnIndexFromRow ("AddressLine1");

Unicode Version

int nIndex

GetColumnCountFromRow

Gets the number of columns.

56 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Syntax

int getColumnCountFromRow(DataRow* dataRow )

Parameter

• Datarow - the DataRow to which this function applies

Results

Returns the number of columns.

Example

//Assume that the dataRow is given here int nColumnCount ; nColumnCount = getColumnCountFromRow (dataRow );

GetByIndex

Gets the value from the fields array by the column index in this DataRow.

Syntax

ASCII Version

const char* getByIndex(DataRow* dataRow, int index)

Unicode Version

const UChar* getByIndex(DataRow* dataRow, int index)

Parameter

• Datarow - the DataRow to which this function applies

• Index with which the specified value is to be associated.

Results

Returns the value for the column index in the DataRow, returns empty string if the index in invalid.

Example

ASCII Version

char* value = getByIndex( dataRow, 0);

Unicode Version

UChar* value = getByIndex( dataRow, 0);

GetByName

Gets the value from the fields array by the column name in this DataRow.

API Guide 57

DataRow

Syntax

ASCII Version

const char* getByName(DataRow* dataRow, const char* name )

Unicode Version

const UChar* getByName(DataRow* dataRow, const UChar* name )

Parameter

• Datarow - the DataRow to which this function applies

• Name with which the specified value is to be associated

Results

Returns the value for the column name in the DataRow, returns empty string if the column name does not exist.

Example

ASCII Version

char* value = getByName ( dataRow, "City")

Unicode Version

UChar* value;

UChar columnName[64]; char* columnNameStr= "City" u_charsToUChars(columnNameStr, columnName, strlen(columnNameStr)); columnName [strlen(columnNameStr)]=0; value = getByName ( dataRow, columnName);

MergeDataRow

Merges the given DataRow and the current DataRow.

Syntax

int mergeDataRow(DataRow* dataRow, DataRow* other)

Parameter

• Datarow - the DataRow to which this function applies

• Other DataRow to be merged with the current DataRow

Results

Returns 0 if successful or error code.

Example

//Assume that the dataRow and otherDataRow are given here int nRet; nRet= mergeDataRow(dataRow, otherDataRow);

58 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

SetByName

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Syntax

ASCII Version

int setByName(DataRow* dataRow, const char* name, const char* value)

Unicode Version

int setByName(DataRow* dataRow, const UChar* name, const

UChar* value)

Parameters

• Datarow - the DataRow to which this function applies

• Name with which the specified value is to be associated

• Value to be associated with the specified name

Exceptions

If input Blank column name or Duplicate column name, return error

Results

Returns 0 if successful or error code.

Example

ASCII Version

int nRet; nRet= setByName (dataRow, "City", "Austin"); if(nRet != SUCCESSFUL_RETURN)

{ printf(getErrorMessage(nRet));

//more code

}

Unicode Version

int nRet;

UChar* error;

UChar columnName[64]; char* columnNameStr= "City"

UChar columnValue[64]; char* columnValueStr= "Austin"; u_charsToUChars(columnNameStr, columnName, strlen(columnNameStr)); columnName [strlen(columnNameStr)]=0; u_charsToUChars(columnValueStr, columnValue, strlen(columnValueStr)); columnValue [strlen(columnValueStr)]=0; nRet= setByName (dataRow, columnName, columnValue); if(nRet != SUCCESSFUL_RETURN)

{ error = getErrorMessage(nRet);

//more code

}

API Guide 59

DataRow

SetByIndex

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Syntax

ASCII Version

int setByIndex(DataRow* dataRow, int index, const char* value)

Unicode Version

int setByIndex(DataRow* dataRow, int index, const UChar* value)

Parameters

• Datarow - the DataRow to which this function applies

• Column index with which the specified value is to be associated

• Value to be associated with the specified name

Exceptions

• The column index is invalid

Results

Returns 0 if successful or error code.

Example

ASCII Version

int nRet; nRet= setByIndex (dataRow, 1, "Austin"); if(nRet != SUCCESSFUL_RETURN)

{ printf(getErrorMessage(nRet));

}

//more code

Unicode Version

int nRet;

UChar* error;

UChar columnValue[64]; char* columnValueStr= "Austin"; u_charsToUChars(columnValueStr, columnValue, strlen(columnValueStr)); columnValue [strlen(columnValueStr)]=0; nRet= setByIndex (dataRow, 1, columnValue); if(nRet != SUCCESSFUL_RETURN)

{ error = getErrorMessage(nRet);

//more code

}

60 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

AddChild

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied

DataRow will be appended to the existing DataRow collection. Otherwise, a new collection will be created with the supplied DataRow as its only element.

Syntax

ASCII Version

void addChild(DataRow* dataRow, const char* childName, DataRow* childDataRow)

Unicode Version

void addChild(DataRow* dataRow, const UChar* childName, DataRow* childDataRow)

Parameters

• The name of the parent/child relationship (e.g., "Flood Plain Data," "References," "Used By," and so forth)

• The DataRow to be added to the relationship

Example

ASCII Version

DataRow* dataRow = createDataRow();

DataRow* child1DataRow1 = createDataRow(); setByName(child1DataRow1, "City", "Austin"); setByName(child1DataRow1, "State", "Texas"); addChild( dataRow, "child1", child1DataRow1);

Unicode Version

UChar* convertcharToUChar( char* name, UChar* value)

{ int lenName= strlen(name); u_charsToUChars(name, value, lenName ); value[ lenName]=0; return value;

} >

DataRow* dataRow = createDataRow();

DataRow* child1DataRow1 = createDataRow();

UChar name[128];

UChar columnValue[128]; setByName(child1DataRow1, convertcharToUChar("City", name), convertcharToUChar("Austin", columnValue)); setByName(child1DataRow1, convertcharToUChar("State", name), convertcharToUChar("Texas", columnValue)); addChild( dataRow, "child1", child1DataRow1);

GetChildren

Retrieves the child rows from a named relationship.

API Guide 61

DataRow

Syntax

ASCII Version

DataRow** getChildren(DataRow* dataRow,const char* childName)

Unicode Version

DataRow** getChildren(DataRow* dataRow,const UChar* childName)

Parameters

• The name of the parent/child relationship, for example "Flood Plain Data", "References", "Used By", and so forth.

Results

Returns the child rows from the named relationship.

Example

ASCII Version

DataRow** child1Rows; child1Rows = getChildren(dataRow, "child1");

Unicode Version

DataRow** child1Rows;

UChar childName[128];

/* see convertcharToUChar in the Example section of "addChild" */ child1Rows = getChildren(dataRow, convertcharToUChar("child1", childName));

ListChildNames

Retrieves all of the names of the named parent/child relationships.

Syntax

ASCII Version

char** listChildNames(DataRow* dataRow)

Unicode Version

UChar** listChildNames(DataRow* dataRow)

Results

Returns the set of the names of the named parent/child relationships.

Example

ASCII Version

char** childsNames; childsNames =listChildNames( dataRow);

62 Spectrum

™

Technology Platform 9.0

Chapter 2: The C API

Unicode Version

UChar** childsNames; childsNames=listChildNames( dataRow);

SetChildren

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

Syntax

ASCII Version

DataRow** setChildren(DataRow* dataRow, const char* childName, DataRow** dataRows)

Unicode Version

DataRow** setChildren(DataRow* dataRow, const UChar* childName, DataRow** dataRows)

Results

Returns the set of the names of the named parent/child relationships.

Example

ASCII Version

DataRow* dataRow = createDataRow();

DataRow* child1DataRow1 = createDataRow();

DataRow* child1DataRow2 = createDataRow();

DataRow* child2DataRow = createDataRow();

DataRow** child2Rows;

DataRow** returnRows; setByName(child1DataRow1, "Address", "200 Congress"); setByName(child1DataRow1, "City", "Austin"); setByName(child1DataRow2, "Address", "100 Congress"); setByName(child1DataRow2, "City", "Dallas"); setByName(child2DataRow, "Address", "100 Congress"); setByName(child2DataRow, "City", "Austin"); addChild( dataRow, "child1", child1DataRow1); addChild( dataRow, "child1", child1DataRow2); addChild( dataRow, "child2", child2DataRow ); child2Rows=getChildren(dataRow, "child2"); returnRows=setChildren( dataRow, "child1", child2Rows);

Unicode Version

DataRow* dataRow = createDataRow();

DataRow* child1DataRow1 = createDataRow();

DataRow* child1DataRow2 = createDataRow();

DataRow* child2DataRow = createDataRow();

DataRow** child2Rows;

DataRow** returnRows;

UChar name[128];

UChar columnValue[128];

API Guide 63

DataRow

UChar childName[128]; setByName(child1DataRow1, convertcharToUChar("Address", name), convertcharToUChar("200 Congress", columnValue)); setByName(child1DataRow1, convertcharToUChar("City", name), convertcharToUChar("Austin", columnValue)); setByName(child1DataRow2, convertcharToUChar("Address", name), convertcharToUChar("100 Congress", columnValue)); setByName(child1DataRow2, convertcharToUChar("City", name) convertcharToUChar("Dallas", columnValue) ); setByName(child2DataRow, convertcharToUChar("Address", name), convertcharToUChar("100 Congress", columnValue) ); setByName(child2DataRow, convertcharToUChar("City", name), convertcharToUChar("Austin", columnValue) ); addChild( dataRow, convertcharToUChar("child1", childName), child1DataRow1); addChild( dataRow, convertcharToUChar("child1", childName),child1DataRow2); addChild( dataRow, convertcharToUChar("child2", childName), child2DataRow

); child2Rows=getChildren(dataRow, convertcharToUChar("child2",childName)); returnRows=setChildren( dataRow, convertcharToUChar("child1",childName), child2Rows);

64 Spectrum

™

Technology Platform 9.0

The C++ API

In this section:

•

Introduction to the C++ API . . . . . . . . . . . . . . . . . . . . . . . .66

•

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

•

Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78

•

Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78

•

DataTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86

•

DataRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92

Introduction to the C++ API

The C++ API consists of the following classes:

• Server

• Service

• Message

• DataTable

• DataRow

UnicodeString in ICU is a string class that stores Unicode characters directly and provides similar functionality as the Java String and StringBuffer classes. The Spectrum

™

Technology Platform Unicode

C++ API uses this class to store Unicode strings.

Supported Libraries

Spectrum

™

Technology Platform provides an ASCII and Unicode version C API, while the Unicode version remains as compatible as possible with the original ASCII-version API design. Spectrum

™

Technology Platform applies International Components for Unicode (ICU) in the API to support the

Unicode feature. ICU is a mature, widely used set of C/C++ libraries for Unicode support and is developed by IBM.

™

Technology Platform uses UChar as the Unicode string representation in our C API.

Note:

For detailed information about UChar, please refer to the following two sites:

• icu.sourceforge.net/userguide/

• www-306.ibm.com/software/globalization/icu/index.jsp

Windows

<lib>g1client<S><U><D>.<lib|dll>

• lib—indicates a static library.

• dll—indiates a dynamic (shared) library.

• S—indicates a single-threaded build. If this is absent it indicates a multi-threaded build.

• U—indicates a UNICODE version build. If this is absent it indicates an ASCII build.

• D—indicates a debug build. If this suffix is absent it indicates an optimized release build.

To enable the UNICODE version, the LIB_UNICODE macro definition must be in your project.

To use the static C/C++ API library UNICODE version, you need to define U_STATIC_IMPLEMENTATION in your project.

To use the dynamic version, you need to define G1CLIENT_DLL in your project.

66 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

We also provide a file called "auto_link.h" in the header file directory and it automatically links to all the corresponding libraries according to the project settings.

To call 64-bit libraries in Windows, you need to define VER_64 in your project.

Static Library

Note:

The names provided in this section are for 32-bit libraries. For 64-bit libraries, replace "32" with

"64" in the library name.

Single Threaded/Release g1 openssl opentop icu

ASCII libg1client_S.lib

otlibeay32.lib otlibssl32.lib

opentop.lib

Unicode libg1client_SU.lib

otlibeay32.lib otlibssl32.lib

opentopw.lib

libicuuc.lib libicudt.lib libicuin.lib

libicuio.lib

PocoXML32w.lib

Poco

Single Threaded/Debug

PocoXML32.lib

g1 openssl opentop icu

ASCII libg1client_SD.lib

otlibeay32d.lib otlibssl32d.lib

opentopd.lib

Unicode libg1client_SUD.lib

otlibeay32d.lib otlibssl32d.lib

opentopwd.lib

libicuucd.lib libicudtd.lib

libicuind.lib libicuiod.lib

PocoXML32wd.lib

Poco g1

PocoXML32d.lib

Multi/Release (using Multi-Threaded CRT)

ASCII libg1client.lib

g1 openssl opentop

Unicode libg1client_U.lib

openssl opentop icu otlibeay32mt.lib otlibssl32mt.lib

otlibeay32mt.lib otlibssl32mt.lib

opentopmt.lib

opentopmtw.lib

libicuucmt.lib libicudtmt.lib

libicuinmt.lib libicuiomt.lib

PocoXML32mtw.lib

Poco PocoXMLmt32.lib

Multi/Debug (using Multi-Threaded CRT)

ASCII libg1client_D.lib

Unicode libg1client_UD.lib

otlibeay32mtd.lib otlibssl32mtd.lib

opentopmtd.lib

opentopmtwd.lib

API Guide 67

Introduction to the C++ API

icu

Poco PocoXMLmt32d.lib

libicuucmtd.lib libicudtmtd.lib

libicuinmtd.lib libicuiomtd.lib

PocoXML32mtwd.lib

Dynamic Library

Note:

The names provided in this section are for 32-bit libraries. For 64-bit libraries, replace "32" with

"64" in the library name.

Multi/Release (using Multi-Threaded CRT)

ASCII g1 g1client.dll

g1 openssl

Unicode g1client_U.dll

openssl opentop icu otlibeay32mts.dll otlibssl32mts.dll

otlibeay32mts.dll otlibssl32mts.dll

opentopmts.dll

opentopmtws.dll

icuuc32.dll icuio32.dll icuin32.dll

icudt32.dll

PocoXML32mtws.dll

Poco PocoXML32mts.dll

Multi/Debug (using Multi-Threaded CRT)

ASCII g1client_D.dll

otlibeay32mtds.dll

otlibssl32mtds.dll

opentopmtds.dll

opentop icu

Poco PocoXML32mtds.dll

Unicode g1client_UD.dll

otlibeay32mtds.dll

otlibssl32mtds.dll

opentopmtwds.dll

icuuc32d.dll icuio32d.dll

icuin32d.dll icudt32d.dll

PocoXML32mtwds.dll

Unix

Each ClientSDK configuration produces library files with a common base name (libg1client ) but with a unique suffix. Spectrum

™

Technology Platform provides a multithread and release build for ASCII version and UNICODE version.

The library suffixes work like this:libg1client<U>.<so|sl|a>

• U—indicates a UNICODE version build. If this is absent it indicates an ASCII build.

To use the UNICODE version, you need to define LIB_UNICODE in your project.

In UNICODE Version C++ API, the namespace for all classes is g1client.

AIX g1 openssl

ASCII libg1client.so

libcrypto.so libssl.so

Unicode libg1client_U.so

libcrypto.so libssl.so

68 Spectrum

™

Technology Platform 9.0

Poco

Linux g1 openssl opentop icu

API Guide

Poco

Itanium g1 openssl opentop icu opentop icu

Poco

HP-UX g1 openssl opentop icu libopentop-xlCmt.so

Chapter 3: The C++ API

libopentop-xlCmtw.so

libotxml-xlCmtw.so

libicudata34.a libicui18n34.a

libicuio34.a libicuuc34.a

libPocoXML.so

ASCII libg1client.sl

libcrypto.sl libssl.sl

libcrypto.sl.0.9.7 libssl.sl.0.9.7

libopentop-accmt.sl

Unicode libg1client_U.sl

libcrypto.sl libssl.sl

libcrypto.sl.0.9.7 libssl.sl.0.9.7

libopentop-accmtw.sl

libotxml-accmtw.sl

libicudata.sl libicudata.sl.34

libicui18n.sl libicui18n.sl.34

libicuio.sl libicuio.sl.34 libicuuc.sl

libicuuc.sl.34

libPocoXML.sl

ASCII libg1client.sl

libcrypto.a libssl.a

libopentop-accmt.sl

Unicode libg1client_U.sl

libcrypto.a

libssl.a

libopentop-accmtw.sl

libotxml-accmtw.sl

libicudata.sl libicudata.sl.34

libicudata.sl.34.0 libicui18n.sl

libicui18n.sl.34 libicui18n.sl.34.0

libicuio.sl libicuio.sl.34

libicuio.sl.34.0 libicuuc.sl

libicuuc.sl.34 libicuuc.sl.34.0

libPocoXML.sl

ASCII libg1client.so

libcrypto.so libcrypto.so.0.9.7

libssl.so libssl.so.0.9.7

libopentop-gccmt.so

Unicode libg1client_U.so

libcrypto.so libcrypto.so.0.9.7

libssl.so libssl.so.0.9.7

libopentop-gccmtw.so

libotxml-gccmtw.so

libicudata.so libicudata.so.34

libicui18n.so libicui18n.so.34

Introduction to the C++ API

Poco

Solaris g1 openssl opentop icu libicuio.so libicuio.so.34

libicuuc.so libicuuc.so.34

libPocoXML.so

ASCII libg1client.so

libcrypto.so libcrypto.so.0.9.7

libssl.so libssl.so.0.9.7

libopentop-fortemt.so

Unicode libg1client_U.so

libcrypto.so libcrypto.so.0.9.7

libssl.so libssl.so.0.9.7

libopentop-fortemtw.so

libotxml-fortemtw.so

libicudata.so libicudata.so.34

libicui18n.so libicui18n.so.34

libicuio.so libicuio.so.34

libicuuc.so libicuuc.so.34

libPocoXML.so

Poco

Constants

The C++ API uses two sets of constants. The first set is for the Server class described in the table below.

Table 19: Constants for the Server Component

Constant Name Description/Default Example

Server::HOST

Server::PORT

Server::ACCOUNT_ID

String for server host name.

Default is "localhost".

65.89.200.89

String for server port. Default is

"8080".

10119

String for server account ID. No default value.

user1

Server::ACCOUNT_PASSWORD String for server account password. No default value.

user1

Server::CONNECTION_TIMEOUT String for server connection timeout, in milliseconds. Default is "5000".

50000

Server::CONNECTION_TYPE

Server::PROXY_HOST

Server::PROXY_PORT

String for server connection type.

Currently only supports HTTP,

HTTPS, or SOCKET. Default is

"HTTP".

HTTP(S)

String for proxy server host name.

No default value.

192.168.1.77

String for proxy server port. No default value.

8080

70 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Constant Name Description/Default Example

Server::PROXY_USER

Server::PROXY_PASSWORD

String for proxy server account

ID. No default value.

String for proxy server account password. No default value.

user1 user1

The second set of constants is for the Message class:

Table 20: Constants for the Message Component

Constant Name Description

Message::CONTEXT_ACCOUNT_ID String for message context account ID.

Message::CONTEXT_ACCOUNT_PASSWORD String for message context account password.

Message::CONTEXT_SERVICE_NAME String for message context service name.

Example

user1 user1 echoservice

Error Messages

In order to get error messages, use the Exception class. Use the try/catch constructs to capture the error message. For example: try{

Server *server=new Server();

//Connect to server server->connect();

}catch(Exception e)

{

// ASCII Version-use the following code cout << "Error Occurs," << e.getErrorMessage();

//Unicode Version -use the following code

UnicodeString error = e.getErrorMessage() ; wcout << error.getTerminatedBuffer();

}

The C++ API uses the following error messages:

• Error Messages for Connection:

• "Connection type not supported"

• "Client timeout"

• "Blank connection property name"

• "Blank property name"

• Error Messages for creating DataTable:

• "Blank column name"

• "Duplicated column name"

• "The column index is invalid"

• Error Messages for MessagePackaging Exception

API Guide 71

Introduction to the C++ API

• "Input Message is null"

• "Failed to connect to Server"

• "Failed to disconnect from Server"

• "Failed to open Http Connection"

• "Failed to get Service"

• "Failed to package the message using Serializer and Encoding"

SmartPointer

Spectrum

™

Technology Platform provides a class called SmartPointer that uses a simple form of reference counting to help track allocation of dynamic memory and perform memory management task.

For example:

SmartPointer<Server> server =new Server(); server.connect();

...

server.disconnect();

You do not need to delete the memory for pointer server. SmartPointer handles all memory management for you.

Example Application

The sample code shown below illustrates how to use the C++ ASCII version API.

try{

//Create Server

SmartPointer<Server> server =new Server();

//Set server connection properties server->setConnectionProperty(Server::HOST, "localhost"); server->setConnectionProperty(Server::PORT, "10119"); server->setConnectionProperty(Server::CONNECTION_TYPE , "SOCKET"); server->setConnectionProperty(Server::ACCOUNT_ID, "guest"); server->setConnectionProperty(Server::ACCOUNT_PASSWORD, "");

//Connect to server server->connect();

//Get Service From Server

SmartPointer<Service> service = server- >getService("ValidateAddress");

//Create Input Message

SmartPointer<Message> request = new Message();

//Fill DataTable in the input message

SmartPointer<DataTable> dataTable = request->getDataTable();

SmartPointer<DataRow> row1 = dataTable->newRow(); row1->set("AddressLine1", "4200 Parliament Place") ; row1->set("City", "Lanham"); row1->set("StateProvince", "Maryland"); dataTable->addRow(row1);

SmartPointer<DataRow> row2 = dataTable->newRow(); row2->set("AddressLine1", "100 Congress"); row2->set("City", "Austin"); row2->set("StateProvince", "Texas"); dataTable->addRow(row2);

//Set"option" Properties to the Input Message request->putOption("OutputCasing", "M");

72 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

request->putOption("OutputRecordType", "A");

//Process Input Message, return output Message

SmartPointer<Message> reply = service->process(request);

//Disconnect from server server->disconnect();

//Get the result from the resonse message

SmartPointer<DataTable> returnDataTable = reply->getDataTable(); vector<string> columnName = returnDataTable- >getColumnNames(); vector< SmartPointer<DataRow> >::iterator iter = returnDataTable->iterator(); for (int i=0; i< returnDataTable->getRowCount(); i++, iter++)

{

SmartPointer<DataRow> dataRow = *iter; for (int col = 0; col < returnDataTable->getColumnCount(); col++)

{ const char* value = dataRow->get(columnName[col].c_str());

} cout << value << "\n";

}

}catch(Exception e)

{ cout << "Error Occurred, " << e.getErrorMessage();

}

The sample code shown below illustrates how to use the C++ Unicode version API.

try{

//Create Server

SmartPointer<Server> server =new Server();

//Set server connection properties server->setConnectionProperty(Server::HOST,"localhost"); server->setConnectionProperty(Server::PORT, "10119"); server->setConnectionProperty(Server::CONNECTION_TYPE , "SOCKET"); server->setConnectionProperty(Server::ACCOUNT_ID, "guest"); server->setConnectionProperty(Server::ACCOUNT_PASSWORD, "");

//Connect to server server->connect();

//Get Service From Server

//NOTE: ValidateAddress does not support unicode, but supports

//characters in Canadian address and International address data files.

SmartPointer<Service> service = server- >getService("ValidateAddress");

//Create Input Message

SmartPointer<Message> request = new Message();

//Fill DataTable in the input message

SmartPointer<DataTable> dataTable = request->getDataTable(); dataTable->addColumn("AddressLine1"); dataTable->addColumn("City"); dataTable->addColumn("PostalCode"); dataTable->addColumn("Country");

SmartPointer<DataRow> row1 = dataTable->newRow();

UnicodeString address1 = "74, Rue Octave Bénard"; row1->set( 0 , address1);

UnicodeString city1 = "Etang-Salé-les-Bains"; row1->set( 1 , city1);

UnicodeString postalCode1 = "97427"; row1->set( 2 , postalCode1);

API Guide 73

Server

UnicodeString country1 = "Reunion Island"; row1->set( 3 , country1); dataTable->addRow(row1);

SmartPointer<DataRow> row2 = dataTable->newRow();

UnicodeString address2 = "Final Av. Panteón Foro Libertador"; row2->set( 0 , address2);

UnicodeString city2 = "Caracas"; row2->set( 1 , city2);

UnicodeString postalCode2 = "1010"; row2->set( 2 , postalCode2);

UnicodeString country2 = "Venezuela"; row2->set( 3 , country2); dataTable->addRow(row2);

//Set"option" Properties to the Input Message request->putOption("OutputCasing", "M"); request->putOption("OutputRecordType", "A");

//Process Input Message, return output Message

SmartPointer<Message> reply = service->process(request);

//Disconnect from server server->disconnect();

//Get the result from the resonse message

SmartPointer<DataTable> returnDataTable = reply->getDataTable(); vector<UnicodeString> columnName = returnDataTable- >getColumnNames(); vector< SmartPointer<DataRow> >::iterator iter = returnDataTable-

>iterator(); for (int i=0; i< returnDataTable->getRowCount(); i++, iter++)

{

SmartPointer<DataRow> dataRow = *iter; for (int col = 0; col < returnDataTable->getColumnCount(); col++)

{

UnicodeString value = dataRow->get(columnName[col]); wcout <<value.getTerminatedBuffer() <<"\n"; }

}

}catch(Exception e)

{

UnicodeString error = e.getErrorMessage() ; wcout << error.getTerminatedBuffer();

}

Server

The Server class is used to connect to the server, disconnect from the server, and get the service from the server. The following table summarizes the functions each method performs in the Server class.

Table 21: Server Methods Summary

Method

connect

Function

Connects to the server.

74 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Method

disconnect setConnectionProperty getService

Function

Disconnects from the server.

Sets the configuration items for the connection to the server.

Gets the service (i.e., ValidateAddress) from the server.

Note:

See the Modules section of this guide for a list of services that may be available to you.

Constructors

Constructors for the Server class are as follows:

• Server()

Destructor

The Destructor for the Server class is:

• ~Server()

Connect

Reads the properties to determine the configuration settings and makes a connection to the server. You can connect via HTTP, HTTPS, or SOCKET.

Note:

C++ uses the HTTP, HTTPS, or SOCKET server connection protocol. HTTP and HTTPS logically establish a client connection but do not actually connect to the server until a GetService or

Process method is invoked. The SOCKET protocol establishes a connection to the server when

Connect is invoked.

Syntax

void connect()

Parameters

None.

Results

Establishes client connection to the server.

Example

//Create Server

SmartPointer<Server> server =new Server();

API Guide 75

Server

server->setConnectionProperty(Server::ACCOUNT_ID, "guest"); server->setConnectionProperty(Server::ACCOUNT_PASSWORD, "");

//Connect to server server->connect();

Disconnect

Disconnects from the server.

Syntax

void disconnect()

Parameters

None.

Results

Client is disconnected from the server.

Example

SmartPointer<Server> server =new Server() server->connect();

...

server->disconnect();

SetConnectionProperty

Establishes the server connection configuration properties, such as host name and length of timeout.

Syntax

ASCII version:

void setConnectionProperty(const char* name, const char* value)

Unicode version:

void setConnectionProperty(const UnicodeString name, const UnicodeString value)

Parameters

• Name — the name of the connection property, such as HOST

• Value — the value for the name of the connection property, such as "www.myhost.com"

Results

The configuration properties for connection to the server are set.

76 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Example

ASCII Version

SmartPointer<Server> server =new Server() server->setConnectionProperty(Server::HOST,"localhost"); server->setConnectionProperty(Server::PORT, "8080");

Unicode Version

Same as ASCII, or:

SmartPointer<Server> server =new Server()

UnicodeString host="localhost";// Or input unicode string server->setConnectionProperty(Server::HOST, host);

GetService

Gets the service from the server.

Note:

See the Component Reference section of this guide for a list of servies that may be available to you.

Syntax

ASCII Version:

SmartPointer<Service> getService(const char* serviceName)

Unicode Version:

SmartPointer<Service> getService(const UnicodeString serviceName)

Parameters

• Name of service

Results

Returns the specific service.

Example

ASCII Version

// Get Service From Server

SmartPointer<Service> service = server- >getService("ValidateAddress");

Unicode Version

Same as ASCII, or:

// Get Service From Server

UnicodeString serviceName="ValidateAddress";// Or input unicode string

SmartPointer<Service> service = server->getService(serviceName);

API Guide 77

Service

The Service class is used to process the message (i.e., send the message to the server and receive a response from the server).

This class has just one method: Process. The Process method is detailed below.

Process

Processes the input message and returns the response message.

Syntax

SmartPointer<Message> process(Message* message)

Parameters

• Input message

Results

Returns the response message.

Example

SmartPointer<Message> reply = service->process(request);

Message

The Message class sends your input data and receives your output data from the service. The properties for Message include context entities, such as account ID, account password, service name, and service method; option entities, which are the Service-specific runtime options; and error entities, which are the error class, error message and error stacktrace.

Constructors

Constructors for the Message class are as follows:

• Message()

For example:

Message *request = new Message():

• Message(const Message&)

For example:

Message* request = new Message();

Message anotherMessage = request;

Message message(anotherMessage);

78 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Destructor

The Destructor for the Message class is:

• ~Message();

The following table summarizes the functions each method performs in the Message class.

Table 22: Message Methods Summary

Method

getContext getContext putContext putContext setContext getOption getOptions putOption putOptions setOptions getError getDataTable

Function

Gets the value of the context entity identified by the name in the context session of the message.

Gets the Map that contains all of the context entries.

Sets the value of the context entity identified by the name in the context session of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Adds the new context properties to the current context properties.

Overwrites the current context properties with the new context properties.

Gets the value of the option entity identified by the name in the option session of the message.

Gets the Map that contains all of the option entries.

Sets the value of the option entity identified by the name in the option session of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Adds the new option properties to the current option properties.

Overwrites the current option properties with the new option properties.

Gets the error message.

Gets the DataTable from the message.

GetContext

Gets the value of the context entity identified by the name in the context session of the message.

Syntax

ASCII Version

const char* getContext(const char* name)

API Guide 79

Message

Unicode Version

const UnicodeString getContext(const UnicodeString name)

Parameters

• The name whose associated value is to be returned

Results

Returns the value for the name in the context entity. If the name does not exist, the method returns empty string.

Example

ASCII Version

const char* value= msg->getContext(Server::ACCOUNT_ID);

Unicode Version

Same as ASCII or:

UnicodeString name= Server::ACCOUNT_ID;// Or input unicode string

UnicodeString value= msg->getContext(name);

GetContext

Gets the Map that contains all of the context entries.

Syntax

ASCII Version

map<string , string> getContext()

Unicode Version

map< UnicodeString, UnicodeString > getContext()

Parameters

None.

Results

Returns the map that contains all of the context entries.

Example

ASCII Version

map<string , string> context = message->getContext();

Unicode Version

map< UnicodeString, UnicodeString > context = message- >getContext();

80 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

PutContext

Sets the value for given name in the context properties. If there is an existing value present for the entity identified by the name, it is replaced. Context properties include the following constants: account ID, account password, service name, service key, and request ID.

Syntax

ASCII Version

void putContext(const char* name, const char* value)

Unicode Version

void putContext(const UnicodeString name, const UnicodeString value)

Parameters

• Name with which the specified value is to be associated.

• Value to be associated with the specified name

Example

ASCII Version

message->putContext(Message.CONTEXT_ACCOUNT_ID, "user1");

Unicode Version

Same as ASCII or:

UnicodeString account="user1" ;// Or input unicode string message->putContext(Message.CONTEXT_ACCOUNT_ID, account);

PutContext

Adds the new context properties to the current context properties.

Syntax

ASCII Version

void putContext(map<string , string> context)

Unicode Version

void putContext(map< UnicodeString, UnicodeString > context)

Parameters

• The new context map to be added to the current context map

API Guide 81

Message

Example

ASCII Version

map<string , string> context ;

//more code message->putContext(context);

Unicode Version

map< UnicodeString, UnicodeString > context ;

//more code message->putContext(context);

SetContext

Overwrites the current context properties with the new context properties.

Syntax

ASCII Version

void setContext(map<string , string> context)

Unicode Version

void setContext(map< UnicodeString, UnicodeString > context)

Parameters

• The new context map to be used to replace the current context map

Example

ASCII Version

map<string , string> context ;

//more code message->setContext(context);

Unicode Version

map< UnicodeString, UnicodeString > context ;

//more code message->setContext(context);

GetOption

Gets the value of the option entity identified by name in the option section of the message. Option entities include the service-specific runtime options, such as output casing, output data format, and so on.

Syntax

ASCII Version

const char* getOption(const char* name)

82 Spectrum

™

Technology Platform 9.0

Unicode Version

const UnicodeString getOption(const UnicodeString name)

Chapter 3: The C++ API

Parameters

• The name whose associated value is to be returned

Results

Returns the value for the name in the context entity. If the name does not exist, the method returns empty string.

Example

ASCII Version

const char* value = message->getOption("OutputCasing");

Unicode Version

Same as ASCII or:

UnicodeString option="OutputCasing"; // Or input unicode string

UnicodeString value= message->getOption(option);

GetOptions

Gets the map that contains all of the option entries.

Syntax

ASCII Version

map<string , string> getOptions()

Unicode Version

map< UnicodeString, UnicodeString > getOptions()

Parameters

None.

Results

Returns the map that contains all of the option entries.

Example

ASCII Version

const char* value = message->getOption("OutputCasing");

Unicode Version

UnicodeString option="OutputCasing"; //or input Unicode string

UnicodeString value= message->getOption(option);

API Guide 83

Message

PutOption

Sets the value for given name in the option properties. If there is an existing value present for the entity identified by the name, it is replaced. Option properties are the service-specific run-time options.

Syntax

ASCII Version

void putOption(const char* name, const char* value)

Unicode Version

void putOption(const UnicodeString name, const UnicodeString value)

Parameters

• Name with which the specified value is to be associated

• Value to be associated with the specified name

Example

ASCII Version

message->putOption("OutputCasing", "M");

Unicode Version

Same as ASCII or:

UnicodeString option="M"; // Or input unicode string message->putOption("OutputCasing", option);

PutOptions

Adds the new option properties to the current option properties.

Syntax

ASCII Version

void putOptions(map<string , string> options)

Unicode Version

void putOptions(map< UnicodeString, UnicodeString > options)

Parameters

• The new option map to be added to the current option properties

Example

ASCII Version

map<string , string> options ;

//more code message->putOptions(options);

84 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Unicode Version

map< UnicodeString, UnicodeString > options ;

//more code message->putOptions(options);

SetOptions

Overwrites the current option properties with the new option properties.

Syntax

ASCII Version

void setOptions(map<string , string> options)

Unicode Version

void setOptions(map< UnicodeString, UnicodeString > options)

Parameters

• The new option map to be used to replace the current option map

Example

ASCII Version

map<string , string> options ;

//more code message->setOptions(options);

Unicode Version

map< UnicodeString, UnicodeString > options ;

//more code message->setOptions(options);

GetError

Gets the error message from the message.

Syntax

ASCII Version

string getError()

Unicode Version

UnicodeString getError()

Parameters

None.

API Guide 85

DataTable

Results

Returns the error message in message

Example

ASCII Version

String error = message->getError();

Unicode Version

UnicodeString error = message->getError();

GetDataTable

Gets the DataTable in the message.

Syntax

SmartPointer<DataTable> getDataTable()

Parameters

None.

Example

SmartPointer<DataTable> dataTable

= message->getDataTable();

DataTable

DataTable contains the records for the input and output data.

Constructors

Constructors for the DataTable class are as follows:

• DataTable()

For example:

DataTable* dataTable = new DataTable()

Destructor

The Destructor for the DataTable class is:

• ~DataTable();

The following table summarizes the functions each method performs in the DataTable class.

86 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Table 23: DataTable Methods Summary

Method

addColumn getColumnNames getColumnIndex getColumnCount clear iterator addRow newRow getRowCount merge

AddColumn

Adds the new column.

Syntax

ASCII Version

int addColumn(const char* columnName)

Unicode Version

int addColumn(const UnicodeString columnName)

Parameters

• Column name

Results

• Returns the index of column

Exceptions

• Blank column name

• Duplicate column name

Function

Adds the new column.

Gets all the column names.

Gets the corresponding column index.

Gets the number of columns.

Clears the data in DataTable.

An iterator that contains all DataRows in the

DataTable.

Adds a DataRow to the DataTable.

Creates a new DataRow in the DataTable.

Gets the number of the DataRows in this

DataTable.

Merges the given DataTable and the current

DataTable.

API Guide 87

DataTable

Example

ASCII Version

SmartPointer<DataTable> dataTable = message.getDataTable(); dataTable->addColumn("Address"); dataTable->addColumn("City");

Unicode Version

Same as ASCII or:

SmartPointer<DataTable> dataTable = message.getDataTable();

UnicodeString columnName="Address"; // Or input unicode string dataTable->addColumn(columnName);

GetColumnNames

Gets all the column names.

Syntax

ASCII Version

vector<string> getColumnNames();

Unicode Version

vector<UnicodeString> getColumnNames();

Parameters

None.

Results

Returns the vector of column names

Example

ASCII Version

vector<string> columnNames = dataTable->getColumnNames();

Unicode Version

vector<UnicodeString> columnNames = dataTable->getColumnNames();

GetColumnIndex

Gets the corresponding column index.

Syntax

ASCII Version

int getColumnIndex(const char* columnName)

88 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Unicode Version

int getColumnIndex(const UnicodeString columnName)

Parameter

• Column name

Results

Returns the corresponding column index.

Example

ASCII Version

int columnIndex = dataTable->getColumnIndex ("City");

Unicode Version

Same as ASCII or:

UnicodeString columnName="City"; // Or input unicode string int columnIndex = dataTable->getColumnIndex (columnName);

GetColumnCount

Gets the number of columns.

Syntax

int getColumnCount()

Parameter

None.

Results

Returns the number of columns.

Example

int columnCount = dataTable->getColumnCount ();

Clear

Clears the data in DataTable.

Syntax

void clear()

Parameters

None.

API Guide 89

DataTable

Example

dataTable->clear();

Iterator

An iterator that contains all DataRows in the DataTable.

Syntax

vector< SmartPointer<DataRow> >::iterator iterator()

Parameters

None.

Results

Returns an iterator that contains all DataRows in the DataTable.

Example

vector<string> columnName

= returnDataTable->getColumnNames(); vector< SmartPointer<DataRow> >::iterator theIterator

= returnDataTable->iterator(); for (int i=0; i< returnDataTable->getRowCount(); i++, theIterator++)

{

SmartPointer<DataRow> dataRow = *theIterator; for (int col = 0; col < returnDataTable->getColumnCount(); col++)

{ const char* value = dataRow->get(columnName[col].c_str());

}

AddRow

Adds a DataRow to the DataTable.

Syntax

void addRow( SmartPointer<DataRow> dataRow)

Parameters

• DataRow to be added to the DataTable

Example

SmartPointer<DataRow> newRow = dataTable->newRow(); newRow->set( 0 , "10535 Boyer"); newRow->set( 1 , "Austin");

90 Spectrum

™

Technology Platform 9.0

newRow->set( 2 , "Texas"); dataTable->addRow(newRow);

NewRow

Creates a new DataRow in the DataTable.

Syntax

SmartPointer<DataRow> newRow()

Results

Returns the new created DataRow

Example

SmartPointer<DataRow> newRow = dataTable->newRow(); newRow->set( 0 , "10535 Boyer"); newRow->set( 1 , "Austin"); newRow->set( 2 , "Texas"); dataTable->addRow(newRow);

GetRowCount

Gets the number of the DataRows in this DataTable.

Syntax

int getRowCount()

Results

Returns the number of the DataRows in this DataTable.

Example

int rowCount = dataTable->getRowCount();

Merge

Merges the given DataTable and the current DataTable.

Syntax

void merge(DataTable* other)

Parameters

• Other DataTable to be merged with the current DataTable

Chapter 3: The C++ API

API Guide 91

DataRow

Example

DataTable* otherDataTable = new DataTable(); dataTable->merge(otherDataTable);

DataRow

DataRow contains the record for the input and output data.

Constructor

Constructors for the DataRow class are as follows:

• DataRow ()

For example:

DataRow * dataRow = new DataRow();

• DataRow(const DataRow&)

For example:

DataRow* dataRow = new DataRow();

DataRow anotheDataRow = dataRow;

DataRow newDataRow(anotheDataRow);

Destructor

The Destructor for the DataRow class is:

• ~ DataRow();

The following table summarizes the functions each method performs in the DataRow class.

Table 24: DataRow Methods Summary

Method

getColumnNames getColumnIndex getColumnCount get get merge

Function

Gets all the column names.

Gets the corresponding column index.

Gets the number of columns.

Gets the value from the fields array by the column index in this DataRow.

Gets the value from the fields array by the column name in this DataRow.

Merges the given DataTable and the current

DataTable.

92 Spectrum

™

Technology Platform 9.0

Method

set set addChild getChildren listChildNames setChildren

Chapter 3: The C++ API

Function

Sets the value for the corresponding column name for the DataRow. If the value for the name exists, the old value is replaced.

Sets the value for the corresponding column index for the DataRow. If the value for the name exists, the old value is replaced.

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied DataRow will be appended to the existing

DataRow Collection, otherwise a new Collection will be created with the supplied DataRow as its only element.

Retrieves the child rows from a named relationship.

Retrieves all of the names of the named parent/child relationships.

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

GetColumnNames

Gets all the column names.

Syntax

ASCII Version

vector<string> getColumnNames()

Unicode Version

vector<UnicodeString> getColumnNames()

Parameters

None.

Results

Returns the vector of column names

Example

ASCII Version

vector<string> columnNames = dataRow->getColumnNames();

Unicode Version

vector<UnicodeString> columnNames = dataRow->getColumnNames();

API Guide 93

DataRow

GetColumnIndex

Gets the corresponding column index.

Syntax

ASCII Version

int getColumnIndex(const char* columnName)

Unicode Version

int getColumnIndex(const UnicodeString columnName)

Parameter

• Column name

Results

Returns the corresponding column index.

Example

ASCII Version

int columnIndex = dataRow->getColumnIndex ("City");

Unicode Version

Same as ASCII or:

UnicodeString columnName="City"; // Or input unicode string int columnIndex = dataRow->getColumnIndex (columnName);

GetColumnCount

Gets the number of columns.

Syntax

int getColumnCount()

Parameter

None.

Results

Returns the number of columns.

Example

int columnCount = dataRow->getColumnCount ();

94 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Get

Gets the value from the fields array by the column index in this DataRow.

Syntax

ASCII Version

const char* get(int index)

Unicode Version

const UnicodeString get(int index)

Parameters

• Index with which the specified value is to be associated

Results

Returns the value for the column index in the DataRow, returns empty string if the index in invalid.

Example

ASCII Version

const char* value = dataRow->get(1);

Unicode Version

const UnicodeString value = dataRow->get(1);

Get

Gets the value from the fields array by the column name in this DataRow

Syntax

ASCII Version

const char* get(const char* columnName)

Unicode Version

const UnicodeString get(const UnicodeString columnName)

Parameters

• Name with which the specified value is to be associated

Results

Returns the value for the column name in the DataRow, returns empty string if the column name does not exist.

API Guide 95

DataRow

Example

ASCII Version

const char* value = dataRow->get("City");

Unicode Version

Same as ASCII, or:

UnicodeString columnName="City"; // Or input unicode string const UnicodeString value = dataRow->get(columnName);

Merge

Merges the given DataRow and the current DataRow.

Syntax

void merge(DataRow* other)

Parameters

• Other DataRow to be merged with the current DataRow

Example

DataRow* otherDataRow = new DataRow();

DataRow->merge(otherDataRow);

Set

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Syntax

ASCII Version

void set(const char* columnName, const char* value)

Unicode Version

void set(const UnicodeString columnName, const UnicodeString value)

Parameters

• Name with which the specified value is to be associated

• Value to be associated with the specified name

Exceptions

• Blank column name

• Duplicate column name

96 Spectrum

™

Technology Platform 9.0

Chapter 3: The C++ API

Example

ASCII Version

SmartPointer<DataRow> newRow = dataTable->newRow(); newRow->set( "AddressLine1" , "10535 Boyer"); newRow->set( "City" , "Austin"); newRow->set( "State" , "Texas");

Unicode Version

Same as ASCII or:

SmartPointer<DataRow> newRow = dataTable->newRow();

UnicodeString address="10535 Boyer"; // Or input unicode string newRow->set( "AddressLine1" , address);

Set

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Syntax

ASCII Version

void set(int index, const char* value)

Unicode Version

void set(int index, const UnicodeString value)

Parameters

• Column index with which the specified value is to be associated

• Value to be associated with the specified name

Exceptions

• The column index is invalid.

Example

ASCII Version

SmartPointer<DataRow> newRow = dataTable->newRow(); newRow->set( 0 , "10535 Boyer"); newRow->set( 1 , "Austin"); newRow->set( 2 , "Texas");

Unicode Version

Same as ASCII or:

SmartPointer<DataRow> newRow = dataTable->newRow();

UnicodeString address="10535 Boyer"; // Or input unicode string newRow->set( 0 , address);

API Guide 97

DataRow

AddChild

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied

DataRow will be appended to the existing DataRow collection. Otherwise, a new collection will be created with the supplied DataRow as its only element.

Syntax

ASCII Version

void addChild(const char* childName, SmartPointer<DataRow> childDataRow)

Unicode Version

void addChild(const UnicodeString childName, SmartPointer<DataRow> childDataRow)

Parameters

• The name of the parent/child relationship (for example, "Flood Plain Data," "References, " "Used By")

• The DataRow to be added to the relationship.

Example

SmartPointer<DataRow> childDataRow =new DataRow(); childDataRow ->set("Address", "100 Congress"); childDataRow ->set("City", "Austin");

SmartPointer<DataRow> dataRow =new DataRow(); dataRow->addChild("child1", childDataRow );

GetChildren

Retrieves the child rows from a named relationship.

Syntax

ASCII Version

list< SmartPointer<DataRow> > getChildren(const char* childName)

Unicode Version

list< SmartPointer<DataRow> > getChildren(const UnicodeString childName)

Parameters

• The name of the parent/child relationship, e.g. "Flood Plain Data", "References", "Used By", etc.

Results

Returns the child rows from the named relationship.

Example

list< SmartPointer<DataRow> > rowsChild2= dataRow- >getChildren("child2");

98 Spectrum

™

Technology Platform 9.0

ListChildNames

Retrieves all of the names of the named parent/child relationships.

Syntax

ASCII Version

list<string> listChildNames()

Unicode Version

list<UnicodeString> listChildNames()

Results

Returns the set of the names of the named parent/child relationships.

Example

list<G1CLIENT_STRING> names = dataRow->listChildNames();

Chapter 3: The C++ API

SetChildren

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

Syntax

ASCII Version

list< SmartPointer<DataRow> > setChildren(const char* childName, list<

SmartPointer<DataRow> > dataRows)

Unicode Version

list< SmartPointer<DataRow> > setChildren(const UnicodeString childName, list< SmartPointer<DataRow> > dataRows)

Results

Returns the set of the names of the named parent/child relationships.

Example

SmartPointer<DataRow> dataRow1=new DataRow(); dataRow1->set("Address", "100 Congress"); dataRow1->set("City", "Austin");

SmartPointer<DataRow> dataRow2=new DataRow(); dataRow2->set("Address", "200 Congress"); dataRow2->set("City", "Austin"); list< SmartPointer<DataRow> > rows ; rows.push_back(dataRow1); rows.push_back(dataRow2); list< SmartPointer<DataRow> > rowsNewChildren = dataRowSpt-

>setChildren("child1", rows);

API Guide 99

The COM API

In this section:

•

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

•

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

•

Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

•

Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

•

DataTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114

•

DataRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120

•

Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126

Introduction

The term Component Object Model (COM) refers to an open architecture for cross-platform development of client/server applications based on object-oriented technology. COM is a way of creating reusable software components. Clients have access to an object through interfaces implemented on the object.

In other words, objects are the communication medium between client and server. The Component

Object Model provides a flexible way for building distributed object-oriented systems. COM objects are language-independent, can be shipped in binary form, can be upgraded without requiring changes to the existing integrated code, and can be transparently relocated on a network. Because of these qualities,

COM objects are extremely flexible and can be adapted to add specific functionality to almost any

Windows-based client-server system.

Note:

The examples shown in this chapter are written in Visual Basic.

The Spectrum

™

Technology Platform COM API consists of the following interfaces:

• Server

• Service

• Message

• DataTable

• DataRow

• Map

These interfaces are described in detail in the following sections of this chapter.

Constants

The COM API uses two sets of constants. The first set is for the Server object, described in the table below.

Table 25: Constants for the Server Component

Constant Name Description/Default Example

SERVER.HOST

SERVER.PORT

SERVER.ACCOUNT_ID

SERVER.ACCOUNT_PASSWORD

SERVER.CONNECTION_TIMEOUT

SERVER.CONNECTION_TYPE

SERVER.PROXY_HOST

SERVER.PROXY_PORT

String for server host name. Default is

"localhost".

65.89.200.89

String for server port. Default is "8080".

10119

String for server account ID. No default value.

user1

String for server account password. No default value.

user1

String for server connection timeout, in milliseconds. Default is "5000".

50000

String for server connection type.

Currently only supports HTTP, HTTPS, or SOCKET. Default is "HTTP".

HTTP(S)

String for proxy server host name. No default value.

192.168.1.77

String for proxy server port. No default value.

8080

102 Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

Constant Name

SERVER.PROXY_USER

SERVER.PROXY_PASSWORD

Description/Default Example

String for proxy server account ID. No default value.

user1

String for proxy server account password. No default value.

user1

The second set of constants is for the Message component.

Table 26: Constants for the Message Component

Constant Name Description Example

MESSAGE.CONTEXT_ACCOUNT_ID

MESSAGE.CONTEXT_ACCOUNT_PASSWORD

String for message context account password.

MESSAGE.CONTEXT_SERVICE_NAME

String for message context account ID.

String for message context service name.

user1 user1 echoservice

Error Messages

The COM API uses the following error messages:

• Error Messages for Connection:

• "Connection type not supported"

• "Client timeout"

• Error Messages for creating DataTable:

• "Blank column name"

• "Duplicated column name"

• "The column index is invalid"

• Error Messages for Message Packaging Exception

• "Input Message is null"

• "Failed to connect to Server"

• "Failed to disconnect to Server"

• "Failed to open Http Connection"

• "Failed to get Service"

• "Failed to package the message using Serializer and Encoding"

For example:

On Error GoTo ErrorHandler

Dim server As New G1CLIENTLib.server

server.setConnectionProperty server.HOST, "localhost" server.setConnectionProperty server.Port, "8080"

'Making connection to the server server.Connect

...

Exit Sub

ErrorHandler:

MsgBox Err.Description

API Guide 103

Introduction

Example Application

The sample code shown below illustrates how to use the COM API.

On Error GoTo ErrorHandler

Dim server As New G1CLIENTLib.server

Dim service As G1CLIENTLib.service

Dim requestMsg As New G1CLIENTLib.Message

Dim replyMsg As G1CLIENTLib.Message

Dim dataTable As G1CLIENTLib.dataTable

Dim newRow As G1CLIENTLib.dataRow

Dim returnDataTable As G1CLIENTLib.dataTable

Dim row As G1CLIENTLib.DataRow

Dim sColumnNames() As String

Dim sColumnName As String

Dim sFieldValue As String

Dim rows() As Variant

Dim nRow As Integer

Dim nColumn As Integer

'Set server connection properties server.setConnectionProperty server.HOST, "localhost" server.setConnectionProperty server.Port, "10119" server.setConnectionProperty server.CONNECTION_TYPE, "SOCKET" server.setConnectionProperty server.ACCOUNT_ID, "guest" server.setConnectionProperty server.ACCOUNT_PASSWORD, ""

'Connect to server server.Connect

'Get the service from the server

Set service = server.getService("ValidateAddress")

'Fill DataTable in the input message

Set dataTable = requestMsg.getDataTable

dataTable.addColumn ("AddressLine1") dataTable.addColumn ("City") dataTable.addColumn ("StateProvince")

Set newRow = dataTable.newRow

newRow.setByIndex 0, "10535 Boyer" newRow.setByIndex 1, "Austin" newRow.setByIndex 2, "Texas" dataTable.addRow newRow

'Set"option" Properties to the Input Message requestMsg.putOption "OutputCasing", "M" requestMsg.putOption "OutputRecordType", "A"

'Process Input Message, return output Message

Set replyMsg = service.process(requestMsg)

'Disconnect from the server server.disconnect

'Get the result from the resonse message

Set returnDataTable = replyMsg.getDataTable

ReDim rows(returnDataTable.getRowCount) As Variant rows = returnDataTable.iterator

ReDim sColumnNames(returnDataTable.getColumnCount) As String sColumnNames = returnDataTable.getColumnNames

For nRow = 0 To returnDataTable.getRowCount - 1

Set row = rows(nRow)

For nColumn = 0 To row.getColumnCount - 1 sColumnName = sColumnNames(nColumn)

104 Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

sFieldValue = row.getByName(sColumnName)

Exit Sub

ErrorHandler:

MsgBox Err.Description

Server

Use the Server object to connect to the server, disconnect from the server, and get the service from the server. The following table summarizes the functions each method performs in the Server object.

Table 27: Server Methods Summary

Method

connect disconnect getService setConnectionProperty

Function

Connects to the server.

Disconnects from the server.

Gets the service (i.e., ValidateAddress) from the server.

Sets the configuration items for the connection to the server.

Note:

See the Modules section of this guide for a list of services that may be available to you.

Connect

Connects to the server. You can connect via HTTP or SOCKET.

Note:

COM uses the HTTP, HTTPS, or SOCKET server connection protocol. HTTP and HTTPS logically establish a client connection but do not actually connect to the server until a GetService or

Process method is invoked. The SOCKET protocol establishes a connection to the server when

Connect is invoked.

Syntax

Sub connect()

Parameters

None.

Results

None.

API Guide 105

Server

Exception

Connection type not supported.

Example

Dim server As New G1CLIENTLib.server

server.connect

Disconnect

Disconnects from the server.

Syntax

Sub disconnect()

Parameters

None.

Results

None.

Examples

Dim server As New G1CLIENTLib.server

server.disconnect

GetService

Gets the service (such as ValidateAddress) from the server.

Note:

See the Component Reference section of this guide for a list of services that may be available to you.

Syntax

Function getService(serviceName As String) As Service

Parameters

• serviceName - the name of the service which the client requires

Results

The requested service or NULL if the service does not exist.

Exceptions

• ERROR_FAIL_TO_GET_SERVICE — if there is no connection to the server.

106 Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

Example

Dim server As New G1CLIENTLib.server

Dim service As G1CLIENTLib.service

...

'get the service from the server

Set service = server.getService("ValidateAddress")

SetConnectionProperty

Establishes the server connection configuration properties, such as host name and length of timeout.

Syntax

Sub setConnectionProperty(name As String, value As String)

Parameters

• Name — the name of the connection property, such as HOST

• Value — the value for the name of the connection property, such as "www.myhost.com"

Results

Return codes — none.

Exceptions

• ERROR-INVALID-COLUMN_NAME — an empty or null column name.

• ERROR_INVALID_VALUE — A null value.

Example

set connection properties

Dim server As New G1CLIENTLib.server

server.setConnectionProperty server.HOST,"localhost" server.setConnectionProperty server.PORT, "8080"

Service

Service calls the service and processes the message you are sending (in other words, it sends the input message and receives the response).

There is only one method in the Service object.

Table 28: Service Methods Summary

Method

process

Function

Processes the input message and gets back the response message from the server.

API Guide 107

Message

Process

Processes the input message and gets back the response message from the server.

Syntax

Function process(IRequest As Message) As Message

Parameters

• iRequest— the input message object that contains the "option" setting and the DataTable

Results

Returns the response message for the request.

Exceptions:

• ERROR_NULL_INPUT_MESSAGE — Request message is null.

Example

Dim service As New G1CLIENTLib.service

Dim replyMsg As G1CLIENTLib.Message

...

'Process the message and return back the response message

Set replyMsg = service.process(requestMsg)

Message

Messages are used to send your input data and receive your output data from the service. The properties for Message include "context entities, such as account ID, account password, service name, and service method; "option entities, which are the service-specific runtime options; and "error entities, which are the error class, error message and error stacktrace.

The following table summarizes the functions each method performs in the Message object.

Table 29: Message Methods Summary

Method

getContext getContextMap putContext putContextMap

Function

Gets the value of the context entity identified by name in the context section of the message.

Gets the map that contains all of the context entries.

Sets the value of the context entity identified by name in the context session of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Add the new context properties to the current context properties.

108 Spectrum

™

Technology Platform 9.0

Method

setContextMap getOption getOptions putOption putOptions setOptions getError getDataTable

Chapter 4: The COM API

Function

Overwrite the current context properties with the new context properties.

Gets the value of the option entity identified by name in the option section of the message.

Gets the map that contains all of the option entries.

Sets the value of the option entity identified by name in the option section of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Add the new option properties to the current option properties.

Overwrite the current option properties with the new option properties.

Gets the error from the error message.

Gets the specified data table from the message.

GetContext

Gets the value of the context entity identified by name in the context section of the message. "Context" entities include the following constants: account ID, account password, service name, and service method.

Syntax

Function getContext(name As String) As String

Parameters

• Name—the name whose associated value is to be returned

Results

String — the value of the named entity or empty string if the named entity does not exist.

Example

Dim msg As New G1CLIENTLib.Message

Dim accountID As String accountID = msg.getContext(msg.CONTEXT_ACCOUNT_ID)

GetContextMap

Gets the Map that contains all of the context entries.

API Guide 109

Message

Syntax

Function getContextMap() As Map

Parameters

• None

Results

Returns the Map that contains all of the context entries.

Example

Dim map As G1CLIENTLib.Map

Dim requestMsg As New G1CLIENTLib.Message

Dim sKey As String

Dim sValue As String requestMsg.putContext

requestMsg.CONTEXT_ACCOUNT_ID, "admin" requestMsg.putContext

requestMsg.CONTEXT_ACCOUNT_PASSWORD, "admin"

Set map = requestMsg.getContextMap

map.Reset

While (map.Next) sKey = map.getKey

sValue = map.getValue

Wend

PutContext

Sets the value for the given name in the context properties. If there is an existing value present for the entity identified by the name, it is replaced. "Context" properties include the following constants: account

ID, account password, service name, and service method.

Syntax

Sub putContext(name As String, value As String)

Parameters

• Name—the name with which the specified value is to be associated

• Value—value to be associated with the specific name.

Results

None.

Example

Dim requestMsg As New G1CLIENTLib.Message

requestMsg.putContext

requestMsg.CONTEXT_ACOUNT_ID, "admin" requestMsg.putContext

requestMsg.CONTEXT_ACOUNT_PASSWORD, "admin"

110 Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

PutContextMap

Adds the new context properties to the current context properties.

Syntax

Sub putContextMap(context As Map)

Parameters

• The new context map to be added to the current context map

Results

None.

Example

Dim map As New G1CLIENTLib.Map

Dim requestMsg As New G1UBCAPICOMLib.Message

map.Insert requestMsg.CONTEXT_ACCOUNT_ID, "admin" map.Insert requestMsg.CONTEXT_ACOUNT_PASSWORD, "admin" requestMsg.putContextMap map

SetContextMap

Overwrites the current context properties with the new context properties.

Syntax

Sub setContextMap(context As Map)

Parameters

• The new context map to replace the current context map

Results

None.

Example

Dim map As New G1CLIENTLib.Map

Dim requestMsg As New G1UBCAPICOMLib.Message

map.Insert requestMsg.CONTEXT_ACCOUNT_ID, "admin" map.Insert requestMsg.CONTEXT_ACOUNT_PASSWORD, "admin" requestMsg.setContextMap map

GetOption

API Guide 111

Message

Syntax

Function getOption(name As String) As String

Parameters

• Name — the name whose associated value is to be returned

Results

• String — the value of the named entity or empty string if the named entity does not exist.

Example

Dim msg As New G1CLIENTLib.Message

Dim optionValue As String

OptionValue = msg.getOption("OutputCasing")

GetOptions

Gets the map that contains all of the option entries.

Syntax

Function getOptions() As Map

Parameters

• None

Results

Returns the map that contains all of the option entries.

Example

Dim map As New G1CLIENTLib.Map

Dim requestMsg As New G1CLIENTLib.Message

Dim sKey As String

Dim sValue As String requestMsg.putOption "OutputCasing", "M" requestMsg.putOption "OutputRecordType", "A"

Set map = requestMsg.getOptions

map.Reset

While (map.Next) sKey = map.getKey

sValue = map.getValue

Wend

PutOption

Sets the value for the given name in the option properties. If there is an existing value present for the entity identified by the name, it is replaced. "Option" properties are the service-specific runtime options.

112 Spectrum

™

Technology Platform 9.0

Syntax

Sub putOption(name As String, value As String)

Parameters

• Name—the name with which the specified value is to be associated

• Value—value to be associated with the specific name.

Example

Dim requestMsg As New G1CLIENTLib.Message

requestMsg.putOption "OutputCasing", "M" requestMsg.putOption "OutputRecordType", "A"

PutOptions

Adds the new option properties to the current option properties.

Syntax

Sub putOptions(options As Map)

Parameters

• The new option map to be added to the current option properties

Example

Dim map As New G1CLIENTLib.Map

Dim requestMsg As New G1CLIENTLib.Message

map.Insert "OutputCasing", "M" map.Insert "OutputRecordType", "A" requestMsg.putOptions map

SetOptions

Overwrites the current option properties with the new option properties.

Syntax

Sub setOptions(options As Map)

Parameters

• The new option map to replace the current option map

Example

Dim map As New G1CLIENTLib.Map

Dim requestMsg As New G1CLIENTLib.Message

map.Insert "OutputCasing", "M"

API Guide

Chapter 4: The COM API

113

DataTable

map.Insert "OutputRecordType", "A" requestMsg.setOptions map

GetError

Gets the error from the error message.

Syntax

Function getError() As String

Parameters

• None

Results

Returns the error message in the message.

Example

Dim sErrorMessage As String

...

sErrorMessage = replyMsg.getError()

GetDataTable

Gets the DataTable in the message.

Syntax

Function getDataTable() As DataTable

Parameters

• None.

Example

Dim DataTable AS G1CLIENTLib.dataTable

Set DataTable = message.getDataTable

DataTable

DataTable contains the records for your input and output data. Using the methods associated with this object, you define the column names for your output and add rows to the DataTable.

The following table summarizes the functions each method performs in the DataTable object.

114 Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

Table 30: DataTable Methods Summary

Method

addColumn getColumnNames getColumnIndex getColumnCount clear iterator addRow newRow getRowCount merge

Function

Adds a new column to the DataTable.

Gets all the column names.

Gets the corresponding column index.

Gets the number of columns.

Clears all the data in the DataTable.

An iterator that contains all the rows in the

DataTable.

Adds a DataRow to the DataTable.

Creates a new DataRow in the DataTable.

Gets the number of DataRows in the DataTable.

Merge the given DataTable and the current

DataTable.

These methods are discussed in more detail in the following sections.

AddColumn

Adds the new column to the DataTable.

Syntax

Function addColumn(columnName As String) As Integer

Parameters

• Column name

Results

Returns the index of the column

Exceptions

• Blank column name

• Duplicate column name

Example

Dim dataTable As G1CLIENTLib.dataTable

dataTable.addcolumn "AddressLine1" dataTable.addcolumn "City"

API Guide 115

DataTable

GetColumnNames

Gets all the column names.

Syntax

Syntax Function getColumnNames() As String()

Parameters

• None

Results

Returns the array of column names.

Example

Dim sColumnNames() As String

Dim sColumnName As String

Dim nColumn As Integer

ReDim sColumnNames(returnDataTable.getColumnCount) As String sColumnNames = returnDataTable.getColumnNames

For nColumn = 0 To dataRow.getColumnCount - 1 sColumnName = sColumnNames (nColumn)

GetColumnIndex

Gets the corresponding column index.

Syntax

Function getColumnIndex(columnName As String) As Integer

Parameters

• Column name

Results

Returns the corresponding column index.

Example

Dim nIndex As Integer nIndex = dataTable.getColumnIndex("AddressLine1")

GetColumnCount

Gets the number of columns in the DataTable.

116 Spectrum

™

Technology Platform 9.0

Syntax

Function getColumnCount() As Integer

Parameters

• None

Results

Returns the number of columns.

Example

Dim nColumnCount As Integer nColumnCount = dataTable.getColumnCount()

Clear

Clears the data in the DataTable.

Syntax

Sub clear()

Parameters

• None

Example

dataTable.clear()

Iterator

An iterator that contains all DataRows in the DataTable.

Syntax

Syntax Function iterator() As DataRow()

Parameters

• None

Results

Returns an iterator that contains all DataRows in the DataTable.

Example

Dim returnDataTable As G1CLIENTLib.dataTable

Dim row As G1CLIENTLib.DataRow

Dim sColumnName As String

Dim sFieldValue As String

API Guide

Chapter 4: The COM API

117

DataTable

Dim rows() As Variant

Dim nRow As Integer

Dim nColumn As Integer

'Get the result from the resonse message

Set returnDataTable = replyMsg.getDataTable

ReDim rows(returnDataTable.getRowCount) As Variant rows = returnDataTable.iterator

For nRow = 0 To returnDataTable.getRowCount - 1

Set row = rows(nRow)

For nColumn = 0 To row.getColumnCount - 1 sColumnName = row.getColumnNames(nColumn) sFieldValue = row.getByName(sColumnName)

AddRow

Adds a DataRow to the DataTable.

Syntax

Sub addRow(DataRow As DataRow)

Parameters

• DataRow to be added to the DataTable

Results

None.

Example

Dim dataTable As G1CLIENTLib.dataTable

Dim newRow As G1CLIENTlib.DataRow

Set dataTable=requestMsg.getDataTable

dataTable.addColumn("AddressLine1") dataTable.addColumn("City") dataTable.addColumn("State")

Set newRow=dataTable.newRow

newRow.setByIndex 0, "10535 Boyer" newRow.setByIndex 1, "Austin" newRow.setByIndex 2, "Texas" dataTable.addRow newRow

NewRow

Creates a new DataRow in the DataTable.

Syntax

Function newRow() As DataRow

118 Spectrum

™

Technology Platform 9.0

Parameters

• None

Results

Returns the newly created DataRow

Example

Dim dataTable As G1CLIENTLib.dataTable

Dim newRow As G1CLIENTlib.DataRow

Set dataTable=requestMsg.getDataTable

Set newRow=dataTable.newRow

newRow.setByName "AddressLine1","10535 Boyer" newRow.setByName "City", "Austin" newRow.setByName "State", "Texas" dataTable.addRow newRow

GetRowCount

Gets the number of DataRows in the DataTable.

Syntax

Function getRowCount() As Integer

Parameters

• None

Results

Returns the number of DataRows in the DataTable.

Example

Dim nRowCount As Integer nRowCount = dataTable.getRowCount

Merge

Merges the given DataTable and the current DataTable.

Syntax

Sub merge(other As DataTable)

Parameters

• The other DataTable to be merged with the current DataTable

Results

None.

API Guide

Chapter 4: The COM API

119

DataRow

Example

Dim otherDataTable As New G1CLIENTlib.dataTable

...

dataTable.merge(otherDataTable)

DataRow

DataRow contains the individual records for your input and output data. Using the methods associated with this class, you define the column names for your output and add records to the DataTable.

The following table summarizes the functions each method performs in the DataRow class.

Table 31: DataRow Methods Summary

120

Method

getColumnNames getColumnIndex getColumnCount getByIndex getByName merge setByName setByIndex addChild getChildren listChildNames setChildren

Function

Gets all the column names.

Gets the corresponding column index.

Gets the number of columns.

Gets the value from the field array by the column index in this DataRow.

Gets the value from the field array by the column name in this DataRow.

Merges the given DataRow and the current

DataRow.

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied DataRow will be appended to the existing

DataRow Collection, otherwise a new Collection will be created with the supplied DataRow as its only element.

Retrieves the child rows from a named relationship.

Retrieves all of the names of the named parent/child relationships.

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

These methods are discussed in more detail in the following sections.

Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

GetColumnNames

Gets all the column names.

Syntax

Function getColumnNames() As String()

Parameters

• None

Results

Returns the array of column names.

Example

Dim sColumnNames() As String

Dim sColumnName As String

Dim nColumn As Integer

ReDim sColumnNames(dataRow.getColumnCount) As String sColumnName = sColumnNames(nColumn)

For nColumn = 0 To dataRow.getColumnCount -1 sColumnName = sColumnNames(nColumn)

GetColumnIndex

Gets the corresponding column index.

Syntax

Function getColumnIndex(columnName As String) As Integer

Parameters

• Column name

Results

Returns the corresponding column index.

Example

Dim nIndex As Integer nIndex = dataRow.getColumnIndex("AddressLine1")

GetColumnCount

Gets the number of columns in the DataRow.

Syntax

Function getColumnCount() As Integer

API Guide 121

DataRow

Parameters

• None

Results

Returns the number of columns.

Example

Dim nColumnCount As Integer nColumnCount = dataRow.getColumnCount()

GetByIndex

Gets the value from the field array by the column index in this DataRow.

Syntax

Function getByIndex(index As Integer) As String

Parameters

• Index with which the specified value is to be associated

Results

Returns the value for the column index in this DataRow. Returns empty string if the index is invalid.

Example

Dim sValue As String sValue = dataRow.getByIndex(1)

GetByName

Gets the value from the field array by the column name in this DataRow.

Syntax

Function getByName(columnName As String) As String

Parameters

• Name with which the specified value is to be associated

Results

Returns the value for the column name in this DataRow; returns empty string if the column name does not exist.

Example

Dim sValue As String sValue = dataRow.getByName("City")

122 Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

Merge

Merges the given DataRow and the current DataRow.

Syntax

Sub merge(other As DataRow)

Parameters

• The other DataRow to be merged with the current DataRow

Results

None.

Example

Dim otherDataRow As New G1CLIENTlib.DataRow

...

dataRow.merge(otherDataRow)

SetByName

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Syntax

Sub setByName(columnName As String, value As String)

Parameters

• The name with which the specified value is to be associated

• Value to be associated with the specified name

Results

None.

Exceptions

• Blank column name

• Duplicate column name

Example

Dim newRow As G1CLIENTLib.DataRow

Set newRow= dataTable.netRow

newRow.setByName "AddressLine1", "100 Congress" newRow.setByName "City", "Austin" newRow.setByName "State", "Texas" dataTable.addRow newRow

API Guide 123

DataRow

SetByIndex

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Syntax

Sub setByIndex(index As Integer, value As String)

Parameters

• The column index with which the specified value is to be associated

• Value to be associated with the specified name

Results

None.

Exceptions

• The column index is invalid

Example

Dim newRow As G1CLIENTLib.DataRow

Set newRow= dataTable.netRow

newRow.setByIndex 0, "100 Congress" newRow.setByIndex 1, "Austin" newRow.setByIndex 2, "Texas" dataTable.addRow newRow

AddChild

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied

DataRow will be appended to the existing DataRow collection. Otherwise, a new collection will be created with the supplied DataRow as its only element.

Syntax

Sub addChild( childName As String, childDataRow As DataRow)

Parameters

• The name of the parent/child relationship (e.g., "Flood Plain Data," "References, " "Used By," etc.)

• The DataRow to be added to the relationship.

Results

None.

Example

Dim dataRow As New G1CLIENTLib.dataRow

Dim childDataRow As New G1CLIENTLib.dataRow

childDataRow .setByName "Address", "100 Congress"

124 Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

childDataRow .setByName "City", "Austin" dataRow.addChild "child1", dataRow

GetChildren

Retrieves the child rows from a named relationship.

Syntax

Function getChildren(childName As String) As DataRow()

Parameters

• The name of the parent/child relationship, e.g. "Flood Plain Data", "References", "Used By", etc.

Result

Returns the child rows from the named relationship.

Example

Dim dataRow As New G1CLIENTLib.dataRow

' Assume that dataRow has children ......

' Or more code to be needed

Dim rowsChild1() As Variant rowsChild1 = dataRow.getChildren("child1")

ListChildNames

Retrieves all of the names of the named parent/child relationships.

Syntax

Function listChildNames() As String()

Parameters

None.

Results

Returns the set of the names of the named parent/child relationships.

Example

Dim dataRow As New G1CLIENTLib.dataRow

' Assume that dataRow has children ......

' Or more code to be needed

Dim sChildNames() As String sChildNames = dataRow.listChildNames

SetChildren

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

API Guide 125

Map

Syntax

Function setChildren(childName As String, DataRows As DataRow()) As

DataRow()

Parameters

None.

Results

Returns the set of the names of the named parent/child relationships.

Example

Dim dataRow1 As New G1CLIENTLib.dataRow

Dim dataRow2 As New G1CLIENTLib.dataRow

dataRow1.setByName "Address", "100 Congress" dataRow1.setByName "City", "Austin" dataRow2.setByName "Address", "200 Congress" dataRow2.setByName "City", "Austin"

Dim rows(1) As G1CLIENTLib.dataRow

Set rows(0) = dataRow1

Set rows(1) = dataRow2

Dim newRows() As Variant newRows = dataRowSpt.setChildren("child1", rows())

Map

Map is an object that maps keys to values. A map cannot contain duplicate keys — each key can map to at most one value.

The following table summarizes the functions each method performs in the Map class.

Table 32: Map Methods Summary

Method

reset next getKey getValue

Function

Sets the cursor to be before the first map.

Moves the cursor down one map from its current position.

Gets the key in the current map.

Gets the value in the current map.

These methods are discussed in more detail in the following sections.

Reset

Sets the cursor to be before the first map.

126 Spectrum

™

Technology Platform 9.0

Chapter 4: The COM API

Syntax

Sub Reset()

Parameters

• None

Results

None.

Example

Dim requestMsg As New G1CLIENTLib.Message

Dim map As G1CLIENTLib.Map

Dim sKey As String

Dim sValue As String requestMsg.putContext requestMsg.CONTEXT_ACCOUNT_ID, "admin" requestMsg.putContext requestMsg.CONTEXT_ACCOUNT_PASSWORD, "admin"

Set map = requestMsg.getContextMap

map.Reset

While (map.Next) sKey = map.getKey

sValue = map.getValue

Wend

Next

Moves the cursor down one map from its current position.

Syntax

Sub Next()

Parameters

• None

Example

Dim requestMsg As New G1CLIENTLib.Message

Dim map As G1CLIENTLib.Map

Dim sKey As String

Dim sValue As String requestMsg.putContext requestMsg.CONTEXT_ACCOUNT_ID, "admin" requestMsg.putContext requestMsg.CONTEXT_ACCOUNT_PASSWORD, "admin"

Set map = requestMsg.getContextMap

map.Reset

While (map.Next) sKey = map.getKey

sValue = map.getValue

Wend

API Guide 127

Map

GetKey

Gets the key in the current map.

Syntax

Function getKey() As String

Parameters

• None

Results

Returns the key on the current map.

Example

Dim requestMsg As New G1CLIENTLib.Message

Dim map As G1CLIENTLib.Map

Dim sKey As String

Dim sValue As String requestMsg.putContext requestMsg.CONTEXT_ACCOUNT_ID, "admin" requestMsg.putContext requestMsg.CONTEXT_ACCOUNT_PASSWORD, "admin"

Set map = requestMsg.getContextMap

map.Reset

While (map.Next) sKey = map.getKey

sValue = map.getValue

Wend

GetValue

Gets the value in the current map.

Syntax

Function getValue() As String

Parameters

• None

Results

Returns the value on the current map.

Example

Dim requestMsg As New G1CLIENTLib.Message

Dim map As G1CLIENTLib.Map

Dim sKey As String

Dim sValue As String requestMsg.putContext requestMsg.CONTEXT_ACCOUNT_ID, "admin" requestMsg.putContext requestMsg.CONTEXT_ACCOUNT_PASSWORD, "admin"

128 Spectrum

™

Technology Platform 9.0

Set map = requestMsg.getContextMap

map.Reset

While (map.Next) sKey = map.getKey

sValue = map.getValue

Wend

Chapter 4: The COM API

API Guide 129

The Java API

In this section:

•

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132

•

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134

•

Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

•

Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

•

DataTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

•

DataRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151

Introduction

A Java class is a blueprint or prototype that defines the variables and methods common to all objects of a certain type. A Java class also defines the implementation of a particular kind of object. It is with these classes that you can create Java applications. In general, Java objects are created from Java classes.

A Java object is a collection of related variables and methods written in the Java language utilizing the

Java Virtual Machine (JVM). The data associated with a class or object is stored in variables. The behavior associated with a class or object is implemented with methods. Methods are similar to the functions or procedures in procedural languages such as C.

Java software objects interact and communicate with each other using messages. Additional information that the receiving object may need to perform its task is passed by parameters.

For more information on Java technology, go to

www.oracle.com/java

Constants

The Java API uses two sets of constants. The first set is for the Server component, described in the table below.

Table 33: Constants for the Server Component

Constant Name

Server.HOST

Server.PORT

Server.ACCOUNT_ID

Server.ACCOUNT_PASSWORD

Server.CONNECTION_TIMEOUT

Server.CONNECTION_TYPE

Server.PROXY_HOST

Server.PROXY_PORT

Server.PROXY_USER

Server.PROXY_PASSWORD

Description Example

String for server host name. Default is

"localhost".

65.89.200.89

String for server port. Default is "8080".

10119

String for server account ID. Default is null.

user1

String for server account password.

Default is null.

user1

String for server connection timeout, in millisecond. Default is "10000".

50000

HTTP String for server connection type.

Currently only support HTTP, HTTPS, or SOCKET. Default is "HTTP".

String for proxy server host name.

Default is null.

192.168.1.77

8080 String for proxy server port. Default is null.

String for proxy server account ID.

Default is null.

String for proxy server account password. Default is null.

user1 user1

The second set of constants is for the Message component.

132 Spectrum

™

Technology Platform 9.0

Chapter 5: The Java API

Table 34: Constants for the Message Component

Constant Name Description/Default Example

Message.CONTEXT_ACCOUNT_ID

Message.CONTEXT_ACCOUNT_PASSWORD

Message.CONTEXT_SERVICE_NAME

String for message context account ID.

String for message context account password.

String for message context service name.

user1 user1 echoservice

Error Messages

The Java API uses the following error messages:

• Error Messages for Connection

• "Connection type not supported."

• "Client timeout"

• Error Messages for creating DataTable:

• "Blank column name"

• "Duplicated column name"

• "Index is out of bounds"

• Error Messages for Message Packaging Exception

• "Cannot pack null Message"

• "Input Message is null"

• "Unable to connect to Server:"

• "Failed to get Service"

• "Unknown serialization type:"

• "Unknown encoding type:"

• "Gateway is not connected" (for SOCKET)

Example Application

The sample code shown below illustrates how to use the Java API.

try

{

// Create Server

Server server = new Server();

// Set server connection properties server.setConnectionProperty(Server.HOST, "localhost"); server.setConnectionProperty(Server.PORT, "10119"); server.setConnectionProperty(Server.CONNECTION_TYPE, "SOCKET"); server.setConnectionProperty(Server.ACCOUNT_ID, "guest"); server.setConnectionProperty(Server.ACCOUNT_PASSWORD, "");

// Connect to server server.connect();

// Get Service From Server

Service service = server.getService("ValidateAddress");

// Create Input Message

API Guide 133

Server

Message request = new Message();

// Fill DataTable in the input message

DataTable dataTable = request.getDataTable();

DataRow row1 = dataTable.newRow(); row1.set("AddressLine1", "4200 Parliament Place"); row1.set("City", "Lanham"); row1.set("StateProvince", "Maryland"); dataTable.addRow(row1);

DataRow row2 = dataTable.newRow(); row2.set("AddressLine1", "100 Congress"); row2.set("City", "Austin"); row2.set("StateProvince", "Texas"); dataTable.addRow(row2);

// Set"option" Properties to the Input

Message request.putOption("OutputCasing", "M"); request.putOption("OutputRecordType", "A");

// Process Input Message, return output Message

Message reply = service.process(request);

// Disconnect from server server.disconnect();

// Get the result from the response message

DataTable returnDataTable = reply.getDataTable();

String[] columnNames = returnDataTable.getColumnNames();

Iterator iter = returnDataTable.iterator(); while (iter.hasNext())

{

DataRow row = (DataRow) iter.next(); for (int col = 0; col & lt; returnDataTable.getColumnCount(); col++)

{

String value = row.get(columnNames[col]);

System.out.println(value);

}

} catch (Exception e)

{

System.out.println("Error Occurred, " + e.getMessage());

}

Server

Table 35: Server Methods Summary

134

Method

connect disconnect setConnectionProperty getService

Function

Connects to the server.

Disconnects from the server.

Sets the configuration items for the connection to the server.

Gets the service from the server.

Spectrum

™

Technology Platform 9.0

Chapter 5: The Java API

Note:

See the Component Reference section of this guide for a list of services that may be available to you.

Connect

Reads the properties to determine which gateway connection to be used and makes a connection to the server. You can connect via HTTP, HTTPS, or SOCKET. However, HTTP and HTTPS do not actually connect to the server until a GetService or Process method is invoked. With a SOCKET connection type, the Connect method is fully functional.

Syntax

public void connect()

Parameters

None.

Results

Throws:

• ConfigurationException: When invalid configuration causes the inability to connect to the server. For example, an unknown protocol would cause a ConfigurationException. There is no value in attempting to retry connect() when this error occurs.

• ConnectionException: When unable to connect to the server. It might be possible to reconnect, depending on the underlying cause of the exception.

• MessageProcessingException: When an error occurs on the server that is not due to Configuration or

Connection issues.

Example

{

//Connect to server server.connect();

} catch (ConfgurationException e)

{

// indicate an error with configuration

} catch (ConnectionException e)

{

// handle connection issue (retry, report error, etc.)

} catch (MessageProcessingException e)

{

}

// report error

API Guide 135

Server

Connection Pooling

Connection pooling for the SOCKET connection type is available to the Java client. This section describes how to enable and disable connection pooling. By default connection pooling is disabled.

To enable connection pooling:

Server server = new Server();

Server.setConnectionProperty(Connection.SOCKET_POOL, "true");

To disable connection pooling:

Server server = new Server();

Server.setConnectionProperty(Connection.SOCKET_POOL, "false");

When connection pooling is enabled, the connect() method borrows a connection from the pool, and the disconnect() method returns the connection back to the pool. When pooling, the client must call disconnect() each time to return the connection to the pool.

Each thread should contain its own server, as shown in the following example:

{

...

Server server = new Server(); server.setConnectionProperty(Server.HOST, "localhost"); server.setConnectionProperty(Server.PORT, "10119"); server.setConnectionProperty(Server.CONNECTION_TYPE, "SOCKET"); server.setConnectionProperty(Server.ACCOUNT_ID, "yourID"); server.setConnectionProperty(Server.ACCOUNT_PASSWORD, "pwd"); server.setConnectionProperty(Connection.SOCKET_POOL, "true"); server.setConnectionProperty(Connection.SOCKET_POOL_MAX_ACTIVE, "20"); server.setConnectionProperty(Connection.SOCKET_POOL_MIN_IDLE, "10"); server.setConnectionProperty(Connection.SOCKET_POOL_MAX_TOTAL, "25");

} server.connect();

...

service = server.getService(serviceName); reply = service.process(requestMessage); server.disconnect();

...

The following table lists the constants you can use for connection pooling.

Table 36: Constants for Connection Pooling

Constant Name

SOCKET_POOL

136

SOCKET_POOL_MAX_ACTIVE*

SOCKET_POOL_MAX_IDLE*

SOCKET_POOL_MAX_TOTAL*

Description

Whether or not to use connection pooling if using the SOCKET connection type.

Valid values are true or false. Default is false.

Maximum number of active socket connections that may be borrowed from the pool. Default is -1, which indicates no maximum.

Maximum number of idle socket connections remaining in the pool.

Default is -1, which indicates no maximum.

Maximum total number of pooled socket connections (both active and idle).

Spectrum

™

Technology Platform 9.0

Chapter 5: The Java API

Constant Name Description

SOCKET_POOL_MAX_WAIT*

SOCKET_POOL_MIN_EVICTABLE_IDLE_TIME_MILLIS*

SOCKET_POOL_MIN_IDLE*

SOCKET_POOL_NUM_TESTS_PER_EVICTION_RUN*

Default is -1, which indicates no maximum.

Maximum amount of time (in milliseconds) to wait before throwing an exception when the pool is exhausted and the "when exhausted" action is

WHEN_EXHAUSTED_BLOCK. Default is -1, which indicates no maximum.

Minimum amount of time a connection may sit idle in the pool before it is eligible for eviction. Default is 1800000 (30 minutes).

Minimum number of connections allowed in the pool before the evictor thread (if active) creates new connections. Default is 0.

Sets the number of idle connections to examine during each run of the evictor thread (if active). Default is -1, which indicates all idle connections are examined.

SOCKET_POOL_TEST_ON_BORROW*

SOCKET_POOL_TEST_ON_RETURN*

SOCKET_POOL_TEST_WHILE_IDLE* Whether connections will be validated by the idle connection eviction thread.

Default is false.

SOCKET_POOL_TIME_BETWEEN_EVICTION_RUNS_MILLIS* Sets the number of milliseconds to sleep between runs of the idle connection evictor thread. When set to zero or a negative number, no idle connection evictor thread will be run. Default is

300000 (5 minutes).

SOCKET_POOL_WHEN_EXHAUSTED_ACTION*

Whether connections will be validated before being borrowed from the pool.

Default is true.

Whether connections will be validated before being returned to the pool. Default is false.

SOCKET_POOL_WHEN_EXHAUSTED_BLOCK*

Sets the "when exhausted action" to take when attempting to borrow a connection and none are available. Default is

SOCKET_POOL_WHEN_EXHA

USTED_BLOCK.

A "when exhausted action" type indicating that when attempting to borrow a connection and none are available, the caller should block until a new object is available, or the maximum wait time has elapsed.

API Guide 137

Server

Constant Name

SOCKET_POOL_WHEN_EXHAUSTED_FAIL*

SOCKET_POOL_WHEN_EXHAUSTED_GROW*

Description

A "when exhausted action" type indicating that when attempting to borrow a connection and none are available, the caller should fail, throwing a

ConnectionException.

A "when exhausted action" type indicating that when attempting to borrow a connection and none are available, a new connection will be made anyway.

* Applicable only if using the SOCKET connection type and connection pooling is enabled.

Disconnect

Disconnects from the server.

Syntax

public void disconnect()

Parameters

None.

Results

Client is disconnected from the server.

Example

...

//Disconnect from server server.disconnect();

SetConnectionProperty

Establishes the server connection configuration properties, such as host name and length of timeout.

Syntax

public void setConnectionProperty(String name, String value)

Parameters

• Name — the name of the connection property, such as HOST

• Value — the value for the name of the connection property, such as "www.myhost.com"

Results

None.

138 Spectrum

™

Technology Platform 9.0

Exceptions

• ERROR-INVALID-COLUMN_NAME — an empty of null column name.

• ERROR_INVALID_VALUE — A null value.

Example

Server server = new Server(); server.setConnectionProperty(Server.HOST, "localhost"); server.setConnectionProperty(Server.PORT, "8080");

//Connect to server server.connect();

Chapter 5: The Java API

GetService

Gets the service from the server.

Note:

See the Component Reference section of this guide for a list of services that may be available to you.

Syntax

public Service getService(String serviceName)

Parameters

• Name - the name of the service

Results

Returns the specific service.

Exceptions

throws ServiceNotFoundException, ServiceCreationException

Example

Service service = server.getService("ValidateAddress");

Service

The Service class is used to process the message (i.e., send the message to the server and receive a response from the server).

This class has just one method: Process. The Process method is detailed below.

Process

Process the input message and returns the response message.

API Guide 139

Message

Syntax

public Message process (Message message)

Parameters

• Input message

Results

Returns the response message.

Exceptions

• TimeoutException: When invalid configuration causes the inability to connect to the server. For example, an unknown protocol would cause a ConfigurationException. There is no value in attempting to retry connect() when this error occurs.

• ConnectionException: When unable to connect to the server. It might be possible to reconnect, depending on the underlying cause of the exception.

• MessageProcessingException: When an error occurs on the server that is not due to Configuration or

Connection issues.

Example

try

{

}

//Process Input Message, return output Message

Message response = service.process(message); catch (ConnectionException e)

{

// handle connection issue (retry, report error, etc.)

} catch (TimeoutException e)

{

// handle timeout issue (retry, report error, etc.)

} catch (MessageProcessingException e)

{

}

// report error

Message

The Message class sends your input data and receives your output data from the service. The properties for Message include context properties, such as account ID, account password, service name, and service method; and option properties, which are the service-specific runtime options.

The following table summarizes the functions each method performs in the Message class.

Table 37: Message Methods Summary

Method

getContext

Function

Gets the value of the context entity identified by name in the context section of the message.

140 Spectrum

™

Technology Platform 9.0

Method

getContext putContext putContext setContext getOption getOptions putOption putOptions setOptions getError getDataTable

Chapter 5: The Java API

Function

Gets the map that contains all of the context entries.

Sets the value of the context entity identified by name in the context session of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Add the new context properties to the current context properties.

Overwrites the current context properties with the new context properties.

Gets the value of the option entity identified by name in the option section of the message.

Gets the map that contains all of the option entries.

Sets the value of the option entity identified by name in the option section of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Add the new option properties to the current option properties.

Overwrites the current option properties with the new option properties.

Gets the error from the error message.

Gets the specified data table from the message.

GetContext

Gets the value by the name in the "context" properties. Context properties include the following constants: account ID, account password, service name, service key, and request ID.

Syntax

public String getContext(String name)

Parameters

• Name - the name whose associated value is to be returned

Results

Returns the value associated with the name in the context properties. If the name does not exist, the method returns NULL.

Example

String value = message.getContext(Message.CONTEXT_ACCOUNT_ID);

API Guide 141

Message

GetContext

Gets the map that contains all of the context entries.

Syntax

public Map getContext()

Parameters

• None

Results

Returns the map that contains all of the context entries.

Example

Map context = message.getContext();

PutContext

Sets the value for the given name in the context properties. If there is an existing value present for the entity identified by the name, it is replaced. Context properties include the following constants: accountID, account password, service name, service key, and request ID.

Syntax

public void putContext(String name, String value)

Parameters

• Name - the name with which the specified value is to be associated

• Value - the value to be associated with the specified name

Results

None.

Example

message.putContext(Message.CONTEXT_ACCOUNT_ID, "user1");

PutContext

Adds the new context properties to the current context properties.

Syntax

public void putContext(Map map)

142 Spectrum

™

Technology Platform 9.0

Parameters

• The new context hashtable to be added to the current context hashtable

Results

None.

Example

Map context = new HashMap();

...

message.putContext(context);

Chapter 5: The Java API

SetContext

Overwrites the current context properties with the new context properties.

Syntax

public void setContext(Map map)

Parameters

• The new context map that will replace the current context map.

Results

None.

Example

Map context = new Map ();

...

message.setContext(context);

GetOption

Gets the value by the name in the option properties. Option properties are the service-specific run-time options.

Syntax

public String getOption(String name)

Parameters

• Name - the name whose associated value is to be returned.

Results

Returns the value for the name in the option properties in the message OR NULL if the name does not exist.

API Guide 143

Message

Example

String value = message.getOption("OutputCasing");

GetOptions

Gets the map that contains all of the option entries.

Syntax

public Map getOptions();

Parameters

• None

Results

Returns the map that contains all of the option entries.

Example

Map options = message.getOptions();

PutOption

Syntax

public void setOption(String name, String value)

Parameters

• Name - name with which the specified value is to be associated

• Value - value to be associated with the specified name

Results

None.

Example

message.setOption("OutputCasing", "M");

PutOptions

Adds the new option properties to the current option properties.

Syntax

public void putOptions(Map map)

144 Spectrum

™

Technology Platform 9.0

Parameters

• The new option map to be added to the current option properties

Example

Map options = new HashMap();

...

message.putOptions(options);

SetOptions

Overwrites the current option properties with the new option properties.

Syntax

public void setOptions(Map map)

Parameters

• The new option map to replace the current option map

Results

None.

Example

Map options = new HashMap();

...

message.setOptions(options);

GetError

Gets the error message from the message.

Syntax

public String getError()

Parameters

• None

Results

Returns the error message in the message.

Example

String error = message.getError();

Chapter 5: The Java API

API Guide 145

DataTable

GetDataTable

Gets the data table in this message.

Syntax

public DataTable getDataTable()

Parameters

None.

Results

None.

Example

DataTable dataTable = message.getDataTable();

DataTable

DataTable contains the records for your input and output data. Using the methods associated with this class, you define the column names for your output and add records to the DataTable.

The following table summarizes the functions each method performs in the DataTable class.

Table 38: DataTable Methods Summary

Method

addColumn getColumnNames getColumnIndex getColumnCount clear iterator addRow newRow getRowCount merge

Function

Adds a new column to the DataTable.

Gets all the column names.

Gets the corresponding column index.

Gets the number of columns.

Clears all the data in the DataTable.

An iterator that contains all the rows in the

DataTable.

Adds a DataRow to the DataTable.

Creates a new DataRow in the DataTable.

Gets the number of DataRows in the DataTable.

Merge the given DataTable and the current

DataTable.

These methods are discussed in more detail in the following sections.

146 Spectrum

™

Technology Platform 9.0

AddColumn

Adds the new column to the DataTable.

Syntax

public int addColumn(String columnName)

Parameters

• columnName

Results

Returns the index of the column

Example

DataTable dataTable = message.getDataTable(); int columnIndex = dataTable.addColumn("AddressLine1"); columnIndex = dataTable.addColumn("City")

GetColumnNames

Gets all the column names.

Syntax

public String[] getColumnNames()

Parameters

• None

Results

Returns the string array of column names.

Example

String[] columnNames = dataTable.getColumnNames();

GetColumnIndex

Gets the corresponding column index.

Syntax

public int getColumnIndex(String columnName)

Parameters

• Column name

API Guide

Chapter 5: The Java API

147

DataTable

Results

Returns the corresponding column index.

Example

int columnIndex = dataTable.getColumnIndex("City");

GetColumnCount

Gets the number of columns in the DataTable.

Syntax

public int getColumnCount()

Parameters

• None

Results

Returns the number of columns.

Example

int columnCount = dataTable.getColumnCount();

Clear

Clears the data in the DataTable.

Syntax

public void clear()

Parameters

• None

Results

None.

Example

dataTable.clear();

Iterator

An iterator that contains all DataRows in the DataTable.

148 Spectrum

™

Technology Platform 9.0

Syntax

public Iterator iterator()

Parameters

• None

Results

Returns an iterator that contains all DataRows in the DataTable.

Example

Iterator iter = dataTable.iterator(); while (iter.hasNext())

{

DataRow row = (DataRow)iter.next();

}

AddRow

Adds a row to the DataTable.

Syntax

public void addRow(DataRow row)

Parameters

• Row - DataRow to be added to the DataTable

Results

None.

Example

DataTable dataTable = message.getDataTable();

DataRow row = dataTable.newRow(); row.set("AddressLine1","4203 Greenridge"); dataTable.addRow(row);

NewRow

Creates a new DataRow to the DataTable.

Syntax

public DataRow newRow()

Parameters

• None

API Guide

Chapter 5: The Java API

149

DataTable

Results

Returns the newly created DataRow

Example

DataRow row = dataTable.newRow(); row.set("AddressLine1", "4203 Greenridge"); dataTable.addRow(row);

GetRowCount

Gets the number of DataRows in the DataTable.

Syntax

public int getRowCount()

Parameters

• None

Results

Returns the number of DataRows in the DataTable.

Example

int rowCount = dataTable.getRowCount();

Merge

Merges the given DataTable and the current DataTable.

Syntax

public void merge(DataTable other)

Parameters

• The other DataTable to be merged with the current DataTable

Results

None.

Example

DataTable otherDataTable = new DataTable(); dataTable.merge(otherDataTable);

150 Spectrum

™

Technology Platform 9.0

Chapter 5: The Java API

DataRow

DataRow contains the individual records for your input and output data. Using the methods associated with this class, you define the column names for your output and add records to the DataTable.

The following table summarizes the functions each method performs in the DataRow class.

Table 39: DataRow Methods Summary

Method

getColumnNames getColumnIndex get get merge set set addChild getChildren listChildNames setChildren

Function

Gets all the column names.

Gets the corresponding column index.

Gets the value from the field array by the column index in this DataRow.

Gets the value from the field array by the column name in this dataTow.

Merges the given DataRow and the current

DataRow.

Sets the value for the corresponding column name for the DataRow. If the value for the name exists, the old value is replaced.

Sets the value for the corresponding column index for the DataRow. If the value for the name exists, the old value is replaced.

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied DataRow will be appended to the existing

DataRow Collection, otherwise a new Collection will be created with the supplied DataRow as its only element.

Retrieves the child rows from a named relationship.

Retrieves all of the names of the named parent/child relationships

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

These methods are discussed in more detail in the following sections.

GetColumnNames

Gets all the column names.

API Guide 151

DataRow

Syntax

public String[] getColumnNames()

Parameters

• None

Results

Returns the string array of column names.

Example

String[] columnNames = dataRow.getColumnNames();

GetColumnIndex

Gets the corresponding column index.

Syntax

public int getColumnIndex(String columnName)

Parameters

• Name - column name

Results

Returns the corresponding column index.

Example

int columnIndex = dataRow.getColumnIndex("City");

Get

Gets the value from the field array by the column index in this DataRow.

Syntax

public String get(int index)

Parameters

• Index with which the specified value is to be associated

Results

Returns the value for the column index in this DataRow.

152 Spectrum

™

Technology Platform 9.0

Chapter 5: The Java API

Example

String value = dataRow.get(1);

Get

Gets the value from the field array by the column name in this DataRow.

Syntax

public String get(String columnName)

Parameters

• Name - name with which the specified value is to be associated

Results

Returns the value for the column name in this DataRow; returns empty string if the column name does not exist.

Example

String value = dataRow.get("City");

Merge

Merges the given DataRow and the current DataRow.

Syntax

public void merge(DataRow other)

Parameters

• The other DataRow to be merged with the current DataRow

Results

None.

Example

DataRow otherDataRow = new DataRow(); dataRow.merge(otherDataRow);

Set

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

API Guide 153

DataRow

Syntax

public void set(int Index, String value)

Parameters

• The column index with which the specified value is to be associated

• Value to be associated with the specified name

Results

None.

Exceptions

• IndexOutOfBounds — the column index is invalid

Example

DataRow row = dataTable.newRow(); row.set(0,"4203 Greenridge"); row.set(1,"Austin"); row.set(2,"Texas") dataTable.addRow(row);

AddChild

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied

DataRow will be appended to the existing DataRow collection. Otherwise, a new collection will be created with the supplied DataRow as its only element.

Syntax

public void addChild(String childName, DataRow childDataRow)

Parameters

• Name - the name of the parent/child relationship (e.g., "Flood Plain Data," "References, " "Used By," etc.)

• Value - the DataRow to be added to the relationship.

Results

None.

Example

DataRow childDataRow = new DataRow(); childDataRow.set("Address", "100 Congress");

...

DataRow dataRow = new DataRow();

...

dataRow.addChild("child1", childDataRow);

154 Spectrum

™

Technology Platform 9.0

Chapter 5: The Java API

GetChildren

Retrieves the child rows from a named relationship.

Syntax

public List getChildren(String childName)

Parameters

• The name of the parent/child relationship, e.g. "Flood Plain Data", "References", "Used By", etc.

Results

Returns the child rows from the named relationship.

Example

List childRows = row.getChildren("child1");

ListChildNames

Retrieves all of the names of the named parent/child relationships.

Syntax

public Set listChildNames()

Parameters

None.

Results

Returns the set of the names of the named parent/child relationships.

Example

Set childNames = row.listChildNames();

SetChildren

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

Syntax

public List setChildren(String childName, List DataRows)

Parameters

None.

API Guide 155

DataRow

Results

Returns the set of the names of the named parent/child relationships.

Example

List rows = dataRow.getChildren("child1"); parentRow.setChildren("child2", rows);

Set

Sets the value for the corresponding column for the DataRow. If the value for the name exists, the old value is replaced.

Syntax

public void set(int Index, String value)

Parameters

• The column index with which the specified value is to be associated

• Value to be associated with the specified name

Results

None.

Exceptions

• IndexOutOfBounds — the column index is invalid

Example

DataRow row = dataTable.newRow(); row.set(0,"4203 Greenridge"); row.set(1,"Austin"); row.set(2,"Texas") dataTable.addRow(row);

156 Spectrum

™

Technology Platform 9.0

ManagementAPI Methods

In this section:

•

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158

•

GetLicenseInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158

•

GetVersionInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159

Introduction

There are two management API methods that are publicly available via the ManagementAPI Web service.

Those methods include getLicenseInfo and getVersionInfo. The wsdl for the ManagementAPI Web service can be viewed using the following URL: http://localhost:8080/managers/ManagementAPIService?wsdl

, where "localhost" is replaced by the name of the Spectrum

™

Technology Platform server.

GetLicenseInfo

The method GetLicenseInfo returns a license object. The license object contains properties for machine type, operating system type, hostname, and CPU limit. It also contains an array of feature objects and an array of restriction objects. These arrays can be processed to determine specific information about features and restrictions. Feature has an ID, a name, and an enabled flag. Restriction has an ID, a limit, and a start date.

Web Service

ManagementAPIService

Parameters

None.

Result

Returns the license object.

Example

License string machineType string osType string hostName string CPULimit

Feature[] features

Restriction[] restrictions

Feature string ID; string name;

Restriction[] restrictions

Restriction string ID long limit datetime startDate

Feature[] features

ExpirationRestriction extends Restriction

UsageRestriction extends Restriction long usages

158 Spectrum

™

Technology Platform 9.0

Chapter 6: ManagementAPI Methods

GetVersionInfo

The GetVersionInfo method returns an array of VersionInfo objects. A VersionInfo object has a name, version number, and a list of VersionAttribute objects. VersionAttribute objects are simple classes that have a label and a value. GetVersionInfo attributes are product-specific as the information is gathered and returned by the product itself. This same information is also displayed in the Version Information node of the Management Console.

Note:

You must run GetVersionInfo once, see what values come back, and then parse the information to get specific pieces of information.

Web Service

ManagementAPIService

Parameters

None.

Result

Returns VersionInfo objects.

Example

VersionInfo string name string version

VersionAttribute[] attributes

VersionAttribute string label string value

API Guide 159

The .NET API

In this section:

•

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162

•

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164

•

Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

•

Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168

•

EnhancedDataTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

Introduction

.NET is a Microsoft

® operating system platform that incorporates applications and a suite of tools and services which enhance Web service and application development.

The .NET framework uses components called Common Language Runtime (CLR), Framework Class

Library (FCL), and ASP.NET. The CLR is equivalent to the Java Virtual Machine, in that it manages code and executes it in the native language of the machine on which it runs. The Framework Class Library is a massive library of re-usable object types that cover a myriad of program functions. ASP.NET is a server-side technology that allows web pages and services to load much faster than traditional ASP pages. Together, these three components of the .NET framework make application and Web development easier, more streamlined, and provides easier integration into existing environments. Clients and servers on different platforms running services written in various programming languages can communicate with each other swiftly and easily.

For more information on .NET technology, go to

msdn.microsoft.com/netframework

Constants

The .NET API uses two sets of constants. The first set is for the Server component, described in the table below.

Table 40: Constants for the Server Component

Constant Name

Server.HOST

Server.PORT

Server.ACCOUNT_ID

Server.ACCOUNT_PASSWORD

Server.CONNECTION_TIMEOUT

Server.CONNECTION_TYPE

Server.PROXY_HOST

Server.PROXY_PORT

Server.PROXY_USER

Server.PROXY_PASSWORD

Description Example

String for server host name. Default is

"localhost".

65.89.200.89

String for server port. Default is "8080".

10119

String for server account ID. Default is null.

user1

String for server account password.

Default is null.

user1

String for server connection timeout, in millisecond. Default is "10000".

50000

HTTP(S) String for server connection type.

Currently only support HTTP, HTTPS, or SOCKET. Defaults is "HTTP".

String for proxy server host name.

Default is null.

192.168.1.77

8080 String for proxy server port. Default is null.

String for proxy server account ID.

Default is null.

String for proxy server account password. Default is null.

user1 user1

The second set of constants is for the Message component.

162 Spectrum

™

Technology Platform 9.0

Chapter 7: The .NET API

Table 41: Constants for the Message Component

Constant Name Description Example

Message.CONTEXT_ACCOUNT_ID

Message.CONTEXT_ACCOUNT_PASSWORD

Message.CONTEXT_SERVICE_NAME

String for message context account ID.

String for message context account password.

String for message context service name.

user1 user1 echoservice

Error Messages

The .NET API uses the following error messages:

• Error Messages for Connection

• "Connection type not supported."

• "Client timeout"

• Error Messages for Message Packaging Exception

• "Input Message is null."

The other error messages will come from the .NET Framework Class Library if they do not get used properly.

Example Application

The sample code shown below illustrates how to use the .NET API.

using System; using System.IO; using System.Collections; using System.Text; using System.Data; try

{

//Create Server

Server server = new Server();

//Set connect property to the server server.SetConnectionProperty(Server.HOST, "localhost"); server.SetConnectionProperty(Server.PORT, "10119"); server.SetConnectionProperty(Server.CONNECTION_TYPE, "SOCKET"); server.SetConnectionProperty(Server.ACCOUNT_ID, "guest"); server.SetConnectionProperty(Server.ACCOUNT_PASSWORD, "");

//Connect to server server.Connect();

//Get Service From Server

Service service = server.GetService("ValidateAddress");

//Create Input Message

Message request = new Message();

//Fill dataTable in the input message

//Datatable is the .net Framework class

DataTable dataTable = request.GetDataTable();

API Guide 163

Server

DataColumn column1 = new DataColumn(); column1.DataType = System.Type.GetType("System.String"); column1.ColumnName = "AddressLine1"; dataTable.Columns.Add(column1);

DataColumn column2 = new DataColumn(); column2.DataType = System.Type.GetType("System.String"); column2.ColumnName = "City"; dataTable.Columns.Add(column2);

DataColumn column3 = new DataColumn(); column3.DataType = System.Type.GetType("System.String"); column3.ColumnName = "StateProvince"; dataTable.Columns.Add(column3);

DataRow newRow = dataTable.NewRow(); newRow[0]="4200 Parliament Place"; newRow[1]="Lanham"; newRow[2]="Maryland"; dataTable.Rows.Add(newRow);

//Set "option" Properties to the Input Message request.PutOption("OutputCasing", "M"); request.PutOption("OutputRecordType", "A");

//Process Input Message, return output Message

Message reply = service.Process(request);

//Disconnect from server server.Disconnect();

//Get the result from the response message

DataTable returnDataTable = reply.GetDataTable(); foreach(DataColumn dc in returnDataTable.Columns)

{

// more code to be added string columnName = dc.ColumnName;

} foreach(DataRow dr in returnDataTable.Rows)

{ for (int col = 0; col < returnDataTable.Columns.Count; col++)

{

// more code to be added string value = (String)dr[col] ;

Console.WriteLine(value);

}

} catch (Exception e)

{

//Error handling

Console.WriteLine("Error Ocurred, " + e.ToString());

}

Server

The Server class is used to connect to server, disconnect from the server, and get the service from the server. The following table summarizes the functions each method performs in the Server class.

164 Spectrum

™

Technology Platform 9.0

Chapter 7: The .NET API

Table 42: Server Methods Summary

Method

Connect

Disconnect

SetConnectionProperty

GetService

Function

Connects to the server.

Disconnects from the server.

Sets the configuration items for the connection to the server.

Gets the service (for example, ValidateAddress) from the server.

Note:

See the Component Reference section of this guide for a list of services that may be available to you.

Connect

Reads the properties to determine which gateway connection to be used and makes a connection to the server.

Note:

.NET uses the HTTP, HTTPS, or SOCKET server connection protocol. HTTP and HTTPS logically establish a client connection, but do not actually connect to the server until a GetService or

Process method is invoked. The SOCKET protocol establishes a connection to the server when

Connect is invoked.

Syntax

public void Connect()

Parameters

None.

Results

None.

Exceptions

• "Connection type not supported."

Example

Server server = new Server();

// set connect property to the server server.SetConnectionProperty(Server.HOST, "localhost"); server.SetConnectionProperty(Server.PORT, "8080");

// more connection properties to be set

// Connect to server server.Connect();

API Guide 165

Server

Disconnect

Disconnects from the server.

Syntax

public void Disconnect()

Parameters

None.

Results

Client is disconnected from the server.

Example

//Disconnect from server server.Disconnect();

SetConnectionProperty

Establishes the server connection configuration properties, such as host name and length of timeout.

Syntax

public void SetConnectionProperty(String name, String value)

Parameters

• Name — the name of the connection property, such as HOST

• Value — the value for the name of the connection property, such as "www.myhost.com"

Results

None.

Example

Server server = new Server(); server.SetConnectionProperty(Server.HOST, "localhost"); server.SetConnectionProperty(Server.PORT, "8080");

//Connect to server server.Connect();

GetService

Gets the service from the server.

Note:

See the Component Reference section of this guide for a list of services that may be available to you.

166 Spectrum

™

Technology Platform 9.0

Syntax

public Service getService(String serviceName)

Parameters

• Name - name of service

Results

Returns the specific service.

Example

Service service = server.GetService("ValidateAddress");

Chapter 7: The .NET API

Service

The Service class is used to process the message (in other words, it sends the message to the server and receives a response from the server).

This class has just one method: Process. The Process method is detailed below.

Process

Processes the input message and returns the response message.

Syntax

public Message Process(Message, message)

Parameters

• Input message

Results

Returns the response message.

Exceptions

MessageProcessingException

Example

//Process Input Message, return output Message

Message reply = service.Process(request);

API Guide 167

Message

The following table summarizes the functions each method performs in the Message class.

Table 43: Message Methods Summary

Method

GetContext

PutContext

SetContexts

GetOption

GetOptions

PutOption

PutOptions

SetOptions

GetError

GetDataTable

Function

Gets the value of the context entity identified by name in the context section of the message.

Gets the properties that contains all of the context entries.

Sets the value of the context entity identified by name in the context session of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Adds the new context properties to the current context properties.

Overwrites the current context properties with the new context properties.

Gets the value of the option entity identified by name in the option section of the message.

Gets the properties that contains all of the option entries.

Sets the value of the option entity identified by name in the option section of the message. If there is an existing value present for the entity identified by the name, it is replaced.

Adds the new option properties to the current option properties.

Overwrites the current option properties with the new option properties.

Gets the error from the error message.

Gets the specified data table from the message.

GetContext

Gets the value by the name in the context properties. Context properties include the following constants: account ID, account password, service name, service key, and the request ID.

168 Spectrum

™

Technology Platform 9.0

Chapter 7: The .NET API

Syntax

public String GetContext(String name)

Parameters

None.

Results

Returns the value associated with the name in the "context" properties. If the name does not exist, the method returns NULL.

Example

String value = message.GetContext(Message.CONTEXT_ACCOUNT_ID);

GetContext

Gets the hashtable that contains all of the context entries. Hashtable is the .NET Framework class.

Syntax

public Hashtable GetContext()

Parameters

• None

Results

Returns the hashtable that contains all of the context entries.

Example

Hashtable context = message.GetContext();

PutContext

ID, account password, service name, service key, and request ID.

Syntax

public void PutContext(String name, String value)

Parameters

• Name - name with which the specified value is to be associated

• Value - value to be associated with the specified name

API Guide 169

Message

Example

message.PutContext(Message.CONTEXT_ACCOUNT_ID, "user1");

PutContext

Adds the new context properties to the current context properties.

Syntax

public void PutContext(Hashtable context)

Parameters

• The new context hashtable to be added to the current context hashtable

Results

None.

Example

//Hashtable is the .NET Framework class

Hashtable context = new Hashtable();

//more code message.PutContext(context);

SetContexts

Overwrite the current context properties with the new context properties.

Syntax

public void SetContexts(Hashtable context)

Parameters

• Context - the new context hashtable that will replace the current context hashtable.

Results

None.

Example

//Hashtable is the .NET Framework class

Hashtable context = new Hashtable();

//more code message.SetContexts(context);

GetOption

Gets the value by the name in the option properties. Option properties are the service-specific run-time options.

170 Spectrum

™

Technology Platform 9.0

Chapter 7: The .NET API

Syntax

public String GetOption(String name)

Parameters

• Name - the name whose associated value is to be returned.

Results

Returns the value for the name in the "option" properties in the message or NULL if the name does not exist.

Example

String value = message.GetOption("OutputCasing");

GetOptions

Gets the hashtable that contains all of the option entries. Hashtable is the .NET Framework class.

Syntax

public Hashtable GetOptions();

Parameters

• None

Results

Returns the hashtable that contains all of the option entries.

Example

Hashtable options = message.GetOptions();

PutOption

Sets the value for given name in the option properties. If there is an existing value present for the entity identified by the name, it is replaced. Option properties are the Service specific run-time options.

Syntax

public void PutOption(String name, String value)

Parameters

• Name - name with which the specified value is to be associated

• Value - value to be associated with the specified name

Example

message.PutOption("OutputCasing", "M");

API Guide 171

Message

PutOptions

Adds the new option properties to the current option properties.

Syntax

public void PutOptions(Hashtable options)

Parameters

• Option - the new option hashtable to be added to the current option hashtable

Results

None.

Example

//Hastable is the .NET Framework class

Hashtable options = new Hashtable();

// more code message.PutOptions(options);

SetOptions

Overwrites the current option properties with the new option properties.

Syntax

public void SetOptions(Hashtable options)

Parameters

• Options - the new option hashtable to replace the current option hashtable

Results

None.

Example

//Hashtable is the .NET Framework class

Hashtable options = new Hashtable();

//more code message.SetOptions(options);

GetError

Gets the error message from the message.

Syntax

public String GetError()

172 Spectrum

™

Technology Platform 9.0

Chapter 7: The .NET API

Parameters

• None

Results

Returns the error message in the message.

Example

String error = message.GetError();

GetDataTable

Gets the DataTable in this message. DataTable is .NET Framework class.

Syntax

public DataTable GetDataTable()

Parameters

None.

Results

None.

Example

//DataTable is the .net Framework class

DataTable dataTable = message.GetDataTable();

DataColumn column1 = new DataColumn(); column1.DataType = System.Type.GetType("System.String"); column1.ColumnName = "AddressLine1"; dataTable.Columns.Add(column1);

DataColumn column2 = new DataColumn(); column2.DataType = System.Type.GetType("System.String"); column2.ColumnName = "City"; dataTable.Columns.Add(column2);

DataRow newRow = dataTable.NewRow(); newRow[0]="4203 Greenridge"; newRow[1]="Austin"; dataTable.Rows.Add(newRow);

EnhancedDataTable

EnhancedDataTable is a class which extends .Net class DataTable. The following table summarizes the functions each method performs in the EnhancedDataTable class.

API Guide 173

EnhancedDataTable

Table 44: EnhancedDataTable Methods Summary

Method

AddChild

GetChildren

ListChildNames

SetChildren

Function

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied DataRow will be appended to the existing

DataRow Collection, otherwise a new Collection will be created with the supplied DataRow as its only element.

Retrieves the child rows from a named relationship.

Retrieves all of the names of the named parent/child relationships.

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

AddChild

Adds a new DataRow to the named parent/child relationship. If the named relationship exists, the supplied

DataRow will be appended to the existing DataRow collection. Otherwise, a new collection will be created with the supplied DataRow as its only element.

Syntax

public void AddChild(DataRow parentRow, string name, DataRow newChild)

Parameters

• Name - the name of the parent/child relationship (e.g., "Flood Plain Data," "References, " "Used By," etc.)

• DataRow - the DataRow to be added to the relationship.

Results

None.

Example

EnhancedDataTable dataTable = new EnhancedDataTable(); dataTable.Columns.Add(new DataColumn("AddressLine1",

System.Type.GetType("System.String"))); dataTable.Columns.Add(new DataColumn("City",

System.Type.GetType("System.String"))); dataTable.Columns.Add(new DataColumn("StateProvince",

System.Type.GetType("System.String"))); dataTable.Columns.Add(new DataColumn("PostalCode",

System.Type.GetType("System.String")));

DataRow row = dataTable.NewRow(); row[0] = "510 S Coit St"; row[1] = "Florence"; row[2] = "SC";

174 Spectrum

™

Technology Platform 9.0

Chapter 7: The .NET API

row[3] = "29501-5221";

EnhancedDataTable childDataTable = new EnhancedDataTable(); childDataTable.Columns.Add(new DataColumn("AddressLine2",

System.Type.GetType("System.String"))); childDataTable.Columns.Add(new DataColumn("City",

System.Type.GetType("System.String"))); childDataTable.Columns.Add(new DataColumn("StateProvince",

System.Type.GetType("System.String"))); childDataTable.Columns.Add(new DataColumn("PostalCode",

System.Type.GetType("System.String")));

DataRow childRow = childDataTable.NewRow(); childRow[0] = "241 Ne C St"; childRow[1] = "Willamina"; childRow[2] = "OR"; childRow[3] = "97396-2714"; dataTable.AddChild(row, "Child1", childRow); dataTable.Rows.Add(row);

GetChildren

Retrieves the child rows from a named relationship.

Syntax

public EnhancedDataTable GetChildren(DataRow parentRow, string name)

Parameters

• ParentRow - the parent row

• Name - the name of the parent/child relationship, e.g. "Flood Plain Data", "References", "Used By", etc.

Results

Returns the child rows from the named relationship.

Example

EnhancedDataTable childRows = dataTable.GetChildren(parentRow, "child1");

ListChildNames

Retrieves all of the names of the named parent/child relationships.

Syntax

public string[] ListChildrenNames(DataRow parentRow)

Parameters

None.

API Guide 175

EnhancedDataTable

Results

Returns the set of the names of the named parent/child relationships.

Example

string[] childNames = dataTable.ListChildrenNames( parentRow);

SetChildren

Sets the rows of a supplied, named parent/child relationship. If rows previously existed under this name, they will be returned to the caller.

Syntax

public void SetChildren(DataRow parentRow, string name, EnhancedDataTable newTable)

Results

Returns the set of the names of the named parent/child relationships.

Example

EnhancedDataTable childRows = dataTable1.GetChildren(parentRow, "child1"); dataTable2.SetChildren(otherParentRow, "child1", childRows);

176 Spectrum

™

Technology Platform 9.0

Module Services

In this section:

•

Address Now Module . . . . . . . . . . . . . . . . . . . . . . . . . . . .178

•

Enterprise Geocoding Module . . . . . . . . . . . . . . . . . . . . .214

•

Enterprise Tax Module . . . . . . . . . . . . . . . . . . . . . . . . . . .354

•

GeoConfidence Module . . . . . . . . . . . . . . . . . . . . . . . . . .393

•

Universal Addressing Module . . . . . . . . . . . . . . . . . . . . .396

•

Universal Name Module . . . . . . . . . . . . . . . . . . . . . . . . . .520

Address Now Module

What Is the Address Now Module?

The Address Now Module is an address standardization and validation tool that provides comprehensive coverage for addresses outside the U.S. and Canada. Address Now is one of two address standardization and validation modules available for Spectrum

™

Technology Platform. The other module is the Universal

Addressing Module. The Address Now Module provides the following benefits over the Universal

Addressing Module for addresses outside the U.S. and Canada:

• Better data—The database used by the Address Now Module is more up to date and complete in many countries than the database used by the Universal Addressing Module. This is because the

Universal Addressing Module relies on data from Universal Postal Union (UPU), a body of the United

Nations, for its international data and while the data coverage is extensive, the updates and the level of address details are not proactively managed by the UPU. Address Now, on the other hand, relies on data directly from the postal authorities (in most countries), plus other third-party data providers.

This means that the data is more current with postal changes and is more detailed.

• Drill-down feature—The Address Now Module also offers drill-down capabilities to address data from any country, allowing users to rapidly enter address information without having to worry about the structure or making data entry mistakes.

• Double-byte support—The Address Now Module is Unicode enabled, recognizing Kanji and other double-byte characters.

Address Now Components

Address Now consists of the following components. These components can work with U.S., Canadian, and international addresses.

• BuildGlobalAddresses—Allows you to interactively build an address by searching for individual address elements.

• GetGlobalCandidateAddresses—Returns a list of addresses that are considered matches for a given address.

• ValidateGlobalAddress—Standardizes addresses using international postal data.

ValidateGlobalAddress can also validate addresses in the U.S. and Canada but its strength is validation of addresses in other countries. If you have a significant amount of non-U.S. and non-Canadian address data, you should consider using ValidateGlobalAddress.

In cases where ValidateGlobalAddress returns multiple address matches for a given input address, you can use GetGlobalCandidateAddresses to return the address stack. GetGlobalCandidateAddresses is designed to return additional information from the postal databases to help you determine which of the returned addresses is the best match.

Address Now Database

The Address Now database contains postal data from all supported countries. You can install the entire database or the data for specific countries only. The database is installed on the server. This database is available by subscription from Pitney Bowes Software and is updated monthly.

BuildGlobalAddress

BuildGlobalAddress allows you to build a valid address starting with just a single address element or a few address elements. BuildGlobalAddress is part of the Address Now Module.

178 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Using BuildGlobalAddress

Building an address is an interactive process that requires you to select address elements at each step of the address building process. This means that building an address requires a sequence of calls to

BuildGlobalAddress, not a single call. To start, you make an initialization call to BuildGlobalAddress.

This call returns a session ID. You then use this session ID in subsequent calls. With each call,

BuildGlobalAddress presents a list of alternative values for an address element. You select the value you want, then move on to the next address element until the complete address is built. With some exceptions, you need to make a separate call for each address element.

The overall process works like this:

• First, you make an initialization call to open a session and receive a system-assigned session ID.

• Make a search call to find possible values for a given address element.

• When you have selected the value you want, you make a commit call to indicate the value you want for the given address element.

• Continue to make search/commit calls until all address elements are committed.

• Finally, you make a close call to end the session.

To familiarize yourself with how the process works, use the Management Console's Preview tab to step through the following procedure.

1. Open the Management Console.

2. Under the Services node, select Build Global Address.

3. On the Options tab, specify the options you want. For information on the options, see

Options

on page 183.

4. Click the Preview tab.

5. In the Action field type init.

6. In the Country field enter the country of the address you want to build.

7. Click Run Preview.

8. Under Preview Output, find the SessionId field, right-click the value, and select Copy from the pop-up menu.

9. Under Preview Input, right-click the SessionId field and select Paste.

API Guide 179

Address Now Module

180

10. Enter the following values in the input fields:

• Action—Type search.

• Country—Keep this field the same.

• FieldIndex—Type the index value of the first field you want to search. For example, if you know you want to search for an address in Chicago, you would type "1" because for U.S. addresses, field index 1 corresponds to the City field.

• SearchValue—Type the value you want to search for. For example, if you want to build an address in Chicago, you would type "chicago".

• SessionId—Keep the same value.

Note:

The values in the other input fields are ignored.

11. Click Run Preview again.

12. The results of the search are placed in up to two output fields: Alternatives.InContext and

AlternativesOutContext. For an explanation of the difference between in context results and out of context results, see

What Is Context?

on page 187.

13. When you have found the value you want, enter the following values in the input fields:

• Action—Type commit.

• AlternativeIndex—Type the index number for the alternative you choose. Index values start with

0, not 1. For example, if you search for Chicago the alternatives returned by BuildGlobalAddress would be indexed as follows. If you want to commit the value "CHICAGO" you would type "0" in the AlternativeIndex field.

• 0—CHICAGO

• 1—CHICAGO HTS

• 2—CHICAGO PARK

• 3—CHICAGO RIDGE

• 4—EAST CHICAGO

• 5—NORTH CHICAGO

• 6—WEST CHICAGO

• AlternativeContext—Type in or out to indicate whether the index value you specified in

AlternativeIndex is for the list of alternatives in the Alternatives.InContext field or the

Alternatives.OutContext field.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

• SessionId—Keep this value the same.

Note:

The values in the other input fields are ignored.

14. Click Run Preview again. The value you specified will now be in the Field.n.Value field for the appropriate address element.

15. Repeat the search and commit steps as often as needed until you have built the address.

16. Close the session by entering the following values in the input fields:

• Action—Type close.

• SessionId—Keep this value the same.

Note:

The values in the other input fields are ignored.

Input

Table 45: BuildGlobalAddress Input

Format Description columnName

Parameter

Action

AlternativeContext

String

Specifies the action to take. One of the following:

init

Initialization. This action opens a session and returns a session ID which is required for all other actions. The init action requires the Country input field.

search

Searches for values for a specific address element and returns a list of alternative values for you to choose. The search action requires the following input fields:

• FieldIndex

• SearchValue

• SessionId

commit

Assigns one of the values returned by the search action to the field. The commit action requires the following input fields:

• AlternativeIndex

• AlternativeContext

• SessionId

clear close

Un-commits the field specified in the FieldIndex field. The clear action requires the following input fields:

• FieldIndex

• SessionID

Ends a session. The close action requires the

SessionId input field.

For the commit action, indicates whether you are choosing a value from the Alternatives.InContext field or the

API Guide 181

Address Now Module

182 columnName

Parameter

AlternativeIndex

Country

FieldIndex

Format Description

String

[79]

String

[79]

String

[79]

Alternatives.OutContext field. This field is ignored for other actions. One of the following:

You are committing a value from the

Alternatives.InContext field. This means that the value you specify in the AlternativeIndex input field corresponds to a value in the Alternatives.InContext output field.

out

You are committing a value from the

Alternatives.OutContext field. This means that the value you specify in the AlternativeIndex input field corresponds to a value in the

Alternatives.OutContext output field.

For the commit action, specifies the value you want to use in the address you are building. For example, if you searched for a city and BuildGlobalAddress returns a list of three cities, you would indicate the city you want by specifying the index value for your choice. Index values for the alternatives presented by BuildGlobalAddress are zero-based, meaning that the first alternative has an index of 0, the second alternative has a value of 1, and so on.

The input field is ignored for actions other than commit.

For the init action, specifies the country in which you want to build an address. Specify the country using the format you chose for input country format (English name two-character

ISO 3116-1 Alpha-2 code, or three-character ISO 3116-1

Alpha-3 code). For a list of ISO codes, see

Country ISO

Codes and Module Support

This input field is ignored for actions other than init.

For the search action, specifies the address element that you want to search on. For the clear action, specifies the address element you want to un-commit. One of the following:

all

performs the "clear" action on all address elements. This option applies to the "clear" action only.

<IndexNumber>

Performs the action on a specific address element. To determine the index of an address element, first look at the

Field.n.Name fields and locate the field you want. The value n indicates the field's index. For example, you want to look up

ZIP Codes for U.S. addresses. After the init call you see that Field.0.Name is "Zip" indicating that the ZIP Code has a field index of "0".

This input field is ignored for actions other than search and clear.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

Parameter

SearchValue

Format Description

SessionId

String

[79]

String

[79]

For the search action, specifies the value you want to search for. This value must be appropriate for the field you specified in FieldIndex. For example, if you specified the ZIP Code field in FieldIndex, then you would enter a ZIP Code or partial ZIP

Code in this field. Likewise if you chose the city field in

FieldIndex you would specify a city name or partial city name in this field. if you leave the field blank the search will return all values that are in context. For more information about in context and out of context values, see

What Is Context?

on page 187.

This input field is ignored for actions other than search.

Specifies the session ID you want to use for this call. To obtain a session ID use the init action. If a session is inactive for 5 minutes it will expire and you will need to perform a new init call to start a new session.

This field is required for all actions except init.

Options

Table 46: BuildGlobalAddress Options

Description

HomeCountry

OutputCountryFormat

Specifies the default country. You should specify the country where most of the addresses in your data are located. For example, if most of your addresses are in Canada, specify Canada. BuildGlobalAddress uses the country you specify to attempt validation when it cannot determine the country from the StateProvince, PostalCode, and Country address fields.

Specifies the format to use for the country name in the output. One of the following:

The country in the output in English (default).

The country in the output as the two-character ISO code.

The country in the output as the three-character UPU code.

OutputPostalCodeSeparator Specifies whether or not to use separators (spaces or hyphens) in ZIP

Codes or Canadian postal codes.

For example, a ZIP + 4

Code with the separator would be 20706-1844 and without the separator it would be 207061844. A Canadian postal code with the separator would be P5E"1S7 and without the separator it would be P5E1S7.

Yes, use separator (default).

No, do not use separator.

Note:

Spaces are used in Canadian postal codes and hyphens in

U.S. ZIP + 4

Codes.

API Guide 183

Address Now Module

ShowExtraAddressLine

MaximumResults

Description

Specifies whether or not to include the city, state/province, and postal code in one of the AddressLine output fields. Regardless of what you specify with this option, the output fields City, State/Province, and

PostalCode will always contain the city, state/province, and postal code.

Yes, include city, state/province, and postal code in an

AddressLine output field (default).

No, do not include city, state/province, and postal code in an

AddressLine output field.

Allows you to set the default value for this option to any value from 1 to

10000; it has a default value of 50 records. Note that values set in

Enterprise Designer override those set in Management Console

Output

BuildGlobalAddress returns address data and return codes for each input address.

Address Data

Table 47: BuildGlobalAddress Output columnName

Action

AddressLine1

AddressLine2

AddressLine3

AddressLine4

AddressLine5

AddressLine6

AddressLine7

AddressLine8

AlternativeContext

AlternativeIndex

Alternatives.InContext

Format

String [79]

Description

Shows the value specified in the Action input field for this call. For more information on this input field see

Input

on page 181.

The formatted first address line.

The formatted second address line.

The formatted third address line.

The formatted fourth address line.

The formatted fifth address line.

The formatted sixth address line.

The formatted seventh address line.

The formatted eighth address line.

Shows the value specified in the AlternativeContext input field for this call. For more information, see

Input

on page 181.

Shows the value specified in the AlternativeIndex input field for this call. For more information on this input field see

Input

on page 181.

A comma-delimited list of the possible values for the field you searched on which fit the context of fields you have already committed. For information on context see

What Is Context?

on page 187.

184 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

Alternatives.InContext.Count

Alternatives.OutContext

Alternatives.OutContext.Count

ApartmentLabel

ApartmentNumber

Building

City

Country

Department

Field.n.CommitFlag

Field.n.Index

Field.n.Name

Field.n.Value

FieldIndex

FirmName

API Guide

Format

String [79]

Description

The number of "in context" results returned by your search. For information on context see

What Is

Context?

on page 187.

A comma-delimited list of the possible values for the field you searched on which do not fit the context of fields you have already committed. For information on context see

What Is Context?

on page 187.

The number of "out of context" results returned by your search. For information about context, see

What Is Context?

on page 187.

Apartment designator (such as STE or APT). For example:

123 E Main St. APT 3

Apartment number. For example:

123 E Main St. APT 3

The name of a building.

The city name.

Shows the value specified in the Country input field for this call. For more information about this input field, see

Input

on page 181.

The two- or three-character ISO code, or English name of the country. For a list of ISO codes, see

Country ISO Codes and Module Support

The name of a distinct part of anything arranged into divisions. For example, the Finance

Department in a corporation.

Indicates whether you have chosen a value for field n (i.e. "committed" a value). One of the following:

Yes, the value of this field has been committed.

No, the value of this field has not been committed.

An index value used to refer to field n, where n is

0 though 10. For example, for U.S. addresses the index value of the ZIP field is "0".

The name of the address element contained in field n, where n is 0 through 10. For example, for U.S.

addresses Field.0.Name is ZIP.

The value that has been committed to field n, where n is 0 through 10.

This field is blank on the init call.

Shows the value specified in the FieldIndex input field for this call. For more information on this input field see

Input

on page 181.

The name of a company. For example:

185

Address Now Module columnName

186

HouseNumber

POBox

PostalCode

PostalCode.AddOn

PostalCode.Base

Principality

SearchFieldIndex

SearchValue

SessionId

StateProvince

StreetName

StreetSuffix

SubCity

SubStreet

Format

String [79]

Description

Pitney Bowes Software

4200 PARLIAMENT PL STE 600

LANHAM MD 20706-1844

USA

House number. For example:

123 E Main St. Apt 3

The post office box number. If the address is a rural route address, the rural route box number will appear here.

The postal code. In the U.S. this is the ZIP Code

™

The 4-digit add-on part of the ZIP + 4

® example, in the ZIP Code

™

Code. For

60655-1844, 1844 is the 4-digit add-on. (U.S. addresses only.)

The 5-digit ZIP Code

™

. For example 20706 (U.S.

addresses only.)

An area within a country. For example, England,

Scotland, and Wales are principalities. This field will normally be blank.

The index value of the field searched in the previous search action.

Shows the value specified in the SearchValue input field for this call. For more information on this input field see

Input

on page 181.

Shows the value specified in the SessionId input field for this call. For more information on this input field see

Input

on page 181.

The state or province abbreviation.

Street name. For example:

123 E Main St. Apt 3

Street suffix. For example:

123 E Main St. Apt 3

A district or suburb. The subcity is used in countries where it is common to include the district or suburb within the address. For example,

27 Crystal Way

Bradley Stoke

Bristol BS32 8GA

In this case, "Bradley Stoke" is the subcity.

The second street address used to identify an address. Substreets are used in countries where it is common to give two street names in the address. For example,

12 The Mews

High Street

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

USCountyName

Format

String [79]

Description

In this example, "High Street" is the substreet.

Substreets can be used to precisely identify the delivery location. In the example, "The Mews" may be a small street that needs another street identification to properly locate the address, so

"High Street" is included. In this case, "High Street" is the main or known street.

For U.S. addresses, the name of the county where the address is located.

Return Codes

Table 48: BuildGlobalAddress Return Codes columnName

Status

Format

String [79]

Status.Code

Status.Description

String [79]

Description

Reports the success or failure of the match attempt.

null

Success

Failure

Reason for failure, if there is one.

• SessionError

• SeverError

• CountryNotFound

Description of the problem, if there is one.

Please initialize new session

This value will appear if

Status.Code=SessionError.

Null or empty action

This value will appear if

Status.Code=SessionError.

Unknown action

This value will appear if

Status.Code=SessionError.

Invalid session

This value will appear if

Status.Code=SessionError.

Invalid value for

This value will appear if

Status.Code=SessionError.

Cannot Search

Committed

Field

This value will appear if

Status.Code=SessionError.

Module not licensed

This value will appear if

Status.Code=ServerError.

Could Not

Identify Country

This value will appear if

Status.Code=CountryNotFound

What Is Context?

When you perform a search for an address element, BuildGlobalAddress looks at the address elements that you have already committed and splits up the values it returns based on whether or not the returned

API Guide 187

Address Now Module

values exist within the context of the address elements you have already committed. For example, in the U.S. the following cities exist:

In Illinois:

• CHICAGO

• CHICAGO HTS

• CHICAGO RIDGE

• NORTH CHICAGO

• WEST CHICAGO

In Indiana:

• EAST CHICAGO

In Nevada:

• CHICAGO PARK

If you have already committed a value of "IN" (Indiana) for the state and then searched for the city

"chicago", BuildGlobalAddress would return EAST CHICAGO as an "in context" result because it exists in Indiana, and it would return all the other matches for "chicago" as out-of-context results. Likewise, if you committed a value of "IL" (Illinois) for the state, BuildGlobalAddress would return EAST CHICAGO and CHICAGO PARK as out of context, and CHICAGO, CHICAGO HTS, CHICAGO RIDGE, NORTH

CHICAGO, and WEST CHICAGO as "in context."

GetGlobalCandidateAddresses

GetGlobalCandidateAddresses returns a list of addresses that are considered matches for a given input address. If the input address matches multiple addresses in the Address Now database, the possible matches are returned. If the input address matches only one address in the Address Now database, no address data is returned.

GetGlobalCandidateAddresses is part of the Address Now Module.

Input

GetGlobalCandidateAddresses takes a standard address as input. All addresses use this format no matter what country the address is from. AddressLine1 and Country are required input fields. The other fields are optional.

Table 49: GetGlobalCandidateAddresses Input columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

AddressLine5

Format Description

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

First address line. This is a required field.

Second address line

Third address line

Fourth address line

Fifth address line

188 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

AddressLine6

AddressLine7

AddressLine8

City

StateProvince

PostalCode

Country

FirmName

Format Description

String

[79]

String

[79]

String

[10]

String

[79]

String

[79]

String

[79]

Sixth address line

Seventh address line

Eighth address line

City name

State or province.

String

[79]

The postal code for the address in one of these formats:

99999

99999-9999

A9A9A9

A9A 9A9

9999 999

The country. Specify the country using the format you chose for input country format (English name or ISO code). For a list of ISO codes, see

Country ISO Codes and Module Support

Company or firm name

Options

Table 50: GetGlobalCandidateAddresses Options optionName

HomeCountry

OutputCountryFormat

OutputCasing

Description/Valid Values

Specifies the default country. Specify the country that is the destination of most of your mailpieces. For example, if most of your mailpieces are going to Canada, specify Canada. GetGlobalCandidateAddresses uses the country you specify to attempt validation when it cannot determine the country from the StateProvince, PostalCode, and Country address fields. For a list of ISO codes, see

Country ISO Codes and Module

Support

Specifies the format to use for the country name in the output. One of the following:

The country in the output in English (default).

The country in the output in the two-character ISO code.

The country in the output in the three-character UPU code.

Specifies the casing of the output data. One of the following:

The output in mixed case (default). For example: 123 Main

St Mytown FL 12345

API Guide 189

Address Now Module optionName Description/Valid Values

The output in upper case. For example: 123 MAIN ST

MYTOWN FL 12345

OutputPostalCodeSeparator Specifies whether or not to use separators (spaces or hyphens) in ZIP

™

Codes or Canadian postal codes.

For example, a ZIP + 4

Code with the separator would be 20706-1844 and without the separator it would be 207061844. A Canadian postal code with the separator would be P5E"1S7 and without the separator it would be P5E1S7.

Yes, use separator (default)

No, do not use separator

Note:

Spaces are used in Canadian postal codes and hyphens in

U.S. ZIP + 4

Codes.

ShowExtraAddressLine

MaximumResults

ReturnUserData

PostalCode will always contain the city, state/province, and postal code.

Yes, include city, state/province, and postal code in an

AddressLine output field (default).

No, do not include city, state/province, and postal code in an

AddressLine output field.

The maximum number of candidate addresses to output. The default is

50. The maximum value is 100.

Specifies whether or not to include in the output data from the input address that could not be validated.

Yes, include input data that could not be validated.

No, do not include input data that could not be validated

(default).

Output

GetGlobalCandidateAddresses returns address data and return codes for each address.

Address Data

Table 51: GetGlobalCandidateAddresses Address Data Output

190 columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

Format Description

The formatted first address line.

String

[79]

String

[79]

String

[79]

String

[79]

The formatted second address line.

The formatted third address line.

The formatted fourth address line.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

Building

Format Description

The formatted fifth address line.

AddressLine5

AddressLine6

AddressLine7

AddressLine8

ApartmentLabel

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

ApartmentNumber String

[79]

The formatted sixth address line.

The formatted seventh address line.

The formatted eighth address line.

Apartment designator (such as STE or APT). For example:

123 E Main St. APT 3

Apartment number. For example:

123 E Main St. APT 3

The name of a building.

City

Country

Department

FirmName

HouseNumber

POBox

PostalCode

String

[79]

String

[79]

String

[79]

PostalCode.AddOn

String

[79]

PostalCode.Base

Principality

String

[79]

String

[79]

StateProvince

StreetName

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

The city name.

The ISO code or English name of the country. For a list of ISO codes, see

Country ISO Codes and Module Support

The name of a distinct part of anything arranged into divisions. For example, the Finance Department in a corporation.

The name of a company. For example:

Pitney Bowes Software

4200 PARLIAMENT PL

STE 600

LANHAM MD 20706-1844

USA

For U.S. addresses, the five-digit ZIP Code.

An area within a country. For example, England, Scotland, and Wales are principalities. This field will normally be blank.

The state or province abbreviation.

Street name. For example:

123 E Main St. Apt 3

House number. For example:

123 E Main St. Apt 3

Post office box number. If the address is a rural route address, the rural route box number will appear here.

The postal code as required by the local postal authority. For example, in the U.S. the postal code is the ZIP Code.

For U.S. addresses, the last four digits of the ZIP + 4

Code.

API Guide 191

Address Now Module columnName

StreetSuffix

SubCity

SubStreet

USCountyName

Format Description

String

[79]

String

[79]

String

[79]

String

[79]

Street suffix. For example:

123 E Main St. Apt 3

A district or suburb. The subcity is used in countries where it is common to include the district or suburb within the address. For example,

27 Crystal Way

Bradley Stoke

Bristol BS32 8GA

In this case, "Bradley Stoke" is the subcity.

The second street address used to identify an address. Substreets are used in countries where it is common to give two street names in the address. For example,

12 The Mews

High Street

In this example, "High Street" is the substreet. Substreets can be used to precisely identify the delivery location. In the example, "The Mews" may be a small street that needs another street identification to properly locate the address, so "High Street" is included. In this case, "High

Street" is the main or known street.

For U.S. addresses, the name of the county where the address is located.

192

Return Codes

Table 52: GetGlobalCandidateAddresses Return Codes columnName

ACRCode

Format

String [79]

Confidence

Status

Status.Code

String [79]

Status.Description

String [79]

Description

The Address Correction Result (ACR) code describes what data has been changed in each record. For information on what this code means, see

The ACR Code

on page 212.

The level of confidence assigned to the address being returned. Range is from zero (0) to 100; zero indicates failure,

100 indicates a very high level of confidence that the match results are correct.

Reports the success or failure of the match attempt.

Null

Success

Failure

Reason for failure, if there is one.

• RequestFailed

• ServerError

• CountryNotFound

Description of the problem, if there is one.

Maximum records cannot be set to 0.

Minimum value should be 1

This value will appear if

Status.Code=RequestFailed.

Spectrum

™

Technology Platform 9.0

columnName Format

Chapter 8: Module Services

Description

Address Not Found

Module not licensed

Could Not Identify

Country

This value will appear if

Status.Code=RequestFailed.

This value will appear if

Status.Code=ServerError.

This value will appear if

Status.Code=CountryNotFound.

columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

AddressLine5

AddressLine6

AddressLine7

AddressLine8

City

StateProvince

ValidateGlobalAddress

ValidateGlobalAddress provides enhanced address standardization and validation for addresses outside the U.S. and Canada. ValidateGlobalAddress can also validate addresses in the U.S. and Canada but its strength is validation of addresses in other countries. If you need to validate addresses outside the

U.S. and Canada, you should consider using ValidateGlobalAddress.

ValidateGlobalAddress is part of the Address Now Module.

Input

ValidateGlobalAddress takes a standard address as input. All addresses use this format no matter what country the address is from.

Table 53: ValidateGlobalAddress Input

Format Description

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

First address line

Second address line

Third address line

Fourth address line

Fifth address line

Sixth address line

Seventh address line

Eighth address line

City name

State or province.

API Guide 193

Address Now Module columnName

PostalCode

Country

FirmName

Format Description

String

[79]:

99999

99999-9999

A9A9A9

A9A 9A9

9999

999

The postal code for the address. In the U.S. this is the ZIP

Code

™

String

[79]

String

[79]

Specify the country using the format you chose for input country format (English name or ISO code). For a list of ISO codes, see

Country ISO Codes and Module Support

Company or firm name

Options

Input Data Options

Table 54: ValidateGlobalAddress Input Data Options optionName

HomeCountry

Description

Specifies the default country. You should specify the country where most of the addresses are located. For example, if most of the addresses you process are in Canada, specify Canada. ValidateGlobalAddress uses the home country to attempt validation when it cannot determine the country from the StateProvince, PostalCode, and Country address fields. For a list of valid values, see

Country ISO Codes and Module

Support

Output Data Options

Table 55: ValidateGlobalAddress Output Data Options optionName

OutputCountryFormat

OutputCasing

Description

Specifies the format to use for the country name in the output. One of the following:

The country in the output is English (default).

The country in the output in the two-character ISO code.

The country in the output in the three-character UPU code.

Specifies the casing of the output data. One of the following:

The output in mixed case (default). For example: 123 Main

St Mytown FL 12345

The output in upper case. For example: 123 MAIN ST

MYTOWN FL 12345

194 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName Description

OutputPostalCodeSeparator Specifies whether to use a separator (spaces or hyphens) in ZIP

™

Codes or Canadian postal codes.

For example, a ZIP + 4

Code with the separator would be 20706-1844 and without the separator it would be 207061844. A Canadian postal code with the separator would be P5E"1S7 and without the separator it would be P5E1S7.

Yes, use separator (default)

No, do not use separator

Note:

Spaces are used in Canadian postal codes and hyphens in

U.S. ZIP + 4

Codes.

ShowExtraAddressLine

StandardizeAddressOnFail

FormatOnFail

ValidateAddress

FormatAddress

Specifies whether to include the city, state/province, and postal code in one of the AddressLine output fields. Regardless of what you specify with this option, the output fields City, State/Province, and PostalCode will always contain the city, state/province, and postal code.

Yes, include city, state/province, and postal code in an

AddressLine output field (default).

No, do not include city, state/province, and postal code in an

AddressLine output field.

Specifies whether to return a standardized address when an address cannot be validated. The address is formatted using the preferred address format for the address's country. If this option is not selected, the output address component fields (StreetName, HouseNumber, etc.) are blank when address validation fails.

No, do not format failed addresses (default).

Yes, standardize failed addresses.

Specifies whether to return a formatted address when an address cannot be validated. The address is formatted using the preferred address format for the address's country.

Yes, return a formatted address when an address cannot be validated.

No, do not return a formatted address when an address cannot be validated (default).

Enables address validation. Address validation does the following:

• Matches components to the relevant country's reference data

• Corrects spelling errors

• Adds missing components

• Corrects or adds postal codes

Yes, validate addresses (default).

No, do not validate addresses.

Formats the address components into the statutory postal or custom formats.

Yes, format addresses (default).

No, do not format addresses.

API Guide 195

Address Now Module

Standardization Options

Table 56: ValidateGlobalAddress Standardization Options optionName Description

StandardizeComponent.Department

Specifies whether or not to populate the Department field when standardizing an address.

Yes (default)

StandardizeComponent.FirmName

Specifies whether or not to populate the FirmName field when standardizing an address.

Yes (default)

StandardizeComponent.Building

Specifies whether or not to populate the Building field when standardizing an address.

Yes (default)

StandardizeComponent.SubBuilding

Specifies whether or not to populate the SubBuilding field when standardizing an address.

Yes (default)

StandardizeComponent.HouseNumber

Specifies whether or not to populate the HouseNumber field when standardizing an address.

Yes (default)

StandardizeComponent.SubStreet

Specifies whether or not to populate the SubStreet field when standardizing an address.

Yes (default)

StandardizeComponent.StreetName

Specifies whether or not to populate the StreetName field when standardizing an address.

Yes (default)

StandardizeComponent.POBox

Specifies whether or not to populate the POBox field when standardizing an address.

Yes (default)

StandardizeComponent.SubCity

Specifies whether or not to populate the SubCity field when standardizing an address.

Yes (default)

196 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName Description

StandardizeComponent.City

Specifies whether or not to populate the City field when standardizing an address.

Yes (default)

StandardizeComponent.USCountyName

Specifies whether or not to populate the USCountyName field when standardizing an address.

Yes (default)

StandardizeComponent.StateProvince

Specifies whether or not to populate the StateProvince field when standardizing an address.

Yes (default)

StandardizeComponent.Principality

Specifies whether or not to populate the Principality field when standardizing an address.

Yes (default)

StandardizeComponent.PostalCode

Specifies whether or not to populate the PostalCode field when standardizing an address.

Yes (default)

StandardizeComponent.Plus4

Specifies whether or not to populate the +4 field when standardizing an address.

Yes (default)

StandardizeComponent.Country

Specifies whether or not to populate the Country field when standardizing an address.

Yes (default)

ReportVulgarWords Specifies whether or not to look for vulgar words. If this option is enabled,

ValidateGlobalAddress returns a value in the WCRCode output field to indicate the results.

Yes

No (default)

FlagVulgarWords

DebugOutput

Specifies whether or not to mark vulgar words in the output using the format ">VulgarWord<".

Yes

No (default)

This option controls whether or not to include troubleshooting information in the output fields Email1, Email2, URL1, and URL2.

Yes

API Guide 197

Address Now Module optionName Description

No (default)

Validation Options

Table 57: ValidateGlobalAddress Validation Options optionName Description

ValidateComponent.Department

Specifies whether or not to include the Department field when validating an address.

Yes

No (default)

ValidateComponent.FirmName

Specifies whether or not to include the FirmName field when validating an address.

Yes

No (default)

ValidateComponent.Building

Option.ValidateComponent.Building

Specifies whether or not to include the Building field when validating an address.

Yes (default)

ValidateComponent.SubBuilding

Specifies whether or not to include the SubBuilding field when validating an address.

Yes (default)

ValidateComponent.HouseNumber

Specifies whether or not to include the HouseNumber field when validating an address.

Yes (default)

ValidateComponent.SubStreet

Specifies whether or not to include the SubStreet field when validating an address.

Yes (default)

ValidateComponent.StreetName

Specifies whether or not to include the StreetName field when validating an address.

Yes (default)

ValidateComponent.POBox

Specifies whether or not to include the POBox field when validating an address.

198 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName Description

Yes (default)

ValidateComponent.SubCity

Specifies whether or not to include the SubCity field when validating an address.

Yes (default)

ValidateComponent.City

Specifies whether or not to include the City field when validating an address.

Yes (default)

ValidateComponent.USCountyName

Specifies whether or not to include the USCountyName field when validating an address.

Yes (default)

ValidateComponent.StateProvince

Specifies whether or not to include the StateProvince field when validating an address.

Yes (default)

ValidateComponent.Principality

Specifies whether or not to include the Principality field when validating an address.

Yes (default)

ValidateComponent.PostalCode

Specifies whether or not to include the PostalCode field when validating an address.

Yes (default)

ValidateComponent.Plus4

Specifies whether or not to include the +4 field when validating an address.

Yes (default)

ValidateComponent.Country

Specifies whether or not to include the Country field when validating an address.

Yes (default)

ForceUpdate.Department

Specifies whether or not to correct the Country field when validating an address.

Yes (default)

API Guide 199

Address Now Module

200 optionName Description

ForceUpdate.FirmName

ForceUpdate.Building

ForceUpdate.SubBuilding

Specifies whether or not to correct the SubBuilding field when validating an address.

Yes (default)

ForceUpdate.HouseNumber

Specifies whether or not to correct the HouseNumber field when validating an address.

Yes (default)

ForceUpdate.SubStreet

Specifies whether or not to correct the SubStreet field when validating an address.

Yes (default)

ForceUpdate.StreetName

Specifies whether or not to correct the FirmName field when validating an address.

Yes (default)

Specifies whether or not to correct the Building field when validating an address.

Yes (default)

ForceUpdate.POBox

ForceUpdate.SubCity

ForceUpdate.City

Specifies whether or not to correct the StreetName field when validating an address.

Yes (default)

Specifies whether or not to correct the POBox field when validating an address.

Yes (default)

Specifies whether or not to correct the SubCity field when validating an address.

Yes (default)

Specifies whether or not to correct the City field when validating an address.

Yes (default)

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName Description

ForceUpdate.USCountyName

Specifies whether or not to correct the USCountyName field when validating an address.

Yes (default)

ForceUpdate.StateProvince

Specifies whether or not to correct the StateProvince field when validating an address.

Yes (default)

ForceUpdate.Principality

Specifies whether or not to correct the Principality field when validating an address.

Yes (default)

ForceUpdate.PostalCode

ForceUpdate.Plus4

ForceUpdate.Country

Specifies whether or not to correct the PostalCode field when validating an address.

Yes (default)

Specifies whether or not to correct the +4 field when validating an address.

Yes (default)

Specifies whether or not to correct the Country field when validating an address.

Yes (default)

ReplaceAlias.Department

ReplaceAlias.FirmName

ReplaceAlias.Building

Specifies whether or not to overwrite the Department field if an alias is found in the Address Now database.

Yes

No (default)

Specifies whether or not to overwrite the FirmName field if an alias is found in the Address Now database.

Yes

No (default)

Specifies whether or not to overwrite the Building field if an alias is found in the Address Now database.

Yes

No (default)

API Guide 201

Address Now Module optionName Description

ReplaceAlias.SubBuilding

ReplaceAlias.HouseNumber

Specifies whether or not to overwrite the HouseNumber field if an alias is found in the Address Now database.

Yes

No (default)

ReplaceAlias.SubStreet

Specifies whether or not to overwrite the SubStreet field if an alias is found in the Address Now database.

Yes

No (default)

ReplaceAlias.StreetName

Specifies whether or not to overwrite the SubBuilding field if an alias is found in the Address Now database.

Yes

No (default)

ReplaceAlias.POBox

ReplaceAlias.SubCity

Specifies whether or not to overwrite the StreetName field if an alias is found in the Address Now database.

Yes

No (default)

Specifies whether or not to overwrite the POBox field if an alias is found in the Address Now database.

Yes

No (default)

Specifies whether or not to overwrite the Subcity field if an alias is found in the Address Now database.

Yes

No (default)

ReplaceAlias.City

Specifies whether or not to overwrite the City field if an alias is found in the Address Now database.

Yes

No (default)

ReplaceAlias.USCountyName

Specifies whether or not to overwrite the USCountyName field if an alias is found in the Address Now database.

Yes

No (default)

ReplaceAlias.StateProvince

Specifies whether or not to overwrite the StateProvince field if an alias is found in the Address Now database.

Yes

No (default)

202 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName

ReplaceAlias.Principality

ReplaceAlias.PostalCode

ReplaceAlias.Plus4

ReplaceAlias.Country

CautiousUpdate

CrossComponentMatch

UseReferenceDiacritics

Description

Specifies whether or not to overwrite the Principality field if an alias is found in the Address Now database.

Yes

No (default)

Specifies whether or not to overwrite the PostalCode field if an alias is found in the Address Now database.

Yes (default)

Specifies whether or not to overwrite the +4 field if an alias is found in the Address Now database.

Yes

No (default)

Specifies whether or not to overwrite the Country field if an alias is found in the Address Now database.

Yes

No (default)

This option, used in conjunction with the "Force Update", ensures that no major changes are made to the data during processing.

Yes

No (default)

Specifies whether or not to correct common address standardization and validation errors by performing cross-component matching.

Cross-component matching checks for matches between data found in one field in the input data and another field in the Address Now database.

Yes

No (default)

Specifies whether or not ValidateGlobalAddress modifies the address to match the diacritics (accents, umlauts, etc.) in the postal database when the only changes to the address are the diacritics . One of the following:

Yes (default)

For example, if UseReferenceDiacritics is enabled, the following would occur:

Input City: Chalon-Sur-Saône

City in the postal database: CHALON SUR SAONE

Output City: CHALON SUR SAONE

Input City: ARTEMIVS'K

City in the postal database: ARTEMIVSK

Output City: ARTEMIVSK

API Guide 203

Address Now Module

204 optionName Description

If UseReferenceDiacritics is not enabled, the following would occur:

Input City: Chalon-Sur-Saône

Reference City: CHALON SUR SAONE

Output City: Chalon-Sur-Saône

Input City: ARTEMIVS'K

Reference City: ARTEMIVSK

Output City: ARTEMIVS'K

Note that this option has no effect on the Transliteration option.

KeepStandardizationChanges Specifies whether or not standardization changes such as changing

"ROAD" to "RD" should be reported in the ACR code.

Yes

No (default)

AcceptanceLevel

The Acceptance Level setting specifies the minimum number of address components that must be validated in order for the whole address to be considered validated. The value specified for AcceptanceLevel corresponds to the second character of the ACR code. For more information, see

The ACR Code

on page 212.

The acceptance level differs from the InnerMatchScore option in that acceptance level measures how many components Validate Global

Address validated, regardless of how well the validated components matched to address components in the postal databases, whereas

InnerMatchScore indicates the probability that the output address is the correct, validated version of the input address.

One of the following:

-1

The acceptance level is automatically set to an appropriate level based on the address's country. For example, U.S.

addresses are processed with an acceptance level of 4.

No components validated (default)

Country only validated

City and country validated

City, postal code and country validated

Street, city, postal code and country validated

Premise number, building name, sub-building, PO box, company, street, city, postal code, and country validated

InnerMatchScore

CompanyWeight

Specifies the minimum confidence level for address validation.

Addresses with a value in the Confidence output field greater than or equal to this value is validated, and those that have a lower value will not be validated (the output field Status will contain F.)

Specify any value between 0 and 100. The higher the value, the higher the degree of confidence necessary for effective address validation.

The default is 60.

A whole number from 0 to 10, indicating the relative importance of the

FirmName field compared to the data in the Address Now database.

Spectrum

™

Technology Platform 9.0

optionName

StreetWeight

CityWeight

PostcodeWeight

OuterMatchScoreLines

Chapter 8: Module Services

Description

This affects the confidence value, and can be used to tailor the confidence to distinguish correct and incorrect updates. For more information, see

The ACR Code

on page 212.

The default value is 1.

A whole number from 0 to 10, indicating the relative importance of the

StreetName field compared to the data in the Address Now database.

A whole number from 0 to 10, indicating the relative importance of this field compared to the others. For more information, see

The ACR Code

on page 212.

The default value is 10.

A whole number from 0 to 10, indicating the relative importance of the

City field compared to the data in the Address Now database. A whole number from 0 to 10, indicating the relative importance of this field compared to the others. For more information, see

The ACR Code

on page 212.

The default value is 8.

A whole number from 0 to 10, indicating the relative importance of the

PostalCode field compared to the data in the Address Now database.

A whole number from 0 to 10, indicating the relative importance of this field compared to the others. For more information, see

The ACR Code

on page 212.

The default value is 8

A value from 0 to 8 indicating the number of address lines to use when calculating the outer match score. The default is 8. For more information on the outer match score, see

The Outer Match Score

on page 211.

Output Format Options

Table 58: ValidateGlobalAddress Output Format Options optionName Description

FormatComponent.Department

Specifies whether or not the Department field should be included in the output of a formatted address.

Yes (default)

FormatComponent.FirmName

Specifies whether or not the FirmName field should be included in the output of a formatted address.

Yes (default)

FormatComponent.Building

Specifies whether or not the Building field should be included in the output of a formatted address.

Yes (default)

API Guide 205

Address Now Module

206 optionName Description

FormatComponent.SubBuilding

Specifies whether or not the SubBuilding field should be included in the output of a formatted address.

Yes (default)

FormatComponent.HouseNumber

Specifies whether or not the HouseNumber field should be included in the output of a formatted address.

Yes (default)

FormatComponent.SubStreet

Specifies whether or not the SubStreet field should be included in the output of a formatted address.

Yes (default)

FormatComponent.StreetName

Specifies whether or not the StreetName field should be included in the output of a formatted address.

Yes (default)

FormatComponent.POBox

Specifies whether or not the POBox field should be included in the output of a formatted address.

Yes (default)

FormatComponent.SubCity

Specifies whether or not the SubCity field should be included in the output of a formatted address.

Yes (default)

FormatComponent.City

Specifies whether or not the City field should be included in the output of a formatted address.

Yes (default)

FormatComponent.USCountyName

Specifies whether or not the USCountyName field should be included in the output of a formatted address.

Yes (default)

FormatComponent.StateProvince

Specifies whether or not the StateProvince field should be included in the output of a formatted address.

Yes (default)

FormatComponent.Principality

Specifies whether or not the Principality field should be included in the output of a formatted address.

Yes (default)

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName Description

FormatComponent.PostalCode

Specifies whether or not the PostalCode field should be included in the output of a formatted address.

Yes (default)

FormatComponent.Plus4

Specifies whether or not the +4 field should be included in the output of a formatted address.

Yes (default)

FormatComponent.Country

Specifies whether or not the Country field should be included in the output of a formatted address.

Yes

No (default)

Transliteration Specifies how to format diacritics in the output address. One of the following:

No transliteration is performed. Diacritic characters are left as specified in the input and/or postal database. Default.

Diacritic characters are removed and replaced with the equivalent unadorned character.

Diacritic characters are transliterated to an equivalent unadorned character or character sequence using language-specific transliteration rules.

For example, the following shows the effect of each of the three transliteration options on a Swedish address. Note the differences in

"Västra Frölunda".

Gustaf Wernersgata 12 S-42132 Västra Frölunda

Gustaf Wernersgata 12 S-42132 Vastra Frolunda

Gustaf Wernersgata 12 S-42132 Vaestra Froelunda

Output

Address Data Output

Table 59: ValidateGlobalAddress Address Data Output columnName

AddressLine1

AddressLine2

Format Description

The formatted first address line.

String

[79]

String

[79]

The formatted second address line.

API Guide 207

Address Now Module columnName

AddressLine3

AddressLine4

AddressLine5

AddressLine6

AddressLine7

AddressLine8

ApartmentLabel

ApartmentNumber

Building

City

Country

Department

FirmName

208

HouseNumber

Latitude

Longitude

POBox

String

[79]

String

[79]

String

[79]

String

[79]

Format Description

The formatted third address line.

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

The formatted fourth address line.

The formatted fifth address line.

The formatted sixth address line.

The formatted seventh address line.

The formatted eighth address line.

Apartment designator (such as STE or APT). For example:

123 E Main St. APT 3

Apartment number. For example:

123 E Main St. APT 3

The name of a building.

The city name.

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

The ISO code or English name of the country. For a list of

ISO codes, see

Country ISO Codes and Module Support

A subdivision of a country used in French and Spanish speaking countries. For example, France is divided into 100 departments.

The name of a company. For example:

Pitney Bowes Software

4200 PARLIAMENT PL

STE 600

LANHAM MD 20706-1844

USA

House number. For example:

123 E Main St. Apt 3

The most precise latitude that could be determined for the address. This could be a point level location or a centroid.

The level of precision can be determined by looking at the

ECRCode output field. For more information, see

The ECR

Code

on page 211.

The most precise longitude that could be determined for the address. This could be a point level location or a centroid.

The level of precision can be determined by looking at the

ECRCode output field. For more information, see

The ECR

Code

on page 211.

The post office box number. If the address is a rural route address, the rural route box number will appear here.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

PostalCode

PostalCode.AddOn

PostalCode.Base

Principality

StateProvince

StreetName

StreetSuffix

SubCity

SubStreet

USCountyName

String

[79]

String

[79]

String

[79]

String

[79]

Format Description

The postal code. In the U.S. this is the ZIP Code

™

String

[79]

String

[79]

The 4-digit add-on part of the ZIP + 4

® in the ZIP Code

™

Code. For example,

60655-1844, 1844 is the 4-digit add-on.

(U.S. addresses only.)

The 5-digit ZIP Code

™

. For example 20706 (U.S. addresses only.)

An area within a country. For example, England, Scotland, and Wales are principalities. This field will normally be blank.

The state or province abbreviation.

String

[79]

String

[79]

String

[79]

String

[79]

Street name. For example:

123 E Main St. Apt 3

Street suffix. For example:

123 E Main St. Apt 3

A district or suburb. The subcity is used in countries where it is common to include the district or suburb within the address.

For example,

27 Crystal Way

Bradley Stoke

Bristol BS32 8GA

In this case, "Bradley Stoke" is the subcity.

The second street address used to identify an address.

Substreets are used in countries where it is common to give two street names in the address. For example,

12 The Mews

High Street

For U.S. addresses, the name of the county where the address is located.

Return Codes

Table 60: ValidateGlobalAddress Return Codes columnName

ACRCode

Format Description

String

[79]

The Address Correction Result (ACR) code describes what data has been changed in each record. For information on what this code means, see

The ACR Code

on page 212.

API Guide 209

Address Now Module columnName

Confidence

ECRCode

Email1

Email2

OuterMatchScore

Status

Status.Code

Status.Description

URL1

URL2

WCRCode

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

String

[79]

Format Description

String

[79]

String

[79]

The level of confidence assigned to the address being returned. Range is from zero (0) to 100; zero indicates failure,

100 indicates a very high level of confidence that the match results are correct. This value is the same as the last three digits of the ACR code, referred to as the validation match score. For more information, see

The ACR Code

on page

212.

The Enhanced Correction Result (ECR) code describes the level of precision of the latitude and longitude returned for the address. For mroe information, see

The ECR Code

on page

211.

Extra standardization information.

String

[79]

String

[79]

A score that measures changes to each address line. For more information, see

The Outer Match Score

on page 211.

Reports the success or failure of the match attempt.

• null—Success

• F—Failure

Reason for failure, if there is one.

• UnableToValidate

• ServerError

• CountryNotFound

Description of the problem, if there is one.

• Address Not Found—This value will appear if

Status.Code=UnableToValidate.

• Module not licensed—This value will appear if

Status.Code=ServerError.

• Could Not Identify Country—This value will appear if

Status.Code=CountryNotFound.

Extra standardization information.

The Word Correction Result (WCR) code describes vulgar words found in the input address. The code has two components:

• Location code—One of the following:

• AB—Indicates a vulgarity was found in the address.

• NB—Indicates a vulgarity was found in the name.

• Count—The number of vulgar words found in the location indicated by the location code.

For example, AB2 indicates that two vulgar words were found in the input address.

210 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

The ECR Code

The Enhanced Correction Result (ECR) code describes the level of precision of the latitude/longitude coordinates returned for the address. The code consists of a prefix followed by a dash then the body of the code.

The prefix always begins with "EL" followed by a number from 1 to 5 indicating the overall level of precision:

• 5—Point geocode

• 4—Street centroid

• 3—Postcode centroid

• 2—City centroid

• 1—Region centroid

The body of the code identifies the components that were used to match the address to a geocode. Note that the body consists of letters and numerals. Here's what they mean:

• P—Premise/house number, building or PO box

• S—Street

• T—City

• R—Region/state

• Z—Postal code

• C—Country

There are only two numeric options in the body: 4 or 0

• 4—The component data was available to make the geocode-address match.

• 0—The component date was not available.

For example: EL4-P0S4T4R4Z4C4

In this example, the 0 following the P tells us that premise/house number data was not available to make this address match; everything from street to country, however, was used in the assignment.

The Outer Match Score

The outer match score indicates how much ValidateGlobalAddress changed each address line to validate the address. The score compares the address lines before standardization and after validation and formatting. This score is only generated if you set the option OuterMatchScoreLines to a value greater than 0.

The outer match score is similar to the validation match score, which is part of the ACR code (see

The

ACR Code

on page 212). The difference is that the outer match score measures any change to an address line, including formatting, whereas the validation match score measures only whether or not the data could be validated,

For example, take the following input address lines before processing:

Address Line 1: 5 camden cres

Address Line 2: bath

Address Line 3: uk

After processing the address lines are:

Address Line 1: 5 Camden Crescent

Address Line 2: Bath

Address Line 3: BA1 5HY

Address Line 4: United Kingdom

This has a validation match score of 84% and in outer match score of 23%.

The validation match score is high because the address components were fairly accurate before validation.

The street name was valid except for casing and use of an abbreviation. The city and country were both

API Guide 211

Address Now Module

valid. The only thing not correct was the postal code (in this case it was missing). Hence the relatively high validation match score of 84%.

The outer match score is low because after formatting, the address lines are considerably different from the input. In this case, Address Line 3 contained "uk" on input, and contains "BA1 5HY" on output. Line

4 was empty on input, and in populated on output. Address line 1 has also changed. The outer score is therefore quite low.

The ACR Code

The Address Correction Result (ACR) code describes what data has been changed in each record. An example of an ACR is:

L5-P0S0A5T1R0Z0C4-098

ACR codes consist of three parts:

• Validation Level

• Component Status

• Validation Match Score

Validation Level

The first two characters of the address correction result state the type and level of validation.

The first character, which is always alphabetic, specifies the type of validation:

• U—Unable to standardize address

• C—Address is in component form

• L—Address has been formatted into address lines

• R—Address has been reverted and has not reached acceptable level

The second character, which is always numeric, specifies the level of validation. The higher the level, the better the validation will be. The levels that can be achieved are as follows:

• 0—No components validated

• 1—Country only validated

• 2—City and country validated

• 3—City, postal code and country validated

• 4—Street, city, postal code and country validated

• 5—Premise number, building name, sub-building, PO box, company, street, city, postal code, and country validated.

Component Status

The second part of the ACR code gives the status of the main address components. The address components are identified as follows:

• Character 3-4: P—Premise/house number

• Character 5-6: S—Street

• Character 7-8: A—Subcity (city area)

• Character 9-10: T—City

• Character 11-12: R—Region/state

• Character 13-14: Z—Postal code/ZIP Code

• Character 15-16: C—Country

A number follows each component and can take one of the following values:

• 0—Not found/empty

• 1—Derived using position in input data

212 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

• 2—Recognized using the Address Now Module database

• 3—Recognized and updated to standard form using the Address Now Module database

• 4—Validated using Address Now Module database

• 5—Updated/corrected using Address Now Module database

• 6—Added using Address Now Module database

• 7—Correctly empty

• 8—Partial recognition using Address Now Module database

• 9—Needs correcting to match Address Now Module database

Validation Match Score

The Validation Match Score comprises characters 17-19, the final three digits of the ACR code. This is a comparison between the standardized data (in component format) and the suggested match returned from the Address Now Module database.

This score is calculated by examining all fields returned from the Address Now Module database and comparing them individually with the existing component data. The overall match score is then calculated by combining these individual values into an average score, taking into account the match score weightings, which can be set from the address validation options dialog box. For example,

Input data:

AddressLine1: 11 High Street

City: Anytown

Country: UK

Standardized data:

Premise: 11

Street: High Street

City: Anytown

When validated, the data returned from the Address Now Module database for this record may be:

Premise: 11

Street: High Street

City: Anytown

Postal Code: ZZ9 9ZZ

Comparing the Address Now Module database to the standardized data we get:

• Premise: 100% match

• Street: 100% match

• City: 100% match

• Postal Code: not used, because empty on input

Combining these percentages gives us a match score of 100%.

Another example may be:

Input data:

AddressLine1: bergerstrasse 12

AddressLine2: munich

AddressLine3: 80124

Country: Germany

Standardized data:

Premise: 12

Street: Bergerstr.

City: München

Postal Code: 80124

API Guide 213

Enterprise Geocoding Module

Address Now Module database output:

Premise: 12

Street: Burgerstr.

City: München

Postal Code: 80142

Comparing the Address Now Module database output to the standardized data we get:

• Premise:100% match

• Street: 90% match (the actual figure is determined by a textual comparison of the two values)

• City: 100% match

• Postal Code: 80% match (because the numbers are transposed)

This gives an overall match score of 92% if the match score weightings are all set at 1. Increasing the match score weighting of the postal code will decrease the match score, because the postal code component score (80%) will be made more important in the calculation. Increasing the match score weighting of the city will increase the match score, because the city component score (100%) will be made more important.

For example:

L5-P4S4A5T5R4Z4C4-098

• L shows that formatting has been carried out to create the address lines

• The validation level is 5, meaning that the highest level of matching against the Address Now Module database was attained

• All component codes except subcity (A) and city (T) are set to 4 indicating that they were validated using the Address Now Module database

• The subcity code and city code are set to 5 indicating that these components were corrected using the Address Now Module database

The overall address matched the Address Now Module database at 98%.

Note:

You may also receive a value of "SDS" for the Validation Match Score. A return of SDS indicates that the address has not been standardized, possibly as a result of the address being reverted.

Enterprise Geocoding Module

What is the Enterprise Geocoding Module?

The Enterprise Geocoding Module performs address standardization, address geocoding, and postal code centroid geocoding. You can enter an address and get outputs such as geographic coordinates, which can be used for detailed spatial analysis and demographics assignment. You can also enter a geocode, a point represented by a latitude and longitude coordinate, and receive address information about the provided geocode.

214

Enterprise Geocoding Components

Enterprise Geocoding Module consists of the following components. The specific components you have depend on your license.

• GeocodeAddressAUS—Takes an address in Australia and returns latitude/longitude coordinates and other information.

• GeocodeAddressGBR—Takes an address in Great Britain and returns latitude/longitude coordinates and other information.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

• GeocodeAddressGlobal—Takes an address in any supported country and returns latitude/longitude coordinates and other information. This component will only geocode addresses from countries you have licensed. It does not support Australia and Great Britain.

• Geocode Address—Takes an address located in any of the supported countries and returns the city centroid or, for some countries, postal centroid. The World component cannot geocode to the street address level.

• Geocode Africa — Provides street-level geocoding for many African countries. It can also determine city or locality centroids, as well as postal code centroids for selected countries.

• Geocode Middle East — Provides street-level geocoding for many Middle East countries. It can also determine city or locality centroids. The Middle East component supports both English and Arabic character sets.

• GeocodeUSAddress—Takes an input address and returns latitude/longitude coordinates and other address information.

• GNAFPIDLocationSearch—Identifies the address and latitude/longitude coordinates for a Geocoded

National Address File Persistent Identifier (G-NAF PID).

• ReverseAPNLookup—Takes an Assessor's Parcel Number (APN), Federal Information Processing

Standards (FIPS) county code, and FIPS state code and returns the address of the parcel.

• ReverseGeocodeUSLocation—Takes as input a geocode (latitude and longitude coordinate) and returns the address of the location.

Enterprise Geocoding Databases

The following table lists the Enterprise Geocoding Module databases. The databases are installed on the Spectrum

™

Technology Platform server. Some of the databases are available by subscription from

Pitney Bowes Software and are updated monthly or quarterly. Others are licensed from the USPS

Table 61: Enterprise Geocoding Module Databases

Database Name & Description Required or

Optional

Supplier

U.S. Geocoding Databases

These databases contain the spatial data necessary to perform address standardization and geocoding. You must install at least one of these databases. You set the database that you want to match against with the processing options.

Enterprise Geocoding tries to match to the database you indicate. To verify you are matching to the database you want, you can review the value returned in the StreetDataType output field.

Required for U.S.

geocoding

These databases use proprietary files called GSD files. For

ZIP Code centroid matching, the file us.Z9 contains all the centroid info for all states and normally has a z9 extension.

• Centrus Enhanced Geocoding—This database consists of TIGER data provided by the U.S. Geological Survey and address data provided by the U.S. Postal Service.

• TomTom Geocoding—This database provides more up-to-date data than the Centrus Enhanced Geocoding database. It requires an additional license. This data is provided by TomTom, a third-party provider of spatial data, and postal data from the U.S. Postal Service.

• NAVTEQ Geocoding—This database provides more up-to-date data than the Centrus Enhanced Geocoding

Pitney Bowes

Software monthly subscription

API Guide 215

Enterprise Geocoding Module

216

Database Name & Description Required or

Optional

Supplier

database. It requires an additional license. NAVTEQ data is provided by NAVTEQ, a third-party provider of spatial data. For more information about these databases, contact your sales representative.

• ZIP + 4 Centroid—This database provides only address standardization and ZIP + 4 centroid matching. It does not provide street-level matching.

Each geocoding database has an optional Statewide

Intersections Index. The Statewide Intersection Index is designed to enable fast intersection identification on a statewide basis. For example, the Statewide Intersection

Index will allow the database search for "1st and Main St,

CO" and return a list of possible matches in Colorado more quickly than searching the entire geocoding database for each instance of the intersection.

International Geocoding Databases

International geocoding databases contain the spatial data necessary to perform address standardization and geocoding for locations outside the U.S. Each country has its own database, and some countries have optional databases that provide enhanced geocoding.

Required for all licensed countries

Pitney Bowes

Software quarterly subscription

Pitney Bowes

Software quarterly subscription

Australia Geocoded National Address File (G-NAF)

This database provides enhanced geocoding for Australian addresses. This is the only authoritative Australian national index of locality, street and number, validated with geographic coordinates. It contains both officially recognized rural and urban addresses and unofficial addresses (aliases). Postal addresses and PO Boxes are not included. However, because some rural areas do not have adequate rural address information, roadside mail box (RMB) numbers, Lot numbers, and Block & Section numbers have been included in the

G-NAF data set.

Optional

When you install this database there will be two subfolders:

• GNAF123—Contains the point-level dictionary. This has the highest precision of geocoding (characterized by

Reliability Level 1, 2, or 3.)

• GNAF456 —Contains the remainder of address information in G-NAF that does not meet high precision geocoding criteria (characterized by Reliability Level 4, 5, or 6.)

You must specify each of these as separate database resources in the Management Console.

We recommend that you use both databases to validate the existence of addresses but only use the GANF123 for parcel-level geocoding. If you do not require parcel-level geocodes you can use the GANF456 database for geocoding.

United Kingdom Address-Point Database

Optional Pitney Bowes

Software

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Database Name & Description Required or

Optional

Supplier

The Address-Point database contains street addresses and is derived from the Ordnance Survey

. Candidate location will be usually to a resolution of 0.1 meters from the building/parcel delivery point. This database is suitable for applications that demand this highest available level of precision, including routing applications.

The Address-Point database provides a greater level of geocoding precision than can be delivered by the CodePoint database. This high level of precision is reflected in S8 and

S7 result codes.

For more information on the Ordnance Survey Address-Point data source, see:

http://www.ordnancesurvey.co.uk/oswebsite/products/address-point/index.html

While the Ordnance Survey data source does not contain addresses for Northern Ireland, the Address-Point dataset from Pitney Bowes Software is supplemented with Royal Mail

® postcode address data for Northern Ireland. This Northern

Ireland data has postcode centroid (result code S3) precision only.

United Kingdom CodePoint Database

The CodePoint Postal Address File (PAF) database provides postcode centroid geocoding. The CodePoint database is suitable for most applications involving address matching, validation, etc.

Optional

The CodePoint database is derived from Royal Mail and covers street addresses for the UK (Great Britain and Northern

Ireland). The CodePoint database is licensed for the entire dataset, rather than by region.

For more information on the Royal Mail data source, see:

www.royalmail.com

The postcode centroid precision provided by the CodePoint database is reflected in S3 result codes.

Pitney Bowes

Software

Reverse Geocoding Database (U.S. Only)

This database contains the data you need to convert a latitude/longitude location to an address.

Optional, but required for

ReverseGeocodeUSLocation.

Additional license required.

Pitney Bowes

Software monthly subscription

Pitney Bowes

Software

New Zealand Point Database

The New Zealand Point Database is based on postal point data which has a roof top precision point of each unique street address. Location X and Y returned for candidates from this database are roof top precision.

Optional

This data is maintained by the government authority, Land

Information New Zealand. This database is a monthly update from what the local district councils supply.

API Guide 217

Enterprise Geocoding Module

218

Database Name & Description Required or

Optional

Supplier

U.S. Points Databases

Points databases contain data for locating the center of a parcel. These databases provides enhanced geocoding accuracy for internet mapping, property and casualty insurance, telecommunications, utilities, and others.

• Centrus Points—This database contains the data necessary to locate the center of a parcel or building. It does not contain assessor's parcel number (APN) or elevation data.

• Centrus Elevation—This database contains the same data as Centrus Points, plus elevation data.

• Centrus Enhanced Points—This database contains the same data as Centrus Points, plus APN data.

• Centrus Premium Points—This database contains the same data as Centrus Points, plus both APN and elevation data.

• Centrus TomTom Points Database—The data in this database is provided by TomTom, a third-party provider of spatial data.

Optional, but

ReverseAPNLookup requires Centrus

Enhanced Points or

Centrus Premium

Points. Additional license required.

Pitney Bowes

Software monthly subscription

Auxiliary Files

Auxiliary files contain user-defined records. You can use auxiliary files to provide custom data to use in address matching and geocode matching.

Optional User-defined

DPV

Database (U.S. Only)

The Delivery Point Validation database allows you to check the validity of any individual mailing address in the U.S. The

DPV database is distributed as an optional feature and can be installed to enhance the geocoding database's ability to validate mailing addresses. Each time an edition of the geocoding database is released, a corresponding edition of the optional DPV database is released. The date of the DPV database must match the date of the geocoding database for

DPV processing to function. DPV lookups may not be performed after the expiration date of the DPV database.

Optional, but required for CASS

Certified

™ processing.

Additional license required.

Pitney Bowes

Software monthly subscription

Note:

CASS processing requires the DPV option. The DPV option is also required to determine ZIP + 4 and ZIP

+ 4 related output (DPBC, USPS record type, etc.).

Postal Service licensing prohibits using DPV for the generation of addresses or address lists, and also prohibits the DPV database being exported outside the United States.

EWS Database (U.S. Only)

The Early Warning System (EWS) database contains data that prevents address records from miscoding due to a delay in postal data reaching the U.S. Postal database.

The USPS

® refreshes the EWS file on a weekly basis. Unlike the DPV and LACS

Link databases, the EWS database does

Optional Download for free from USPS website

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Database Name & Description Required or

Optional

Supplier

not need to have the same date as the geocoding database.

You can download the EWS file from the CASS section of the

USPS

RIBBS website at:

https://ribbs.usps.gov/

When you download the EWS database, you will receive a file named OUT. You must rename the OUT file to EWS.txt

before using it.

LACS

Link

Database (U.S. Only)

The LACS

Link database allows you to correct addresses that have changed as a result of a rural route address converting to street-style address, a PO Box renumbering, or a street-style address changing.

The date of the LACS

Link database must match the date of the geocoding database for LACS

Link processing to function.

Optional, but required for CASS

Certified

™ processing

Pitney Bowes

Software monthly subscription

Note:

The Enterprise Geocoding Module requires the

LACS

Link option in CASS mode to receive ZIP + 4 and ZIP + 4 related output (delivery point barcode,

USPS record type, etc.).

USPS licensing prohibits using LACS

Link for the generation of addresses or address lists, and also prohibits the LACS

Link database being exported outside the United States.

Geocoding Concepts

Geocoding is the process of determining the latitude/longitude coordinates of an address. There are different ways that an address can be geocoded. In order of most accurate to least accurate, these methods are:

Point Level Matching

Point-level matching locates the center of the actual building footprint or parcel. This is the most accurate type of geocode and is used in industries such as internet mapping, insurance, telecommunications, and utilities.

Centerline matching is used with point-level matching to tie a point-level geocode with its parent street segment. This provides you with additional data about the parent street segment that is not retrievable using only the point-level match. The output information also includes the bearing from the point data geocode to the centerline match.

Street Matching

Street matching identifies the approximate location of an address on a street segment. In street matching, the location is determined by calculating the approximate location of a house number based on the range

API Guide 219

Enterprise Geocoding Module

of numbers in the location's street. For example, if the address is on a street segment with a range of addresses from 50 to 99, then it is assumed that the house number 75 would be in the middle of the street segment. This method assumes that the addresses are evenly spaced along the street segment.

As a result, it is not as exact as point matching since addresses may not be evenly distributed along a street segment.

For example, the following diagram shows the results of street-level matching along a segment with unevenly-spaced buildings. The first three buildings are fairly accurately geocoded because they are evenly spaced. The fourth building, however, resides on a slightly larger parcel than the others along this street. Since street-level matching assumes that the buildings are evenly spaced, the result is that fourth, fifth, and sixth houses are not as precise as the first three. If you were to use point-level geocoding, the results would be more accurate.

Centroid Matching

ZIP Code centroid matching is a center point of an area defined by either a ZIP Code or a ZIP + 4, and is the least accurate type of geocode. A ZIP Centroid is the center of a ZIP Code; a ZIP + 4 centroid is the center of a ZIP + 4. Since a ZIP + 4 represents a smaller area than a ZIP Code, a ZIP + 4 centroid is more accurate than a ZIP Code centroid.

The following diagram illustrates centroid matching. All six houses would have the same geocode in this example because they all reside in the same ZIP + 4 code.

220

Geocoding Match Strategies for Non-U.S. Locations

The Enterprise Geocoding Module offers a variety of options for controlling geocoding precision and match rate. The following information describes different approaches for matching which you can apply to any country geocoder except the U.S. geocoder (GeocodeUSAddress), which has a different set of options.

Maximizing the Match Rate

To generate the highest match rate possible, do not specify house number, street, and city/locality using the ExactMatch option.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Another way to maximize the match rate is by setting FallbackToPostal=Y. This means that the geocoder will fall back to the four-digit postcode centroid if a close street level match cannot be made. While this scenario might yield false positives, it may be the best matching solution when you have large databases to geocode.

You should evaluate if the percentage of false positives will affect your analysis. To reduce the number of false positives without sacrificing hit rate, analyze the result codes after a geocoding session and adjust your settings accordingly.

Maximizing Precision

If your analysis requires highly precise geocoded addresses, choose a strategy in which the geocoder returns the maximum percentage of high precision geocodes and the lowest number of imprecise matches

(false positives). To do this, use the ExactMatch option to require close matches to match on all address elements. Also, set FallbackToPostal=N.

This technique may produce a lower percentage match rate, but will provide the best precision.

Balancing Match Rate and Precision

You may want to use a balanced strategy between match rate and geographic precision. That is, you may want to geocode as many records as possible automatically, but at the same time want to minimize the number of weaker matches (false positives). For example, false positives can occur when the geocoder:

• finds a street that sounds like the input street.

• finds the same street in another city (if postal code match is not required).

• finds the street but with a different house number (if house number is not required).

The following settings may achieve a good balance between match rate and precision:

• CloseMatchesOnly—Specify "Y".

• MustMatchHouseNumber—Specify "Y".

• MustMatchStreet—Specify "Y".

• FallbackToPostal—Specify "N".

Postal Concepts

The following sections contain information on postal concepts used by the Enterprise Geocoding Module.

Dual Addresses

GeocodeUSAddress can process input that contains two addresses for the same record on the same address line. For example, GeocodeUSAddress can process the following input address:

3138 HWY 371

PO BOX 120

PRESCOTT AR 71857

GeocodeUSAddress does not recognize dual addresses where the two addresses are both street addresses. For example, GeocodeUSAddress does NOT recognize 135 Main St 4750 Walnut St Ste

200. GeocodeUSAddress does recognize dual addresses where the two addresses are the same type of address but are not street addresses. For example, GeocodeUSAddress does recognize PO BOX 12

PO BOX 2000.

After GeocodeUSAddress parses the dual address, it searches for a match. GeocodeUSAddress determines which address has preference for a match based on the processing mode. In CASS mode,

GeocodeUSAddress ignores the prefer PO Box and prefer street options, and attempts to find a match based on the following order: PO Box, Street, Rural Route, and General Delivery. In Relaxed mode,

GeocodeUSAddress recognizes the Address Preference (AddressPreference) input option.

API Guide 221

Enterprise Geocoding Module

Note:

GeocodeUSAddress does not perform dual address processing in Exact and Close mode.

GeocodeUSAddress does not perform dual address processing on multi-line addresses.

Locatable Address Conversion System (LACS)

The USPS

Locatable Address Conversion System (LACS) corrects addresses that have changed as a result of a rural route address converting to street-style address, a PO Box renumbering, or a street-style address changing. The following are examples of LACS

Link conversions:

• Rural Route Converted to Street-Style Address: Old Address: RR 3 Box 45 New Address: 1292 North

Ridgeland Drive

• Street Renamed and Renumbered: Old Address: 23 Main Street New Address: 45 West First Avenue

• PO Box Renumbered: Old Address: PO Box 453 New Address: PO Box 10435

LACS

Link is required for CASS processing.

Delivery Point Validation (DPV)

Delivery Point Validation (DPV

) is a United States Postal Service

(USPS

) technology that validates the accuracy of address information down to the individual mailing address. By using DPV

® to validate addresses, you can reduce undeliverable-as-addressed (UAA) mail, thereby reducing postage costs and other business costs associated with inaccurate address information.

Note:

DPV

® is only available for U.S. addresses.

Without DPV

, the address validation process only verifies that an individual address is within a range of valid addresses for the given street. For example, the USPS data indicates that the range of addresses on Maple Lane is 500 to 1000. You attempt to validate an address of 610 Maple Ln. Without DPV

, this address would appear to be valid because it is in the range of 500 to 1000. However, in reality the address

610 Maple Ln does not exist: the house numbers in this section of the street are 608, 609, 613, and 616.

With DPV

® processing, you would be alerted to the fact that 610 Maple Ln does not exist and you could take action to correct the address.

DPV

® also provides unique address attributes to help produce more targeted mailing lists. For example, can indicate if a location is vacant and can identify commercial mail receiving agencies (CMRAs) and private mail boxes.

Although DPV

® can validate the accuracy of an existing address, you cannot use DPV

® to create address lists. For example, you can validate that 123 Elm Street Apartment 6 exists, but you cannot ask if there is an Apartment 7 at the same street address. To prevent the generation of address lists, the DPV

® database contains false positive records. False positive records are artificially manufactured addresses that reside in a false positive table. For each negative response that occurs in a DPV

® query, a query is made to the false positive table. A match to this table will stop DPV

® processing.

Early Warning System (EWS)

The Early Warning System (EWS) provides up-to-date address information for new and recently changed addresses that have not yet been updated in the monthly USPS database. EWS prevents address records from miscoding due to a delay in postal data reaching the USPS

® databases.

The older the U.S. Postal Database, the higher potential you have for miscoding addresses. When a valid address is miscoded because the address it matches to in the U.S. Postal Database is inexact, it will result in a broken address.

EWS data consists of partial address information limited to the ZIP Code

™

, street name, predirectional, postdirectional, and a suffix. For an address record to be EWS-eligible, it must be an address not present on the most recent monthly production U.S. Postal Database.

The USPS

® refreshes the EWS file on a weekly basis. You can download the EWS file from the USPS website at

ribbs.usps.gov/files/CASS

222 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Geocode Address Global

For information on using the API to access Geocode Address Global, see the geocoding guides.

GeocodeAddressWorld

The GeocodeAddressWorld component takes an address located in any of the supported countries and returns the city centroid or, for some countries, postal centroid. The GeocodeAddressWorld component cannot geocode to the street address level. If you require address-level geocoding, use

GeocodeAddressGlobal.

GeocodeAddressWorld is typically used as a fallback geocoder to cover countries for which a Geocode

Address Global country is not available. For example, you may have licensed the Australia geocoder because you are primarily interested in geocoding Australian addresses. However, your data may have some records with locations outside Australia. In this case you could use GeocodeAddressWorld to provide centroid geocodes for locations outside Australia, while using the Australia geocoders to provide more precise geocodes for Australian addresses. In other dataflows, you may choose to use

GeocodeAddressWorld as a first pass geocoder and then route the results to country-specific geocoders.

The best strategy depends on your business case and the nature of your address data.

The GeocodeAddressWorld component is an optional part of the Enterprise Geocoding Module. For more information about Enterprise Geocoding Module, including a listing of other components included with it, see

What is the Enterprise Geocoding Module?

on page 214.

Geocode Precision

GeocodeAddressWorld automatically provides the best geocode possible based on the data you provide on input. If you provide a city and valid postal code, you will receive a postal code centroid. If you provide a city and an invalid postal code, or a city and no postal code, GeocodeAddressWorld will return the geographic centroid of the city.

See

Geographic Geocoding

on page 224 and

Postal Geocoding

on page 223.

From Management Console, you can select Geographic or Postal geocoding. You can also select Best

Match. In both geographic and postal geocoding are possible, the Best Match selection will return a close match geographic candidate if the geographic result is to a city level or better (that is, a G3 or G4 result code). If the geographic result is less accurate than a city level (that is, a G1 or G2 result code), then Best Match may return a postal (Z1 result). If a postal result is not available, then the best available geographic candidate is returned.

See

Geographic Geocoding Result Codes

and

Postal Geocoding Result Codes

Postal Geocoding

Geocode Address World can geocode to a postal centroid if postcode information is available from the country. Postcode information can come from any of the data sources (TomTom, GeoNames, or Pitney

Bowes). See

Country Postal Data Coverage

on page 235 for a summary of Geocode Address World postal data coverage. Depending on the country, postal geocoding may provide more accurate results that geographic geocoding.

Postal level geocoding is possible if these conditions are met:

• Your input address consists of a valid postcode.

• The data source contains postcode information for the country. Not every country has postcode data.

Geocode Address World may return multiple close matches for postal geocoding. For example, a postcode of 12180 matches Troy NY but the identical postcode occurs in several other countries. If the input is the postcode only, then all those candidates are returned as close matches.

However, if the input includes geographic address elements (such as country, state, region, or city name),

Geocode Address World may be able to use that information to return a more accurate single close match. If you want to use geographic address content to refine your postal geocoding results, consider the following:

API Guide 223

Enterprise Geocoding Module

• Different countries derive their postal data from either the TomTom, GeoNames, or Pitney Bowes sources. Therefore, the available geographic content in the postal data source varies by country. For example, city name (City) is a close match weighting factor for countries that use the GeoNames postal data source, but city name is ignored for countries that use the TomTom postal data source. See

Data

Sources and Coverage

on page 226 for information on the geographic content of the TomTom,

GeoNames, and Pitney Bowes data sources.

Postal Geocoding with Geographic Information

In this postal geocoding example, the input address includes a valid postcode of 41012 and the province (StateProvince) of Emilia Romagna. A street address is provided, but this is ignored for postal geocoding.

Fornaci 40

Emilia Romagna

41012

Because the TomTom postal data source for Italy includes StateProvince, the province of Emilia Romagna is considered when evaluating close matches. Therefore, Emilia

Romagna, Italy with the matching 41012 postal code is returned as the single close match with a Z1 result code. Candidates with a 41012 postcode from other countries are returned as non-close candidates. If StateProvince or Country information was not provided on input, then Geocode Address World would return multiple close matches because the five-digit 41012 postcode can be found in a number of countries.

: e t o

The geographic content must be present in the postal data source in order refine postal geocoding results. For example, the Italy TomTom postal data source does not include city/town (City). So if you input the city of Carpi with the 41012 postal code, Geocode Address World ignores the city name and returns multiple close matches for the

41012 postal code (unless you also specified the ITA country name).

See

Data Sources and Coverage

on page 226 for information on the geographic content of the TomTom, GeoNames, and Pitney Bowes data sources.

Geographic Geocoding

Geocode Address World can geocode to the centroid of an administrative division (such as town or village).

Geocode Address World can geocode to the geographic level if these conditions are met:

• Your input addresses contains accurate geographic information without valid postcode address content in the input. If the address in question includes valid postcode input, then Geocode Address World will attempt postal geocoding.

• The data source contains geographic level information for the country. Geographic information can come from any of the data sources (TomTom, GeoNames, or Pitney Bowes).

• Country name or country ISO codes are not required, but if included, they must be matched. Including the country name may produce better close matches.

Geographic Geocoding to City

In this example, the input address includes the city (City) of Vaihingen an der Enz.

The country is not specified in this example. The street address information (street name and number) is ignored for the purposed of geographic geocoding.

Muldenweg 2

Vaihingen an der Enz

224 Spectrum

™

Technology Platform 9.0

API Guide

Chapter 8: Module Services

Geocode Address World returns a G3 close match candidate. Even though the country was not specified, Geocode Address World identifies one close match in Germany

(DEU).

StateProvince: Baden-Württemberg

County: Ludwigsburg

City: Vaihingen an der Enz

Country: DEU

Result Code: G3

X: 8.95948

Y: 48.930059

Geographic Geocoding with Common City Name

In this example, the input address includes the city (City) of Venice. This city name occurs in a number of countries, but the country is not specified on input.

St Marks Plaza

Venice

Geocode Address World selects Venice, Italy as the close match candidate because of its large population (approximately 270,000) and because Venice is the administrative capital of the Veneto region of Italy. A number of non-close matches may also be returned for cities of Venice in other countries. The close match candidate for Venice,

ITA is:

StateProvince: Veneto

County: Venezia

City: Venice

Country: ITA

Result Code: G3

X: 12.33878

Y: 45.43434

Geographic Geocoding with State/Province Abbreviation

In this example the input address includes the city name of Rome and GA, which is the abbreviation for the state of Georgia in the USA. See

State or Province

Abbreviations

on page 244 to see the countries for which state/province abbreviations are recognized. Because the state abbreviation is used, it is not necessary to specify the country name.

Rome, GA

Geocode Address World considers the StateProvince and returns a close match for

Rome, Georgia USA. Even though Rome, Italy is a much larger city and is the capital of Italy, that is returned as a non-close candidate because the StateProvince (GA) that was specified on input

StateProvince: Georgia

County: Floyd

City: Rome

Country: USA

Result Code: G3

X: -85.16467

Y: 34.25704

225

Enterprise Geocoding Module

Geographic Geocoding to Locality

In this example, the input address includes the locality of Altamira and province abbreviation of GRO Geocode Address World recognizes the state abbreviation of

GRO, so the country name is not necessary.

City: Altamira

StateProvince: GRO

In this example, Geocode Address World returns a close match to Locality) of Altamira even if Altamira was input as City. The (StateProvince) of GRO is also returned. If

Guerrero is entered as StateProvince then Guerrero is returned.

StateProvince: GRO

City: ACAPULCO DE JUÁREZ

Locality: ALTAMIRA

Country: MEX

Result Code: G4

X: 99.87984

Y: 16.87637

Address input can be formatted into separate input fields or input can be unformatted

(single line input). Geocoding of unformatted input is shown in

Single Line Input

on page 245.

Geographic Areas

Every country has administrative divisions and many of these administrative areas are used in addresses.

Geocode Address World identifies four AreaNames, each one corresponding to an administrative division.

Administrative division naming and hierarchy vary by country.

• locality

• city

• county

• state/province

226

Data Sources and Coverage

Geocode Address World relies on several data sources to build its comprehensive worldwide address databases. If an input address cannot be located using one of these data sources, then Geocode Address

World uses one of the other data sources. The best available candidate is returned.

These data sources (for both geographic and postal data) are used in the listed order:

• TomTom data

• GeoNames data

• Pitney Bowes World data

Geocode Address World is partitioned into six databases based on continent. The geographic and postal data is integrated into each address dictionary to support both geographic geocoding and postal geocoding.

• Africa

• Asia

• Europe

• NorthAmerica

• Oceana

• SouthAmerica

See

Geographic Geocoding

on page 224 for a description and examples of geographic geocoding. See

Postal Geocoding

on page 223 for a description and examples of postal geocoding.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

The postal source data can access the geographic content, which can be used to refine postal results.

That is, geographic information (country name and administrative divisions) can be used to help evaluate close matches when the same postal code can be found in different countries.

Depending on the source of the postal data, the following geographic information is available to help refine postal results:

• TomTom source: Country, StateProvince

• GeoNames source: Country, StateProvince and City

• Pitney Bowes World source: Country, StateProvince, County, City, and Locality

Note:

The Geocode Address World data set contains data licensed from the GeoNames Project

(

http://www.geonames.org

) provided under the Creative Commons Attribution License

(“Attribution License”) located at

http://creativecommons.org/licenses/by/3.0/legalcode

. Your use of the GeoNames data (described in the Spectrum User Manual) is governed by the terms of the Attribution License, and any conflict between your agreement with PBSI and the Attribution

License will be resolved in favor of the Attribution License solely as it relates to your use of the

GeoNames data.

Country Coverage

Geocode Address World includes coverage for almost every country in the world. The accuracy and scope of coverage varies depending on the quality of the available data source. Some countries include postcode data, while other countries have geographic coverage only.

See

Data Sources and Coverage

on page 226 for more information on the TomTom, GeoNames, and

Pitney Bowes geographic and postal data sources.

For a complete list of Geographic coverage by country, see

Country Geographic Data Coverage

on page 227. For Postal coverage by country, see

Country Postal Data Coverage

on page 235.

Country Geographic Data Coverage

Table 62: Country Names and Geographic Data Coverage

Country Name

AFGHANISTAN

ALAND ISLANDS

ALBANIA

ALGERIA

AMERICAN SAMOA

ANDORRA

ANGOLA

ANGUILLA

ANTARCTICA

ANTIGUA AND BARBUDA

ARGENTINA

ARMENIA

ARUBA

AUSTRALIA

AUSTRIA

ARG

ARM

ABW

AUS

AUT

AND

AGO

AIA

ATA

ATG

ISO 3166

Country Code

AFG

ALA

Data Source

GeoNames

ALB

DZA

ASM

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

Vintage

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

API Guide 227

Enterprise Geocoding Module

228

Country Name

AZERBAIJAN

BAHAMAS

BAHRAIN

BANGLADESH

BARBADOS

BELARUS

BELGIUM

CAMBODIA

CAMEROON

CANADA

CAPE VERDE

CAYMAN ISLANDS

CENTRAL AFRICAN REPUBLIC

CHAD

CHILE

CHINA

ISO 3166

Country Code

Data Source

AZE

BHS

BELIZE

BENIN

BERMUDA

BHUTAN

BOLIVIA

BONAIRE, SINT EUSTATIUS AND

SABA

BES

BOSNIA AND HERZEGOWINA BIH

BOTSWANA

BOUVET ISLAND

BRAZIL

BWA

BVT

BRA

IOT BRITISH INDIAN OCEAN

TERRITORY

BRUNEI DARUSSALAM

BULGARIA

BURKINA FASO

BURUNDI

BRN

BGR

BFA

BDI

BLZ

BEN

BMU

BTN

BOL

BHR

BGD

BRB

BLR

BEL

KHM

CMR

CAN

CPV

CYM

CAF

TCD

CHL

CHN

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

Vintage

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Country Name

CHRISTMAS ISLAND

COCOS (KEELING) ISLANDS

COOK ISLANDS

COSTA RICA

COTE D'IVOIRE

CROATIA (LOCAL NAME:

HRVATSKA)

CUBA

ISO 3166

Country Code

Data Source

CXR

CCK

COLOMBIA

COMOROS

COL

COM

CONGO COG

CONGO, DEMOCRATIC REPUBLIC

OF THE

COD

COK

CRI

CIV

HRV

GeoNames

TomTom

GeoNames

TomTom

CURAÇAO

CYPRUS

CZECH REPUBLIC

DENMARK

DJIBOUTI

DOMINICA

CUB

CUW

CYP

CZE

DNK

DJI

DMA

GeoNames

TomTom

GeoNames

DOMINICAN REPUBLIC

ECUADOR

EGYPT

EL SALVADOR

EQUATORIAL GUINEA

ERITREA

ESTONIA

ERI

EST

ETHIOPIA ETH

FALKLAND ISLANDS (MALVINAS) FLK

DOM

ECU

EGY

SLV

GNQ

FAROE ISLANDS

FIJI

FINLAND

FRANCE

FRENCH GUIANA

FRO

FJI

FIN

FRA

GUF

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

Vintage

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

API Guide 229

Enterprise Geocoding Module

Country Name

FRENCH POLYNESIA

FRENCH SOUTHERN

TERRITORIES

GABON

GAMBIA

GEORGIA

GERMANY

GHANA

ISO 3166

Country Code

Data Source

PYF

ATF

GIBRALTAR

GREECE

GREENLAND

GRENADA

GUADELOUPE

GUAM

GUATEMALA

GUERNSEY

GUINEA

GUINEA-BISSAU

GUYANA

HAITI

GUY

HTI

HEARD AND MCDONALD ISLANDS HMD

HONDURAS HND

GUM

GTM

GGY

GIN

GNB

GIB

GRC

GRL

GRD

GLP

GAB

GMB

GEO

DEU

GHA

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom HONG KONG

HUNGARY

ICELAND

INDIA

INDONESIA

IRAN (ISLAMIC REPUBLIC OF)

IRAQ

IRELAND

ISLE OF MAN

ISRAEL

HKG

HUN

ISL

IND

IDN

IRN

IRQ

IRL

IMN

ISR

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

Vintage

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

230 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Country Name

ITALY

JAMAICA

JAPAN

JERSEY

JORDAN

KAZAKHSTAN

KENYA

ISO 3166

Country Code

Data Source

ITA

JAM

KIRIBATI KIR

KOREA, DEMOCRATIC PEOPLE'S

REPUBLIC OF

PRK

KOREA, REPUBLIC OF

KUWAIT

KYRGYZSTAN

KOR

KWT

KGZ

LAO LAO PEOPLE'S DEMOCRATIC

REPUBLIC

LATVIA

LEBANON

LESOTHO

LIBERIA

LVA

LBN

LSO

LBR

JPN

JEY

JOR

KAZ

KEN

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

LIBYAN ARAB JAMAHIRIYA

LIECHTENSTEIN

LITHUANIA

LUXEMBOURG

MACAO

MACEDONIA, THE FORMER

YUGOSLAV REPUBLIC OF

MADAGASCAR

LBY

LIE

LTU

LUX

MAC

MKD

TomTom

GeoNames

TomTom

GeoNames

TomTom

MALAWI

MALAYSIA

MALDIVES

MALI

MALTA

MARSHALL ISLANDS

MDG

MWI

MYS

MDV

MLI

MLT

MHL

GeoNames

TomTom

GeoNames

TomTom

GeoNames

Vintage

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

API Guide 231

Enterprise Geocoding Module

Country Name

MARTINIQUE

MAURITANIA

MAURITIUS

MAYOTTE

MEXICO

MICRONESIA, FEDERATED

STATES OF

MOLDOVA, REPUBLIC OF

MONACO

MONGOLIA

MONTENEGRO

MONTSERRAT

MOROCCO

MOZAMBIQUE

MYANMAR

NAMIBIA

NAURU

NEPAL

NETHERLANDS

NETHERLANDS ANTILLES

NEW CALEDONIA

NEW ZEALAND

NICARAGUA

NIGER

NIGERIA

NIUE

NORFOLK ISLAND

NORTHERN MARIANA ISLANDS

NORWAY

OMAN

PAKISTAN

PALAU

NLD

ANT

NCL

NZL

NIC

MOZ

MMR

NAM

NRU

NPL

MDA

MCO

MNG

MNE

MSR

MAR

NOR

OMN

PAK

PLW

NER

NGA

NIU

NFK

MNP

ISO 3166

Country Code

Data Source

MTQ

MRT

GeoNames

TomTom

MUS

MYT

MEX

FSM

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

Pitney Bowes

GeoNames

Vintage

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

C. 2006

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

232 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Country Name

PALESTINIAN TERRITORY,

OCCUPIED

PANAMA

PAPUA NEW GUINEA

PARAGUAY

PERU

PHILIPPINES

PITCAIRN

POLAND

PORTUGAL

PUERTO RICO

QATAR

REUNION

ROMANIA

RUSSIAN FEDERATION

RWANDA

SAINT BARTHÉLEMY

ROU

RUS

RWA

BLM

SAINT HELENA, ASCENSION AND

TRISTAN DA CUNHA

SHN

POL

PRT

PRI

QAT

REU

SAINT KITTS AND NEVIS

SAINT LUCIA

SAINT MARTIN (FRENCH PART

SAINT PIERRE AND MIQUELON

SAINT VINCENT AND THE

GRENADINES

SAMOA

SAN MARINO

SAO TOME AND PRINCIPE

SAUDI ARABIA

SENEGAL

SERBIA

SEYCHELLES

SIERRA LEONE

ISO 3166

Country Code

Data Source

PSE GeoNames

KNA

LCA

MAF

SPM

VCT

PAN

PNG

PRY

PER

PHL

PCN

WSM

SMR

STP

SEN

SRB

SYC

SLE

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

Vintage

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

API Guide 233

Enterprise Geocoding Module

234

Country Name

SINGAPORE

SINT MAARTEN (DUTCH PART)

SLOVAKIA (SLOVAK REPUBLIC)

SLOVENIA

SOLOMON ISLANDS

SOMALIA

SOUTH AFRICA

SOUTH GEORGIA AND THE

SOUTH SANDWICH ISLANDS

SPAIN

ISO 3166

Country Code

Data Source

SGP

SXM

SVK

SVN

SLB

SOM

ZAF

SGS

SRI LANKA

SUDAN

SURINAME

SVALBARD AND JAN MAYEN

ISLANDS

SWAZILAND

SWEDEN

SWITZERLAND

SYRIAN ARAB REPUBLIC

TAIWAN

TAJIKISTAN

TWN

TJK

TANZANIA, UNITED REPUBLIC OF TZA

THAILAND THA

SWZ

SWE

CHE

SYR

ESP

LKA

SDN

SUR

SJM

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames TIMOR-LESTE

TOGO

TOKELAU

TONGA

TRINIDAD AND TOBAGO

TUNISIA

TURKEY

TURKMENISTAN

TURKS AND CAICOS ISLANDS

TUVALU

TLS

TGO

TKL

TON

TTO

TUN

TUR

TKM

TCA

TUV

TomTom

GeoNames

TomTom

GeoNames

Vintage

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Country Name

UGANDA

UKRAINE

UNITED ARAB EMIRATES

UNITED KINGDOM

UNITED STATES

UNITED STATES MINOR

OUTLYING ISLANDS

URUGUAY

UZBEKISTAN

VANUATU

URY

UZB

VUT

VATICAN CITY STATE (HOLY SEE) VAT

VENEZUELA VEN

VIET NAM

VIRGIN ISLANDS (BRITISH)

VIRGIN ISLANDS (U.S.)

WALLIS AND FUTUNA ISLANDS

WESTERN SAHARA

YEMEN

ZAMBIA

ZIMBABWE

VNM

VGB

VIR

WLF

ESH

YEM

ZMB

ZWE

ISO 3166

Country Code

Data Source

UGA

UKR

TomTom

ARE

GBR

USA

UMI

TomTom

GeoNames

TomTom

GeoNames

TomTom

GeoNames

Country Postal Data Coverage

Table 63: Country Names and Postal Data Coverage

Country Name

ALGERIA

AMERICAN SAMOA

ANDORRA

ARGENTINA

ARMENIA

AUSTRALIA

AUSTRIA

AZERBAIJAN

Vintage

ARM

AUS

AUT

AZE

ISO 3166

Country Code

DZA

Data Source

Pitney Bowes

ASM

AND

ARG

GeoNames

TomTom

GeoNames

Pitney Bowes

GeoNames

TomTom

Pitney Bowes

Vintage

C. 2006

2011.07

2011.06

2011.07

C. 2006

2011.07

2011.06

C. 2006

2011.06

2011.07

2011.06

2011.07

2011.06

2011.07

API Guide 235

Enterprise Geocoding Module

236

Country Name

BAHRAIN

BANGLADESH

BELARUS

BELGIUM

BERMUDA

BOSNIA AND HERZEGOWINA

BRAZIL

BRITISH INDIAN OCEAN

TERRITORY

BRUNEI DARUSSALAM

BULGARIA

CAMBODIA

CANADA

CAPE VERDE

CHILE

CHINA

CHRISTMAS ISLAND

COCOS (KEELING) ISLANDS

COSTA RICA

CROATIA (LOCAL NAME:

HRVATSKA)

CUBA

CYPRUS

CZECH REPUBLIC

DENMARK

DOMINICAN REPUBLIC

ECUADOR

EGYPT

EL SALVADOR

ESTONIA

ETHIOPIA

EST

ETH

FALKLAND ISLANDS (MALVINAS) FLK

FAROE ISLANDS FRO

CUB

CYP

CZE

DNK

DOM

ECU

EGY

SLV

CPV

CHL

CHN

CXR

CCK

BRN

BGR

KHM

CAN

CRI

HRV

BLR

BEL

BMU

BIH

BRA

IOT

ISO 3166

Country Code

Data Source

BHR

BGD

Pitney Bowes

GeoNames

Pitney Bowes

TomTom

Pitney Bowes

TomTom

Pitney Bowes

GeoNames

Pitney Bowes

TomTom

Pitney Bowes

GeoNames

Pitney Bowes

TomTom

GeoNames

Pitney Bowes

TomTom

Pitney Bowes

GeoNames

Vintage

C. 2006

2011.07

C. 2006

2011.06

C. 2006

2011.09

C. 2006

2011.07

C. 2006

2011.09

C. 2006

2011.07

C. 2006

2011.06

2011.07

C. 2006

2011.06

C. 2006

2011.07

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Country Name

FINLAND

FRANCE

FRENCH GUIANA

FRENCH POLYNESIA

GEORGIA

GERMANY

GREECE

GREENLAND

GUADELOUPE

GUAM

GUATEMALA

GUERNSEY

GUINEA

GUINEA-BISSAU

HAITI

HONDURAS

HUNGARY

ICELAND

INDIA

INDONESIA

IRAN (ISLAMIC REPUBLIC OF)

IRAQ

IRELAND

ISLE OF MAN

ISRAEL

ITALY

JAMAICA

JAPAN

JERSEY

JORDAN

KAZAKHSTAN

KENYA

JPN

JEY

JOR

KAZ

KEN

IRL

IMN

ISR

ITA

JAM

ISL

IND

IDN

IRN

IRQ

GIN

GNB

HTI

HND

HUN

GRL

GLP

GUM

GTM

GGY

GUF

PYF

GEO

DEU

GRC

ISO 3166

Country Code

Data Source

FIN

FRA

TomTom

GeoNames

Pitney Bowes

TomTom

GeoNames

Pitney Bowes

GeoNames

Pitney Bowes

TomTom

Pitney Bowes

GeoNames

Pitney Bowes

GeoNames

TomTom

Pitney Bowes

Vintage

2011.07

2011.06

C. 2006

2011.07

C. 2006

2011.06

C. 2006

2011.07

C. 2006

2011.07

C. 2006

2011.07

2011.06

2011.07

C. 2006

2011.06

API Guide 237

Enterprise Geocoding Module

Country Name

KOREA, REPUBLIC OF

KUWAIT

KYRGYZSTAN

LAO PEOPLE'S DEMOCRATIC

REPUBLIC

LATVIA

LEBANON

LESOTHO

LIBERIA

LIECHTENSTEIN

LITHUANIA

LUXEMBOURG

MACEDONIA, THE FORMER

YUGOSLAV REPUBLIC OF

MADAGASCAR

MALAYSIA

MALDIVES

MALTA

MARSHALL ISLANDS

MARTINIQUE

MAYOTTE

MEXICO

MICRONESIA, FEDERATED

STATES OF

MOLDOVA, REPUBLIC OF

MONACO

MONGOLIA

MOROCCO

MOZAMBIQUE

MYANMAR

NEPAL

NETHERLANDS

NEW CALEDONIA

LVA

LBN

LSO

LBR

LIE

LTU

LUX

MKD

MTQ

MYT

MEX

FSM

MDG

MYS

MDV

MLT

MHL

MDA

MCO

MNG

MAR

MOZ

MMR

NPL

NLD

NCL

ISO 3166

Country Code

Data Source

KOR

KWT

KGZ

LAO

Pitney Bowes

Vintage

C. 2006

TomTom

Pitney Bowes

GeoNames

TomTom

GeoNames

Pitney Bowes

GeoNames

Pitney Bowes

GeoNames

TomTom

Pitney Bowes

GeoNames

Pitney Bowes

TomTom

Pitney Bowes

TomTom

Pitney Bowes

2011.07

C. 2006

2011.06

C. 2006

2011.06

C. 2006

2011.07

C. 2006

2011.07

2011.06

C. 2006

2011.06

C. 2006

2011.07

2011.06

2011.07

238 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Country Name

NEW ZEALAND

NICARAGUA

NIGER

NIGERIA

NORFOLK ISLAND

NORTHERN MARIANA ISLANDS

NORWAY

ISO 3166

Country Code

Data Source

NZL

NIC

OMAN

PAKISTAN

PALAU

PAPUA NEW GUINEA

PARAGUAY

PHILIPPINES

PITCAIRN

POLAND

PORTUGAL

PUERTO RICO

REUNION

ROMANIA

REU

ROU

RUSSIAN FEDERATION RUS

SAINT HELENA, ASCENSION AND

TRISTAN DA CUNHA

SHN

PHL

PCN

POL

PRT

PRI

OMN

PAK

PLW

PNG

PRY

NER

NGA

NFK

MNP

NOR

GeoNames

Pitney Bowes

GeoNames

TomTom

Pitney Bowes

GeoNames

Pitney Bowes

GeoNames

Pitney Bowes

TomTom

GeoNames

Pitney Bowes

TomTom

Pitney Bowes

SAINT PIERRE AND MIQUELON

SAN MARINO

SAUDI ARABIA

SENEGAL

SINGAPORE

SLOVAKIA (SLOVAK REPUBLIC)

SLOVENIA

SOUTH AFRICA

SOUTH GEORGIA AND THE

SOUTH SANDWICH ISLANDS

SPAIN

SPM

SMR

SEN

SGP

SVK

SVN

ZAF

SGS

ESP

GeoNames

TomTom

Pitney Bowes

TomTom

GeoNames

Pitney Bowes

TomTom

Vintage

C. 2006

2011.07

C. 2006

2011.07

C. 2006

2011.06

2011.07

C. 2006

2011.07

2011.06

2011.07

C. 2006

2011.06

C. 2006

2011.07

2011.06

C. 2006

2011.06

2011.07

C. 2006

2011.06

API Guide 239

Enterprise Geocoding Module

Country Name

SRI LANKA

SUDAN

SWAZILAND

SWEDEN

SWITZERLAND

TAIWAN

TAJIKISTAN

ISO 3166

Country Code

Data Source

LKA

SDN

THAILAND

TIMOR-LESTE

TUNISIA

TURKEY

TURKMENISTAN

TURKS AND CAICOS ISLANDS

UKRAINE

UNITED ARAB EMIRATES

UNITED KINGDOM

UNITED STATES

URUGUAY

UZBEKISTAN

URY

UZB

VATICAN CITY STATE (HOLY SEE) VAT

VENEZUELA VEN

TCA

UKR

ARE

GBR

USA

THA

TLS

TUN

TUR

TKM

SWZ

SWE

CHE

TWN

TJK

GeoNames

Pitney Bowes

GeoNames

TomTom

Pitney Bowes

TomTom

Pitney Bowes

TomTom

Pitney Bowes

TomTom

Pitney Bowes

TomTom

Pitney Bowes

Pitney Bowes VIET NAM

VIRGIN ISLANDS (U.S.)

WALLIS AND FUTUNA ISLANDS

WESTERN SAHARA

ZAMBIA

VNM

VIR

WLF

ESH

ZMB

GeoNames

Pitney Bowes

Vintage

2011.06

C. 2006

2011.06

C. 2006

2011.06

2011.07

C. 2006

2011.07

2011.06

C. 2006

2011.06

C. 2006

2011.07

C. 2006

Spectrum Geocoding Scenarios

You can use Enterprise Manager to create dataflows that are appropriate for your business requirements and for the nature and quality of your data.

Multiple Country Stage with Geocode Address World as Last Geocoding Pass

You may be able to optimize your results by geocoding your input in several passes.

In general, you can use more strict matching criteria in the first pass. In subsequent

240 Spectrum

™

Technology Platform 9.0

API Guide

Chapter 8: Module Services

geocoding passes, you can apply less restrictive matching criteria to any addresses that previously failed to return a close match candidate. This strategy can produce accurate matches for your high-quality addresses and still give you the best possible matches for less accurate addresses, or for addresses in countries that do not have a comprehensive level of coverage.

Let's assume the following scenario:

• Your input file includes addresses for six countries: Argentina (ARG), Brazil (BRA),

Mexico (MEX), Chile (CHL), Venezuela (VEN), and Panama (PAN).

• You have geocoders for three of these countries (ARG, BRA, and MEX) are deployed in a multiple country stage.

• Geocode Address World is deployed in a separate stage to geocode addresses that could not be identified by the country-specific geocoders.

• Your stage uses conditional routers (and optionally stream combiner) to manage the geocoding flow.

1. Read input into the multiple-country stage. Geocoded addresses can be written out to a file or optionally sent to the stream combiner.

2. Some Addresses that could not be geocoded in step 1. This may be because they were addresses from CHL, VEN, or PAN, and you do not have geocoders for these countries in the first stage. Or they may have failed to return a close match candidate in the first stage because of input errors or ambiguities in the addresses.

These ungeocoded addresses are sent to the Geocode Address World stage.

3. Addresses can be geocoded to postal or geographic accuracy by Geocode Address

World. Successfully geocoded addresses can be written out to a file or optionally sent to the stream combiner.

Postal geocoded candidates will have a Z1 result code. Postal geocoded results may be very accurate in countries with robust postcode systems. See

Postal

Geocoding

on page 223. Geographic candidates will have a G result code (for example G3 for a town/city match). See

Geographic Geocoding

on page 224.

4. The stream combiner (if used in your dataflow) can combine all geocoded addresses and write them to a file or direct them for further processing.

This is one scenario. You could use Enterprise Manager to design more complex dataflows that are suitable for your needs.

Using Geocode Address World as First Geocoding Pass

You could also use a strategy with Geocode Address World as the first geocoding pass.

Assume the following:

• Your addresses do not typically specify a country (although some may).

• Some addresses contain only street and city address information.

• You have country-specific geocoders for some countries, but not all.

• You use a main dataflow with subflows to manage the geocoding process.

Use a dataflow (possibly with subflows) that perform the following actions. Note that these steps illustrate a simplified view of a sample dataflow.

1. Read input into the mulitple-country stage that also includes Geocode Address

World. Based on city name (and possibly state name for USA addresses), each address can produce one or more potential close match candidates for several different countries. Each candidate will now be associated with a country, even though the input address may not have included a country.

241

Enterprise Geocoding Module

2. If a country-specific geocoder is available, the candidate is sent to that geocoder.

This processing involves conditional routing, stream combiners, and other Spectrum control stages. Depending on the completeness of the input address and capabilities of the country-specific geocoder, candidates may be geocoded to a street (S result code), geographic (G result code), or postal (Z result code) level.

3. If no country-specific geocoder is available, the candidate is routed to Geocode

Address World, where candidates can be geocoded to a geographic or postal level.

4. Candidates from all subflows are combined and ranked using a number of criteria.

Ranking could be based on population of the city (city rank), accuracy of the match

(street, geographic, postal), proximity to a user's locality, or other criteria.

242

Input

GeocodeAddressWorld takes an address as input. To obtain the best performance and the most possible matches, your input address lists should be as complete as possible, free of misspellings and incomplete addresses, and as close to postal authority standards as possible. Most postal authorities have websites that contain information about address standards for their particular country.

Note:

The country name or two- or three- character country ISO code is optional. If you omit the country,

GeocodeAddressWorld returns the best available candidates based on the other input provided.

Input Fields

The following table provides information on the format and layout of GeocodeAddressWorld input.

Note:

Specify input using the DataTable class. For information on the DataTable class, see the "API

Fundamentals" section.

Table 64: GeocodeAddressWorld Input Data columnName

AddressLine1

AddressLine2

City

County

Format Description

String

The first address line. For example, 4360 DUKES RD:

4360 DUKES RD KALGOORLIE WA 6430

The second address line of a two-line address. For example,

Level 6 51 Jacobson St:

26 WELLINGTON ST E SUITE 500 TORONTO ON M5E 1S2

This field is not used in Australia, Austria, Belgium, Brazil,

Denmark, Finland, France, Germany, Ireland, Italy,

Liechtenstein, Luxembourg, Malaysia, The Netherlands,

Poland, Portugal, Spain, Sweden, Switzerland, and Thailand.

The city or town name. Your input address should use the official city name. This will produce the best geocoding results.

For Thailand, this field contains the subdistrict (tambon).

The name of one of the following depending on the country:

• Not used—AUT, BRA, CAN, FIN, GBR, MYS, PRT, SGP.

• Department—FRA

• District (amphoe)—THA

• District (fylke/counties)—NOR

• District (poviat)—POL

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

FirmName

LastLine

Locality

PostalCode

StateProvince

Country

Format Description

String

• Kommun—SWE

• Kreis—DEU

• Local Government Authority (LGA)—AUS

• Province—BEL, CHE, DNK, ESP, IRL, ITA, LIE, LUX, NLD

• Region—NZL

Company or name or place name. For example, PITNEY

BOWES.

PITNEY BOWES 4360 DUKES RD KALGOORLIE WA 6430

The last line of the address. For example, KALGOORLIE WA

6430:

4360 DUKES RD KALGOORLIE WA 6430

The name of one of the following depending on the country:

• Not used—AUS, AUT, BEL, CHE, DEU, DNK, FIN, FRA,

IRL, LIE, LUX, MYS, NLD, NOR, POL, SGP, SWE, THA

• Dissemination Area and Enumeration Area (DA and

EA)—CAN

• Locality—BRA, GBR, ITA, PRT

• Suburb—NZL

The postal code in the appropriate format for the country.

The name of one of the following depending on the country:

• Not used—BEL, CHE, DNK, IRL, LIE, LUX, NLD, NOR,

SGP

• Bundesland—DEU

• Province—CAN

• Province (changwat)—THA

• Province (voivodship)—POL

• Region—AUT, ESP, FRA, GBR, NZL, PRT

• Region (län)—FIN

• Region (lan)—SWE

• State—AUS, BRA

• State (negeri)—MYS

The two- or three-character ISO country code. This field is optional. If you omit the country, GeocodeAddressWorld returns the best available candidates based on the other input provided

For a list of ISO codes, see

Country ISO Codes and Module

Support

Address Aliases

Some countries have alternative administrative names. For example, there may be an official name for a city or town, but there may also be common but unofficial alternative name for the same city or town.

If alias information is available in the source data, Geocode Address World includes this alias in the database. This enables Geocode Address World to geocode successfully when alternative names are used in input addresses.

API Guide 243

Enterprise Geocoding Module

Language Aliases

on page 244 are also supported.

Language Aliases

Some countries have more than one official or prominent language. For example, the same town may be commonly known by both German and Italian names. If language alias information is available in the source data, Geocode Address World uses this in the database. This enables Geocode Address World to geocode successfully when alternative language names are used in input addresses.

Aliases can exist for all administrative levels, from StateProvince state/province to Locality locality. See

Administrative Divisions and Postal Codes

on page 244 for a description of administrative levels associated with the geographic data.

Address Aliases

on page 243 are also supported for commonly used, alternative administrative areas.

State or Province Abbreviations

In some countries, the state or province is an important part of the address and often this address component is abbreviated. For selected countries, these state/province abbreviations are recognized by Geocode Address World. For example, in the United States each state has a two-letter abbreviation

(such as CA for California). Similarly, Netherlands, state abbreviations (such as GLD for Gelderland) are recognized.

Geocode Address World accepts state/province abbreviations for the following countries:

Table 65: Country State/Province Abbreviation Support

Country Name

Australia (AUS)

Canada (CAN)

Italy (ITA)

Mexico (MEX)

Netherlands (NLD

United States (USA)

State Or Province

Division

Example

StateProvince (State) NSW (abbreviation for New South Wales

StateProvince (Province) AB (abbreviation for Alberta)

County (Province)

StateProvince (State)

MO (abbreviation for Modena)

JA (abbreviation for Jalisco)

County (State)

StateProvince (State)

FR (abbreviation for Friesland)

CA (abbreviation for California)

Geocode Address World evaluates these state or province abbreviations to better identify close matches.

See

Geographic Geocoding with State/Province Abbreviation

on page 225 for an example that illustrates this feature.

Administrative Divisions and Postal Codes

Typical input addresses consist of street address, administrative division, and postal code information.

Geocode Address World uses the administrative divisions and postal codes for geographic or postal geocoding.

• StateProvince (state or province)

• County (county, region, or district)

• City (town or city)

• Locality (locality suburb, or village)

• postal code

Specific administrative divisions vary by country. For example, Locality may contain locality, suburb, or barrio, depending on the country. StateProvince may contain state, province, region, or some other name depending on the country. See

State or Province Abbreviations

on page 244 for more information on how state/province abbreviations are interpreted by Geocode Address World.

Not all administrative divisions are used in addressing conventions for all countries. For example, in the

USA, County (county) is not typically used in addresses. But for some countries, County is an important part of the address.

If your input data includes postal codes, Geocode Address Worldcan use this for postal geocoding, assuming that the source data includes postal data for the specific country.

244 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Input Recommendations

You can optimize Geocode Address World results if you prepare and understand your input records.

Follow these guidelines :

• Ensure that your input addresses are as complete and accurate as possible. If there are errors in your input addresses, Geocode Address World may still be able to geocode those addresses, but there may be more than one possible match or you may get non-close matches. If you can verify and correct any incomplete or inaccurate input addresses, you can get better results.

• Include postcodes in your input addresses if you have them. This is not required, but it allows Geocode

Address World to perform postal geocoding. This may give you more accurate results for some addresses, depending on the country and on the completeness and accuracy of other address components.

• Include the country name or official three-character or two-character country ISO code in your input addresses. This is not required, but it may help Geocode Address World distinguish between similar addresses and city names that may occur in different countries.

• Format your input addresses consistently. Geocode Address World can handle input addresses in a wide variety of input formats, or can handle unformatted (single line) input. But you can get more accurate and faster results if your input addresses are consistently formatted and conform to country-specific address conventions. Even if your input address are single line (unformatted), you may get better results and performance if the address components are ordered consistently. Use the

AddressLine1 input area for unformatted addresses. See

Single Line Input

on page 245

Single Line Input

Address input can be formatted into separate input fields or input can as single line input. Use

AddressLine1 to enter single line input.

Single Line Geographic Geocoding

In this example, unformatted (single line) input is used. Geocode Address World analyzes single line input to identify the geographic address components (Graz in this example), and then geocodes to a geographic centroid. The MainAddress (street information) is not used.

Sackstraße 10 Graz

Geocode Address World returns a geographic close match candidate based on an

City match. Even though the country was not specified, there is a close match in Austria

(AUT).

StateProvince: Steirmark

County: Graz (Stadt)

City: Graz

Country: AUT

Result Code: G3

X: 15.44172

Y: 47.06792

If your input addresses are accurate, unformatted input can produce a match rate comparable to that of formatted input. However, geocoding unformatted addresses typically has slower performance than geocoding formatted addresses.

Single Line Postal Geocoding with Country Specified

In this example, single line input is used and a postcode is provided. The country

Austria (AUT) is also specified. The street address is also input, but this is ignored by

Austria.

Alpenstraße 117 5020 AUT

API Guide 245

Enterprise Geocoding Module

Austria returns a postal centroid close match candidate (Z1 result code). Because the country (AUT) is specified in the input, the country must be matched and a single close match for that postal code in Austria is returned. Non-close matches with the 5020 postal code from other countries are also returned.

StateProvince: Salzburg

Country: AUT

Postcode: 5020

Result Code: Z1

X: 13.04685

Y: 47.80262

Options

Geocoding Options

The following table lists the options that control how a location's coordinates are determined.

Table 66: Geocoding Options optionName

CoordinateSystem

Description

A coordinate system is a reference system for the unique location of a point in space. Cartesian (planar) and Geodetic (geographical) coordinates are examples of reference systems based on Euclidean geometry. Spectrum

™

Technology Platform supports systems recognized by the European Petroleum Survey Group (EPSG).

One the following:

EPSG:4283

EPSG:4326

Also known as the GDA94 coordinate system.

Also known as the WGS84 coordinate system.

Default.

246

Matching Options

Table 67: Matching Options optionName

KeepMultimatch

MaxCandidates

Description

Specifies whether to return results when the address matches to multiple candidates in the database. If this option is not selected, an address that results in multiple candidates will fail to geocode.

If you select this option, specify the maximum number of candidates to return using the MaxCandidates option (see below).

Yes, return candidates when multiple candidates are found.

Default.

No, do not return candidates. Addresses that result in multiple candidates will fail to geocode.

If you specify KeepMultimatch=Y, this option specifies the maximum number of results to return.

Spectrum

™

Technology Platform 9.0

optionName

CloseMatchesOnly

Chapter 8: Module Services

Description

The default is 1.

Specifies whether to return only those geocoded results that are close match candidates. For example, if there are 10 candidates and two of them are close candidates, and you enable this option, only the two close matching candidates would be returned instead of all 10.

Yes, return only close matches.

No, do not return only close matches. Default.

Data Options

The Data tab allows you to specify which databases to use in geocoding. Databases contain the address and geocode data necessary to determine the geocode for a given address. The data is based on address and geocoding data from postal authorities and suppliers of geographical data.

Table 68: Data Options optionName

DatabaseSearchOrder

Description

The name of one or more database resources to use in the search process. Use the database name specified in the Management Console's

Database Resources tool. For more information, see the Spectrum

™

Technology Platform Administration Guide.

You can specify multiple database resources. If you specify more than one database, list them in order of preference. The order of the database has an effect when there are close match candidates from different databases. The close matches that are returned come from the database that is first in the search list. Close matches from lower ranked databases are demoted to non-close matches.

Output

GeocodeAddressWorld returns the latitude/longitude, city, county, and result indicators. Result indicators describe how well the geocoder matched the input to a known location and assigned a latitude/longitude; they also describe the overall status of a match attempt. The output returned is in the DataTable class.

For information on the DataTable class, see the "API Fundamentals" section.

Address Output

Table 69: Address Output columnName

City

CityRank

Country

API Guide

Description

Municipality name.

CityRank is a numeric value ranging from 1 (high) to 10 (low) based on total and relative population, importance, and other criteria.

The three-letter ISO 3166-1 Alpha 3 country code. The two-letter code can also be used. See

Country Geographic Data Coverage

on page

247

Enterprise Geocoding Module columnName

248

County

PostalCode

StateProvince

Description

227 for a list of countries and data sources for geographic geocoding.

See

Country Postal Data Coverage

on page 235 for a list of postal geocoding countries and data sources.

This field contains an area that is smaller than a state/province but larger than a city. The specific area varies by country:

• AUS—Local Government Authority (LGA)

• AUT—Province

• BEL—Province

• BHS—Not used

• BRA—Not used

• CAN—Not used

• CHE—Province

• DEU—Kreis

• DNK—Province

• FIN—Province (kommune)

• FRA—Department

• GBR—County

• ITA—Province

• LIE—Province

• LUX—Province

• MYS—District (daerah)

• NLD—Province

• NZL—Not used

• POL—District (poviat)

• PRT—Not used

• SGP—District

• SWE—Region (kommun)

• THA—District (amphoe)

The postcode for the address. The format of the postcode varies by country.

The meaning of StateProvince varies by country:

• AUS—State

• AUT—Region

• BEL—Not used

• BRA—State

• CAN—Province

• CHE—State

• DEU—Bundesland

• DNK—Not used

• ESP—Region

• FIN—Region (län)

• FRA—Region

• GBR—Region

• IRL—Not used

• ITA—Region

• LIE—State

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Description

• LUX—Not used

• MYS—State (negeri)

• NLD—Not used

• NOR—Not used

• NZL—Region

• POL—Province (voivodship)

• PRT—Region

• SGP—Not used

• SWE—Region (lan)

• THA—Province (changwat)

Geocode Output

Table 70: Geocode Output columnName

CoordinateSystem

Latitude

Longitude

Description

The coordinate system used to determine the latitude and longitude coordinates. A coordinate system specifies a map projection, coordinate units, etc. An example is EPSG:4326. EPSG stands for European

Petroleum Survey Group.

Seven-digit number in degrees and calculated to four decimal places

(in the format specified).

Seven-digit number in degrees and calculated to four decimal places

(in the format specified).

Result Codes

Result codes contain information about the success or failure of the geocoding attempt, as well as information about the accuracy of the geocode.

Table 71: Result Code Output columnName

Geocoder.MatchCode

IsCloseMatch

MultiMatchCount

API Guide

Description

Indicates how closely the input address matches the candidate address.

Indicates whether or not the address is considered a close match. An address is considered close based on the "Close match criteria" options on the Matching tab.

Yes, the address is a close match.

No, the address is not a close match.

For street address geocoding, the number of matching address positions found for the specified address.

For intersection geocoding, the number of matching street intersection positions found for the specified addresses.

249

Enterprise Geocoding Module columnName

Status

Status.Code

Status.Description

LocationPrecision

Description

Reports the success or failure of the match attempt

null

Success

Failure

If the geocoder could not process the address, this field will show the reason.

• Internal System Error

• No Geocode Found

• Insufficient Input Data

• Multiple Matches Found

• Exception occurred

• Unable to initialize Geocoder

• No Match Found

If the geocoder could not process the address, this field will show a description of the failure.

Problem + explanation

Returned when Status.Code = Internal

System Error.

Geocoding Failed

No location returned

Returned when Status.code = No

Geocode Found.

Returned when Status.code = No

Geocode Found.

No Candidates Returned

The geocoder could not identify any candidate matches for the address.

Multiple Candidates

Returned and Keep

Multiple Matches not selected

The address resulted in multiple candidates. In order for the candidate address to be returned, you must specify

KeepMultimatch=Y

A code describing the precision of the geocode. One of the following:

No coordinate information is available for this candidate address.

Interpolated street address.

Street segment midpoint.

Postal code 1 centroid.

Partial postal code 2 centroid.

Postal code 2 centroid.

Intersection.

Point of interest.

State/province centroid.

County centroid.

City centroid.

Locality centroid.

250 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

StreetDataType

Description

12 - 15

(LocationPrecision codes)

For most countries, LocationPrecision codes 12 through 15 are reserved for unspecified custom items.

Additional point precision for unspecified custom item.

The result is an Address Point.

The result was generated by using address point data to modify the candidates segment data.

The default search order rank of the database used to geocode the address. A value of "1" indicates that the database is first in the default search order, "2" indicates that the database is second in the default search order, and so on.

The default database search order is specified in the Management

Console with the Database Resources tool.

Geographic Candidate Ranking

Identical geographic area names can be found in many countries. When this occurs, Geocode Address

World uses a ranking system to determine which of potential candidates is the most likely close match.

The specific details of this weighted ranking depend somewhat on the data source (TomTom, GeoNames, or Pitney Bowes source), but the following criteria are weighted to determine the most likely close match candidate.

• country capital

• administrative area (state/province, regional, county) capital

• population range

Country capital status outweighs any other geographic ranking criteria. For example, San Juan entered as City returns San Juan, Puerto Rico (PRI) as the close match because it is the capital of PRI. Other

San Juan cities in the world (including Spain, Costa Rica, Dominican Republic and Philippines) can be returned as non-close matches regardless of their population. To return matches, you must check the

Keep multiple matches check box in Matching Options of the Management Console, and specify the number of matches you want to return.

Similarly, Geocode Address World returns Roma, ITA as a close match since that is the capital of Italy, but Roma in Romania, Honduras, and Panama are returned as non-close matches.

State/province administrative capitals are highly weighted even if their populations are not very large.

For example, Springfield returns a close geographic match to Springfield, Illinois USA because this is the state capital of Illinois. Springfield, Massachusetts has a somewhat larger population, but this is outweighed by the state capital status of Springfield Illinois. Other less populous Springfield communities in the USA and other countries are also returned as close matches, but are listed below the Springfield

Illinois candidate. It is possible for a large city to rate as an equal close match along with a smaller, identically named state/province capital. However, the state/province capital will not be demoted, even if it has a relatively small population.

Similarly, if your input is Albany in City with no country specified, Geocode Address World returns Albany,

NY, USA as the close match candidate. This is because Albany is the capital of New York State, and therefore gets a high ranking as administrative area capital. The population is also a contributing ranking factor. If you specify the city of Albany with a different country, such as New Zealand, then the country is used and Albany, NZL is returned as the close match candidate.

API Guide 251

Enterprise Geocoding Module

If a candidate includes a city, a CityRank value is also returned, if available. CityRank is a numeric value ranging from 1 (high) to 10 (low) that indicates the relative ranking of the city. This ranking is based on relative population, administrative status, and other criteria. If multiple geographic candidates are returned, they are listed in city rank order.

Match Codes

Matches in the G category indicate that the candidate is located at the geographic centroid with the following possible accuracy levels. Not all levels of accuracy are possible for all countries.

• G0—Country centroid. This is not returned for GeocodeAddressWorld.

• G1—State or province centroid. For Japan, this indicates a prefecture (ken) match.

• G2—County centroid. For Japan, this indicates a city (shi) match.

• G3—City centroid. For Japan, this indicates a municipality subdivisio (oaza) match. For Australia,

Local Government Authority (LGA) information can be returned from the Street Range Address

Database only (not the G-NAF database).

• G4—Locality centroid. For Japan, this indicates a city district (chome) match.

Matches in the Z category indicate that no street match was made for one of the following reasons:

• You specified to match to postal code centroids. The resulting point is located at the postal code centroid with four possible accuracy levels.

• There is no close match and you specified to fall back to postal code centroid

The Z category contains the following accuracy levels:

• Z0—Postal Code match, no coordinates available (rare occurrence).

• Z1—Postal Code centroid match.

• Z3—Full postal code centroid match. For Canada, this is an FSALDU centroid.

• Z6—Postal Code centroid match for point ZIP.

GeocodeUSAddress

GeocodeUSAddress takes an address and returns latitude/longitude coordinates. GeocodeUSAddress also standardizes and validates addresses using data from the U.S. Postal Service.

GeocodeUSAddress can also geocode intersections. Instead of entering a mailing address, you can enter and intersection such as "Pearl St. and 28th" and obtain the coordinates of the intersection.

GeocodeUSAddress is part of the Enterprise Geocoding Module. For more information on the Enterprise

Geocoding Module, including a listing of other components included with it, see

What is the Enterprise

Geocoding Module?

on page 214.

Input

GeocodeUSAddress takes an address as input. To obtain the best performance with GeocodeUSAddress and the most possible matches, your input address should be as complete as possible and free of misspellings and incomplete information. Input addresses should be as close to USPS standards as possible for the highest match rate. For information on USPS standards, see the USPS website

http://www.usps.com

Input addresses should contain a street address line and a lastline, or a single line with both address and lastline elements. This helps GeocodeUSAddress accurately identify an area in which to search for a match candidate, based on the city, state, and ZIP Code.

GeocodeUSAddress also accepts a street address line with individual city, state, and ZIP Code lines instead of a last line. You should only use this type of input if you are confident that the input address is free of misspellings and incomplete information.

If you are using GeocodeUSAddress for address standardization, input addresses must have at least a street name, and either a city and state or a ZIP Code to obtain a match. If you are using

252 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

GeocodeUSAddress to obtain geocoding information, input addresses only need to contain a ZIP + 4

Code to receive geocoding information.

The following table provides information on the format and layout of GeocodeUSAddress input.

Note:

Specify input using the DataTable class. For information on the DataTable class, see the "API

Fundamentals" section.

Table 72: GeocodeUSAddress Input Data columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

AddressLine5

AddressLine6

City

FirmName

LastLine

PostalCode

StateProvince

API Guide

Format Description

String

The first address line or a street intersection.

To specify a street intersection, use and, &, at, or @. For example, PEARL & 28th. GeocodeUSAddress does not match intersections when processing in CASS mode.

You may enter an address range instead of an individual address number. For example, 10-12 FRONT ST. For additional information, see

Address Range Matching

on page 255.

The second address line or a street intersection.

To specify a street intersection, use and, &, at, or @. For example, PEARL & 28th.L GeocodeUSAddress does not match intersections when processing in CASS mode.

Third address line.

Fourth address line.

Fifth address line.

Sixth address line.

The name of the municipality, such as a city or town.

Note:

If there is any data in the input fields AddressLine3,

AddressLine4, AddressLine5, or AddressLine6,

GeocodeUSAddress will ignore data in the City input field.

String

The name of a business. GeocodeUSAddress attempts to match the input firm name to the recognized firm names in the USPS data for a higher quality match. If the firm name is not in the USPS data, GeocodeUSAddress ignores the firm name when matching and returns the firm name with the output.

The last line of an address containing the city, state, and ZIP

Code.

The 5-digit ZIP Code or the 9-digit ZIP + 4 code.

Note:

If there is any data in the input fields AddressLine3,

AddressLine4, AddressLine5, or AddressLine6,

GeocodeUSAddress will ignore data in the

PostalCode input field.

String The name or abbreviation of the state.

253

Enterprise Geocoding Module columnName Format Description

Note:

If there is any data in the input fields AddressLine3,

AddressLine4, AddressLine5, or AddressLine6,

GeocodeUSAddress will ignore data in the

StateProvince input field.

254

How GeocodeUSAddress Processes Addresses

GeocodeUSAddress processes addresses in the following order:

1. Parses the address elements.

GeocodeUSAddress parses input address data into single elements. Parsing occurs on data in the order in which you load the data. Even if a valid address is missing an element, GeocodeUSAddress can find a match. Some elements, such as predirectionals, may not be critical elements of some addresses. By comparing an address as input against all known addresses in a search area,

GeocodeUSAddress can usually determine if any of these elements are missing or incorrect.

2. Finds possible matches within the search area.

GeocodeUSAddress uses the last line elements of an address to determine a search area. You can specify if you want the search area based on a finance area or on an area defined by the city, state, and ZIP Code. (A Finance Area is a collection of ZIP Codes within a contiguous geographic region.)

If the city and state are not in the ZIP Code, GeocodeUSAddress performs separate searches for the ZIP Code and city.

After GeocodeUSAddress has determined the search area, it tries to match the elements from the street address line to the records in the standardized data files and does the following:

• Checks input address ranges for missing or misplaced hyphens, and alpha-numeric ranges for proper sequence.

• Searches for any misspellings and standard abbreviations. For example, the GeocodeUSAddress can recognize Mane for Main and KC for Kansas City.

• Searches for any alias matches to the USPS and Spatial data (TIGER and TomTom). For example,

GeocodeUSAddress recognizes that in Boulder, CO Highway 36 is know as 28th Street.

• Searches for any USPS recognized firm names for additional match verification.

• Searches for street intersection matches. Matching to an intersection is extremely useful when you are using address matching to obtain a geocode.

• Searches for addresses lines that contain a house number and unit number as the same element.

For example, GeocodeUSAddress recognizes the input 4750-200 Walnut Street and performs recombination to output 4750 WALNUT ST STE 200.

Note:

The USPS does not consider intersections valid addresses for postal delivery. Therefore, the

GeocodeUSAddress does not match intersections when processing in CASS mode.

3. Scores each possible match against the parsed input.

GeocodeUSAddress compares each element in the input address to the corresponding element in the match candidates, and assigns a confidence level. GeocodeUSAddress weighs the confidence level for all of the elements within a match candidate, and assigns a final score to the sum.

Note:

GeocodeUSAddress uses a penalty scoring system. If an element does not exactly match an element in the match candidate, the GeocodeUSAddress adds a penalty to the score of the match candidate. Therefore, scores with lower numbers are better matches.

4. Determines the match.

GeocodeUSAddress prioritizes each match candidate based on the assigned confidence score and returns as a match the candidate that has the lowest score.

The match mode you choose determines the range that GeocodeUSAddress allows for a match.

GeocodeUSAddress only returns a match if the score of the target address falls within the range designated by the selected match mode.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

In some cases, more than one match candidate may have the lowest score. In this instance,

GeocodeUSAddress cannot determine on its own which record is correct, and returns a status indicating multiple matches.

Note:

If you have enabled Delivery Point Validation (DPV) processing, GeocodeUSAddress automatically attempts to resolve multiple matches using DPV.

Along with a standardized address, GeocodeUSAddress also returns the following:

• Geocode—Longitude and latitude for the address

• Match code—Information about the match of the input address to the reference data

• Location code—Precision level of a geocode

• Parity—The side of the street on which the match resides.

GeocodeUSAddress does not return parity when processing in relaxed mode. For more information on GeocodeUSAddress output, see

Output

on page 267.

Address Range Matching

Some business locations are identified by address ranges. For example, a shopping plaza could be addressed as 10-12 Front St. This is how business mail is typically addressed to such a business location.

These address ranges can be geocoded to the interpolated mid-point of the range.

Address ranges are different from hyphenated (dashed) addresses that occur in some metropolitan areas. For example, a hyphenated address in Queens County (New York City) could be 243-20 147

Ave. This represents a single residence (rather than an address range) and is geocoded as a single address. If a hyphenated address returns as an exact match, GeocodeUSAddress does not attempt to obtain an address range match.

Address range matching is not available in Exact or CASS modes, since an address range is not an actual, mailable USPS

® address. The following fields are not returned by address range geocoding:

• ZIP + 4

(in multiple segment cases)

• Delivery point

• Check digit

• Carrier route

• Record type

• Multi-unit

• Default flag

Address range matching works within the following guidelines:

• There must be two numbers separated by a hyphen.

• The first number must be lower than the second number.

• Both numbers must be of the same parity (odd or even) unless the address range itself has mixed odd and even addresses.

• Numbers can be on the same street segment or can be on two different segments. The segments do not have to be contiguous.

• If both numbers are on the same street segment, the geocoded point is interpolated to the approximate mid-point of the range.

• If the numbers are on two different segments, the geocoded point is based on the last valid house number of the first segment. The ZIP Code and FIPS Code are based on the first segment.

• In all cases, odd/even parity is evaluated to place the point on the correct side of the street.

API Guide 255

Enterprise Geocoding Module

Options

Geocoding Options

Table 73: GeocodeUSAddress Geocoding Options optionName

Dataset

Offset

Description

The name of the database resource that contains the data to use in the search process. Use the database name specified in the Management Console's

Database Resources tool. For more information, see the Spectrum

™

Technology Platform Administration Guide.

Specifies the offset distance from the street segments, in feet. The range is

0 to 5280. The default value is 50.

The offset distance is used in street-level geocoding to prevent the geocode from being in the middle of a street. It compensates for the fact that street-level geocoding returns a latitude and longitude point in the center of the street where the address is located. Since the building represented by an address is not on the street itself, you do not want the geocode for an address to be a point on the street. Instead, you want the geocode to represent the location of the building which sits next to the street. For example, an offset of 50 feet means that the geocode will represent a point 50 feet back from the center of the street. The distance is calculated perpendicular to the portion of the street segment for the address. Offset is also used to prevent addresses across the street from each other from being given the same point. The following diagram shows an offset point in relation to the original point.

256

Squeeze

Street coordinates are accurate to 10,000ths of a degree and interpolated points are accurate to the millionths of a degree.

Specifies the distance, in feet, to move the street segment end points toward the middle of the segment. Squeeze is used in street-level matching. Use the squeeze setting to prevent address points from residing in an intersection or too close to the end of a street.

The range is 0 to 2147483647. The default value is 50.

The following diagram compares the end points of a street to squeezed end points.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName Description

LatLonFormat

CentroidPreference

FallbackToStreet

Squeezing the street segment endpoints affects street-level matching by reducing the length of a street segment, thereby reducing the spacing between address points along the segment. For example, if the length of a street segment is 1,000 feet and there are 10 addresses along the segent, street-level matching would result in each address being spaced 100 feet apart (1,000 ÷ 10). If you were to set a squeeze value of 100 feet, moving each street segment endpoint 100 feet torward the center of the street segment, the length of the street segment would be reduced to 800 feet

(reduced by 100 feet on each end). Street-level matching would then result in addresses beging spaced 80 feet apart (800 ÷ 10).

Specifies the format of the latitude/longitude returned by GeocodeUSAddress.

Decimal

The latitude/longitude is returned in decimal format

(default). For example: 90.000000-180.000000

Integer

The latitude/longitude is returned in integer format. For example: 90000000-180000000

Determines the type of centroids returned by GeocodeUSAddress. A centroid is the center of an area. The centroid coordinates are the average of the sets of coordinates that describe the area.

NoCentroids

Do not return centroids. If an address-level geocode cannot be determined, do not attempt to determine a centroid.

AllCentroids

Return ZIP Code centroids only. If you select this option, address-level geocodes will not be returned.

AddressUnavailable

Return a ZIP Code centroid if an address-level geocode cannot be determined (default).

Specifies whether to attempt to return a street centroid when an address-level geocode cannot be determined. To determine a street centroid,

GeocodeUSAddress searches the input ZIP Code or city for the closest match. If GeocodeUSAddress is able to locate the street, it returns a geocode along the matched street segment.

For example, if the input address is 5000 Walnut Street, Boulder 80301, and there is no 5000 Walnut Street, GeocodeUSAddress searches for the closest match to that address within the ZIP Code 80301. If there were no input ZIP

Code, GeocodeUSAddress would search for the closest match to the input address within Boulder.

If the input address is Walnut Street, Boulder 80301, since there is no house number, GeocodeUSAddress searches for the street within the input ZIP

Code.

API Guide 257

Enterprise Geocoding Module optionName Description

Street centroid geocodes are indicated by value in the LocationCode output field that begins with "C". For more information, see

Street Centroid Location

Codes

on page 334.

Note:

This option is not available if you set MatchMode to CASS.

Yes, attempt to determine the street centroid when an address-level geocode cannot be determined.

No, do not attempt to determine the street centroid when an address-level geocode cannot be determined.

FallbackToGeographic Specifies whether to attempt to return a city, county, or state centroid when an address-level geocode cannot be determined. The geocoder returns the most precise geographic centroid that it can based on the input. For example, if the input contains a valid city and state, a city centroid would be returned.

Note:

There are approximately 300 major cities that can be geocoded to a city centroid level even if a valid state is not provided in the input.

Datum

CenterlineOffset

Geographic centroid geocodes are indicated by value in the LocationCode output field that begins with "G". For more information, see

Geographic

Centroid Location Codes

on page 339.

Note:

This option is not available if you set MatchMode to CASS.

Yes, attempt to determine the geographic centroid when an address-level geocode cannot be determined.

No, do not attempt to determine the geographic centroid when an address-level geocode cannot be determined.

Determines the North American Datum to use when geocoding datum on the input value. Datum is the mathematical model of the Earth used to calculate the coordinates on any map, chart, or survey system.

NAD27

This datum does not include the Alaskan Islands or Hawaii.

Latitudes and longitudes that are surveyed in the NAD27 system are valid only in reference to NAD27 and are not valid for maps outside the U.S.

NAD83

This datum is earth-centered and defined with satellite and terrestrial data. NAD83 is compatible with the World Geodetic

System 1984 (WGS84), which is the terrestrial reference frame associated with the NAVSTAR Global Positioning System (GPS) used extensively for navigation and surveying. This is the default setting.

The offset distance, in feet, used to calculate the street centerline coordinates.

The default is 0.

If you specify a value other than 0, GeocodeUSAddress calculates the street centerline coordinates by offsetting the centerline point by the distance you specify in the direction of the parcel centroid.

258 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName Description

RetrieveElevation

In an interpolated match, the centerline offset cannot be greater than the distance from the centerline to the interpolated address point. If you specify a centerline offset distance that is greater than this distance, the offset will be limited to the distance to the interpolated point. In effect, the centerline coordinates would be the same as the coordinates for the interpolated point.

Specifies whether GeocodeUSAddress returns the elevation of the address.

Elevation is the distance above or below sea level of a given location. The elevation is returned in the Elevation output field, which is part of the

Latitude/Longitude output group.

Note:

This option requires that you have licensed and installed the Centrus

Premium Points database. Elevation data is not available for all addresses. See the coverage map included with the points database.

AddressPointInterpolation Specifies whether to perform address point interpolation when an exact match for the address cannot be found in the geocoding database. Address point interpolation is a patented process that results in a more accurate interpolated point. It improves upon regular street segment interpolation by using point data in the interpolation process, as opposed to using street segments alone.

Note:

Address point interpolation is only available when using a point-level geocoding database. It is not available when using point addresses in an auxiliary file.

Yes, perform address point interpolation.

No, do not perform address point interpolation.

The following illustration shows how address point interpolation works. In the example, the input house number is 71. The geocoding database contains address points for 67 and 77. The street segment has a range of 11 to 501.

With address point interpolation, GeocodeUSAddress performs the interpolation for the input house number 71 using the points of 67 and 77.

Without address point interpolation, GeocodeUSAddress performs the interpolation with the street segment end points of 11 and 501, resulting in a far less accurate result.

API Guide 259

Enterprise Geocoding Module optionName Description

260

Matching Options

Table 74: GeocodeUSAddress Matching Options optionName

AddressPreference

FirmNameSearch

FirstLetterSearch

Description

Determines which address to use when more than one address is present in the address block.

PreferBottom

Uses the second line entered (default). You must select this value if you specify

MatchMode=CASS.

PreferPOBox

PreferStreetAddress

Uses the P.O Box.

Uses the street address.

Specifies whether GeocodeUSAddress should use firm name matching logic to enhance address matching. Firm matching logic matches a business name in the input to recognized business names. The input firm name does not need to be spelled correctly to obtain a match.

GeocodeUSAddress uses a soundex algorithm to match the firm name.

A suite or unit number is not required to make the match.

Note:

This type of match is not available when processing in CASS mode.

One of the following:

Never

Do not use firm matching (default). Note that

GeocodeUSAddress may correct the firm name even if you specify Never if it can find a match using the address line data.

OnAddressLineFail

Use firm matching only if a match cannot be determined using address matching.

Always

Always attempt to match using firm name matching. If firm name matching fails, attempt to match using address matching.

Specifies whether to look for the correct first letter of a street name if the first letter is missing or incorrect. If enabled, GeocodeUSAddress searches through the alphabet looking for the correct first letter to complete the street address.

Note:

This option is not available if the match mode is set to exact.

Spectrum

™

Technology Platform 9.0

optionName

BuildingSearch

RetrieveAPN

API Guide

Chapter 8: Module Services

Description

Perform first letter search.

Do not perform first letter search (default).

This example includes an incorrect first letter:

Input: 4750 nalnut boulder co 80301

Output: 4750 Walnut St Boulder CO 80301-2532

This example excludes a first letter:

Input: 4750 alnut boulder co 80301

Output: 4750 Walnut St Boulder CO 80301-2532

This example includes an extra first letter:

Input: 4750 wwalnut boulder co 80301

Output: 4750 Walnut St Boulder CO 80301-2532

Specifies whether GeocodeUSAddress attempts to obtain a street address when the input address contains a building name with no suite or unit number.

When this option is disabled, GeocodeUSAddress is able to match to building names only if there is a unit number in the input. For example, if the building search option were disabled and you entered this input:

5001 Chrysler Bldg

New York, NY 10174

GeocodeUSAddress would successfully return the street address:

405 Lexington Ave

RM 5001

New York, NY 10174-5002

With this option enabled, GeocodeUSAddress is also able to obtain a street address when only a building name with no unit number is provided. For example, if you enable this option and provide this address:

Chrysler Bldg

New York, NY 10174

You will get the street address:

405 Lexington Ave

New York, NY 10174-00

Note:

This type of match is not available when processing in CASS mode.

Use firm name matching logic (default).

Do not use firm name matching logic.

Specifies whether GeocodeUSAddress should determine the address's

APN (assessor's parcel number). The APN is an ID number assigned to a property by the local property tax authority. The APN is returned in the APN output field, which is part of the Census output group.

Note:

This option requires that you have licensed and installed the

Cenrus Enhanced Points or Centrus Premium Points database.

261

Enterprise Geocoding Module optionName

PerformDPV

PerformLACSLink

PreferZipCodeOverCity

Description

APN data is not available for all addresses. See the coverage map included with the points database.

Specifies whether GeocodeUSAddress should process addresses using

Delivery Point Validation (DPV). DPV is a United States Postal Service

(USPS) technology that validates the accuracy of address information down to the physical delivery point. You must have licensed the optional

DPV processing option to use this feature. You must also install the

DPV database.

To use DPV, enable this processing option and specify D in

OutputRecordType.

Perform DPV.

Do not perform DPV (default).

If you use DPV, GeocodeUSAddress automatically resolves multiple matches.

False-positive addresses, also known as seed records, are addresses the USPS monitors to ensure users are not attempting to create a mailing list from the DPV data. If GeocodeUSAddress matches an address in your input data to a false-positive address, you receive a message indicating you have encountered a false-positive address. Processing continues to the end of your job, but DPV processing is not available for this job and subsequent jobs until you have reported the false-positive address encounter to technical support and have received a new security key.

Specifies whether GeocodeUSAddress should process addresses using

LACS

Link

Perform LACS

Link

Do not perform LACS

Link

(default).

If you use LACS

Link

, be sure to choose to specify output record types

P and Q so that the fields USLACS, USLACS.ReturnCode, and

LACSADDRESS are included in the output.

For more information, see

Locatable Address Conversion System

(LACS)

on page 222.

Specifies whether to prefer candidates that match the input ZIP over candidates that match to input city.

Note:

This option is not available when processing in CASS mode.

Perfer candidates that match the input ZIP Code.

Prefer candidates that match the input city (default).

For example, consider this input address:

301 BRYANT ST

SAN FRANCISCO CA 94301

Without this option enabled, the best match would be the one that matches the input city name:

262 Spectrum

™

Technology Platform 9.0

optionName

KeepMultimatch

KeepCandidates

CloseMatchesOnly

MatchMode

API Guide

Chapter 8: Module Services

Description

301 BRYANT ST

SAN FRANCISCO CA 94107-4167

With this option enabled, the best match would be the one that matches the input ZIP Code:

301 BRYANT ST

PALO ALTO CA 94301-1408

Select this option to return the list of possible matches when Geocode

US Address finds more than one possible match for the input address and cannot identify a single best match.

Return the addresses that are possible matches for the input address (default).

Do not return the ambiguous matches.

Select this option to return candidate addresses whenever the match attempt produces candidates. If you enable this option, the geocoder will return candidates both when the input address matches to a single address and when the input address matches multiple addresses.

This option differs from KeepMultimatch in that the KeepMultimatch option does not return candidates if the input address matches to a single address.

Return candidates for all match attempts.

Do not return candidates for all matches (default).

If you specify KeepCandidates=Y you can choose to return just those candidates that are considered to be a close match. The criteria used to determine whether a candidate is a close match are those you specify in the MatchMode option.

Note:

A close match does not necessarily indicate a high-quality match. You should always check the values in the output fields

MatchCode and LocationCode to determine the quality of the match.

Return close match candidates only (default).

Return all candidates.

Determines the leniency used to find a match. One of the following:

Custom

Allows you to select the specific criteria to use when matching the input address to an address in the postal database.

Exact

Requires a very tight match. This is a restrictive mode that generates the fewest number of match candidates to search, which decreases the time to obtain a match. When using this mode, ensure that your input address list is very clean; free of misspellings and incomplete addresses.

Close

Relax

Requires a moderately confident match. Generates a moderate number of match candidates.

Default. This is the loosest match mode and generates the most match candidates, which increases the processing time

263

Enterprise Geocoding Module optionName

MustMatchInput

MustMatchHouseNumber

Description

CASS

and results in more multiple matches. Use this mode if your address list may contain misspellings and incomplete addresses. This is the only mode that does not respect the street parity for an address match.

Imposes additional rules to ensure compliance with the USPS regulations for CASS. The purpose of this mode is to create a list of mailable addresses. This mode generates a large number of match candidates. This mode deviates from the other modes in its processing. This mode does not perform intersection, building name, or spatial alias (TIGER and

TomTom street name alias) matches. It also does not match to candidates from data sources that do not have USPS equivalent records. This mode recognizes and parses two unit numbers on the same address line, for example a building and unit number.

Specifies whether candidates must match all non-blank input fields. For example, if an input address contains a city and postal code, then candidates for this address must match the city and postal code.

Yes, candidates must match all input.

No, candidates do not have to match all input. Default.

Specifies whether candidates must match the house number. If the input house number is not within a range from the street, GeocodeUSAddress selects the nearest range on the street which has the same parity (even or odd house number) as the input address number. GeocodeUSAddress returns one or more of the closest matches inside this range that preserves street parity. This requires GeocodeUSAddress to change the house number. The new house number is equal to one of the range's endpoints, possibly plus or minus one to preserve street parity.

Note:

Even when this option is disabled and an inexact match on the house number is found, GeocodeUSAddress still returns an error code.

When this option is disabled and no exact matching house number is found, a match code of either E029 (no matching range, single street segment found), or E030 (no matching range, multiple street segment) is returned.

GeocodeUSAddress does not change the house number on the output address. In order to access the inexact address number candidates, you must specify KeepMultimatch=Y. If there are inexact house number candidates returned, the corresponding match codes begin with the letter 'H' indicating that the house number was not matched.

Additionally, even when one or more exact candidates are found, inexact matches to the house number are still on the list of possible candidates, and these can be differentiated from the others by their Hxx match codes. For more information on match codes, see

Geocoding Match

Codes

on page 341.

One of the following:

Yes, candidates must match the house number.

264 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName

MustMatchStreet

MustMatchCity

MustMatchStateProvince

MustMatchPostalCode

Description

No, candidates do not have to match the house number.

Specifies whether candidates must match the street name.

Yes, candidates must match the street name.

No, candidates do not have to match the street name.

Specifies whether candidates must match the city. If you do not require exact matches on city, the geocoder searches on the street address matched to the particular postal code, and considers other cities that do not match the name, but do match the postal code.

Yes, candidates must match the city.

No, candidates do not have to match the city.

Specifies whether candidates must match the state.

Yes, candidates must match the state.

No, candidates do not have to match the state.

Specifies whether candidates must match the postal code. If you do not require exact match on postal codes, the geocoder searches a wider area for a match. While this results in slower performance, the match rate is higher because the request does not need to match exactly when it compares match candidates.

Yes, candidates must match the postal code.

No, candidates do not have to match the postal code.

Difference Between Match Criteria for U.S. and Non-U.S. Geocoding

The "must match criteria" used in the custom match mode of Geocode US Address work differently than the "close match criteria" in non-U.S. geocoders. For Geocode US Address, the custom match criteria specify which address elements must match the reference database in order for the match to be returned as a candidate. All candidates returned by Geocode US Address will match the elements you specify as long as those elements are available in the reference database. However, in non-U.S. geocoders, the "close match" criteria are used to determine which candidates are close matches and which are non-close matches. Non U.S. geocoders can return both close candidates and non-close candidates, depending on whether you enable the CloseMatchesOnly option. In summary, the "must match" criteria used by Geocode US Address automatically limit the candidates returned, whereas the "close match criteria" used by non-U.S. geocoders do not limit the candidates returned.

Output Format

The following table lists the GeocodeUSAddress options that control the format of the output.

Table 75: GeocodeUSAddress Output Format Options optionName

OutputCasing

Description

Specifies the casing of the output data. One of the following:

API Guide 265

Enterprise Geocoding Module optionName Description

The output in mixed case (default). For example:

123 Main St

Mytown FL 12345

The output in upper case. For example:

123 MAIN ST

MYTOWN FL 12345

OutputFormattedOnFail Specifies whether GeocodeUSAddress normalizes an addresses that fail to match, and addresses that are unchanged. Normalization formats an address to the USPS guidelines without validating the address.

Perform standardization (default).

Do not perform standardization.

OutputPostalCodeSeparator Specifies whether GeocodeUSAddress should include the dash in full postal code output.

Include the dash (default).

Do not include the dash.

OutputVerbose Specifies whether GeocodeUSAddress provides an additional description field as output. These fields provide the text equivalent to a field represented by a code. For example, LocationCode returns a code that indicates the accuracy (quality) of the assigned geocode. LocationCode.Description

provides the description for the code returned.

Include verbose fields.

Do not include verbose fields (default).

266

Output Data

The following table shows the GeocodeUSAddress options that control which data GeocodeUSAddress returns in the output.

Table 76: GeocodeUSAddress Output Data Options optionName

OutputRecordType

Description

Specifies optional data to include in the output. Note that GeocodeUSAddress always returns the default data listed in

Default Output

on page 274. The data you select here is returned with the default output data.

• B—Block Address

• C—Census

• D—DPV (The DPV field group is disabled unless you select Perform

Delivery Point Validation (DPV) on the Configuration Options tab.)

• Z—Geoconfidence

• L—Latitude/Longitude

• E—Parsed Elements

• P—Postal Data

Spectrum

™

Technology Platform 9.0

optionName

OutputFields

Chapter 8: Module Services

Description

• Q—Qualifiers

• R—Range

• S—Segment

For a description of the fields in each output group, see

Output

on page 267.

If you do not want all of the fields in a particular category returned, do not select the check box, and list only those fields you want returned in

OutputFields.

Specifies the individual output fields you want returned. List fields with a pipe

( | ) between each field. You can use this option instead of the

OutputRecordType option to limit the output to those fields that are important to your data needs.

By default, these are the address fields returned:

For a list of all the fields included in each data field, see

Output

on page 267.

Output

GeocodeUSAddress always returns a default set of output fields that contain the latitude/longitude, standardized address, and result indicators. For information on these fields, see

Default Output

on page

274. You can also choose to include the following optional categories of output data:

Note:

The output returned is in the DataTable class. For information on the DataTable class, see the

"API Fundamentals" section.

Auxiliary

Auxiliary data output fields contain information on the an auxiliary file match. For more information on using an auxiliary file, see

Auxiliary File Overview

on page 323. GeocodeUSAddress only returns values when matching against an auxiliary file. To include segment data fields in the output, set

OutputRecordType = X.

Table 77: Auxiliary Data Output Fields columnName

AuxiliaryData

MCDCode

MCDName

Description

The user data field in an auxiliary file match.

Note:

GeocodeUSAddress does not process this information. It simply includes the user data contained in the auxiliary file.

The Minor Civil Division (MCD) code. A Minor Civil Division is a subdivision of a county, such as a township. There are Minor Civil

Divisions in 28 states, the District of Columbia, Puerto Rico, and Island

Areas. Minor Civil Divisions are defined by U.S. Census Bureau.

The Minor Civil Division (MCD) name. A Minor Civil Division is a subdivision of a county, such as a township. There are Minor Civil

Divisions in 28 states, the District of Columbia, Puerto Rico, and Island

Areas. Minor Civil Divisions are defined by U.S. Census Bureau.

API Guide 267

Enterprise Geocoding Module columnName

BlockLine1

BlockLine2

BlockLine3

BlockLine4

BlockLine5

BlockLine6

Block Address

Block data output fields contain extraneous information from the input address that GeocodeUSAddress could not process. To include block data in the output, set OutputRecordType = B.

If there are any empty lines in the input fields AddressLine1 through AddressLine6, GeocodeUSAddress moves the output lines to the first empty BlockLine output field, eliminating the blank lines. For example:

Input Field Input Data

AddressLine1

AddressLine2

AddressLine3

Data.AddressLine3

AddressLine4

Pitney Bowes

4750 Walnut

Ste 200

Output Field

AddressLine1

LastLine

BlockLine1

BlockLine2

BlockLine3

BlockLine4

Output Data

4750 Walnut St Ste 200

Boulder, CO 80301-2532

Pitney Bowes

Dept ABC

Note:

Moved up one line from the input

AddressLine5.

AddressLine5

AddressLine6

Data.AddressLine6

Dept ABC

80301

Table 78: Block Data Output Fields

BlockLine5

BlockLine6

Description

Returns input address information GeocodeUSAddress could not process.

268 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Census

Census output fields contain U.S. Census information about the address. To include census data in the output, set OutputRecordType = C.

Table 79: Census Data Output Fields columnName

APN

BlockSuffix

CBSACode

CBSADivisionCode

CBSADivisionName

Description

The assessor's parcel number of the property. The assessor's parcel number is an ID number assigned to a property by the local property tax authority.

The block suffix for the Census block in which the address is located.

A block suffix is a single character assigned to subsections of U.S.

Census blocks that are split by a higher-level boundary, such as a municipal boundary. A block suffix is either "A" or "B". For information about U.S. Census block suffixes, see the Geographic Areas Reference

Manual, available at the U.S. Census Bureau website:

www.census.gov/geo/www/garm.html

Block suffixes are only available if you are using Centrus Enhanced data.

The code for the Core Based Statistical Area (CBSA) in which the address is located.

A CBSA is a collective term that refers to both metropolitan and micropolitan areas. A metropolitan area has a population of more than

50,000, and a micropolitan area has a population between 10,000 and

49,999. For more information, see Metropolitan and Micropolitan

Statistical Areas section of the U.S. Census Bureau website:

www.census.gov/population/www/metroareas/metroarea.html

The code of the Core Based Statistical Area (CBSA) division in which the address is located.

A CBSA division is a metropolitan statistical area with a population of at least 2.5 million that has been subdivided to form smaller groupings of counties referred to as "metropolitan divisions." For more information, see Metropolitan and Micropolitan Statistical Areas section of the U.S.

Census Bureau website:

www.census.gov/population/www/metroareas/metroarea.html

The name of the Core Based Statistical Area (CBSA) division in which the address is located.

Census Bureau website:

www.census.gov/population/www/metroareas/metroarea.html

The CBSA division name is only returned if you set the option

OutputVerbose=Y.

API Guide 269

Enterprise Geocoding Module columnName

CBSAMetro

270

CBSAName

CensusBlockID

Description

Indicates whether the core based statistical area (CBSA) in which the address is located is a metropolitan area or a micropolitan area. One of the following:

Yes, the address is located in a metropolitan statistical area.

Metropolitan areas have a population greater than 50,000.

N null

No, the address is not located in a metropolitan area. It is located in a micropolitan area. Micropolitan areas have a population between 10,000 and 49,999.

There is no data available to determine whether the address is in a metropolitan or micropolitan area.

A CBSA is a collective term that refers to both metropolitan and micropolitan areas. A metropolitan area has a population of more than

50,000, and a micropolitan area has a population between 10,000 and

49,999. For more information, see Metropolitan and Micropolitan

Statistical Areas section of the U.S. Census Bureau website:

www.census.gov/population/www/metroareas/metroarea.html

The name of the core based statistical area (CBSA) in which the address is located. The CBSA division name is only returned if you set the option

OutputVerbose=Y.

A CBSA is a collective term that refers to both metropolitan and micropolitan areas. A metropolitan area has a population of more than

50,000, and a micropolitan area has a population between 10,000 and

49,999. For more information, see Metropolitan and Micropolitan

Statistical Areas section of the U.S. Census Bureau website:

www.census.gov/population/www/metroareas/metroarea.html

The 15-digit identification number of the census block in which the address is located. Census blocks are the smallest geographic area for which the Bureau of the Census collects and tabulates decennial census data. Census blocks are formed by streets, roads, railroads, streams and other bodies of water, other visible physical and cultural features, and the legal boundaries shown on Census Bureau maps. For more information about U.S. Census blocks, see the Geographic Areas

Reference Manual, available at the U.S. Census Bureau website:

www.census.gov/geo/www/garm.html

The Census block ID is in the format: sscccttttttgbbb

Where:

ss ccc tttttt g bbb

The two-digit state FIPS code.

The three-digit county FIPS code.

The six-digit Census tract FIPS code.

The single-digit block group FIPS code.

The block FIPS code.

Note:

GeocodeUSAddress does not return a period for the Centrus tract FIPS code. This may deviate from the industry standard.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

CensusTract

CSACode

CSAName

USCountyName

USFIPSCountyNumber

USFIPSStateCode

USFIPSStateCountyCode

Description

The six-digit ID of the Census tract in which the address is located.

Census tracts are small, relatively permanent geographic entities within counties (or the statistical equivalents of counties). Generally, census tracts have between 2,500 and 8,000 residents and boundaries that follow visible features. For more information about U.S. Census tracts, see the Geographic Areas Reference Manual, available at the U.S.

Census Bureau website:

www.census.gov/geo/www/garm.html

Denotes the code for a geographic entity that consists of 2 or more adjacent CBSAs with employment interchange measures of at least 15.

The name of the combined statistical area (CSA) in which the address is located.

A CSA is a combination of two or more adjacent Core Based Statistical

Areas (CBSAs) with a high employment interchange measure. The employment interchange measure is the sum of the percentage of employed residents of the smaller entity who work in the larger entity and the percentage of the employment in the smaller entity that is accounted for by workers who reside in the larger entity. Pairs of CBSAs with employment interchange measures of at least 25% combine automatically. Pairs of CBSAs with employment interchange measures of at least 15%, but less than 25%, may combine if local opinion in both areas favors combination.

The CSA name is only returned if you set the option OutputVerbose=Y.

The name of the county or parish in which the address is located. The county/parish name is only returned if you set the option

OutputVerbose=Y.

The three-digit FIPS county code of the county in which the address is located.

The two-digit FIPS state code of the state in which the address is located.

The five-digit FIPS code for the state and county in which the address is located.

Centerline Projection

Centerline projection output fields contain information specific to a centerline match. To include centerline projection fields in the output, set OutputRecordType = N.

Table 80: Centerline Projection Output Fields columnName

CenterlineBearing

Description

The compass direction, in decimal degrees, from the point data match to the street centerline match. The compass direction is measured clockwise from 0 degrees north. For example, if the centerline match is directly north of the point match, the centerline bearing would be 0.

API Guide 271

Enterprise Geocoding Module

272 columnName Description

CenterlineBlockLeft

CenterlineBlockRight

CenterlineBlockSuffixLeft

CenterlineBlockSuffixRight

CenterlineDataCode

CenterlineDirection

CenterlineDistance

The Census FIPS Code that indicates the address is on the left side of the street.

The Census FIPS Code that indicates the address is on the right side of the street.

The block suffix of the block on the left side of the street.

A block suffix is a single character assigned to subsections of U.S.

Manual, available at the U.S. Census Bureau website:

www.census.gov/geo/www/garm.html

Block suffixes are only available if you are using Centrus Enhanced data.

The block suffix of the block on the right side of the street.

A block suffix is a single character assigned to subsections of U.S.

Manual, available at the U.S. Census Bureau website:

www.census.gov/geo/www/garm.html

Block suffixes are only available if you are using Centrus Enhanced data.

Indicates the data used to obtain a centerline match for the address.

One of the following:

USPS data in either the Centrus Enhanced, Centrus

TomTom, or Centrus NAVTEQ database.

TIGER data in the Centrus Enhanced database.

TomTom data in the Centrus TomTom database.

NAVTEQ data in the Centrus NAVTEQ database.

TomTom point-level data in the Centrus TomTom Points database.

Point-level data from the Centrus Points database.

Auxiliary file data.

For more information about these databases, see

Enterprise

Geocoding Databases

on page 215

Indicates the order of numbers on a segment for a centerline match.

Forward

Reversed

Both

Undetermined

Distance, in feet, from the point-level match to the centerline match.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Description

CenterlineHouseNumberHigh The highest address number in the range of addresses on the street segment. For example, if the address range for the street segment is

1000 to 2000, the CenterlineHouseNumberHigh would be 2000.

CenterlineHouseNumberLow The lowest address number in the range of addresses on the street segment. For example, if the address range for the street segment is

1000 to 2000, the CenterlineHouseNumberLow would be 1000.

CenterlineIsAlias Three characters indicating that GeocodeUSAddress located a centerline match by an index alias. The first is an N for normal street match or A for alias match (including buildings, aliases, firms, etc.). The next two characters are:

Basic index (normal address match)

USPS street name alias index

USPS building index

USPS firm name index

Statewide intersection alias match (when using the

Usw.gsi or Use.gsi file)

Spatial data street name alias (when using, the

Us_pw.gsi, Us_pe.gsi, Us_psw.gsi, or Us_pse.gsi file is required)

Alternate index (when using Zip9.gsu, Zip9e.gsu, and

Zip9w.gsu)

LACS

Link

CenterlineLatitude

CenterlineLeadingDirectional The street directional that precedes the street name for a centerline match. For example, the N in 138 N Main Street.

CenterlineLongitude

A seven-digit number in degrees and calculated to four decimal places for a centerline match. This field is only returned if

AlwaysFindCandidates=Y

CenterlineParity

7-digit number in degrees and calculated to 4 decimal places (in the format specified) for a centerline match. This field is only returned if

AlwaysFindCandidates=Y

Indicates which side of the street has odd numbers for a centerline match.

The left side of the street has odd numbers.

The right side of the street has odd numbers.

Both sides of the street have odd numbers.

Undetermined.

CenterlineRoadClass

CenterlineSegmentCode

The type of road for a centerline match:

Major

Minor

The unique 10-digit street segment ID assigned by the street network data provider.

API Guide 273

Enterprise Geocoding Module columnName Description

CenterlineStreetName The name of the street.

CenterlineStreetSuffix The street type of the matched centerline location. For example, AVE in "Washington AVE".

CenterlineTrailingDirectional The street directional that follows the street name. For example, the N in 456 Washington AVE N.

Default Output

GeocodeUSAddress always returns fields that contain the latitude/longitude, standardized address, and result indicators. Result indicators describe how well GeocodeUSAddress matched the input address to a known address and assigned a location. They also describes the overall status of a match attempt.

Table 81: Default Output Fields columnName

AddressLine1

AddressLine2

City

Confidence

Description

The first line of the address. For example:

1 Global View

Troy, NY 12180-8371

The second line of the address. For example:

4200 Parliament Pl

STE 600

Lanham, MD 20706-1882

The municipality name.

Indicates the confidence in the output provided, from 0 to 100. The higher the score, the higher the probability that the match is correct. If the match is exact, the confidence score is 100. For all other matches,

GeocodeUSAddress calculates the confidence score by subtracting values from 100 as follows:

• If GeocodeUSAddress changed the state to obtain a match:

• Added the state -3.75

• No state -7.5

• If GeocodeUSAddress changed the city to obtain a match:

• Added city -2.5

• No city -5.0

• If GeocodeUSAddress change the house number to obtain a match:

• Added house number -3.75

• No house number -7.5

• If GeocodeUSAddress changed the street name to obtain a match:

• Added street name -3.75

• No street name -7.5

274 Spectrum

™

Technology Platform 9.0

columnName

Country

FirmName

LastLine

Latitude

LocationCode

Longitude

MatchCode

PostalCode

PostalCode.AddOn

PostalCode.Base

ProcessedBy

StateProvince

API Guide

Chapter 8: Module Services

Description

• If GeocodeUSAddress changed the trailing directional to obtain a match:

• Added trailing directional -1.25

• No trailing directional -2.5

• If GeocodeUSAddress changed the leading directional to obtain a match:

• Added leading directional -1.25

• No leading directional -2.5

• If GeocodeUSAddress changed the street suffix to obtain a match:

• Added street suffix -1.25

• No street suffix -2.5

• If GeocodeUSAddress changed the postal code to obtain a match:

-11.25

If you have enabled the option to return centroids, the confidence value indicates the type of centroid returned:

• 60 for a street centroid

• 50 for a postal code centroid

• 35 for a city centroid

• 30 for a county centroid

• 25 for a state centroid

The name of the country. Since GeocodeUSAddress only works for U.S.

locations, this field will always contain United States of America.

The name of the business if the address is a business address.

The complete last address line (city, state, and postal code).

Seven-digit number in degrees and calculated to four decimal places

(in the format specified).

A value indicating the accuracy (quality) of the assigned geocode.

For more information, see

Address Location Codes

on page 328.

Seven-digit number in degrees and calculated to four decimal places

(in the format specified).

Indicates the portions of the address that matched to the directory file.

For more information, see

Geocoding Match Codes

on page 341.

Nine-digit ZIP Code with or without a hyphen.

Four-digit ZIP Code extension

Five-digit ZIP Code.

The underlying software that processed the request.

EnterpriseGeocoding for GeocodeUSAddress.

Two-character state abbreviation.

275

Enterprise Geocoding Module columnName

Status

Status.Code

Status.Description

StreetDataType

StreetSide

USUrbanName

Description

Reports the success or failure of the match attempt

null

Success

Failure

If GeocodeUSAddress could not process the address, this field will show the reason.

• Internal System Error

• No Geocode Found

• Insufficient Input Data

If GeocodeUSAddress could not process the address, this field will show a description of the failure.

Problem + explanation

Returned when Status.Code = Internal

System Error.

Geocoding Failed

No location returned

Returned when Status.code = No

Geocode Found.

Returned when Status.code = No

Geocode Found.

The data set GeocodeUSAddress attempted to match against.

Indicates the side of the street the range occupies. One of the following:

The range occupies the left side of the street.

The range occupies the right side of the street.

The range occupies both sides of the street.

Undetermined.

Urbanization name. Used for addresses in Puerto Rico.

DPV

DPV data output fields contain information about a match made using DPV data. GeocodeUSAddress only returns values when matching against DPV data. To include DPV data in the output, set

OutputRecordType = D.

Table 82: DPV Data Output Fields columnName

CMRA

Description

Indicates whether the address is for a Commercial Mail Receiving Agent

(CMRA). A CMRA is a private company that rents out mailboxes. A customer of a commercial mail receiving agency can receive mail and other deliveries at the street address of the CMRA rather than the customer's own street address. Depending on the agreement between the customer and the CMRA, the CMRA can forward the mail to the customer or hold it for pickup.

Yes, the address is a CMRA.

276 Spectrum

™

Technology Platform 9.0

columnName

DPV

DPVFootnote

API Guide

Chapter 8: Module Services

Description

N null

No, the address is not a CMRA.

DPV data is not available. DPV data is required to determine if an address is a CMRA.

Indicates whether the address is confirmed to be a deliverable address by USPS Delivery Point Validation (DPV).

Nothing confirmed

Everything confirmed (ZIP+4, primary, and secondary)

ZIP+4 and primary (house number) confirmed

ZIP+4 and primary (house number) confirmed and a default match

Non-matched input address to USPS ZIP+4 data, or DPV data not loaded

Contains detailed information about the address. The DPV footnote codes are combined together consecutively.

DPV footnotes include the following:

• FOOTNOTE1 provides information about matched DPV records.

• AA—ZIP+4 matched record

• A1—Failure to match a ZIP+4 record

• null—Address not presented to hash table or DPV data not loaded

• FOOTNOTE2 provides information about matched DPV records.

• BB—All DPV categories matched

• CC—Matched primary/house number, where the secondary/unit number did not match (present but invalid)

• M1—Missing primary/house number

• M3—Invalid primary/house number

• N1—Matched primary/house number, with a missing highrise secondary number

• P1—Missing PS, RR, or HC Box number

• P3—Invalid PS, RR or HC Box number

• F1—All military addresses

• G1—All general delivery addresses

• U1—All unique ZIP Code addresses

• null—Address not presented to hash table or DPV data not loaded

• FOOTNOTE3 provides information about matched DPV records.

• R1—Matched CMRA, without a present secondary/unit number

• RR—Matched CMRA

• null—Address not presented to hash table or DPV data not loaded

Note:

A unique ZIP Code is a ZIP Code assigned to a company, agency, or entity with sufficient mail volume to receive its own

ZIP Code.

277

Enterprise Geocoding Module

Geoconfidence

Geoconfidence data output fields contain information about the type of geoconfidence polygon returned.

To include geoconfidence fields in the output, set OutputRecordType = Z.

Description columnName

Response Element

GeoConfidenceCode

StreetSegmentPoints

GeoConfidenceCentroidLatitude

GeoConfidenceCentroidLongitude

The value returned in this field indicates which geoconfidence surface type has been returned.

Possible values are:

INTERSECTION

A geocode point for the intersection of two streets.

ADDRESS

POINT

POSTAL1

POSTAL2

An array of street segment points representing the street segment where the address is located.

If the geocoder was able to match the address using point data, the point geometry where the address is located.

A geocode point for the ZIP centroid.

POSTAL3

ERROR

An array of points for all street segments in the ZIP + 2 in which the address is located.

An array of points for street segments in the ZIP + 4 in which the address is located.

An error has occurred.

An array of latitude/longitude values that represent the street segment points.

Note:

This field contains values only if the

GeoConfidenceCode field returns a value of

ADDRESS

, POSTAL2, or POSTAL3.

The latitude of the centroid of the geoconfidence polygon.

The longitude of the centroid of the geoconfidence polygon.

Latitude/Longitude

The latitude/longitude output fields contain the geographic coordinates of the address. To include latitude/longitude output fields in the output, set OutputRecordType = L.

278 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Table 83: Latitude/Longitude Output Fields columnName

Elevation

Latitude

Longitude

Description

The location's elevation in feet above or below sea level.

The latitude of the address. The latitude is a seven-digit number in degrees, calculated to six decimal places.

The longitude of the address. The longitude is a seven-digit number in degrees, calculated to six decimal places.

Parsed Elements

The parsed elements output fields contain standard address information as individual units, such as street suffixes (for example AVE, ST, or RD) and leading directionals (for example N and SE). To include parsed elements in the output, set OutputRecordType = E.

Table 84: Parsed Elements Output Fields columnName Description

ApartmentLabel

ApartmentLabel2

The type of unit, such as apartment, suite, or lot.

The type of unit, such as apartment, suite, or lot, for addresses that contain two units, such as: 123 E Main St APT 3, 4th Floor .

Apartment number. For example: 123 E Main St APT 3 ApartmentNumber

ApartmentNumber2 Secondary apartment number. For example: 123 E Main St APT 3, 4th

Floor

CrossStreetLeadingDirectional

Leading directional, for example: 123 E Main St Apt 3

CrossStreetName

CrossStreetSuffix

Name of cross street.

Street suffix, for example: 123 E Main St Apt 3

CrossStreetTrailingDirectional

Trailing directional, for example: 123 Pennsylvania Ave NW

HouseNumber

HouseNumber2

Building number for the address.

If an address consists of a range of house numbers, this field contains the second house number. The HouseNumber field contains the first number. For example, given this address:

5-7 Maple Ave.

The HouseNumber field would contain "5" and the HouseNumber2 field would contain "7".

LeadingDirectional

PrivateMailbox

PrivateMailbox.Designator

Leading directional, for example: 123 E Main St Apt 3

Private mailbox. Not returned for multiline input.

Private mailbox description. Not returned for multiline input.

GeocodeUSAddress only returns Cross street outputs if you entered an intersection as an address. For example, entering Pearl and 28th, Boulder, CO returns cross street information. Entering 2800 Pearl,

Boulder, CO does NOT return cross street information.

API Guide 279

Enterprise Geocoding Module columnName

RRHC

StreetName

StreetSuffix

TrailingDirectional

Description

Rural Route/Highway Contract portion of the address.

Street name.

The street type of the matched location. For example, AVE for Avenue.

Street directional that follows the street name. For example, the N in

456 Washington N.

280

Postal Data

Postal data output fields contain detailed postal information for the address, such as the preferred city name and the US carrier route. To include postal data fields in the output, set OutputRecordType = P.

Table 85: Postal Data Output Fields columnName

CityPreferredName

CityShortName

CityStateRecordName

DeliveryPointCode

GovernmentBuilding

PostalBarCode

PostalCodeClass

Description

The USPS

® preferred city name for the ZIP Code of the address.

The USPS

-approved abbreviation for the city, if there is one. The

USPS

® provides abbreviations for city names that are 14 characters long or longer. City abbreviations are 13 characters or less and can be used when there is limited space on the mailing label. If there is no short city name for the city, then the full city name is returned.

USPS

® city state city name.

Two-digit delivery point bar code.

Indicates if a building is used by the city, state, or federal government.

City government building

Federal government building

State government building

Firm only

City government building and firm only

Federal government building and firm only

State government building and firm only

The values A, B, C, E, F, and G are valid for Alternate records only. The value D is valid for both base and alternate records.

Six-digit combination of ZIP+4 Code and the delivery point bar code.

ZIP Classification code.

null

Standard ZIP Code

Military ZIP Code

ZIP Code has P.O. boxes only

Unique ZIP Code (ZIP Code assigned to a single organization)

Spectrum

™

Technology Platform 9.0

columnName

PostalCodeUnique

PostalFacility

USBCCheckDigit

USCarrierRouteCode

USCarrierRouteSort

USCityDelivery

USLACS

API Guide

Chapter 8: Module Services

Description

Indicates if the ZIP Code is a unique ZIP Code assigned to an individual company or agency.

Unique ZIP name

null

No unique ZIP name

USPS City State Name Facility code.

Airport Mail Facility (AMF)

Branch

Community Post Office (CPO)

Area Distribution Center (ADC)

Sectional Center Facility (SCF)

Delivery Distribution Center (DDC)

General Mail Facility (GMF)

Bulk Mail Center (BMC)

Money Order Unit

Non-Postal Community Name, Former Postal Facility, or Place Name

Post Office

Station

Urbanization

Check-digit for delivery point bar code.

Carrier Route code.

Indicates if the USPS uses a carrier route sort, and what type of sort the USPS allows.

Automation cart allowed, optional cart merging allowed

Automation cart allowed, no optional cart merging allowed

No automation cart allowed, optional cart merging allowed

No automation cart allowed, no optional cart merging allowed

Indicates if has city-delivery carrier routes.

Has city-delivery carrier routes

Does not have city-delivery carrier routes.

Indicates if LACS

Link match occurred.

Matched LACS

Link record

LACS

Link match not found

False-positive LACS

Link record

Secondary information (unit number) removed to make a LACS

Link match

281

Enterprise Geocoding Module columnName

USLACS.ReturnCode

USLOTCode

Description null

Records not processed through LACS

Link

For more information, see

Locatable Address Conversion System

(LACS)

on page 222.

Indicates LACS

Link results.

Matched LACS

Link record

LACS

Link match was not found

Matched to highrise default, but noLACS

Link conversion

Found LACS

Link match, but no LACS

Link conversion

92 null

Secondary information (unit number) was removed to make a LACS

Link match

Records not processed through LACS

Link

For more information, see

Locatable Address Conversion System

(LACS)

on page 222.

A combination of the 4-digit Line of Travel (LOT) Code and the ascending

(A) or descending (D) indicator.

Qualifiers

Qualifier output fields contain qualification information on the match, such as the location code and the match code. To include postal data fields in the output, set OutputRecordType = Q.

Table 86: Qualifier Output Fields columnName

AddressLineResolved

CountryLevel

DatabaseVersion

Description

For two-line addresses, indicates which address line was used to obtain the match. One of the following:

The address could not be matched, or the address matched to multiple addresses.

AddressLine1 was used to obtain the match.

AddressLine2 was used to obtain the match.

Both address lines were used in their original order.

Both address lines were used but the order of the lines was switched to obtain the match.

The input address was a one line address.

The category of postal data available. Always returns A in

GeocodeUSAddress—Validates, corrects, and provides missing postal code, city name, state/county name, street address elements, and country name.

USPS publish date, in the format Month Year.

282 Spectrum

™

Technology Platform 9.0

columnName

EWSMatch

ExpirationDate

Geocoder.MatchCode

GeoStanMatchScore

Intersection

IsAlias

IsCloseMatch

LACSAddress

Chapter 8: Module Services

Description

Indicates if GeocodeUSAddress denied a match because of the input address matched an address in the Early Warning System (EWS) data.

The address matched to an address in the EWS data so the match was denied.

null

The address did not match to an address in the EWS data.

Date the database expires, in the format MM/DD/YY.

Indicates how closely the input address matches the candidate address.

Note:

The match codes returned in this field are different from the match codes described in

Geocoding Match Codes

on page

341. Instead, the match codes returned in this field are taken from a set of match codes that are compatible with all other country geocoders. For more information, see

Result Codes for International Geocoding

on page 349.

Record matching score (for multimatches only).

Indicates if GeocodeUSAddress found a cross-street match.

True

False

GeocodeUSAddress located a match by an index alias. Returns 3 characters. The first is an N for normal street match or A for alias match

(including buildings, aliases, firms, etc.). The next 2 characters are:

Basic index (normal address match)

USPS street name alias index

USPS building index

USPS firm name index

Statewide intersection alias match

Spatial data street name alias

Alternate index

LACS

Link

Indicates whether or not the address was a unique match or if there were candidate addresses.

Yes, the address is a close match. This field always contains

"Y" if there is only one match.

No, the address is not a close match. The record is a candidate.

Indicates if GeocodeUSAddress converted an address due to the

Locatable Address Conversion System (LACS)

Converted

null

Not converted

API Guide 283

Enterprise Geocoding Module columnName

LocationCode.Description

MatchCode.Description

RecordType

RecordType.Default

StreetDataCode

StreetDataType

Description

LocationCode converted to text. Only returned when you set the configuration options to return additional descriptions (verbose).

MatchCode converted to text. Only returned when you set the configuration options to return additional descriptions (verbose).

Indicates the record type:

• GeneralDelivery

• HighRise

• FirmRecord

• Normal

• PostOfficeBox

• RRHighwayContract

• Geographic (non USPS TIGER match)

• Auxiliary (match to an auxiliary file)

Indicates type of match that occurred for the record type HighRise or

RRHighwayContract:

Default match

Exact match

Not matched

Indicates the data used to geocode the address. One of the following:

USPS data in either the Centrus Enhanced, Centrus

TomTom, or Centrus NAVTEQ database.

TIGER data in the Centrus Enhanced database.

TomTom data in the Centrus TomTom database.

NAVTEQ data in the Centrus NAVTEQ database.

TomTom point-level data in the Centrus TomTom Points database.

Point-level data from the Centrus Points database.

Auxiliary file data.

For more information about these databases, see

Enterprise

Geocoding Databases

on page 215.

Indicates the data initially used for the match attempt. Note that the output field StreetDataCode shows which data was actually used to obtain the match.

The data indicated in StreetDataType may be different from that in

StreetDataCode if a match cannot be made in the initial match attempt.

For example, if a points database is loaded, GeocodeUSAddress will first attempt a match to the point data because this is the most accurate type of match. If a point-level match cannot be made,

GeocodeUSAddress will attempt to match to street data. If the match is made using street data, then the SreetDataType would indicate the point-level data and the StreetDataCode would indicate the street data.

284 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Description

For more information, see

How GeocodeUSAddress Processes

Addresses

on page 254.

Range

Range output fields contain information on the street range, such as the high and low unit numbers. To include range data fields in the output, set OutputRecordType = R.

Table 87: Range Data Output Fields columnName Description

Alternate

HouseNumberHigh

HouseNumberLow

HouseNumberParity

PostalCodeExtensionHigh

PostalCodeExtensionLow

UnitNumberHigh

UnitNumberLow

UnitNumberParity

USPS code that specifies whether a record is a base or alternate record.

Base record. Base records can represent a range of addresses or an individual address, such as a firm record.

Alternate record. Alternate records are individual delivery points.

The highest house number in the range.

The lowest house number in the range.

Indicates if the house number range contains even or odd numbers.

Even

Odd

Both

The highest four-digit ZIP Code extension in the range. The ZIP Code extension is the four digits at the end of the ZIP Code. For example:

60510-1134.

The lowest four-digit ZIP Code extension in the range. The ZIP Code extension is the four digits at the end of the ZIP Code. For example:

60510-1134.

The highest unit number in the range.

The lowest unit number in the range.

Indicates if the unit number range contains even or odd numbers.

Even

Odd

Both

Segment

Segment output fields contain information on the street segment identified by the data provider. To include segment data fields in the output, set OutputRecordType = S.

API Guide 285

Enterprise Geocoding Module

Table 88: Segment Data Output Fields

286 columnName Description

BlockLeft

BlockRight

BlockSuffixLeft

BlockSuffixRight

RoadClass

SegmentCode

SegmentDirection

The Census FIPS Code that indicates the address is on the left side of the street.

The Census FIPS Code that indicates the address is on the right side of the street.

The block suffix of the block on the left side of the street.

A block suffix is a single character assigned to subsections of U.S.

Manual, available at the U.S. Census Bureau website:

www.census.gov/geo/www/garm.html

Block suffixes are only available if you are using Centrus Enhanced data.

The block suffix of the block on the right side of the street.

A block suffix is a single character assigned to subsections of U.S.

Manual, available at the U.S. Census Bureau website:

www.census.gov/geo/www/garm.html

Block suffixes are only available if you are using Centrus Enhanced data.

The type of road:

Major

Minor

The unique 10-digit street segment ID assigned by the street network data provider.

Indicates the order of numbers on a segment.

Forward

Reversed

Both

Undetermined

SegmentHouseNumberHigh The highest house number in the segment.

SegmentHouseNumberLow The lowest house number in the segment.

SegmentLength

SegmentParity

The length, in feet, of a block segment.

Indicates which side of the street has odd numbers.

Left side of the street

Right side of the street

Spectrum

™

Technology Platform 9.0

columnName

StreetSide.NAVTEQ

Chapter 8: Module Services

Description

Both sides of the street

Undetermined

Indicates which side of the street the address is located on. The value in this field is determined by using the NAVTEQ reference nodes for the street segment. A street segment represents part of a street. Each segment has a node at each end: the reference node and the non-reference node. The reference node is the node with the lower latitude (southernmost). If the latitudes of both nodes are identical, the reference node is the end node with the lower longitude (westernmost).

The street side corresponds to the street sides you would see if you were standing at the reference node and looking at the non-reference node.

One of the follwoing:

The address is on the left side of the street.

The address is on the right side of the street.

The address occupies both sides of the street.

U null

The street side is unknown.

NAVTEQ data was not used, or segment output data was not selected, or the address did not match a street segment

(for example, the address was geocoded to a centroid).

Reports

There is one report available with GeocodeUSAddress: the GeocodeUSAddress Summary Report. To create the report, in Enterprise Designer, drag the GeocodeUSAddress Summary Report icon to the canvas. You do not need to draw a connector to the report.

GeocodeUSAddress Summary Report

The GeocodeUSAddress Summary Report contains information about the job, such as the settings, number of records processed, performance statistics, and the database used, as well as detailed information about the geocoding and address matching results. This report contains the following sections.

Address Matching Summary

This section shows the number of records processed and the number of matches obtained.

• Total Records in File—The total number of records in the input file used by this job.

• Records Processed—The number of input records minus those records that were skipped.

• Addresses Matched—The number of addresses that were successfully standardized and validated.

This count includes all the Standardized addresses listed under the Matched Address Records section plus those with match codes beginning with G (auxiliary file), T (geographic data only), and X

(intersections).

• Unmatched—The number of records that could not be validated.

Matched Address Records

This section contains information about the addresses that were successfully matched.

API Guide 287

Enterprise Geocoding Module

• Standardized—The number of addresses that match to USPS-relevant records. These addresses have match codes beginning with A (alias), D (small town), Q (unique ZIP), S (street), and U (rare).

Only these types of matches are counted as Standardized.

• Auxiliary File—The number of records that were matched to a user-defined file. These records have a MatchCode beginning with G.

• Intersections—The number of records that were matched to an intersection. These records have a

MatchCode beginning with X.

• Non-USPS—The number of records that were matched to non-USPS data.

Unmatched Address Records

This section lists the number of unmatched addressees and the reasons why the addresses were not matched. For information on these codes, see

Geocoding Match Codes

on page 341.

Standardized Address Quality

This section describes the changes that GeocodeUSAddress made to addresses in order to validate them.

• Original address unchanged—None of the address elements were changed to obtain a match.

• Original last line unchanged—The last line (city, state, ZIP Code) was unchanged but other elements were changed to obtain a match.

• Corrected predirectional—The predirectional of a street name was changed to obtain a match. For example, E MAIN ST changed to W MAIN ST.

• Corrected street name—The name of the street was changed to obtain a match. For example, MAIN

ST changed to MAINE ST.

• Corrected street suffix—The street suffix was changed to obtain a match. For example, MAIN ST changed to MAIN AVE.

• Corrected postdirectional—The postdirectional of a street was changed to obtain a match. For example, MAIN ST NW changed to MAIN ST SW.

• Corrected city name—The name of the city was corrected to obtain a match. For example, LOS

ANGLES changed to LOS ANGELES.

• Corrected state abbreviation—The state abbreviation was corrected to obtain a match. For example,

ROCHESTER NY changed to ROCHESTER MN.

• Corrected ZIP Code—The ZIP Code as corrected to obtain a match. For example: 1071 MAPLE LN

BATAVIA IL 49423 Changed to: 1071 MAPLE LN BATAVIA IL 60510

• Corrected ZIP + 4 add on—The four digits that appear after the "-" in a ZIP + 4 were corrected to obtain a match. For example, 60510 changed to 60510-1135.

Geocode Matching Levels

This section describes the level of accuracy for the geocodes returned by GeocodeUSAddress.

• Geocodes Assigned—The number of records to which GeocodeUSAddress assigned a geocode.

This is the cumulative count of the following fields:

• Address Match—Address geocodes indicate a geocode made directly to a street network segment

(or two segments, in the case of an intersection). Addresses included in this count have a value that begins with A in the LocationCode output field.

• Auxiliary Match—The geocode was determined using the Auxiliary File. Addresses included in this count have a value that begins with AG in the LocationCode output field. For more information, see

Auxiliary Match Details

on page 289.

• Point Match—The geocode was determined using a points database, which means the geocode represents the center of a building or parcel. Addresses included in this count have a value that begins with AP in the LocationCode output field. For more information, see

Point Matching Details

on page

289.

• ZIP Centroids Match—The address could not be matched, so the geocode is the center of the address's ZIP Code. This is the least accurate geocode for a given address. Addresses included in

288 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

this count have a value that begins with Z in the LocationCode output field. For more information, see

ZIP Centroid Matching Details

on page 289.

Auxiliary Match Details

This section describes the level of accuracy for the geocodes returned by GeocodeUSAddress that were obtained from the Auxiliary File. For more information, see

Auxiliary File Overview

on page 323.

These fields are ordered from the most accurate type of geocode to the least.

• Point—The geocode represents the center of a building or parcel. Addresses included in this count have a value of AG0 in the LocationCode output field.

• Centerline—The geocode represents the location of an address along a street segment. Addresses included in this count have a value of AG1 in the LocationCode output field.

• Centerline with unknown street side—The geocode represents the location of an address along a street segment but the side of the street where the address resides could not be determined. Addresses included in this count have a value of AG2 in the LocationCode output field.

• Midpoint—The geocode represents the midpoint of the street segment where the address resides.

GeocodeUSAddress could not determine where on the street segment the address is located. Addresses included in this count have a value of AG3 in the LocationCode output field.

Point Matching Details

This section describes the types of point-level geocodes returned by GeocodeUSAddress. Point-level geocodes represent the center of a parcel or building.

• Parcel Centroid—The geocode represents the center of a parcel. Addresses included in this count have a value of AP02 in the LocationCode output field.

• Field-collected GPS—The geocode is determined using data collected by teams of field verification specialists who drive the roads of selected areas to verify and update the data. Addresses included in this count have a value of AP04 in the LocationCode output field.

• Structure Centroid—The geocode represents the center of an addressable building footprint. An addressable structure is typically a structure that receives mail or has telephone service. Addresses included in this count have a value of AP05 in the LocationCode output field.

• Manual Frontage Midpoint—The geocode represents the center of a the parcel's boundary with the street. These points are offset at a specific distance from the street centerline near the center of the side of the parcel that fronts the street segment. Street frontage points estimate address locations more accurately than do interpolated ranges. Addresses included in this count have a value of AP07 in the LocationCode output field.

• Unknown Point-Level Geocode—The type of geocode is not known.

ZIP Centroid Matching Details

This section describes the types of ZIP Code centroids and census centroids returned by

GeocodeUSAddress.

• Location Accuracy—These fields describe the accuracy of the ZIP Code centroids.

• ZIP + 4—The centroid indicates the center of a ZIP + 4 code. This is the most accurate type of ZIP centroid. Addresses included in this count have a value of 9 in the third character of the value in the

LocationCode output field.

• ZIP + 2—The centroid represents the center of a ZIP + 2 code. Addresses included in this count have a value of 7 in the third character of the value in the LocationCode output field.

• ZIP Code—The centroid represents the center of a five-digit ZIP Code. This is the least accurate type of ZIP centroid. Addresses included in this count have a value of 5 in the third character of the value in the LocationCode output field.

• Census Accuracy—These fields describe the accuracy of the census centroids.

API Guide 289

Enterprise Geocoding Module

• Block Group—The centroid represents the center of a block group. This is the most accurate type of census centroid. Addresses included in this count have a value of that begins with ZB in the

LocationCode output field.

• Census Tract—The centroid represents the center of a census tract. Addresses included in this count have a value of that begins with ZT in the LocationCode output field.

• County—The centroid represents the center of a county. This is the least accurate type of census centroid. Addresses included in this count have a value of that begins with ZC in the LocationCode output field.

LACS/Link Statistics

This section describes the results of LACS/Link address processing. For information on LACS/Link, see

Locatable Address Conversion System (LACS)

on page 222.

• Records processed by LACS/Link—Addresses that were processed using LACS/Link.

• LACS/Link Matched—Addresses that were matched to addresses in the LACS/Link database.

• LACS/Link Matched w/ dropped unit info—Addresses whose secondary address information was removed in order to obtain a LACS

Link match.

• Not LACS/Link Matched—Addresses that GeocodeUSAddress attempted to match to LACS

Link were not found in the LACS

Link database.

but

• Not LACS/Link Converted—The address matched a LACS

Link record but was not converted.

• Not LACS/Link Converted - highrise default—The address matched a highrise default record but was not converted.

• Last LACS/Link false positive record—This is the record number within the input file of the last address to result in a false positive. For example, if the 5th record in the file was a LACS

Link false positive, this field would contain "5". For more information on false positives, see

Encountering False

Positives

on page 351.

Delivery Point Validation

This section describes the results of DPV address processing. For information on DPV, see

Delivery

Point Validation (DPV)

on page 222.

• Records processed by DPV—The number of addresses that were processed using DPV.

• DPV Records with ZIP + 4—Addresses that contained a ZIP + 4 code and were processed by DPV.

• DPV Confirmed—The number of addresses that were verified as deliverable addresses.

• Primary Confirmed, Secondary Missing—The primary portion of the address (the house number and street) was verified. The address requires a secondary element (for example, a suite or apartment number) to be a deliverable address, and the secondary information was missing from the input address.

• Primary Confirmed, Secondary Incorrect—The primary portion of the address (the house number and street) were verified. The address requires a secondary element (for example, a suite or apartment number) to be a deliverable address, and the secondary information in the input address was incorrect.

• DPV CMRA Confirmed—Commercial Mail Receiving Agency (CMRA) addresses confirmed by DPV.

• DPV Not Confirmed—Addresses that could not be verified as deliverable.

• USPS Street Records Confirmed—Street addresses that were confirmed by DPV.

• USPS General Delivery Records Confirmed—DPV processing confirmed that the address accepts general delivery mail.

• Records with confirmed CMRA—Commercial Mail Receiving Agency (CMRA) addresses that were confirmed with DPV.

• Records not confirmed CMRA—Commercial Mail Receiving Agency (CMRA) addresses that could not be confirmed with DPV.

• DPV False Positive Seed table hits—Addresses that matched to DPV false positive records. For more information, see

Encountering False Positives

on page 351.

290 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Records with DPV Footnote

This section lists the DPV footnote codes that were returned for the job. For an explanation of the DPV footnote codes, see

DPV

on page 276.

USPS Firm Records

This section describes the results of address validation for firm (business) addresses.

• Confirmed—GeocodeUSAddress confirmed that the address is a business address.

• Confirmed with PMB presented—GeocodeUSAddress confirmed that the address is a business address, and the business address contains a private mailbox (PMB).

• Failed primary house number—Business addresses that contained a primary house number which could not be confirmed.

• Failed secondary unit number—Business addresses that contained a secondary unit number which could not be confirmed.

USPS Highrise Records

This section describes the results of DPV processing for highrise addresses.

• Confirmed—Highrise addresses that were confirmed by DPV.

• Confirmed with PMB presented—Highrise addresses that contain a Private Mailbox (PMB) and were confirmed by DPV.

• Conf. CMRA with/without PMB—Highrise addresses that are also CMRA addresses, and that did or did not contain a Private Mailbox (PMB) address element.

• Failed primary house number—Highrise addresses that contained a primary house number which could not be confirmed.

• Failed secondary unit number—Highrise addresses that contained a secondary unit number which could not be confirmed.

USPS PO Box Records

This section describes the results of DPV processing for PO box addresses.

• Confirmed—PO Box addresses that were confirmed by DPV.

• Failed primary box number—PO Box addresses that contained a primary box number which could not be confirmed.

USPS Rural Route Records

This section describes the results of DPV processing for rural route addresses.

• Confirmed—Rural Route addresses that were confirmed by DPV.

• Conf. CMRA with/without PMB—Rural Route addresses that were also CMRA addresses, and that did or did not contain a Private Mailbox (PMB) address element.

• PMB Presented—Rural Route addresses that contained a Private Mailbox (PMB) address element.

• Failed primary house number—Rural Route addresses that contained a primary house number which could not be validated.

USPS Street Records

This section describes the results of DPV processing for street addresses.

• Confirmed—Street addresses that were confirmed by DPV.

• Confirmed with PMB presented—Street addresses that contained a Private Mailbox (PMB) and were confirmed by DPV.

• Conf. CMRA with/without PMB—Street addresses that were also CMRA addresses, and that did or did not contain a Private Mailbox (PMB) address element.

API Guide 291

Enterprise Geocoding Module

• Failed primary house number—Street addresses that contained a primary house number which could not be confirmed.

• Failed secondary unit number—Street addresses that contained a secondary unit number which could not be confirmed.

GNAFPIDLocationSearch

GNAFPIDLocationSearch identifies the address and latitude/longitude coordinates for a Geocoded

National Address File Persistent Identifier (G-NAF PID). The G-NAF PID is a 14-character alphanumeric string that uniquely identifies each G-NAF address in the G-NAF database (a database of Australian locations). The PID is constructed from a combination of the major address fields of the G-NAF database.

An example of a G-NAF PID is:

GAVIC411711441

Note:

You must have the G-NAF database installed to use GNAFPIDLocationSearch.

GNAFPIDLocationSearch is part of the Enterprise Geocoding Module. For more information on the

Enterprise Geocoding Module, including a listing of other components included with it, see

What is the

Enterprise Geocoding Module?

on page 214.

Input

GNAFPIDLocationSearch takes a G-NAF PID as input. The following table provides information on the format and layout of the input.

Note:

Specify input using the DataTable class. For information on the DataTable class, see the "API

Fundamentals" section.

Table 89: GNAFPIDLocationSearch Input columnName

GNAFPID

Format Description

String The 14-character G-NAF persistent identifier you want to look up. For example:

GAVIC411711441

292

Options

Geocoding Options

Table 90: GNAFPIDLocationSearch Geocoding Options optionName

GNAFPointType

Description

Specifies whether to return the parcel latitude/longitude or the street frontage latitude/longitude. This option is only available if you have the G-NAF database installed. This option only affects addresses matched to the G-NAF database.

One of the following:

In a street address match, return the exact location of the parcel. This is the standard G-NAF point which is the exact authoritative point returned by the G-NAF database. Default.

Spectrum

™

Technology Platform 9.0

optionName

Return8DecimalPlaceLatLong

Chapter 8: Module Services

Description

In a street address match, return the street frontage point for the parcel. The street frontage point is 12.5

metres from the front boundary of the parcel. Street frontage points are more suitable for routing applications.

Specifies whether to return the original latitude and longitude, precise up to eight digits after the decimal. This is the latitude/longitude that the candidate matched to in the G-NAF database. These are the original coordinates directly from the G-NAF data prior to truncation or rounding. This option is only available if you have the G-NAF database installed. This option only affects addresses matched to the G-NAF database.

Yes, return the original latitude/longitude, up to eight digits after the decimal.

No, do not return the original latitude/longitude.

Data Options

Table 91: GNAFPIDLocationSearch Data Options optionName

Database

Description

Specifies the database to use to look up the parcel. Use the database name specified in the Management Console's Database Resources tool. For more information, see the Spectrum

™

Technology Platform

Administration Guide.

Note:

Only database resources that contain G-NAF databases are available in this list.

Output

Address Output

Table 92: Address Output columnName

AddressLine1

AddressLine2

ApartmentLabel

ApartmentNumber

City

Country

County

Description

First line of the address.

Second line of the address.

The type of unit, such as apartment, suite, or lot.

Unit number.

Municipality name.

The three-letter ISO 3166-1 Alpha 3 country code.

The Local Government Authority (LGA).

API Guide 293

Enterprise Geocoding Module columnName Description

FirmName

HouseNumber

HouseNumberHigh

HouseNumberLow

HouseNumberParity

LastLine

LeadingDirectional

Complete last address line (city, state/province, and postal code).

Street directional that precedes the street name. For example, the N in

138 N Main Street.

This field is not used for this country.

Locality

NumberOfCandidateRanges Indicates whether or not the address has a house number. One of the following:

The address has no house number. Examples of addresses that have no house number are P.O. box addresses and general delivery addresses.

The address has a house number. For information about the range in which the house number falls, see the

HouseNumberHigh, HouseNumberLow, and HouseNumberParity fields.

NumberOfRangeUnits Indicates whether or not the address has a unit number, such as a suite number or apartment number. One of the following:

The address has no unit number.

The address has a unit number. For information about the range in which the unit number falls, see the UnitNumberHigh and UnitNumberLow.

PostalCode

Name of the company or a place name.

Building number for the matched location.

The highest house number of the range in which the address resides.

The lowest house number of the range in which the address resides.

Indicates if the house number range contains even or odd numbers or both.

Even

Odd

Both

PostalCode.Addon

PreAddress

PrivateMailbox

SegmentParity

StateProvince

The postcode for the address. The format of the postcode varies by country.

The second part of a postcode. For example, for Canadian addresses this will be the LDU. This field is not used by most countries.

Miscellaneous information that appears before the street name.

This field is not currently used.

Indicates which side of the street has odd numbers.

Left side of the street

Right side of the street

Both sides of the street

Undetermined

The state name.

294 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

StreetDataType

StreetName

StreetPrefix

StreetSuffix

TrailingDirectional

UnitNumberHigh

UnitNumberLow

Description

The default database search order is specified in the Management

Console with the Database Resources tool.

The street name.

The type of street when the street type appears before the base street name. For example, AVENUE:

12 AVENUE B KALGOORLIE WA 6430

The street type of the matched location. For example, AVE for Avenue.

Street directional that follows the street name. For example, the N in

456 Washington N.

The highest unit number of the range in which the unit resides.

The lowest unit number of the range in which the unit resides.

Geocode Output

Table 93: Geocode Output columnName

CoordinateSystem

Latitude

Longitude

Description

Petroleum Survey Group.

Seven-digit number in degrees and calculated to four decimal places

(in the format specified).

Seven-digit number in degrees and calculated to four decimal places

(in the format specified).

Result Codes

Result codes contain information about the success or failure of the geocoding attempt, as well as information about the accuracy of the geocode.

Table 94: Result Code Output columnName

Geocoder.MatchCode

IsCloseMatch

Description

Indicates how closely the input address matches the candidate address.

Indicates whether or not the address is considered a close match. An address is considered close based on the "Close match criteria" options on the Matching tab.

API Guide 295

Enterprise Geocoding Module columnName

MultiMatchCount

Status

Status.Code

Status.Description

LocationPrecision

Description

Yes, the address is a close match.

No, the address is not a close match.

For street address geocoding, the number of matching address positions found for the specified address.

For intersection geocoding, the number of matching street intersection positions found for the specified addresses.

Reports the success or failure of the match attempt

null

Success

Failure

If the geocoder could not process the address, this field will show the reason.

• Internal System Error

• No Geocode Found

• Insufficient Input Data

• Multiple Matches Found

• Exception occurred

• Unable to initialize Geocoder

• No Match Found

If the geocoder could not process the address, this field will show a description of the failure.

Problem + explanation

Returned when Status.Code = Internal

System Error.

Geocoding Failed

No location returned

Returned when Status.code = No

Geocode Found.

Returned when Status.code = No

Geocode Found.

No Candidates Returned

The geocoder could not identify any candidate matches for the address.

Multiple Candidates

Returned and Keep

Multiple Matches not selected

The address resulted in multiple candidates. In order for the candidate address to be returned, you must specify

KeepMultimatch=Y

A code describing the precision of the geocode. One of the following:

No coordinate information is available for this candidate address.

Interpolated street address.

Street segment midpoint.

Postal code 1 centroid.

Partial postal code 2 centroid.

Postal code 2 centroid.

296 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

StreetDataType

Description

Intersection.

Point of interest.

State/province centroid.

County centroid.

12 - 15

(LocationPrecision codes)

For most countries, LocationPrecision codes 12 through 15 are reserved for unspecified custom items.

Additional point precision for unspecified custom item.

City centroid.

Locality centroid.

Additional point precision for unspecified custom item.

The result is an Address Point.

The result was generated by using address point data to modify the candidates segment data.

The default database search order is specified in the Management

Console with the Database Resources tool.

G-NAF Output

The following table lists output fields that are unique to the Australian Geocoded National Address File

(G-NAF

) database. G-NAF is an optional database that is available for all six states and two territories.

G-NAF is the only authoritative Australian national index of locality, street and number, validated with geographic coordinates.

Table 95: Austraila G-NAF Output columnName

AUS.GNAF_CONFIDENCE

API Guide

Description

A number indicating how many G-NAF datasets the address is found in. A higher confidence level means that the same address was found in more data contributor sources. One of the following:

<number>

The number of datasets the address was found in, minus 1. For example, a value of 0 indicates that the address was found in one contributor's dataset, a value of 1 indicates that the address

297

Enterprise Geocoding Module columnName Description

-1

was found in two contributors' datasets, a value of 2 indicates that the address was found in three contributors' datasets, and so forth.

The address could not be found in any

G-NAF dataset.

AUS.GNAF_EIGHT_DECIMAL_PLACE_LATITUDE

The parcel latitude, precise to eight digits after the decimal. This is the latitude that the candidate matched to in the G-NAF database. These are the original coordinates directly from the G-NAF data prior to truncation or rounding.

This field is only returned if you specify

Return8DecimalPlaceLatLong=Y.

AUS.GNAF_EIGHT_DECIMAL_PLACE_LONGITUDE

The parcel longitude, precise to eight digits after the decimal. This is the longitude that the candidate matched to in the G-NAF database. These are the original coordinates directly from the G-NAF data prior to truncation or rounding.

This field is only returned if you specify

Return8DecimalPlaceLatLong=Y.

AUS.GNAF_GEOCODE_LEVEL

A number indicating the level o f geocode for the address. Every principal address within the G-NAF database has at least a locality level geocode. They may also have a street level geocode and a point level geocode.

One of the following:

No geocode.

Parcel level geocode only (no locality or street level geocode).

Street level geocode only (no locality or parcel level geocode).

Street and parcel level geocodes (no locality geocode).

Locality level geocode only (no street or parcel level geocode).

Locality and parcel level geocodes (no street level geocode).

Locality and street level geocodes (no parcel level geocodes).

Locality, street and parcel level geocodes.

AUS.GNAF_PID

The G-NAF Persistent Identifier (G-NAF PID) is a

14-character alphanumeric string that uniquely identifies each G-NAF address. The PID is constructed from a combination of the major

298 Spectrum

™

Technology Platform 9.0

columnName

AUS.GNAF_RELIABILITY

AUS.LEVEL_NUMBER

API Guide

Chapter 8: Module Services

Description

address fields of the G-NAF Dictionary. An example of a G-NAF PID is:

GAVIC411711441

A number indicating the geocode precision.

Reliability is related to the dictionary used to determine the geocode. Data with geocoded reliability levels 1, 2, and 3 is contained in the

GNAF123 Dictionary. This is point (parcel) level geocoded data. Data with geocoded reliability levels

4, 5, and 6 is contained in the GNAF456 Dictionary.

This contains non-parcel centroid geocoded data.

Geocode accuracy recorded to appropriate surveying standard. For example, this could apply to an address level geocode that was manually geocoded. Geocode resolution is sufficient to place the centroid within address site boundary with a GPS.

Geocode accuracy sufficient to place centroid within address site boundary. For example, this could apply to an address level geocode that was automatically calculated as the centroid of the corresponding cadastre parcel.

Geocode accuracy sufficient to place centroid near (or possibly within) address site boundary. For example, this could apply to an address level geocode that was automatically calculated by calculating where on the road the address was likely to appear based upon other bounding geocoded addresses.

Geocode accuracy sufficient to associate address site with a unique road feature. For example, this could apply to a street level geocode that was automatically calculated by using the road centerline reference data.

Geocode resolution sufficient to associate address site with a unique locality or neighborhood. For example, this could apply to a locality level geocode that was automatically calculated as the centroid of the locality.

Geocode resolution sufficient to associate address site with a unique region. For example, this could apply to a locality level geocode that was derived from topographic feature.

The number of a floor or level in a multi-story building. For example,

Floor 2 , 17 Jones Street

299

Enterprise Geocoding Module columnName

300

AUS.LEVEL_TYPE

AUS.MESH_BLOCK_ID

Description

The G-NAF database includes level information for some Australian states. Level information may be associated with unit information, but not necessarily. If the G-NAF database contains multiple records with the same level, the level information is returned only if the input address contains unique content (such as a unit number).

If the G-NAF dictionary has level information for an address, that information is returned with the matched candidate.

The correct level information is returned (when available) even if the input address did not include level information, or if the input had the wrong level information. If the input address has level information but the G-NAF database does not include level information for the matching address, then the input level information is discarded since it is not validated in the G-NAF data.

The label used for a floor of a multi-story building.

For example, "Level" or "Floor". In this example, the level type is "Level":

Suite 3 Level 7, 17 Jones Street

In this example, Suite 3 is a unit.

If the G-NAF dictionary has level information for an address, that information is returned with the matched candidate.

A Meshblock is the smallest geographic unit for which statistical data is collected by the Australian

Bureau of Statistics (ABS). Meshblocks usually contain a minimum of 20 to 50 households. This is about one fifth the size of a Collection District (CD).

You can use the Meshblock ID to do additional attributions against your own data.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

ReverseAPNLookup

ReverseAPNLookup allows you to look up an address using:

• An Assessor's Parcel Number (APN). An APN is an ID number assigned to a piece of land by a county assessor. An APN is unique only within a county.

• A FIPS county code. A Federal Information Processing Standard (FIPS) code is an ID number assigned to a county by the U.S. Federal government.

• A FIPS state code. A FIPS state code is an ID number assigned to each state by the U.S. Federal government.

These three pieces of information, used together, can uniquely identify a specific parcel. You must use all three pieces of information to perform a lookup using ReverseAPNLookup.

Note:

ReverseAPNLookup only works for U.S. addresses for which APN data is available. See the coverage map included with the points database for more information.

ReverseAPNLookup is part of the Enterprise Geocoding Module. For more information on the Enterprise

Geocoding Module, including a listing of other components included with it, see

What is the Enterprise

Geocoding Module?

on page 214.

Input

ReverseAPNLookup takes an APN, FIPS county code, and FIPS state code as input. The following table provides information on the format and layout of the input.

Note:

Specify input using the DataTable class. For information on the DataTable class, see the "API

Fundamentals" section.

Table 96: Reverse APNLookup Input Data columnName

APN

InputKeyValue

USFIPSCountyNumber

USFIPSStateCode

Format Description

String

[45]

The assessor's parcel number (APN) for the property you want to look up.

String User-defined data, such as a record ID or source code.

String [5] The FIPS county code for the county in which the property resides.

String [2] The FIPS state code for the state in which the property resides.

Options

The following table lists the options that control ReverseAPNLookup processing.

Table 97: ReverseAPNLookup Options optionName

Dataset

Description

Specifies the database to use to look up the parcel. Use the database name specified in the Management Console's Database Resources tool. For more information, see the Spectrum

™

Technology Platform

Administration Guide.

API Guide 301

Enterprise Geocoding Module optionName

LatLongFormat

RetrieveElevation

OutputCasing

OutputVerbose

OutputRecordType

OutputFields

Description

Specifies the format for returned latitude/longitude.

Decimal

(90.000000-180.000000) Default.

Integer

(90000000-180000000)

Specifies whether or not ReverseAPNLookup returns the elevation of the address. Elevation is the distance above or below sea level of a given location. The elevation is returned in the Elevation output field, which is part of the Latitude/Longitude output group.

Note:

This option requires that you have licensed and installed the

Centrus Premium Points database. Elevation data is not available for all addresses. See the coverage map included with the points database.

Specifies the casing of the output data. One of the following:

The output in mixed case (default). For example:

123 Main St

Mytown FL 12345

The output in upper case. For example:

123 MAIN ST

MYTOWN FL 12345

Specifies whether or not ReverseAPNLookup provides an additional description field as output. This field provides the text equivalent to a field represented by a code. For example, LocationCode returns a code that indicates the accuracy (quality) of the assigned geocode.

LocationCode.Description provides the description for the code returned.

Include verbose fields.

Do not include verbose fields. Default.

Specifies optional data to include in the output. Note that

ReverseAPNLookup always returns the default data listed in

Default

Output

on page 304. The data you select here is returned with the default output data.

• C—Census

• L—Latitude/Longitude

• E—Parsed Elements

• Q—Qualifiers

• R—Range

• S—Segment

For a list of fields included in each record type, see

Output

on page 303.

If you do not want all of the fields in a group returned, do not select the group, and instead list only those fields you want returned in

OutputFields

Indicate the individual output fields you want returned. List fields with a pipe ( | ) between each field. You can use this field instead of the

302 Spectrum

™

Technology Platform 9.0

optionName

Chapter 8: Module Services

Description

OutputRecordType field to limit the output to the specific fields you want.

Default list:

Output

ReverseAPNLookup returns the following categories of data:

•

Census

on page 303

•

Default Output

on page 304

•

Latitude/Longitude

on page 306

•

Parsed Elements

on page 306

•

Qualifiers

on page 307

•

Range

on page 309

•

Segment

on page 309

Census

The Census output fields contain census information from the U.S. 2000 Census. To include census data in the output, set OutputRecordType = C.

Table 98: Census Output Fields columnName

BlockSuffix

CBSACode

CBSADivisionCode

CBSADivisionName

CBSAMetro

CBSAName

CensusBlockID

CensusTract

CSACode

Description

Single character block suffix for split Census blocks. Returns A or B.

Only available in Centrus Enhanced data.

Indicates Core Based Statistical Area (CBSA).

Denotes a subdivision of a CBSA.

Describes a subdivision of a CBSA. Only returned when you set the configuration options to return additional descriptions (verbose).

Metropolitan Statistical Area. Valid values include:

Metro statistical area

N null

Micro statistical area

Data unavailable

Describes CBSA. Only returned when you set the configuration options to return additional descriptions (verbose).

The ID of the Census Federal Information Processing Standard (FIPS) code.

Six digits extracted from the CensusBlockID.

Denotes the code for a geographic entity that consists of 2 or more adjacent CBSAs with employment interchange measures of at least 15.

API Guide 303

Enterprise Geocoding Module columnName

CSAName

USCountyName

USFIPSStateCountyCode

Description

Describes the name for a geographic entity that consists of 2 or more adjacent CBSAs with employment interchange measures of at least 15.

Only returned when you set the configuration options to return additional descriptions (verbose).

Name of the county, including the text "County" or "Parish." Only returned when you set the configuration options to return additional descriptions

(verbose).

Five-digit FIPS code for state and county extracted from the

CensusBlockID.

AddressLine1

AddressLine2

APN

City

Confidence

Country

Distance

Elevation

FirmName

LastLine

Latitude

LocationCode

Default Output

ReverseAPNLookup always returns the address, geocode, and result indicators.

Table 99: Default Output Fields columnName

AdditionalInputData

Longitude

Description

Mailstop, attention line, or deliver instructions as included in the input data. This field is always null.

Note:

ReverseAPNLookup does not process this information. It simply includes the information as entered in the input data.

First line of the address.

Second line of the address.

The Assessor's Parcel Number that was specified in the input.

Municipality name.

Indicates the confidence in the output provided. The range is from 0

(zero) to 100, with 0 being no match and 100 being an exact match.

The name of the country. Since ReverseAPNLookup only works for U.S.

locations, this field will always contain United States of America.

The distance, in feet, of the dwelling along the segment.

The distance in feet above or below sea level of the parcel.

Name of the company.

Complete last address line (municipality, state, and postal code).

Seven-digit number in degrees and calculated to 4 decimal places (in the format specified).

Indicates the accuracy (quality) of the assigned geocode.

For more information, see

Address Location Codes

on page 328.

Seven-digit number in degrees and calculated to 4 decimal places (in the format specified).

304 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

MatchCode

PercentGeocode

PostalCode

PostalCode.AddOn

PostalCode.Base

ProcessedBy

StateProvince

Status

Status.Code

Status.Description

StreetDataType

StreetSide

USFIPSCountyNumber

USFIPSStateCode

USUrbanName

Description

Indicates the portions of the address that matched to the directory file.

For more information, see

Geocoding Match Codes

on page 341.

The percent along the street segment that matches the geocode. For example, if the returned geocode falls 1/3 along the way of the entire street segment, the percent is 33.000.

Note:

This value is always 0.0 for matches to point-level data and intersections.

Nine-digit ZIP Code with or without a hyphen.

Four-digit ZIP Code extension.

Five-digit ZIP Code.

The feature code for the stage that processed the request. The value is EnterpriseGeocoding for ReverseAPNLookup.

Two-character state abbreviation.

Reports the success or failure of the match attempt

null

Success

Failure

Reason for failure:

• Internal System Error

• No Address Found

• Insufficient Input Data

Description of the problem:

Problem + explanation

Returned when Status.Code = Internal

System Error.

Geocoding Failed

No location returned

Returned when Status.code = No Address

Found)

Returned when Status.code = No Address

Found.

The data set that ReverseAPNLookup attempted to match against.

Indicates the side of the street for the range.

LEFT

Left side of the street.

RIGHT

BOTH

Right side of the street.

Both sides of the street.

Three-digit FIPS county code specified in the input.

Two-digit FIPS state code specified in the input.

USPS

® urbanization name. Puerto Rican addresses only.

API Guide 305

Enterprise Geocoding Module

Latitude/Longitude

The latitude/longitude output fields contain the geographic coordinates of the location and elevation. To include latitude/longitude output fields in the output, set OutputRecordType = L.

Table 100: Latitude/Longitude Output Fields columnName

Elevation

Latitude

Longitude

Description

The distance in feet above or below sea level of the parcel.

7-digit number in degrees and calculated to 4 decimal places (in the format specified).

Parsed Elements

The Parsed Elements output fields contain standard address information as individual units, such as street suffixes (AVE) and leading directionals (N and SE). To include parsed elements in the output, set

OutputRecordType = E.

Table 101: Parsed Elements Output Fields columnName Description

ApartmentLabel Apartment designator (such as STE or APT), for example: 123 E Main

St. APT 3

ApartmentLabel2 Secondary apartment designator, for example: 123 E Main St. APT 3,

4th Floor

Apartment number, for example: 123 E Main St. APT 3 ApartmentNumber

ApartmentNumber2 Secondary apartment number, for example: 123 E Main St. APT 3, 4th

Floor

Municipality name.

City

CrossStreetLeadingDirectional Leading directional, for example: 123 E Main St. Apt 3

CrossStreetName

Cross street name, for example: 123 E Main St. Apt 3

CrossStreetSuffix Cross street suffix, for example: 123 E Main St. Apt 3

CrossStreetTrailingDirectional Cross street trailing directional, for example: 123 Pennsylvania Ave NW

HouseNumber Building number, for example: 123 E Main St. Apt 3

Note:

This is an approximate building number based on the APN,

FIPS county code, and FIPS state code provided. This approximate address may not exist or may not accept mail delivery.

306

ReverseAPNLookup only returns Cross street outputs if you entered an intersection as an address. For example, entering Pearl and 28th, Boulder, CO returns cross street information. Entering 2800 Pearl,

Boulder, CO does NOT return cross street information.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Description

LeadingDirectional

PrivateMailbox

PrivateMailbox.Designator

RRHC

StreetName

StreetSuffix

TrailingDirectional

Leading directional, for example: 123 E Main St. Apt 3

Private mailbox indicator. Not output for multiline input.

The type of private mailbox. Possible values include:

• Standard

• Non-Standard

Rural Route/Highway Contract indicator.

Street name, for example: 123 E Main St. Apt 3

Street suffix, for example: 123 E Main St. Apt 3

Trailing directional, for example: 123 Pennsylvania Ave NW

Qualifiers

The qualifiers output fields contain qualification information on the match, such as the location code and the match code. To include qualifier output fields in the output, set OutputRecordType = Q.

Table 102: Qualifiers Output Fields columnName

CountryLevel

DatabaseVersion

EWSMatch

ExpirationDate

GeoStanMatchScore

Intersection

IsAlias

API Guide

Description

The category of postal data available. Always returns A in

ReverseAPNLookup—Validates, corrects, and provides missing postal code, city name, state/county name, street address elements, and country name.

USPS publish date, in the format Month Year.

Indicates if ReverseAPNLookup denied a match because of Early

Warning System (EWS) data.

EWS denied a match.

null

EWS did not deny a match.

For more information on EWS, see

Early Warning System (EWS)

on page 222.

Date the database expires, in the format MM/DD/YY.

Record matching score (for multimatches only).

Indicates if ReverseAPNLookup found a cross-street match.

True, a cross-street match was found.

False, a cross-street match was not found.

ReverseAPNLookup located a matched record by an index alias. Returns

3 characters. The first is an N for normal street match or A for alias match (including buildings, aliases, firms, etc.). The next 2 characters are:

Basic index (normal address match)

307

Enterprise Geocoding Module columnName

LACSAddress

LocationCode.Description

MatchCode.Description

RecordType

RecordType.Default

StreetDataCode

Description

USPS street name alias index

USPS building index

USPS firm name index

Statewide intersection alias match (when using the

Usw.gsi or Use.gsi file)

Spatial data street name alias (when using the

Us_pw.gsi, Us_pe.gsi, Us_psw.gsi, or Us_pse.gsi file)

Alternate index (when using Zip9.gsu, Zip9e.gsu, and

Zip9w.gsu)

LACS

Link

Indicates if ReverseAPNLookup converted an address due to the

Locatable Address Conversion System (LACS).

L null

Converted

Not converted

For more information on LACS, see

Locatable Address Conversion

System (LACS)

on page 222.

LocationCode converted to text. Only returned when you set the configuration options to return additional descriptions (verbose).

MatchCode converted to text. Only returned when you set the configuration options to return additional descriptions (verbose).

Indicates the record type:

• GeneralDelivery

• HighRise

• FirmRecord

• Normal

• PostOfficeBox

• RRHighwayContract

Indicates type of match that occurred for the record type HighRise or

RRHighwayContract:

Default match

Exact match

Not matched

Indicates the data used to obtain a match.

USPS data in either the Centrus Enhanced, Centrus

TomTom, or Centrus NAVTEQ database.

TIGER data in the Centrus Enhanced database.

TomTom data in the Cenrus TomTom database.

NAVTEQ data in the Centrus NAVTEQ database.

308 Spectrum

™

Technology Platform 9.0

columnName

Chapter 8: Module Services

Description

TomTom point-level data in the Centrus TomTom Points database.

Point-level data from the Centrus Points database.

Auxiliary file data

Range

The range output fields contain information on the street range, such as the high and low unit numbers.

To include range data fields in the output, set OutputRecordType = R.

Table 103: Range Output Fields columnName Description

Alternate

HouseNumberHigh

HouseNumberLow

HouseNumberParity

PostalCodeExtensionHigh

PostalCodeExtensionLow

UnitNumberHigh

UnitNumberLow

UnitNumberParity

USPS code that specifies whether a record is a base or alternate record.

Base record. Base records can represent a range of addresses or an individual address, such as a firm record.

Alternate record. Alternate records are individual delivery points.

House number high.

House number low.

Indicates if the house number range contains even or odd numbers.

Even

Odd

Both

4-digit ZIP Code extension high.

4-digit Zip Code extension low.

Unit number high.

Unit number low.

Indicates if the unit number range contains even or odd numbers.

Even

Odd

Both

Segment

The segment output fields contain information on the street segment identified by the data provider. To include segment data fields in the output, set OutputRecordType = S.

API Guide 309

Enterprise Geocoding Module

Table 104: Segment Output Fields columnName Description

BlockLeft

BlockRight

BlockSuffixLeft

BlockSuffixRight

RoadClass

Provides the Census FIPS Code that indicates the address is on the left side of the street.

Provides the Census FIPS Code that indicates the address is on the right side of the street.

Current left Block suffix for Census 2000 Geography. Returns A or B.

Only available in Centrus Enhanced data.

Current right Block suffix for Census 2000 Geography. Returns A or B.

Only available in Centrus Enhanced data.

The type of road:

The road is a major road.

The road is a minor road.

PointCode

SegmentCode

SegmentDirection

Unique point ID assigned by the data provider. This field is blank if the matched record is not from point-level data.

Unique 10-digit segment ID assigned by the street network provider.

Indicates the order of numbers on a segment.

Forward

Reversed

Both

Undetermined

SegmentHouseNumberHigh A high range number in the segment.

SegmentHouseNumberLow A low range number in the segment.

SegmentLength

SegmentParity

The length, in feet, of a block segment.

Indicates which side of the street has odd numbers.

Left side of the street

Right side of the street

Both sides of the street

Undetermined

Reverse Geocode Address Global

For information on using the API to access Reverse Geocode Address Global, see the geocoding guides.

ReverseGeocodeUSLocation

ReverseGeocodeUSLocation takes a latitude and longitude point as input and returns the address that is the best match for that point. For example, you could enter the following information:

Longitude: -105239771 Latitude: 40018912 Search Distance: 150 feet

310 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

This input would result in the following output:

4750 WALNUT ST BOULDER, CO 80301-2538

MatchCode = NS0

LocCode = AS0

Lon = -105239773

Lat = 40018911

Distances:

Search = 150

Offset = 50

Squeeze = 50

Nearest = 50.0

Pct Geocode = 94.0

SegID = 472881795

PtID = GDT

Block = 080130122032066

County Name = BOULDER COUNTY

DPBC = 50

Note:

The address returned is an approximate address based on the latitude and longitude provided.

This approximate address may not exist or may not accept mail delivery.

ReverseGeocodeUSLocation is part of the Enterprise Geocoding Module. For more information on the

Enterprise Geocoding Module, including a listing of other components included with it, see

What is the

Enterprise Geocoding Module?

on page 214.

ReverseGeocodeUSLocation processes geocodes in the following order:

1. ReverseGeocodeUSLocation defines a small rectangle based on your input geocode and search distance.

2. ReverseGeocodeUSLocation computes the distance between each street segment and the input location.

3. If one segment is closest, ReverseGeocodeUSLocation finds the offset and interpolated percentage

(using the squeeze factor) and the street side. It then computes an approximate house number based on this information.

If there is more than one segment that is equally close to the input location, a multi-match occurs.

ReverseGeocodeUSLocation returns the information for all of the equally close segments so that you can determine which segment is applicable.

4. ReverseGeocodeUSLocation returns the address information, including the segment range, the approximate house number, and the parity of the range along with other standard address information.

Note:

Although many of the standard address matching outputs apply to the reverse geocoding option, several outputs are unavailable (such as LACS

Link information and unit numbers).

ReverseGeocodeUSLocation returns these outputs as blank. ReverseGeocodeUSLocation also has outputs specific to reverse geocode processing, such as specific match codes and the distance from the input location to the matched segment.

To use ReverseGeocodeUSLocation, you need additional data files, called GSX files. There is an option to install these files when you install the geocoding database. The GSX files must be installed the GSX subdirectory of the geocoding database. If you install the Centrus Enhanced Points, Centrus Premium

Points, or Centrus TomTom Points database, you must recreate the GSX files. Consult with Pitney Bowes

Software Technical Support if you need more information on GSX files.

Input

ReverseGeocodeUSLocation takes longitude and latitude information as input. The following table provides information on the format and layout of the input.

Note:

Specify input using the DataTable class. For information on the DataTable class, see the "API

Fundamentals" section.

API Guide 311

Enterprise Geocoding Module

Table 105: ReverseGeocodeUSLocation Input Data columnName

Latitude

Longitude

Format Description

String

Latitude of the point for which you want address information returned. Specify latitude in millionths of decimal degrees.

Longitude of the point for which you want address information returned. Specify longitude in millionths of decimal degrees.

Options

Configuration Options

The following table lists the configuration options for ReverseGeocodeUSLocation.

Table 106: ReverseGeocodeUSLocation Configuration Options optionName

Dataset

SearchDistance

FindNearestAddress

FindNearestUnranged

FindNearestIntersection

Description

The name of the database that contains the data to use in the search process. Use the database name specified in the Management Console's

Database Resources tool. For more information, see the Spectrum

™

Technology Platform Administration Guide.

Specifies the radius, in feet, that ReverseGeocodeUSLocation search for matches. The range is 0 - 5280 feet, with a default value of 150 feet.

Specifies whether or not ReverseGeocodeUSLocation should find the nearest address to the input geocode.

Find the nearest address. Default.

Do not find the nearest address.

Note:

You can use this option with the FindNearestIntersection option to geocode to both addresses and intersections.

Specifies whether or not ReverseGeocodeUSLocation can match to a street segment that does not have a number range. This option is active when FindNearestAddress=Y.

Allow ReverGeocodeUSLocation to match to an unranged street segment. Default.

Do not allow ReverseGeocodeUSLocation to match to an unranged street segment.

Note:

If you are using the point-level data option,

ReverseGeocodeUSLocation ignores the Nearest Unranged option.

Specifies whether or not ReverseGeocodeUSLocation should find the nearest street intersection to the input geocode.

Find the nearest street intersection. Default.

Do not find the nearest street intersection.

312 Spectrum

™

Technology Platform 9.0

optionName

RetrieveAPN

Offset

Chapter 8: Module Services

Description

Note:

You can use this option with the FindNearestAddress option to geocode to both addresses and intersections.

Specifies whether or not ReverseGeocodeUSLocation should determine the address's APN (assessor's parcel number). The APN is an ID number assigned to a property by the local property tax authority. The APN is returned in the APN output field, which is part of the Census output group.

Note:

This option requires that you have licensed and installed the

Cenrus Enhanced Points or Centrus Premium Points database.

APN data is not available for all addresses. See the coverage map included with the points database.

Specifies the offset distance from the street segments. The range is 0

- 5280 feet, with the default value of 50 feet.

The distance is calculated perpendicular to the portion of the street segment for the address. Offset is also used to prevent addresses across the street from each other from being given the same point. The following diagram shows an offset point in relation to the original point.

Squeeze

Street coordinates are accurate to 1/10,000th of a degree and interpolated points are accurate to 1/1,000,000th of a degree.

Specifies the distance, in feet, to squeeze the street end points in street-level geocoding. The range is 0 -2147483647 feet, with the default value of 50 feet. The following diagram compares the end points of a street to squeezed end points.

API Guide 313

Enterprise Geocoding Module optionName Description

LatLonFormat

InputLatLonFormat

RetrieveElevation

Specifies the format to use for returned latitude/longitude.

Decimal

The format is 90.000000-180.000000. Default.

Integer

The format is 90000000-180000000.

Specifies the format to use for input latitude/longitude.

Decimal

The format is 90.000000-180.000000. Default.

Integer

The format is 90000000-180000000.

Specifies whether or not ReverseGeocodeUSLocation returns the elevation of the address. Elevation is the distance above or below sea level of a given location. The elevation is returned in the Elevation output field, which is part of the Latitude/Longitude output group.

Note:

This option requires that you have licensed and installed the

Centrus Premium Points database. Elevation data is not available for all addresses. See the coverage map included with the points database.

314

Output Format

The following table lists the options that control the format of the output .

Table 107: ReverseGeocodeUSLocation Output Format Options optionName

OutputCasing

OutputVerbose

Description

Specifies the casing of the output data. One of the following:

The output in mixed case (default). For example:

123 Main St

Mytown FL 12345

The output in upper case. For example:

123 MAIN ST

MYTOWN FL 12345

Specifies whether or not ReverseGeocodeUSLocation provides an additional description field as output. This field provides the text equivalent to a field represented by a code. For example, LocationCode returns a code that indicates the accuracy (quality) of the assigned

Spectrum

™

Technology Platform 9.0

optionName

Chapter 8: Module Services

Description

geocode. LocationCode.Description provides the description for the code returned.

Include verbose fields.

Do not include verbose fields. Default.

Output Data

The following table lists the options that control which data is returned by ReverseGeocodeUSLocation.

Table 108: ReverseGeocodeUSLocation Output Data Options optionName

OutputRecordType

OutputFields

Description

Specifies the optional data to include in the output. Note that

ReverseGeocodeUSLocation always returns the data listed in

Default

Output

on page 317. The data you select here is returned with the default output data.

• C—Census

• L—Latitude/Longitude

• E—Parsed Elements

• Q—Qualifiers

• R—Range

• S—Segment

For a list of the fields included in each data type, see

Output

on page

315.

If you do not want all of the fields in a record type returned, do not specify the record type. Instead, list only those fields you want returned in

OutputFields.

Specifies the individual output fields you want returned. List fields with a pipe ( | ) between each field. You can use this field instead of the

Output Record Type to limit the output to those fields that are important to your data needs.

Default list:

Output

ReverseGeocodeUSLocation returns the following categories of data:

•

Census

on page 316

•

Default Output

on page 317

•

Latitude/Longitude

on page 318

•

Parsed Elements

on page 319

•

Qualifiers

on page 319

•

Range

on page 321

•

Segment

on page 322

API Guide 315

Enterprise Geocoding Module

Note:

The output returned is in the DataTable class. For information on the DataTable class, see the

"API Fundamentals" section.

Census

The Census output record type contains census information from the U.S. 2000 Census. To include census data in the output, set OutputRecordType = C.

Table 109: Census Output Fields columnName

APN

BlockSuffix

CBSACode

CBSADivisionCode

CBSADivisionName

CBSAMetro

CBSAName

CensusBlockID

CensusTract

CSACode

CSAName

USCountyName

USFIPSCountyNumber

USFIPSStateCode

USFIPSStateCountyCode

Description

The assessor's parcel number of the property. The assessor's parcel number is an ID number assigned to a property by the local property tax authority.

Single character block suffix for split Census blocks. Returns A or B.

Only available in Centrus Enhanced data.

Indicates Core Based Statistical Area (CBSA).

Denotes a subdivision of a CBSA.

Describes a subdivision of a CBSA. Only returned when you set the configuration options to return additional descriptions (verbose).

Metropolitan Statistical Area. Valid values include:

Metro statistical area.

N null

Micro statistical area.

Data unavailable.

Describes CBSA. Only returned when you set the configuration options to return additional descriptions (verbose).

The ID of the Census Federal Information Processing Standard (FIPS) code.

6-digits extracted from the CensusBlockID.

Denotes the code for a geographic entity that consists of 2 or more adjacent CBSAs with employment interchange measures of at least 15.

Describes the name for a geographic entity that consists of 2 or more adjacent CBSAs with employment interchange measures of at least 15.

Only returned when you set the configuration options to return additional descriptions (verbose).

Name of the county, including the text "County" or "Parish." Only returned when you set the configuration options to return additional descriptions

(verbose).

3-digit FIPS county code extracted from the CensusBlockID.

2-digit FIPS state code extracted from the CensusBlockID.

5-digit FIPS code for state and county extracted from the CensusBlockID.

316 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

AddressLine1

AddressLine2

City

Confidence

Country

Distance

Elevation

FirmName

LastLine

Latitude

LocationCode

Default Output

ReverseGeocodeUSAddress always includes the following fields in the output.

Table 110: Default Output Fields columnName

AdditionalInputData

Longitude

MatchCode

PercentGeocode

PostalCode

PostalCode.AddOn

PostalCode.Base

ProcessedBy

Description

Mailstop, attention line, or deliver instructions as included in the input data.

Note:

ReverseGeocodeUSLocation does not process this information.

It simply includes the information as entered in the input data.

First line of the address.

Second line of the address.

Municipality name.

Indicates the confidence in the output provided. The range is from 0

(zero) to 100, with 0 being no match and 100 being an exact match.

Country name.

The distance, in feet, of the dwelling along the segment.

The location's elevation in feet above or below sea level.

Name of the company.

Complete last address line (municipality, state, and postal code).

7-digit number in degrees and calculated to 4 decimal places (in the format specified).

Indicate the accuracy (quality) of the assigned geocode.

For more information, see

Address Location Codes

on page 328.

7-digit number in degrees and calculated to 4 decimal places (in the format specified).

Indicates the portions of the address that matched to the directory file.

For more information, see

Geocoding Match Codes

on page 341.

The percent along the street segment that matches the geocode. For example, if the returned geocode falls 1/3 along the way of the entire street segment, the percent is 33.000.

Note:

This value is always 0.0 for matches to point-level data and intersections.

9-digit ZIP Code with or without a hyphen.

4-digit ZIP Code extension.

5-digit ZIP Code.

The underlying software that processed the request. KGR for

ReverseGeocodeUSLocation.

API Guide 317

Enterprise Geocoding Module columnName

RRHC

StateProvince

Status

Status.Code

Status.Description

StreetDataType

StreetSide

USUrbanName

Description

Rural Route Highway Contract (RRHC). This field is null if the address not a RRHC.

2-character state abbreviation.

Reports the success or failure of the match attempt

null

Success

Failure

Reason for failure:

• Internal System Error

• No Geocode Found

• Insufficient Input Data

Description of the problem:

Problem + explanation

Returned when Status.Code contains

"Internal System Error."

Geocoding Failed

No location returned

Returned when Status.code contains "No

Geocode Found".

Returned when Status.code contains "No

Geocode Found."

The data set that ReverseGeocodeUSLocation attempted to match against.

Indicates the side of the street for the range.

LEFT

Left side of the street

RIGHT

BOTH

Right side of the street

Both sides of the street

Urbanization name. Puerto Rico addresses only.

Latitude/Longitude

The latitude/longitude output fields contain the geographic coordinates of the location. To include latitude/longitude output fields in the output, set OutputRecordType = L.

Table 111: Latitude/Longitude Output Fields columnName

Elevation

Latitude

Longitude

Description

The location's elevation in feet above or below sea level.

7-digit number in degrees and calculated to 4 decimal places (in the format specified).

318 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Parsed Elements

The Parsed Elements output record type contains standard address information as individual units, such as street suffixes (AVE) and leading directionals (N and SE). To include parsed elements in the output, set OutputRecordType = E.

Table 112: Parsed Elements Output Fields columnName Description

ApartmentLabel

ApartmentLabel2

ApartmentNumber

Unit, such as apartment, suite, or lot.

Unit number.

ApartmentNumber2 Unit number.

CrossStreetLeadingDirectional Prefix for cross street.

CrossStreetName Name of cross street.

CrossStreetSuffix Cross street suffix.

CrossStreetTrailingDirectional Postfix for cross street.

HouseNumber Building number for the matched location.

Note:

This is an approximate building number based on the latitude and longitude provided. This approximate address may not exist or may not accept mail delivery.

LeadingDirectional

PrivateMailbox

PrivateMailbox.Designator

StreetName

StreetSuffix

TrailingDirectional

Street directional that precedes the street name. For example, the N in

138 N Main Street.

Private mailbox. Not output for multiline input.

Private mailbox description. Not output for multiline input.

Street name.

The street type of the matched location. For example, AVE for Avenue.

Street directional that follows the street name. For example, the N in

456 Washington N.

Qualifiers

The qualifiers output record type contains qualification information on the match, such as the location code and the match code. To include latitude/longitude output fields in the output, set OutputRecordType

= Q.

Table 113: Qualifiers Output Fields columnName

CountryLevel

Description

The category of postal data available. Always returns A in

ReverseGeocodeUSLocation—Validates, corrects, and provides missing

API Guide 319

Enterprise Geocoding Module columnName

DatabaseVersion

EWSMatch

ExpirationDate

GeoStanMatchScore

Intersection

IsAlias

LACSAddress

LocationCode.Description

Description

postal code, city name, state/county name, street address elements, and country name.

USPS publish date, in the format Month Year.

Indicates if ReverseGeocodeUSLocation denied a match because of

Early Warning System (EWS) data.

EWS denied a match.

null

EWS did not deny a match.

For more information on EWS, see

Early Warning System (EWS)

on page 222.

Date the database expires, in the format MM/DD/YY.

Record matching score (for multimatches only).

Indicates if ReverseGeocodeUSLocation found a cross-street match.

True, a cross-street match was found.

False, a cross-street match was not found.

ReverseGeocodeUSLocation located a matched record by an index alias. Returns 3 characters. The first is an N for normal street match or

A for alias match (including buildings, aliases, firms, etc.). The next 2 characters are:

Basic index (normal address match)

USPS street name alias index

USPS building index

USPS firm name index

Statewide intersection alias match (when using the

Usw.gsi or Use.gsi file)

Spatial data street name alias (when using, the

Us_pw.gsi, Us_pe.gsi, Us_psw.gsi, or Us_pse.gsi file is required)

Alternate index (when using Zip9.gsu, Zip9e.gsu, and

Zip9w.gsu)

LACS

Link

Indicates if ReverseGeocodeUSLocation converted an address due to the Locatable Address Conversion System (LACS).

Converted

null

Not converted.

For more information on LACS, see

Locatable Address Conversion

System (LACS)

on page 222.

LocationCode converted to text. Only returned when you set the configuration options to return additional descriptions (verbose).

320 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

MatchCode.Description

RecordType

RecordType.Default

StreetDataCode

StreetDataType

Description

MatchCode converted to text. Only returned when you set the configuration options to return additional descriptions (verbose).

Indicates the record type:

• GeneralDelivery

• HighRise

• FirmRecord

• Normal

• PostOfficeBox

• RRHighwayContract

Indicates type of match that occurred for the record type HighRise or

RRHighwayContract:

Default match.

Exact match.

Not matched.

Indicates the data used to obtain a match.

USPS data in either the Centrus Enhanced, Centrus

TomTom, or Centrus NAVTEQ database.

TIGER data in the Centrus Enhanced database.

TomTom data in the Centrus TomTom database.

NAVTEQ data in the Centrus NAVTEQ database.

TomTom point-level data in the Centrus TomTom Points database.

Point-level data from the Centrus Points database.

Auxiliary file data.

Indicates the data first used to attempt a match.

Range

The range output record type contains information on the street range, such as the high and low unit numbers. To include range data fields in the output, set OutputRecordType = R.

Table 114: Range Output Fields columnName

Alternate

HouseNumberHigh

API Guide

Description

USPS code that specifies whether a record is a base or alternate record.

Base record. Base records can represent a range of addresses or an individual address, such as a firm record.

Alternate record. Alternate records are individual delivery points.

House number high.

321

Enterprise Geocoding Module columnName Description

HouseNumberLow

HouseNumberParity

PostalCodeExtensionHigh

PostalCodeExtensionLow

UnitNumberHigh

UnitNumberLow

UnitNumberParity

House number low.

Indicates if the house number range contains even or odd numbers.

Even

Odd

Both

4-digit ZIP Code extension high.

4-digit Zip Code extension low.

Unit number high.

Unit number low.

Indicates if the unit number range contains even or odd numbers.

Even

Odd

Both

322

Segment

The segment output record type contains information on the street segment identified by the data provider.

To include segment data fields in the output, set OutputRecordType = S.

Table 115: Segment Output Fields columnName

BlockLeft

BlockRight

BlockSuffixLeft

BlockSuffixRight

RoadClass

SegmentCode

SegmentDirection

Description

Provides the Census FIPS Code that indicates the address is on the left side of the street.

Provides the Census FIPS Code that indicates the address is on the right side of the street.

Current left Block suffix for Census 2000 Geography. Returns A or B.

Only available in Centrus Enhanced data.

Current right Block suffix for Census 2000 Geography. Returns A or B.

Only available in Centrus Enhanced data.

The type of road:

Major

Minor

Unique 10-digit segment ID assigned by the street network provider.

Indicates the order of numbers on a segment.

Forward

Reversed

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Description

Both

Undetermined

SegmentHouseNumberHigh A high range number in the segment.

SegmentHouseNumberLow A low range number in the segment.

SegmentLength

SegmentParity

The length, in feet, of a block segment.

Indicates which side of the street has odd numbers.

Left side of the street

Right side of the street

Both sides of the street

Undetermined

Geocode US Address Auxiliary Files

Auxiliary File Overview

Use auxiliary files to match against special data that is not included in the GeocodeUSAddress database.

The GeocodeUSAddress database is updated regularly to incorporate changes made by the USPS and third-party data vendors. You may have newer information that has not yet been incorporated. Auxiliary files provide a way for you to process your input records against a file that includes these changes.

Note:

ReverseGeocodeUSAddress does not support auxiliary files.

There are two types of auxiliary file records:

• Street Records—Contains a range of one or more addresses on a street. For required fields, see

Auxiliary File Layout

on page 325. A street record must not have secondary address information mailstops, Private mail boxes (PMBs), and PO Boxes.

• Landmark Records—Represents a single site. For required fields, see

Auxiliary File Layout

on page 325. A landmark record must not have street type abbreviations, predirectional and postdirectional abbreviations, or low and high house numbers.

Note:

You cannot update the auxiliary file while GeocodeUSAddress is running. If you want to update the auxiliary file, stop GeocodeUSAddress before attempting to replace or edit the file.

Matching to Auxiliary Files

GeocodeUSAddress matches an input address to an auxiliary file as follows:

1. GeocodeUSAddress determines if there is an auxiliary file present.

If you have an auxiliary file in the dataset directory, GeocodeUSAddress automatically loads and attempts to match to the auxiliary file. You can verify that GeocodeUSAddress found an auxiliary file by looking at the version information page in the Management Console. One of the following statuses display:

• Loaded—An auxiliary file is loaded

• None—An auxiliary file has not been found or loaded

• Invalid—An auxiliary file was found, but failed to successfully load

API Guide 323

Enterprise Geocoding Module

GeocodeUSAddress only accepts one auxiliary file. If more than one auxiliary files is present,

GeocodeUSAddress attempts to match against the first file. GeocodeUSAddress ignores any additional auxiliary files for matching, regardless if GeocodeUSAddress found a match to the first auxiliary file.

If a record in the auxiliary files is invalid, GeocodeUSAddress returns a invalid record message.

GeocodeUSAddress continues to match input addresses with the auxiliary file, but will not match to the invalid auxiliary file record.

2. If an auxiliary file is present, GeocodeUSAddress attempts to match to the auxiliary file.

GeocodeUSAddress assumes that the auxiliary file is the most accurate data set and attempts to find a match to the input address in the auxiliary file. If GeocodeUSAddress cannot find a match in the auxiliary file, it matches the input address with the other Enterprise Geocoding Module databases.

Note:

GeocodeUSAddress only matches input address lists to auxiliary files if there is an exact match. Your input address list should be free of misspellings and incomplete addresses.

3. If GeocodeUSAddress finds an exact record match to the auxiliary file, it standardizes the match to

USPS regulations and returns the output of the auxiliary file match.

GeocodeUSAddress uses the following defaults if you do not include the values in the auxiliary file:

• House number parity = B (both odds and evens)

• Segment direction = A (ascending)

• Side of street = U (unknown)

Record Type Matching Rules

When matching against an auxiliary file, GeocodeUSAddress uses the following rules:

Street record match

• The input house number must fall within or be equal to the low and high house number values of the auxiliary record.

• The input house number must agree with the parity of the auxiliary record.

• The input ZIP Code must exactly match the ZIP Code of the auxiliary record.

Landmark record match

• The input data must contain a ZIP Code and address line, and the values must exactly match the values on the auxiliary record.

• The input address cannot have any other data, such as a house number, unit number, or Private Mail

Box (PMB).

Note:

GeocodeUSAddress only matches the ZIP Code against the auxiliary file. GeocodeUSAddress does not verify that the ZIP Code of the input address record is correct for the city and state.

Validate this information in your input lists before processing against the auxiliary file.

Unavailable Features and Functions

The following features and functions do not apply when GeocodeUSAddress makes an auxiliary file match.

• GeocodeUSAddress does not match to

• two-line addresses

• multi-line addresses

• intersection addresses

• dual addresses

• GeocodeUSAddress does not perform EWS, ZIPMove, LACSLink, or DPV processing on auxiliary matches

• You can only access the auxiliary file with processing through the Find function. You cannot access the auxiliary file through the Find First/Next or MBR functions

• You can only access the auxiliary file logic using the address code option of the Find function, not the geocode option.

324 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Auxiliary Match Output

GeocodeUSAddress provides special data type, match codes, and location code values for auxiliary matches. When GeocodeUSAddress finds a match to an auxiliary file, the default output follows these conventions:

• GeocodeUSAddress formats the auxiliary file match as a street-style address for output. This excludes

PO Boxes, Rural Routes, General Delivery, etc.

• GeocodeUSAddress follows the case setting you indicate (by default, upper case) by the casing function. GeocodeUSAddress does not maintain the casing in the auxiliary file for mixed casing values.

For example, GeocodeUSAddress returns O'Donnell as ODONNELL or Odonnell depending on the setting of the casing function.

Note:

GeocodeUSAddress does not change the casing for the User Data field.

• GeocodeUSAddress removes spaces at the beginning and ending of fields in the auxiliary file.

Note:

GeocodeUSAddress does not remove spaces for the User Data field.

Auxiliary File Layout

You must comply with the following organizational rules when you create auxiliary file:

• Files are fixed-width text files with a .gax extension

• Files can contain up to 500,000 records.

• Use semicolons in the first column to indicate a row is a comment, not a data record;

GeocodeUSAddress ignores rows that begin with a semicolon.

• For optimal performance, order the records within the file by descending ZIP Code, and then descending street name.

• Records must represent only one side of a street. To represent both sides of a street, create a record for each side of the street.

• Records must represent segments that are straight lines.

• House numbers must follow USPS rules documented in Publication 28.

• Numeric fields, such as ZIP Codes, must contain only numbers.

• If house numbers are present in the record, the house number range must be valid according to USPS rules documented in Publication 28, Appendix E.

• Latitude and Longitude values must be in millionths of decimal degrees.

• Records cannot contain PO Box addresses.

The following table shows auxiliary file layout.

Table 116: Auxiliary File Layout

Field Description

ZIP Code

Street name

Street type abbreviation

5-digit ZIP Code.

Name of the street or landmark.

Street type. Also called street suffix.

Required Required for

Street

Segment

Match

Required for

Landmark

Match

Exact

Match

Required if

Present

Length Position

1-5

6-35

X 4 36-39

API Guide 325

Enterprise Geocoding Module

326

Field Description

See the USPS

Publication 28,

Appendix C for a complete list of supported street types.

Predirectional USPS street name predirectional abbreviation.

Supported values are

N, E, S, W, NE, NW,

SE, and SW.

Postdirectional USPS street name postdirectional abbreviations.

Supported values are

N, E, S, W, NE, NW,

SE, and SW.

RESERVED RESERVED

Low house number

Low house number of the address range.

High house number

High house number of the address range.

House number parity

Indicates the parity of the house number in the range.

E - Even

O - Odd

B - Both

Segment direction

RESERVED

FIPS state

Direction the house numbers progress along the segment:

F - Forward (default)

R - Reverse

RESERVED

US government FIPS state code.

FIPS county

Census tract

US government FIPS county code.

US Census tract number.

Required Required for

Street

Segment

Match

Required for

Landmark

Match

Exact

Match

Required if

Present

Length Position

40-41

42-43

44-47

48-58

59-69

73-74

75-77

78-83

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Field Description

Census block group

US Census block group number.

Census block

US Census block ID number.

RESERVED RESERVED

State abbreviation

USPS state abbreviation.

County name Name of the county.

MCD code

MCD name

CBSA code

Minor Civil Division code.

Minor Civil Division name.

Core Based Statistical

Area code.

CBSA name

RESERVED

City Name

Core Based Statistical

Area name.

RESERVED

City name. Overrides the city/state preferred city name upon a return.

RESERVED

User-defined data.

RESERVED

User-defined data

Record ID

Number

Side of street

User-defined unique record identifier.

Side of the street for the address:

L - Left side

R - Right side

B - Both sides

U - Unknown side

(default)

This is relative to the segment endpoints and the segment direction.

Required Required for

Street

Segment

Match

Required for

Landmark

Match

Exact

Match

Required if

Present

Length Position

1 84

237

300

85-87

88-92

93-94

95-119

120-124

125-164

165-169

170-218

219-223

224-263

264-500

501-800

801-810

811

API Guide 327

Enterprise Geocoding Module

Field Description

Beginning longitude

Beginning latitude

Ending longitude

Beginning longitude of the street segment in millionths of degrees.

Beginning latitude of the street segment in millionths of degrees.

Ending longitude of the street segment in millionths of degrees.

Ending latitude Ending latitude of the street segment in millionths of degrees.

Required Required for

Street

Segment

Match

Required for

Landmark

Match

Exact

Match

Required if

Present

Length Position

X X 11 812-822

X X 10

823-832

833-843

844-853

Location and Match Codes for U.S. Geocoding

Address Location Codes

Location codes that begin with an "A" are address location codes. Address location codes indicate a geocode made directly to a street network segment (or two segments, in the case of an intersection).

An address location code has the following characters.

1 st character

2 nd character

Always an A indicating an address location.

May be one of the following

3 rd and 4 th character

C Interpolated address point location

Auxiliary file data location

Application infers the correct segment from the candidate records

Point-level data location P

R Location represents a ranged address

Location on a street range S

X Location on an intersection of two streets

Digit indicating other qualities about the location.

328 Spectrum

™

Technology Platform 9.0

Table 117: Address Location Codes

Code

AGn n = 0 n = 1 n = 2 n = 3

APnn nn = 02

API Guide

nn = 04 nn = 05

Chapter 8: Module Services

Description

Indicates an auxiliary file for a geocode match where n is one of the following values:

The geocode represents the center of a parcel or building.

The geocode is an interpolated address along a segment.

The geocode is an interpolated address along a segment, and the side of the street cannot be determined from the data provided in the auxiliary file record.

The geocode is the midpoint of the street segment.

Indicates a point-level geocode match representing the center of a parcel or building, where nn is one of the following values:

Parcel centroid

Indicates the center of an accessor's parcel (tract or lot) polygon. When the center of an irregularly shaped parcel falls outside of its polygon, the centroid is manually repositioned to fall inside the polygon as closely as possible to the actual center.

Address points

Represents field-collected GPS points with field-collected address data.

Structure centroid

Indicates the center of a building footprint polygon, where the building receives mail or has telephone service.

Usually a residential address consists of a single building. For houses with outbuildings

(detached garages, shed, barns, etc.), only the residences have a structure point. Condominiums and duplexes have multiple points

329

Enterprise Geocoding Module

Code

330

nn = 07 nn = 08 nn = 09 nn = 10

Description

for each building. Larger buildings, such as apartment complexes, typically receive mail at one address for each building and therefore individual apartments are not represented as discrete structure points.

Shopping malls, industrial complexes, and academic or medical center campuses where one building accepts mail for the entire complex are represented as one point. When addresses are assigned to multiple buildings within one complex, each addressed structure is represented by a point.

If the center of a structure falls outside of its polygon, the center is manually repositioned to fall inside the polygon.

Manually placed

Address points are manually placed to coincide with the midpoint of a parcel's street frontage at a distance from the center line.

Front door point

Represents the designated primary entrance to a building. If a building has multiple entrances and there is no designated primary entrance or the primary entrance cannot readily be determined, the primary entrance is chosen based on proximity to the main access street and availability of parking.

Driveway offset point

Represents a point located on the primary access road (most commonly a driveway) at a perpendicular distance of between 33-98 feet (10-30 meters) from the main roadway.

Street access point

Represents the primary point of access from the street network.

This address point type is located

Spectrum

™

Technology Platform 9.0

Code

API Guide

nn=21

AIn

ASn

AIn and ASn share the same qualities for n as follows: n = 0 n = 1 n = 2

Chapter 8: Module Services

Description

where the driveway or other access road intersects the main roadway.

Base parcel point

When unable to match to an input unit number, or when the unit number is missing from an address location with multiple units, the "base" parcel information is returned, the address is not standardized to a unit number, and additional information, such as an

Assessor's Parcel Number, is not returned.

The correct segment is inferred from the candidate records at match time.

House range address geocode.

This is the most accurate geocode available.

Best location.

Street side is unknown. The

Census FIPS Block ID is assigned from the left side; however, there is no assigned offset and the point is placed directly on the street.

Indicates one or both of the following:

• The address is interpolated onto a TIGER segment that did not initially contain address ranges.

• The original segment name changed to match the USPS spelling. This specifically refers to street type, predirectional, and postdirectional.

Note:

Only the second case is valid for non-TIGER data because segment range interpolation is only completed for TIGER data.

331

Enterprise Geocoding Module

Code

ACnh n = 3 n = 7

Description

Both 1 and 2.

Placeholder. Used when starting and ending points of segments contain the same value and shape data is not available.

The ACnn 4 th digit characteristics are as follows: n = 0 n = 1 n = 2 n = 3 n = 4 n = 5 n = 6 n = 7

Represents the interpolation between two points, both coming from User Dictionaries.

Represents the interpolation between two points. The low boundary came from a User

Dictionary and the high boundary, from a non-User Dictionary.

Represents the interpolation between one point and one street segment end point, both coming from User Dictionaries.

Represents the interpolation between one point (low boundary) and one street segment end point

(high boundary). The low boundary came from a User

Dictionary and the high boundary from a non-User Dictionary.

Represents the interpolation between two points. The low boundary came from a non-User

Dictionary and the high boundary from a User Dictionary.

Represents the interpolation between two points, both coming from non-User Dictionaries.

Represents the interpolation between one point (low boundary) and one street segment end point

(high boundary). The low boundary came from a non-User

Dictionary and the high boundary from a User Dictionary.

Represents the interpolation between one point and one street segment end point and both came from non-User Dictionaries.

332 Spectrum

™

Technology Platform 9.0

ARn

API Guide

Code

n = 8 n = 9 n = A n = B n = C n = D n = E n = F n = 1

Chapter 8: Module Services

Description

Represents the interpolation between one street segment end point andone point, both coming from User Dictionaries.

Represents the interpolation between one street segment end point (low boundary) andone point

(high boundary). The low boundary came from a User

Dictionary and the high boundary from a non-User Dictionary.

Represents the interpolation between two street segment end points, both coming from User

Dictionaries.

Represents the interpolation between two street segment end points. The low boundary came from a User Dictionary and the high boundary from a non-User

Dictionary.

Represents the interpolation between one street segment end point (low boundary) and one point (high boundary). The low boundary came from a non-User

Dictionary and the high boundary from a User Dictionary.

Represents the interpolation between one street segment end point and one point, both coming from non-User Dictionary.

Represents the interpolation between two street segment end points. The low boundary came from a non-User Dictionary and the high boundary from a User

Dictionary.

Represents the interpolation between two street segment end points, both coming from non-User Dictionaries.

Ranged address geocode, where n is one of the following:

The geocode is placed along a single street segment, midway between the interpolated location

333

Enterprise Geocoding Module

Code

AXn n = 2 n = 4 n = 7 n = 3 n = 8

Description

of the first and second input house numbers in the range.

The geocode is placed along a single street segment, midway between the interpolated location of the first and second input house numbers in the range, and the side of the street is unknown.

The Census FIPS Block ID is assigned from the left side; however, there is no assigned offset and the point is placed directly on the street.

The input range spans multiple

USPS segments. The geocode is placed on the endpoint of the segment which corresponds to the first input house number, closest to the end nearest the second input house number.

Placeholder. Used when the starting and ending points of the matched segment contain the same value and shape data is not available.

Intersection geocode, where n is one of the following:

Standard single-point intersection computed from the center lines of street segments.

Interpolated (divided-road) intersection geocode. Attempts to return a centroid for the intersection.

Street Centroid Location Codes

Location codes that begin with "C" are street centroid location codes. Street centroid location codes indicate the Census ID accuracy and the position of the geocode on the returned street segment. Street centroids may be returned if the street centroid fallback option is enabled and an address-level geocode could not be determined.

A street centroid location code has the following characters.

1 st character Always C indicating a location derived from a street segment.

2 nd character Census ID accuracy based on the search area used to obtain matching Street Segment.

334 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

3 rd character Location of geocode on the returned street segment.

The following table contains the values and descriptions for the location codes.

Character position

2 nd

Character

Code Description

Block Group accuracy (most accurate). Based on input ZIP

Code.

Census Tract accuracy. Based on input ZIP Code.

Unclassified Census accuracy.

Normally accurate to at least the

County level. Based on input ZIP

Code.

Unknown Census accuracy.

Based on Finance area.

Unknown Census accuracy.

Based on input City.

3 rd

Character

Segment Centroid.

Segment low-range end point.

Segment high-range end point.

ZIP + 4 Centroid Location Codes

Location codes that begin with a "Z" are ZIP + 4 centroid location codes. ZIP + 4 centroids indicate a geocode could not be determined for the address, so the location of the center of the address's ZIP + 4 was returned instead. ZIP + 4 centroid location codes indicate the quality of two location attributes:

Census ID accuracy and positional accuracy.

A ZIP + 4 centroid location code has the following characters.

1 st character Always Z indicating a location derived from a ZIP centroid.

2 nd character

3 rd character

Census ID accuracy.

Location type.

4 th character How the location and Census ID was defined.

Provided for completeness, but may not be useful for most applications.

API Guide 335

Enterprise Geocoding Module

Table 118: ZIP + 4 Centroid Location Codes

Character Position

2 nd

Character

Code

3 rd

Character

336

4 th

Character

A a

Description

Block Group accuracy (most accurate).

Census Tract accuracy.

Unclassified Census accuracy.

Normally accurate to at least the

County level.

Location of the Post Office that delivers mail to the address, a

5-digit ZIP Code centroid, or a location based upon locale (city).

See the 4th character for a precise indication of locational accuracy.

Location based upon a ZIP + 2 centroid. These locations can represent a multiple block area in urban locations, or a slightly larger area in rural settings.

Location based upon a ZIP + 4 centroid. These are the most accurate centroids and normally place the location on the correct block face. For a small number of records, the location may be the middle of the entire street on which the ZIP + 4 falls. See the

4th character for a precise indication of locational accuracy.

Address matched to a single segment. Location assigned in the middle of the matched street segment, offset to the proper side of the street.

Address matched to a single segment, but the correct side of the street is unknown. Location assigned in the middle of the matched street segment, offset to the left side of the street, as address ranges increase.

Spectrum

™

Technology Platform 9.0

Character Position Code

B b

API Guide

D d

Chapter 8: Module Services

Description

Address matched to multiple segments, all segments have the same Block Group. Location assigned to the middle of the matched street segment with the most house number ranges within this ZIP + 4. Location offset to the proper side of the street.

Same as methodology B except the correct side of the street is unknown. Location assigned in the middle of the matched street segment, offset to the left side of the street, as address ranges increase.

Address matched to multiple segments, with all segments having the same Census Tract.

Returns the Block Group representing the most households in this ZIP + 4. Location assigned to t he middle of the matched street segment with the most house number ranges within this

ZIP + 4. Location offset to the proper side of the street.

Same as methodology C except the correct side of the street is unknown. Location assigned in the middle of the matched street segment, offset to the left side of the street, as address ranges increase.

Address matched to multiple segments, with all segments having the same County. Returns the Block Group representing the most households in this ZIP + 4.

Location assigned to the middle of the matched street segment with the most house number ranges within this ZIP + 4.

Location offset to the proper side of the street.

Same as methodology D except the correct side of the street is unknown. Location assigned in the middle of the matched street segment, offset to the left side of

337

Enterprise Geocoding Module

Character Position Code

338

Description

the street, as address ranges increase.

Street name matched; no house ranges available. All matched segments have the same Block

Group. Location placed on the segment closest to the center of the matched segments. In most cases, this is on the mid-point of the entire street.

Street name matched; no house ranges available. All matched segments have the same Census

Tract. Location placed on the segment closest to the center of the matched segments. In most cases, this is on the mid-point of the entire street.

Street name matched (no house ranges available). All matched segments have the same County.

Location placed on the segment closest to the center of the matched segments. In most cases, this is on the mid-point of the entire street.

Same as methodology G, but some segments are not in the same County. Used for less than

.05% of the centroids.

Created ZIP + 2 cluster centroid as defined by methodologies A, a, B, and b. All centroids in this

ZIP + 2 cluster have the same

Block Group. Location assigned to the ZIP + 2 centroid.

Created ZIP + 2 cluster centroid as defined by methodologies A, a, B, b, C, and c. All centroids in this ZIP + 2 cluster have the same Census Tract. Location assigned to the ZIP + 2 centroid.

Created ZIP + 2 cluster centroid as defined by methodologies A, a, B, b, C, c, D, and d. Location assigned to the ZIP + 2 centroid.

Created ZIP + 2 cluster centroid as defined by methodology E. All

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Character Position Code

Description

centroids in this ZIP + 2 cluster have the same Block Group.

Location assigned to the ZIP + 2 centroid.

Created ZIP+2 cluster centroid as defined by methodology E and F.

All centroids in this ZIP + 2 cluster have the same Census Tract.

Location assigned to the ZIP + 2 centroid.

Created ZIP + 2 cluster centroid as defined by methodology E, F,

G, and H. Location assigned to the ZIP + 2 centroid.

Over 95% of addresses in this

ZIP Code are in a single Census

Tract. Location assigned to the

ZIP Code centroid.

Over 80% of addresses in this

ZIP Code are in a single Census

Tract. Reasonable Census Tract accuracy. Location assigned to the ZIP Code centroid.

Less than 80% of addresses in this ZIP Code are in a single

Census Tract. Census ID is uncertain. Location assigned to the ZIP Code centroid.

Rural or sparsely populated area.

Census code is uncertain.

Location based upon the USGS places file.

P.O. Box or General Delivery addresses. Census code is uncertain. Location based upon the Post Office location that delivers the mail to that address.

Geographic Centroid Location Codes

Location codes that begin with "G" are geographic centroid location codes. Geographic centroids may be returned if the street centroid fallback option is enabled and an address-level geocode could not be determined. Geographic centroid location codes indicate the quality a city, county, or state centroid.

A geographic centroid location code has the following characters.

1 st character Always G indicating a location derived from a geographic centroid.

API Guide 339

Enterprise Geocoding Module

2 nd character Geographic area type. One of the following:

Municipality (for example, a city)

County

State

Address Unavailable

Location codes that begin with "E" indicate that neither an address location nor a ZIP + 4 centroid could be determined. This usually occurs when you have requested ZIP Code centroids of a high quality, and one is not available for that match.

An unavailable address code has the following characters.

Table 119: Match Codes for No Match

Code

Ennn nnn = 000 nnn = 001 nnn = 002 nnn = 003 nnn = 004 nnn = 010 nnn = 011 nnn = 012 nnn = 013 nnn = 014 nnn = 015

Description

Indicates an error, or no match.

This can occur when the address entered does not exist in the database, or the address is badly formed and cannot be parsed correctly. The last three digits of an error code indicate which parts of an address the application could not match to the database.

No match made.

Low level error.

Could not find data file.

Incorrect GSD file signature or version ID.

GSD file out of date. Only occurs in CASS mode.

No city and state or ZIP Code found.

Input ZIP not in the directory.

Input city not in the directory.

Input city not unique in the directory.

Out of licensed area. Only occurs if using Pitney Bowes Software licensing technology.

Record count is depleted and license has expired.

340 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Code

nnn = 020 nnn = 021 nnn = 022 nnn = 023 nnn = 024 nnn = 025 nnn = 026 nnn = 027 nnn = 028 nnn = 029 nnn = 030

Description

No matching streets found in directory.

No matching cross streets for an intersection match.

No matching segments.

Unresolved match.

No matching segments. (Same as 022.)

Too many possible cross streets for intersection matching.

No address found when attempting a multiline match.

Invalid directional attempted.

Record also matched EWS data, therefore the application denied the match.

No matching range, single street segment found.

No matching range, multiple street segments found.

Geocoding Match Codes

Geocoding components return match codes indicating the address portions that matched or did not match to the database. If the geocoder cannot make a match, the match code begins with E and the remaining digits indicate why the address did not match. The digits do not specifically refer to which address elements did not match, but rather why the address did not match.

Table 120: Match Codes

D00

Gxx

Hhh

Code

Ahh

Chh

Description

Same as Shh, but indicates match to an alias name record or an alternate record.

The street address did not match, but the geocoder located a street segment based on the input ZIP

Code or city

Matched to a small town with P.O. Box or General

Delivery only.

Matched to an auxiliary file.

The house number was changed.

API Guide 341

Enterprise Geocoding Module

342

Code

Jhh

Nxx

Qhh

Rhh

Shh

Thh

Uhh

Xhhh

Yhhh

Description

Matched to a user-defined dictionary.

Matched to the nearest address. Used with reverse geocoding. The following are the only values for N:

NSO

Nearest street center match

(nearest street segment interpolated)

NS1

NP0

NX0

Nearest unranged street segment

Nearest point address

Nearest intersection

Successful reverse APN lookup.

Matched to USPS range records with unique ZIP

Codes. CASS rules prohibit altering an input ZIP if it matches a unique ZIP Code value.

Matched to a ranged address.

Matched to USPS data. This is considered the best address match, because it matched directly against the USPS list of addresses. S is returned for a small number of addresses when the matched address has a blank ZIP + 4.

Matched to a street segment record. Street segment records do not contain ZIP Code information. If you enter a ZIP Code, the application returns the ZIP Code you entered. If the input city and state has only one ZIP Code, the application returns that ZIP Code.

Matched to USPS data but cannot resolve the ZIP

+ 4 code without the firm name or other information.

CASS mode returns an E023 (multiple match) error code.

Matched to an intersection of two streets, for example, "Clay St & Michigan Ave." The first hex digit refers to the last line information, the second hex digit refers to the first street in the intersection, and the third hex digit refers to the second street in the intersection.

Note:

The USPS does not allow intersections as a valid deliverable address.

Same as Xhhh, but an alias name record was used for one or both streets.

No address given, but verified the provided ZIP

Code .

The following table contains the description of the hex digits for the match code values.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Table 121: Description of Hex Digits

Code

In first hex position means: In second and third hex position means:

No change in last line.

ZIP Code changed.

City changed.

No change in address line.

Street type changed.

Predirectional changed.

City and ZIP Code changed.

State changed.

State and ZIP Code changed.

State and City changed.

Street type and predirectional changed.

Postdirectional changed.

Street type and postdirectional changed.

Predirectional and postdirectional changed.

Street type, predirectional, and postdirectional changed.

Street name changed.

State, City, and ZIP Code changed.

ZIP + 4 changed.

ZIP and ZIP + 4 changed.

City and ZIP + 4 changed.

Street name and street type changed.

Street name and predirectional changed.

City, ZIP, and ZIP + 4 changed.

Street name, street type, and predirectional changed.

State and ZIP + 4 changed.

Street name and postdirectional changed.

State, ZIP, and ZIP + 4 changed.

Street name, street type, and postdirectional changed.

State, City, and ZIP + 4 changed.

Street name, predirectional, and postdirectional changed.

State, City, ZIP, and ZIP + 4 changed.

Street name, street type, predirectional, and postdirectional changed.

If neither an address location nor a ZIP + 4 centroid can be determined, the location code will start with

"E". This occurs infrequently when the component does not have a 5-digit centroid location. Enterprise

Geocoding Module components can also return an E location code type when it cannot standardize an input address and there is no input ZIP Code. In this case, do not assume the ZIP Code returned with the non-standardized address is the correct ZIP Code because the component did not standardize the address; therefore, the component does not return geocoding or Census Block information.

API Guide 343

Enterprise Geocoding Module

Table 122: Match Codes for No Match

Code

Ennn

344

nnn = 000 nnn = 001 nnn = 002 nnn = 003 nnn = 004 nnn = 010 nnn = 011 nnn = 012 nnn = 013 nnn = 014 nnn = 015 nnn = 020 nnn = 021 nnn = 022 nnn = 023 nnn = 024 nnn = 025 nnn = 026

Description

Indicates an error, or no match.

No match made.

Low level error.

Could not find data file.

Incorrect GSD file signature or version ID.

GSD file out of date. Only occurs in CASS mode.

No city and state or ZIP Code found.

Input ZIP not in the directory.

Input city not in the directory.

Input city not unique in the directory.

Out of licensed area. Only occurs if using Pitney Bowes Software licensing technology.

Record count is depleted and license has expired.

No matching streets found in directory.

No matching cross streets for an intersection match.

No matching segments.

Unresolved match.

No matching segments. (Same as 022.)

Too many possible cross streets for intersection matching.

No address found when attempting a multiline match.

Spectrum

™

Technology Platform 9.0

Code

nnn = 027 nnn = 028 nnn = 029 nnn = 030

Chapter 8: Module Services

Description

Invalid directional attempted.

Record also matched EWS data, therefore the application denied the match.

No matching range, single street segment found.

No matching range, multiple street segments found.

Match Codes for U.S. Geocoding

Geocoding Match Codes

Table 123: Match Codes

D00

Gxx

Hhh

Jhh

Nxx

Code

Ahh

Chh

Description

Same as Shh, but indicates match to an alias name record or an alternate record.

The street address did not match, but the geocoder located a street segment based on the input ZIP

Code or city

Matched to a small town with P.O. Box or General

Delivery only.

Matched to an auxiliary file.

The house number was changed.

Matched to a user-defined dictionary.

Matched to the nearest address. Used with reverse geocoding. The following are the only values for N:

NSO

Nearest street center match

(nearest street segment interpolated)

NS1

NP0

NX0

Nearest unranged street segment

Nearest point address

Nearest intersection

API Guide 345

Enterprise Geocoding Module

Code

Qhh

Rhh

Shh

Thh

Uhh

Xhhh

Yhhh

Description

Successful reverse APN lookup.

Matched to USPS range records with unique ZIP

Codes. CASS rules prohibit altering an input ZIP if it matches a unique ZIP Code value.

Matched to a ranged address.

Matched to USPS data but cannot resolve the ZIP

+ 4 code without the firm name or other information.

CASS mode returns an E023 (multiple match) error code.

Note:

The USPS does not allow intersections as a valid deliverable address.

Same as Xhhh, but an alias name record was used for one or both streets.

No address given, but verified the provided ZIP

Code .

The following table contains the description of the hex digits for the match code values.

Table 124: Description of Hex Digits

Code In first hex position means: In second and third hex position means:

No change in last line.

ZIP Code changed.

City changed.

No change in address line.

Street type changed.

Predirectional changed.

346 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Code

In first hex position means: In second and third hex position means:

City and ZIP Code changed.

State changed.

State and ZIP Code changed.

State and City changed.

Street type and predirectional changed.

Postdirectional changed.

Street type and postdirectional changed.

Predirectional and postdirectional changed.

State, City, and ZIP Code changed.

Street type, predirectional, and postdirectional changed.

Street name changed.

ZIP + 4 changed.

ZIP and ZIP + 4 changed.

Street name and street type changed.

City and ZIP + 4 changed.

City, ZIP, and ZIP + 4 changed.

Street name and predirectional changed.

Street name, street type, and predirectional changed.

State and ZIP + 4 changed.

Street name and postdirectional changed.

State, ZIP, and ZIP + 4 changed.

Street name, street type, and postdirectional changed.

State, City, and ZIP + 4 changed.

Street name, predirectional, and postdirectional changed.

State, City, ZIP, and ZIP + 4 changed.

Street name, street type, predirectional, and postdirectional changed.

If neither an address location nor a ZIP + 4 centroid can be determined, the location code will start with

"E". This occurs infrequently when the component does not have a 5-digit centroid location. Enterprise

Table 125: Match Codes for No Match

Code

Ennn

Description

Indicates an error, or no match.

This can occur when the address entered does not exist in the database, or the address is badly formed and cannot be parsed correctly. The last three digits of

API Guide 347

Enterprise Geocoding Module

Code

348

nnn = 015 nnn = 020 nnn = 021 nnn = 022 nnn = 023 nnn = 024 nnn = 025 nnn = 026 nnn = 027 nnn = 028 nnn = 029 nnn = 000 nnn = 001 nnn = 002 nnn = 003 nnn = 004 nnn = 010 nnn = 011 nnn = 012 nnn = 013 nnn = 014

Description

an error code indicate which parts of an address the application could not match to the database.

No match made.

Low level error.

Could not find data file.

Incorrect GSD file signature or version ID.

GSD file out of date. Only occurs in CASS mode.

No city and state or ZIP Code found.

Input ZIP not in the directory.

Input city not in the directory.

Input city not unique in the directory.

Out of licensed area. Only occurs if using Pitney Bowes Software licensing technology.

Record count is depleted and license has expired.

No matching streets found in directory.

No matching cross streets for an intersection match.

No matching segments.

Unresolved match.

No matching segments. (Same as 022.)

Too many possible cross streets for intersection matching.

No address found when attempting a multiline match.

Invalid directional attempted.

Record also matched EWS data, therefore the application denied the match.

No matching range, single street segment found.

Spectrum

™

Technology Platform 9.0

Code

nnn = 030

Chapter 8: Module Services

Description

No matching range, multiple street segments found.

Result Codes for International Geocoding

Candidates returned by Spectrum geocoders return another class of return codes that are referred to as International Geocoding Result Codes. Each attempted match returns a result code in the

Geocoder.MatchCode output field.

International Street Geocoding Result Codes (S Codes)

Street level geocoded candidates return a result code beginning with the letter S. The second character in the code indicates the positional accuracy of the resulting point for the geocoded record.

Table 126: Street (S ) Result Codes

S Result Code

Description

Single close match with the point located at postal code centroid.

Single close match with the point located at the street centroid. The S4 code is followed by letters and dashes indicating match precision. see

Interpreting S

Result Codes

on page 349

Single close match with the point located at a street address position. The S5 code is followed by letters and dashes indicating match precision. For information about these letters, see

Interpreting S Result Codes

on page 349.

Single close match with the point located at centroid of geometry postal code. (For example, large buildings having their own codes.)

Single match with the point located at an interpolated point along the candidate's street segment. When the potential candidate is not an address point candidate and there are no exact house number matches among other address point candidates, the S7 result is returned using address point interpolation. The point is interpolated according to the next highest or lowest address point candidate that both intersects the segment and whose house number is contained within the range of houses of the original candidate. By using known address reference points on the street segment, the S7 point can be adjusted to a more accurate position.

Single close match with the point located at either the single point associated with an address point candidate or at an address point candidate that shares the same house number. No interpolation is required.

Single close match with the point located at street intersection.

Interpreting S Result Codes

For S (street geocoded) international result codes, eight additional characters describe how closely the address matches an address in the database. The characters appear in the order listed in the following table. Any non-matched components are represented by a dash.

For example, the result code S5--N-SCZA represents a single close match that matched the street name, street suffix direction, town, and postcode. The dashes indicate that there was no match on house number, street prefix direction, or thoroughfare type. The match came from the Street Range Address database. This record would be geocoded at the street address position of the match candidate.

API Guide 349

Enterprise Geocoding Module

Category

A, G, or U

Description Example

House number 18

Street prefix direction

P is present if any of these conditions are satisfied:

North

• The candidate pre-directional matches the input pre-directional.

• The candidate post-directional matches the input pre-directional after pre- and post-directionals are swapped.

• The input does not have a pre-directional.

Street name

Street type

Merivale

Street suffix direction

S in result code is present if any of these conditions are satisfied:

• The candidate post-directional matches the input post-directional.

• The candidate pre-directional matches the input post-directional after pre- and post-directionals are swapped.

• The input does not have a post-directional.

City name

Postal code

Database type used to obtain the match.

• A—Street Range Address database.

• U—Customer (user-defined) database.

South Brisbane

4101

350

International Postal Geocoding Result Codes (Z Codes)

Matches in the Z category indicate that a match was made at the postcode level. A postcode match is returned in either of these cases:

• You specified to match to postal code centroids. The resulting point is located at the postal code centroid with the following possible accuracy levels.

• There is no street level close match and you specified to fall back to postal code centroid.

Table 127: Postal (Z) Result Codes

Z Result Code

Description

Postal Code centroid match.

Full postal code centroid match. For Canada, this is an FSALDU centroid.

Postal level geocoded candidates return a result code beginning with the letter Z. Geocode Address

World can generate a Z1 result code. Country-specific geocoders can often generate more accurate postcode results (with Z2 or Z3 result codes).

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

International Geographic Geocoding Result Codes (G Codes)

Geographic level geocoded candidates return a result code beginning with the letter G. The numbers following the G in the result code provides more detailed information on the accuracy of the candidate.

Table 128: Geographic (G) Result Codes

G Result Code

Description

State or province centroid. match.

County (district or region) centroid match.

City or town (municipality) centroid match.

Locality (village, suburb, or neighborhood) centroid match.

Reverse Geocoding Codes (R Codes)

Matches in the R category indicate that the record was matched by reverse geocoding. The second two characters of the R result code indicate the type of match found. R geocode results include an additional letter to indicate the dictionary from which the match was made.

Example reverse geocoding codes:

Table 129: Reverse Geocoding (R) Result Codes

Reverse Geocoding Code Description

RS8A

RS5A

RS4A

Point/parcel level precision for reverse geocoding. Candidate returned from address dictionary.

Interpolated street candidate for reverse geocoding. Candidate returned from address dictionary.

Street centroid candidate for reverse geocoding. Candidate returned from address dictionary.

Non-match Codes

The following result codes indicate no match was made:

• N—No close match.

• NX—No close match for street intersections.

• ND—Spectrum

™

Technology Platform could not find the geocoding database for the given postal code or municipality/state/province.

Encountering False Positives

What is a False-Positive?

To prevent the generation of address lists, the DPV and LACS

Link databases include false-positive records. False-positive records are artificially manufactured addresses that reside in a false-positive table. For each negative response that occurs in a DPV or LACS

Link query, a query is made to the false-positive table. A match to this table (called a false-positive match) disables your DPV or LACS

Link key. In batch processing the job that contains the violation will complete successfully but you will not be

API Guide 351

Enterprise Geocoding Module

able to run any subsequent jobs that use DPV or LACS

Link to reactivate DPV or LACS

Link

until you report the violation and obtain a key

Note:

The term "seed record violation" is also used to refer to encountering false positive records. The two terms mean the same thing.

Position

1-40

41-98

99-126

127-128

129-137

138-146

147-155

Reporting DPV False-Positive Violations

Spectrum

™

Technology Platform indicates a false-positive match via messages in the server log.

Client/server calls throw an exception if a false-positive match occurs. When a DPV fals positive record violation occurs, the server log will say:

WARN [Log] Seed record violation for S<ZIP, ZIP+4, Address, Unit> ERROR

[Log] Feature Disabled: DPU: DPV Seed Record Violation. Seed Code:

S<Address, ZIP, ZIP+4, Unit>

Note:

If a DPV false positive record is found, the process() method (COM, C++, Java, and .NET) will throw an exception that the feature DPU has been disabled. In C, the processMessage() function will return a non-zero value.

You can report the violation and obtain a restart key by following these steps.

1. In your browser, go to http://<yourserver>:<port>/<product code>/dpv.jsp. For example, http://localhost:8080/unc/dpv.jsp for the Universal Addressing Module and http://localhost:8080/geostan/dpv.jsp for the Enterprise Geocoding Module.

2. Enter the mailer's information into each field. The number in parentheses after each field name indicates the maximum length of the field.

3. Click Submit when you're done. A File Download dialog will appear.

4. Click Save to save the file to your computer. A Save As dialog will appear.

5. Specify a file name and location on your local hard drive (for example c:\DPVSeedFile.txt) and click Save.

6. Go to

www.g1.com/support

and log in.

7. Click DPV & LACS

Link

False Positive.

8. Follow the on-screen instructions to attach your seed file and obtain a restart key.

DPV False Positive Header File Layout

The USPS

® has determined the required layout of the DPV false-positive header file, which is currently defined as a fixed-length file containing two or more 180-byte records. The first record must always be the header record, whose layout is shown below.

Table 130: DPV False-Positive Header Record Layout

Length

Description

Mailer's company name

Mailer's address line

Mailer's city name

Mailer's state abbreviation

Mailer's 9-digit ZIP Code

Total Records Processed

Total Records DPV Matched

Format

Alphanumeric

Alphabetic

Numeric

352 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Position

1-2

3-30

31-34

35-36

37-46

47-50

51-58

59-63

64-67

68-180

Position

156-164

165-173

174-178

179-180

Length

Description

Percent Match Rate to DSF

Percent Match Rate to ZIP + 4

Number of ZIP Codes on file

Number of False-Positives

Format

Numeric

The trailer record contains information regarding the DPV false-positive match. There must be one trailer record added to the false-positive file for every DPV false-positive match. The layout is shown below.

Table 131: DPV False-Positive Trailer Record Layout

Length

113

Description

Street predirectional

Street name

Street suffix abbreviation

Street postdirectional

Address primary number

Address secondary abbreviation

Address secondary number

Matched ZIP Code

Matched ZIP + 4

Filler

Format

Alphanumeric

Numeric

Spaces

Reporting LACS/Link False-Positive Violations

Spectrum

™

Technology Platform indicates a false-positive match via messages in the server log. Batch jobs will fail if a false-positive match occurs and client/server calls will throw an exception.

Note:

The term "seed record violation" is also used to refer to encountering false positive records. The two terms mean the same thing.

When a false positive record is encountered, the server log will say:

2005-05-06 17:05:38,978 WARN [com.g1.component.ValidateAddress] Seed record violation for RR 2 28562 31373

2005-05-06 17:05:38,978 ERROR [com.g1.component.ValidateAddress] Feature

Disabled: LLU: LACS Seed Record Violation. Seed Code: 28562 31373

2005-05-06 17:05:38,978 ERROR [com.g1.dcg.gateway.Gateway] Gateway exception: com.g1.dcg.stage.StageException: com.g1.dcg.component.ComponentException: Feature Disabled: LLU

2005-05-06 17:06:30,291 ERROR

[com.pb.spectrum.platform.server.runtime.core.license.impl.policy.Policy]

Feature LACSLink Real- time is disabled.

API Guide 353

Enterprise Tax Module

Note:

If a LACS

Link false positive record is found, the process() method (COM, C++, Java, and .NET) will throw an exception that the feature LLU has been disabled. In C, the processMessage() function will return a non-zero value.

1. In your browser, go to http://<ServerName>:<port>/<product code>/lacslink.jsp. For example, http://localhost:8080/unc/lacslink.jsp for the Universal Addressing Module and http://localhost:8080/geostan/lacslink.jsp for the Enterprise Geocoding Module.

2. Enter the mailer's information into each field. The number in parentheses after the field name indicates the maximum length of the field. Click Submit when you're done. A File Download dialog will appear.

3. Click Save to save the file to your computer. A Save As dialog will appear.

4. Specify a file name and location on your local hard drive (for example c:\lacslink.txt) and click

Save.

5. Go to

www.g1.com/support

and log in.

6. Click DPV & LACS

Link

False Positive.

7. Follow the on-screen instructions to attach your seed file and obtain a restart key.

Enterprise Tax Module

What Is the Enterprise Tax Module?

The Enterprise Tax Module determines the tax jurisdiction for an address. The Enterprise Tax Module takes a standardized address and matches it to an exact physical location, returning latitude/longitude coordinates with the correct place code for the address. This solution greatly reduces the inaccuracies associated with 9-digit and 5-digit ZIP Code-based matching.

The Enterprise Tax Module uses a database of tax jurisdictions provided by TomTom. This data, which is collected through an ongoing research program and updated regularly, provides current jurisdictional boundary information down to the municipal and special tax district levels.

The Enterprise Tax Module can also calculate latitude/longitude coordinates for individual address locations, including the use of interpolation and offset.

Note:

The Enterprise Tax Module processes only U.S. addresses. Before using the Enterprise Tax

Module, you need to standardize your address data using a product such as the Universal

Addressing Module.

Enterprise Tax Components

The Enterprise Tax Module consists of the following components.

• AssignGeoTAXInfo - Takes an input address and returns census, latitude/longitude, and tax information about the address. AssignGeoTAXInfo utilizes Pitney Bowes Software's GeoTAX technology.

• CalculateDistance - Takes two latitude/longitude coordinates as input and computes and returns the distance between the coordinates.

Enterprise Tax Databases

The Enterprise Tax Module provides you with several different databases, along with the ability to include additional databases to match against your input addresses.

354 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Table 132: Enterprise Tax Module Databases

Database Name & Description Required or

Optional

GeoTAX Master Files

The master files are the main data files used by the Enterprise

Tax module. They identify all geographic components associated with a street address, such as the latitude/longitude, census tract, and block group. This file, at over two gigabytes of data, is significantly larger than the postal file, but provides the greatest coding accuracy.

The master files are on the disc labeled GeoTAX Subscription.

Required

State-Supplied Files

State-supplied files are provided by individual state governments that the Enterprise Tax Module uses to override results from the master files.

Optional

The Enterprise Tax Module provides you with the ability to override, at the state level, match results based upon information supplied by the states. By matching to the state-supplied files, you can remain compliant with tax jurisdiction assignment requirements mandated by new federal and state laws, such as the Mobile Telecommunications Sourcing Act and the Florida state Communications Services Tax Simplification Law.

Currently, there are two file formats supported in the Enterprise

Tax Module: the Florida-native format, and the national TS-158 format (ANSI Transaction Set No. 158). The state of Florida provides address files in both the TS-158 and its own native format. The state of Washington provides address data in the

TS-158 format.

Note:

This database option may not be available to all

Enterprise Tax users. Individual states may restrict the use of state-supplied address files to licensed communications carriers or other business entities registered with the individual state.

The Enterprise Tax Module first attempts to match to the state database. If the Enterprise Tax Module cannot find a state match, it attempts a match to the master files.

GeoTAX Auxiliary File

The GeoTAX Auxiliary file contains new addresses that have not yet been added to the Master File. It provides the most up-to-date address data possible.

Optional

User Auxiliary File

User Auxiliary files are user-defined files that the Enterprise Tax

Module uses to override results from the master files in street-level matching. If you have data that is more current than that in the master files, you can enter the new data into the auxiliary file and use it for your address matching. The Enterprise

Tax Module returns matches made with a code that signifies the

Optional

Supplier

Pitney Bowes

Software monthly subscription

State

Governments

Pitney Bowes

Software monthly subscription

User-defined

API Guide 355

Enterprise Tax Module

356

Database Name & Description Required or

Optional

answer came from the auxiliary file. You can also return user-defined data from the auxiliary file with the match.

Boundary Files

Boundary files provide additional data about locations of special tax districts: Special Purpose Tax Districts (SPDs), Insurance

Premium Tax Districts (IPDs), Payroll Tax Districts (PAYs), and

Personal Property Tax Districts (PTDs).

Optional

• The Special Purpose District (SPD) file provides you with return data on special purpose tax districts. Special purpose tax districts include such districts as Regional Transit Areas and Metropolitan Football districts.

• The Insurance Premium District (IPD) file is used by the insurance industry to determine sales tax on insurance premiums written in some states. This file allows insurers to correctly determine the rate due on each insurance policy.

Boundaries vary by state and are based on fire and police district and municipal boundaries.

• The Payroll Tax District (PAY) file can help your company comply with state legislation that requires employers to deduct taxes from employee paychecks for special districts, such as taxes for emergency municipal services districts.

• The Personal Property Tax District (PTD) file provides your company with a complete solution for accurate, automated asset collection and jurisdiction assignment.

Pitney Bowes Software provides you with the appropriate boundary file on separate media if you license any of the optional files.

Note:

The Enterprise Tax Module only loads one boundary file at a time. For more information, see the configuration options in

AssignGeoTAXInfo

on page 357.

User-Defined Boundary Files

A user-defined boundary file is a file that you create to represent polygons that you want to match against, such as sales territories, insurance rating territories, or any geographic areas that are of interest to you.

Optional

Sales Tax Cross-Reference Files

Sales tax cross-reference files allow you to use the Enterprise

Tax Module to determine tax jurisdictions for a given address, then use third-party software to determine the sales tax rates for those jurisdictions. The cross-reference files combine the

U.S. Government Federal Information Processing Standards

(FIPS) codes with the proprietary geocodes used by tax software from third parties.

Optional

• Vertex Files—The Vertex files enable you to integrate the

Enterprise Tax Module with tax compliance software from

Vertex, Inc. With this file, the Enterprise Tax Module component AssignGeoTAXInfo can return the nine-digit Vertex

Supplier

Pitney Bowes

Software

User-created

Pitney Bowes

Software

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Supplier Database Name & Description Required or

Optional

jurisdiction code for an address. You can then match these codes to the Vertex tax tables, which tell you the tax rate for each jurisdiction. To use the Vertex file you must have either the MatchMaster file from Vertex or the PBBI Vertex file from

Pitney Bowes Software to build the cross reference.

• Taxware Files—The Taxware files enable you to integrate the Enterprise Tax Module with tax compliance software from

ADP/Taxware. With this file, the Enterprise Tax Module component AssignGeoTAXInfo can return the Taxware jurisdiction code for an address. You can then match these codes to the Taxware tax tables, which tell you the tax rate for each jurisdiction. The Taxware files are supplied by Pitney

Bowes Software and support both the SUT and TWE Taxware versions.

Payroll Tax Cross-Reference Files

Payroll tax cross-reference files allow you to use third-party software to determine the payroll tax rates. The cross-reference files combine the U.S. Government Federal Information

Processing Standards (FIPS) codes with the proprietary geocodes used by tax software from third parties. The Payroll

System Tax Code file is a customized file that you build to return the payroll tax codes used by your payroll system. For more information, see

AssignGeoTAXInfo

on page 357.

Optional Pitney Bowes

Software

AssignGeoTAXInfo

AssignGeoTAXInfo identifies the tax districts that apply to a given address. Specifically, AssignGeoTAXInfo returns this information about an address:

• Latitude/longitude

• FIPS state codes and county codes

• County names

• MCD/CCD codes and names

• Place codes and names

• Incorporated or unincorporated status codes

• Cross-reference tax keys

• Result indicators

• Optionally, the relationship of an address to user-defined polygons

AssignGeoTAXInfo optionally includes enhanced tax jurisdiction information for an address, including:

• Insurance premium districts—Areas designated for the collection of taxes imposed on insurance policy premiums, based on the policy holder's address. Insurance premium districts are created by state governments.

• Payroll tax districts—Areas designated for the collection of taxes imposed on employers to support state or local government facilities and services, based on the employee's and/or employer's address.

Examples include taxes collected for districts to pay for schools, police, or other services. Payroll tax districts are created by state or local governments.

• Payroll system tax codes—Codes that represent specific jurisdictions that collect payroll tax. Using payroll system tax codes has advantages over using the payroll tax district information returned by

Assign GeoTAX Info:

API Guide 357

Enterprise Tax Module

• AssignGeoTAXInfo uses an additional database to determine payroll tax codes, resulting in more accurate payroll tax determination.

• Many payroll systems use specific codes to determine withholding amounts. Since you can customize the payroll tax codes returned by AssignGeoTAXInfo, you can set up a process where

AssignGeoTAXInfo returns the exact payroll tax codes required by your payroll system, instead of returning jurisdictional IDs that must then be translated into the codes used by your system.

• Property tax districts—Areas designated for the collection of taxes imposed on property owners to support local government facilities and services, based on the property's location. Examples include taxes collected for districts to pay for schools, police, or other services. Property tax districts are created by local governments.

• Special purpose tax districts—Areas designated for the collection of taxes imposed on residents to support specialized services for residents of the district, based on the resident's address. Examples include services such as sewer service, transit service, or water resources. Special purpose tax districts are created by legislative action, court action, or public referendums. This optional information requires the use of boundary files which require an additional license. Contact your Pitney Bowes Software sales representative for more information.

AssignGeoTAXInfo is part of the Enterprise Tax Module.

Determining Tax Rates with AssignGeoTAXInfo

AssignGeoTAXInfo does not determine tax rates, it determines tax jurisdictions that apply to a given location. You must use other software or a custom process to determine the tax rates for the jurisdictions returned by AssignGeoTAXInfo. There are two ways of determining tax rates: use software from Vertex or ADP/Taxware, or look up tax rates using your own custom process

• Using Vertex or ADP/Taxware Software a) Click the Data tab.

b) Under Include data, select the Tax Jurisdiction check box. This option returns several tax jurisdiction fields. The GeoTAXKey field contains the Vertex or Taxware code. For more information on these fields, see

Tax Jurisdiction

on page 383.

c) In the Sales tax cross-reference key field, select Vertex MatchMaster or PBBI Vertex to have AssignGeoTAXInfo return a Vertex key, or select Taxware to have AssignGeoTAXInfo return a Taxware key.

• Using a Custom Process

If your organization has defined custom tax codes, you can use the jurisdiction information returned by AssignGeoTAXInfo to look up the tax jurisdictions in your custom tables. To do this, you need to configure AssignGeoTAXInfo to return the following fields:

• StateCode

• County.Code

• GNISCode

• SPDn.DistrictCode

To include these fields in the output, a) Click the Data tab.

b) Under Include data, select the Census check box. This option returns the StateCode,

County.Code, and GNISCode fields that you will need to look up tax rates. For more information on these fields, see

Census

on page 369.

c) In the Tax district field, select Special Purpose District. This option returns the

SPDnDistrictCode field that you will need to look up tax rates, as well as several other fields that describe any special purpose districts that apply to the location. For more information, see

Special

Purpose Tax District

on page 382.

Address Matching

AssignGeoTAXInfo takes a house address and matches it to the correct street segment. Using the house number, it determines the side of the street on which the house resides (usually based on an odd-even division). Knowing the correct side of the street is important because streets are often the boundaries

358 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

between municipalities or other adjoining jurisdictions that may have different tax rates. Thus, two addresses on the same street, in the same city, within the same ZIP Code could exist in different jurisdictions and have different tax rates.

After AssignGeoTAXInfo knows the correct street segment, it determines the actual physical location of the house based on known latitudes/longitudes and other geographic data in the street segment database.

AssignGeoTAXInfo returns the coordinates of the house, along with other data.

Note:

Before using AssignGeoTAXInfo, you need to standardize your address data using a product such as the Universal Addressing Module.

Buffering

Use buffering to define areas that are close to the edges of a polygon, line, or point.

Buffered Polygon (zone) Buffered Line (corridor) Buffered Point (circle)

For example, if you work for an insurance company you may want to know if a potential customer's house is within 500 feet of a flood plain so that you can suggest that they buy flood insurance even though they are not actually within the flood plain. The following illustration shows this scenario using a buffered polygon. The dotted line indicates the boundary of the flood plain and the shaded area shows a 500-foot buffer zone around the boundary.

The buffer area extends on both sides of the boundary (inside and outside). When you use buffering, the output field BufferRelation indicates whether or not the point is in the buffered zone, and whether the point is inside or outside of the polygon, as shown in the following illustrations.

The point is inside the polygon and not in the buffer area.

The output field BufferRelation will contain "P".

The point is inside the polygon and in the buffer area.

The output field BufferRelation will contain "I".

The point is outside the polygon but in the buffer area.

The output field BufferRelation will contain "B".

Specify the size of polygon buffers using the BufferWidth input field to set it on a record-by-record basis and the DefaultBufferWidth option to set a default polygon buffer width for the job.

Input

The following table provides information on the format of AssignGeoTAXInfo input.

API Guide 359

Enterprise Tax Module

Note:

Specify input using the DataTable class. For information on the DataTable class, see the "API

Fundamentals" section.

Table 133: AssignGeoTAXInfo Input Data columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

BufferWidth

City

Country

FirmName

PostalCode

StateProvince

UserBufferWidth

Format Description

String

[100]

String

[100]

String

[100]

String

[100]

String

[10]

First address line

Second address line

Third address line

Fourth address line

String

[50]

String

[var]

Specifies the width of the polygon buffers to use for Boundary

File processing. The buffer width is used to determine if a point is close to the edge of a polygon. The output field

BufferRelation indicates whether or not the point is within the polygon's buffer area. For more information, see

Buffering

on page 359.

This field overrides the value specified in the

DefaultBufferWidth option. Specify the border width in the units specified by the DistanceUnits option.

If you do not specify a buffer width in this input field, the default is used.

City name

The country where the address resides. The data you enter in this field has no impact on processing. It is simply passed through to output.

Note:

AssignGeoTAXInfo only supports US addresses.

String

[var]

Company or firm name

String [9] Nine-digit ZIP Code

String

[50]

Long

[10]

The state where the address resides. The data you enter in this field has no impact on processing. It is simply passed through to output.

Specifies the width of the polygon buffers to use for

User-Defined Boundary File processing. The buffer width is used to determine if a point is close to the edge of a polygon.

The output field BufferRelation indicates whether or not the point is within the polygon's buffer area. For more information, see

Buffering

on page 359.

360 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Format Description

This field overrides the value specified in the

DefaultBufferWidth option. Specify the border width in the units specified by the DistanceUnits option.

If you do not specify a buffer width in this input field, the default is used.

Options

Data

Data options control the data returned by AssignGeoTAXInfo.

Table 134: AssignGeoTAXInfo Data

Options

on page 361 lists the output data options.

Table 134: AssignGeoTAXInfo Data Options optionName

Database.GTX

UseStreetLevelMatching

UseGeoTaxAuxiliaryFile

UseAuxiliaryFile

UseStateProvidedFile

Description

The name of the database resource that contains the data to use in the search process. Use the database name specified in the Management

Console's Database Resources tool. For more information, see the

Spectrum

™

Technology Platform Administration Guide.

Specifies whether or not AssignGeoTAXInfo should attempt a match to the street level data.

Yes, use the street matcher (default).

No, do not use the street matcher.

Specifies whether or not AssignGeoTAXInfo should attempt a match to the GeoTAX Auxiliary file. The GeoTAX Auxiliary file contains new addresses that have not yet been added to the Master File.

Because matching to the GeoTAX Auxiliary file involves street-level matching, you must specify UseStreetLevelMatching=Y in order for this option to work.

Yes, attempt to match to GeoTAX Auxiliary file (default).

No, do not use the GeoTAX Auxiliary file.

Specifies whether or not AssignGeoTAXInfo should attempt a match to a User Auxiliary file. User Auxiliary files are user-defined files that the

Enterprise Tax Module uses to override results from the master files in street-level matching.

Because matching to the User Auxiliary file involves street-level matching, you must specify UseStreetLevelMatching=Y in order for this option to work.

Yes, attempt to match to User Auxiliary file.

No, do not use the User Auxiliary file (default).

Specifies whether or not AssignGeoTAXInfo should attempt a match to the state-supplied file. Use this option in combination with

FileSearchOrder to specify a state-supplied file to use.

API Guide 361

Enterprise Tax Module

362 optionName Description

State-supplied files are provided by individual state governments. By matching to the state-supplied files, you can remain compliant with tax jurisdiction assignment requirements mandated by new federal and state laws, such as the Mobile Telecommunications Sourcing Act and the Florida state Communications Services Tax Simplification Law.

There are two supported file formats: the Florida-native format and the national TS-158 format (ANSI Transaction Set No. 158). The state of

Florida provides address files in both the TS-158 and its own native format. The state of Washington provides address data in the TS-158 format.

Assign GeoTAX Info attempts to match to the state supplied file first. If a state match cannot be found, it attempts a match to the master files.

You must install the appropriate state-supplied file to use these options.

For instructions, see the Spectrum

™

Technology Platform Installation

Guide.

One of the following:

Yes, attempt to match to state-supplied file.

Do not use the state-supplied file (default).

FileSearchOrder Specifies which state-supplied file to use. This option only takes effect if you specify UseStateProvidedFile=Y. One of the following:

FLOnly

Use only the Florida-native formatted file.

TSOnly

Use only the TS-158 formatted file.

UseRelaxedSecondaryMatching Specifies whether or not AssignGeoTAXInfo matches input addresses with secondary information to records without secondary information.

This option applies only to Florida-native files. One of the following:

Yes, use relaxed matching.

No, do not use relaxed matching (default).

GeoTAXOutputRecordType Select one or more of the following to obtain the type of data you want returned. AssignGeoTAXInfo groups the output fields into record types.

If you do not want all of the fields in a record type returned, do not select the check box, and list only those fields you want returned in Extra

Output Fields.

• C—Census

• L—Latitude/Longitude

• T—Tax Jurisdiction

• U—User-defined boundary file

• W—Payroll System Tax Codes

• X—Auxiliary File

You can also specify one, and only one, of the following:

Insurance Premium Tax District (IPD)

Property Tax District (PTD)

Payroll Tax District (PAY)

Special Purpose Tax District (SPD)

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName

TaxKey

OutputFields

Description

For a description of the fields in each output group, see

Output

on page

369.

Note:

If you specify W, also specify R to obtain the best payroll system tax code match possible.

If you integrate AssignGeoTAXInfo with third-party tax compliance software from Vertex or ADP/Taxware, select which vendor you use.

This controls the value returned in the GeoTAXKey output field. One of the following:

Return the Taxware jurisdiction code for the address.

Return the Vertex jurisdiction code for the address. Select this option if you obtained a MatchMaster file from Vertex.

Return the Vertex jurisdiction code for the address. Select this option if you obtained a Vertex file from Pitney Bowes

Software.

Do not return either the Taxware or Vertex jurisdiction codes

(default).

Indicates the individual output fields you want returned. You can use this field instead of the Output Record Type to limit the output to those fields that are important to your current data needs.

For a list of the fields included in each data type, see

Output

on page

369.

Specifying Default State-Supplied File Options

If you use the Spectrum

™

Technology Platform API, note that the value you specify in the Management

Console for the State supplied file field controls the default settings for three AssignGeoTAXInfo API options: UseStateProvidedFile, UseRelaxedSecondary, and FileSearchOrder. The following table show how each value in the State supplied file field affects these three options.

"State supplied file" value

None

Florida-native

Florida-native with relaxed secondary matching

TS-158

UseStateProvidedFile FileSearchOrder UseRelaxedSecondary

N/A

FSOnly

Y TSOnly N

Geocoding

Geocoding is the process of determining the latitude/longitude coordinates of a given address. Address coordinates are used as the basis for determining the tax jurisdictions for an address. Geocoding options control how AssignGeoTAXInfo determines address latitude and longitude.

API Guide 363

Enterprise Tax Module

Table 135: AssignGeoTAXInfo Geocoding Options optionName

LatLongOffset

Description

Indicates the offset distance in feet from the street center line.

364

Squeeze

No offset (default).

Twenty feet offset from street center line

Forty feet offset from street center line

Sixty feet offset from street center line

Specifies if AssignGeoTAXInfo should squeeze the street end points when determining the geocode of an address in street-level matching.

The squeeze value is 5% (2.5% from each endpoint). The following diagram compares the end points of a street segment to the squeezed end points of a street segment.

No, do not apply squeeze.

Apply squeeze (default).

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services optionName

LatLongFormat

DistanceUnits

DefaultBufferWidth

DefaultUserBufferWidth

Description

Indicates the desired format for returned latitude/longitude. Options include:

PreZero

Latitude/longitude in the following format:

090000000N180000000W. (Default)

PreZeroDecimal

Decimal

Latitude/longitude in the following format:

090.000000N180.000000W.

Latitude/longitude in the following format:

90.000000-180.000000.

DecimalAssumed

Latitude/longitude in the following format:

90000000-180000000.

DegMinSec

Latitude/longitude in the following format: 90 00

00N180 00 00W.

Specifies the units in which to measure distance. One of the following:

Miles

Distances are measured in miles.

Feet

Meters

Distances are measured in kilometers.

Distances are measured in feet. (Default)

Distances are measured in meters.

Specifies the buffer width to use for tax district boundary files. The tax district boundary files are the Special Purpose District (SPD) file, the

Insurance Premium District (IPD) file, the Payroll Tax District (PAY) file and the Personal Property Tax District (PTD) file.

Specify the distance in the units of measurement specified in the

DistanceUnits option.

The default buffer width that you specify here can be overridden on a record-by-record basis using the BufferWidth input field.

For more information on buffers, see

Buffering

on page 359.

Specifies the buffer width to use for user-defined boundary files. Specify the distance in the units of measurement specified in the DistanceUnits option. For information on buffers, see

Buffering

on page 359. The default buffer width that you specify here can be overridden on a record-by-record basis using the BufferWidth input field.

Note:

To use buffers, the user-defined boundary file must support buffers.

Output Format

Output format options control how AssignGeoTAXInfo formats output data. The following table lists the output format options.

API Guide 365

Enterprise Tax Module

Table 136: AssignGeoTAXInfo Output Format Options optionName

OutputCasing

Description

Specifies the casing of these output fields: County.Name, MSA.Name,

MCD.Name, Place.Name, IPDn.DistrictName, PAYn.DistrictName,

SPDn.DistrictName, and PTCn.PayrollDescription.

One of the following:

The output in mixed case (default). For example:

Rensselaer.

The output in upper case. For example: RENSSELAER.

Creating a User-Defined Boundary File

User-defined boundary files define areas of interest to your organization, such as sales territories or insurance rating territories. AssignGeoTAXInfo uses this data to determine if an address falls within an area of interest. For example, you can create a boundary file that defines your sales territories.

AssignGeoTAXInfo can then determine the tax jurisdictions that apply to an address and the sales territory of that address.

Note:

User-defined boundary files in AssignGeoTAXInfo allow you to perform basic "point-in-polygon" spatial analysis. Point In Polygon provides additional point-in-polygon features.

1. Create an ESRI shapefile (.SHP) or MapInfo data interchange format file (.MIF) with the boundaries you want. Your .SHP or .MIF file can have up to three columns of user-defined data. The first and second columns are 10 bytes long and the third column is 50 bytes long. For information on .SHP

and .MIF files, see

User-Defined Centrus Databases

2. Use the Boundary File Conversion utility to convert your .SHP or .MIF file to a .TXB file. This utility is available on the GeoTAX Utilities CD. This CD also contains instructions on using the conversion utility.

Using a Payroll Tax Correspondence File

Payroll system tax codes are proprietary codes used by some payroll tax applications to represent specific jurisdictions or combinations of jurisdictions. If you have licensed this option, you can use a payroll tax correspondence (PTC) file to determine the payroll system tax codes for a given address.

To use a payroll system tax code database, customize the PTC file and then install the file.

1. Customize the PTC file.

After you receive your initial PTC file, modify it using a text editor of your choice. Specifically, you need to modify the following:

• Description—A meaningful description of the code that represents business rules within your organization.

• Flags—Flags indicate the payroll codes you want Assign GeoTAX Info to return. Possible flag values are:

• N—No, do not return this payroll tax code. Continue searching the PTC file for other matching records. A blank flag has the same effect as "N".

• D—Done. Return this payroll system tax code and stop searching the PTC file for other matching records.

• Any other value—Any other value indicates to return the code. Typically, the letter Y (for "yes") is used. Use other flags if you like. For example, if there is an area with two codes, one for a work location and the other for the worker's residence, you could use flags of "W" and "R" so that the output field PTCn.PayrollFlag returned by AssignGeoTAX Info indicates the type of location.

The following table shows how to use flags.

366 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Note:

Each record in the PTC file can contain up to six payroll system tax codes and their associated descriptions and flags. In the following example, the first three codes are on the first record and the second three are on the second. See

Table 138: Payroll System Tax Code File

Layout

on page 368 for the layout of the PTC file.

Table 137: Example PTC File

Record

Description

HARBORCREEK TWP

HARBOR CREEK SD

HARBORCREEK TWP (M + SD)

DAYTON BORO

ARMSTRONG SD

DAYTON BORO (M + SD)

Payrolll System Tax Code

123ABC

456DEF

789GHI

592UID

143XMA

592JKT

Flag

In this example, the first record in the PTC file contains tax codes for a municipality called Harbor

Creek Township and a school district called Harbor Creek School District. There is a separate code that represents points that are in both the Harbor Creek Township and the Harbor Creek School

District. The second record in the PTC file contains codes for Dayton, a school district called Armstrong, and points located in both Dayton and the Armstrong School District.

This example returns the payroll system tax codes for the individual taxing jurisdictions for a given address, not the codes that represent the combined jurisdictions.

For addresses located in both the Harbor Creek Township and Harbor Creek School District,

AssignGeoTAXInfo returns the following:

• PTC1.PayrollDescription=HARBORCREEK TWP

• PTC1.PayrollCode=123ABC

• PTC1.PayrollFlag=D

• PTC2.PayrollDescription=HARBOR CREEK SD

• PTC2.PayrollCode=456DEF

• PTC2.PayrollFlag=D

For addresses located in both Dayton and the Armstrong School District, AssignGeoTAXInfo returns the following:

• PTC1.PayrollDescription=DAYTON BORO

• PTC1.PayrollCode=592UID

• PTC1.PayrollFlag=Y

• PTC2.PayrollDescription=ARMSTRONG SD

• PTC2.PayrollCode=143XMA

• PTC2.PayrollFlag=Y

• For addresses located in just Dayton but not the Armstrong School District, AssignGeoTAXInfo returns the code 592UID and its associated flag and description. For addresses located in just the

Armstrong School District but not Dayton, AssignGeoTAXInfo returns the code 143XMA and its associated flag and description.

Note:

For a listing of output fields returned for payroll system tax codes, see

Payroll System Tax

Code

on page 375.

The following table describes the PTC file layout.

API Guide 367

Enterprise Tax Module

Table 138: Payroll System Tax Code File Layout

Position Length Name

1 9 (required) Key Value. Lookup key into the file. Must be one of the following.

• 5 character jurisdiction ID from the Pay.txb boundary file. This file contains polygons for special areas, such as school districts.

• 9 character GNIS code.

• 5 character county key made up of the State and County FIPS codes.

• 2 character State FIPS code.

317

332

372

373

374

167

207

222

262

277

375

376

377

112

152

10 2 (optional) State

12 30 (optional) County

The payroll code and payroll description fields are paired. Each pair has a corresponding flag field.

The flag field determines if GeoTAX returns data for the corresponding payroll code and description fields. GeoTAX does not return the fields if the flag is N or blank. This lets you create meaningful flags based on your business rules.

Payroll code 1

Payroll description 1

Payroll code 2

Payroll description 2

Payroll code 3

Payroll description 3

Payroll code 4

Payroll description 4

Payroll code 5

Payroll description 5

Payroll code 6

Payroll description 6

Flag 1

Flag 2

Flag 3

Flag 4

Flag 5

Flag 6

2. Install the PTC file. For instructions on installing the PTC file, see the Spectrum

™

Installation Guide

Technology Platform

PTC file updates are provided at intervals defined in your contract. When you receive the PTC update files, enter flags for the modified records and then run Enterprise Tax Module database load utility to merge the updated PTC file with your existing file. For instructions, see "Installing Payroll Tax

Correspondence Files" in the Spectrum

™

Technology Platform Installation Guide. This process maintains the existing user-defined flags you have already associated with the PTC data.

368 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Output

Auxiliary File

The following table lists the output fields that contain auxiliary file data. To include auxiliary file data in the output, set GeoTAXOutputRecordType = X. The following table lists the output fields that contain tax jurisdiction data.

Table 139: Auxiliary File Output Fields columnName Description

AuxiliaryData.AuxiliaryFile

AuxiliaryData.StateFile

Data retrieved as a result of an auxiliary match from the user-defined area of the auxiliary file.

Data retrieved as a result of a state match. Data content and format vary depending on the state file used.

Census

The census output fields contains census information from the U.S. Census, including Minor Civil Divisions

(MCDs) and Census County Division (CCD) names and codes. MCDs are the primary political or administrative divisions of a county, representing many kinds of legal entities with a variety of governmental and administrative functions. CCDs are established in states where there are no legally established

MCDs. The Census Bureau recognizes MCDs in 28 states and has established CCDs in 21 states. The

District of Columbia has no primary divisions, and the city of Washington, DC is considered equivalent to an MCD for data presentation purposes.

Census data also contains the Federal Information Processing Standards (FIPS) codes for each state and county. The FIPS State Code and the FIPS County Code are both used by the Census Bureau to identify these geographic units.

The following table lists the output fields that contain census data. To include census data in the output, set GeoTAXOutputRecordType = C.

Table 140: Census Data Output Fields columnName

Census.BlockCode

Census.MatchCode

Description

Census Block Group code.

The level of match obtained against the databases.

Note:

This field is always included in the output regardless of whether or not you choose to include census data in the output.

5 null

Auxiliary street match

State file address match

Street address match

GeoTAX Auxiliary file match

ZIP + 4 Code level match

ZIP Code level match

Unsuccessful match

API Guide 369

Enterprise Tax Module columnName

Census.MatchLevel

Census.Tract

County.Code

County.Name

GNISCode

MCD.Code

MCD.Name

MSA.Code

MSA.Name

State.Abbreviation

StateCode

Description

The level of match obtained against the databases.

Note:

This field is always included in the output regardless of whether or not you choose to include census data in the output.

Auxiliary

Aux2

Street

Gov

ZIP+4

ZIP null

Auxiliary street match

GeoTAX Auxiliary file match

Street address match

State file address match

ZIP + 4 Code level match

ZIP Code level match

No match

Six-digit tract number extracted from the Census.BlockCode.

Three-digit Federal Information Processing Standards (FIPS) county code extracted from the Census.BlockCode.

Note:

This field is always included in the output regardless of whether or not you choose to include census data in the output.

Name of the county.

Note:

This field is always included in the output regardless of whether or not you choose to include census data in the output.

Unique nine-digit Geographic Names Information System (GNIS) code.

Note:

This field is always included in the output regardless of whether or not you choose to include census data in the output.

Minor Civil Division/Census County Division (MCD/CCD) Code.

Minor Civil Division/Census County Division (MCD/CCD) name.

Metropolitan Statistical area (MSA) code.

Metropolitan Statistical area (MSA) name.

Two-character state abbreviation.

Note:

This field is always included in the output regardless of whether or not you choose to include census data in the output

Two-digit Federal Information Processing Standards (FIPS) state code extracted from the Census.BlockCode.

Note:

This field is always included in the output regardless of whether or not you choose to include census data in the output.

370

Input Address

AssignGeoTAXInfo always returns the input address as part of the output. The input address fields are returned as input from the data. AssignGeoTAXInfo does not change these input values.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

City

Country

FirmName

PostalCode

StateProvince

Table 141: Input Address Output Fields

Description

Input address line 1.

Input address line 2.

Input address line 3.

Input address line 4.

Input address city.

Input address country.

Input address firm name.

Input address postal code

Input address state.

Insurance Premium Tax District

The following table lists the output fields that contain Insurance Premium Tax District (IPD) data. For more information on insurance premium tax districts, see

AssignGeoTAXInfo

on page 357. To include census data in the output, set GeoTAXOutputRecordType = I.

Note:

AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.

Table 142: Insurance Premium Tax District Output Fields columnName

IPDn.BoundaryBuffer.BufferRelation

Description

Indicates where in the district the address resides in relation to the edge of the district.

One of the following:

The address is inside the district at a distance from the edge that is greater than the specified buffer width. Buffer width is specified either by the option DefaultBufferWidth or by the input field BufferWidth.

The address is inside the district but is close to the edge. This indicates that the address is in the buffer area specified either by the option DefaultBufferWidth or by the input field

BufferWidth.

The address is outside the district but is close to the edge. This indicates that the address is in the buffer area specified either by the option DefaultBufferWidth or by the input field

BufferWidth.

For more information, see

Buffering

on page 359.

API Guide 371

Enterprise Tax Module columnName

IPDn.BoundaryBuffer.DistanceToBorder

IPDn.DistrictID

IPDn.DistrictName

IPDn.DistrictType

IPDn.UpdateDate

IPDn.VersionDate

IPDn.Notes

372

IPDn.ChangeDate

IPDn.EffectiveDate

IPDn.ExpirationDate

IPDn.FireRate

IPDn.FireFlag

IPDn.CasualtyRate

IPDn.CasualtyFlag

IPDn.VehicleRate

Description

Indicates the distance from the address to the border of the district. The distance is in the units specified by the option DistanceUnits.

IPD ID.

IPD name.

IPD district type.

IPD update date.

IPD compiled date.

Tax code descriptions.

Field Length: 20

Possible Values: 01, 33, A, B

IPD change date.

MMDDYY - Identifies when district becomes active

- State supplied

Field Length: 6

Possible Values: 010108

MMDDYY - Identifies when district becomes inactive - State supplied

Field Length: 6

Possible Values: 063009

Format is dependent on associated flag

Field Length: 20

Possible Values: .13, 15.00 or 3;7

P - Percentage; .1 = 10%, .0575 = 5.75%

F - Flat Fee dollar amount

M - Multiple Percentages has a semi colon as a delimiter. 3;7 = "3% or 7%"

Format is dependent on associated flag

Field Length: 20

Possible Values: .13, 15.00 or 3;7

P - Percentage; .1 = 10%, .0575 = 5.75%

F - Flat Fee dollar amount

M - Multiple Percentages has a semicolon as a delimiter. 3;7 = "3% or 7%"

Format is dependent on associated flag

Field Length: 20

Possible Values: .13, 15.00 or 3;7

Spectrum

™

Technology Platform 9.0

IPDn.LifeRate

IPDn.LifeFlag

IPDn.OtherRate

IPDn.OtherFlag

IPDn.MinimumRate

IPDn.MinimumFlag

API Guide columnName

IPDn.VehicleFlag

IPDn.MarineRate

IPDn.MarineFlag

IPDn.HealthRate

IPDn.HealthFlag

Chapter 8: Module Services

Description

P - Percentage; .1 = 10%, .0575 = 5.75%

F - Flat Fee dollar amount

M - Multiple Percentages has a semicolon as a delimiter. 3;7 = "3% or 7%"

Format is dependent on associated flag

Field Length: 20

Possible Values: .13, 15.00 or 3;7

P - Percentage; .1 = 10%, .0575 = 5.75%

F - Flat Fee dollar amount

M - Multiple Percentages has a semicolon as a delimiter. 3;7 = "3% or 7%"

Format is dependent on associated flag

Field Length: 20

Possible Values: .13, 15.00 or 3;7

P - Percentage; .1 = 10%, .0575 = 5.75%

F - Flat Fee dollar amount

M - Multiple Percentages has a semicolon as a delimiter. 3;7 = "3% or 7%"

Format is dependent on associated flag

Field Length: 20

Possible Values: .13, 15.00 or 3;7

P - Percentage; .1 = 10%, .0575 = 5.75%

M - Multiple Percentages has a semicolon as a delimiter. 3;7 = "3% or 7%"

Format is dependent on associated flag

Field Length: 20

Possible Values: .13, 15.00 or 3;7

P - Percentage; .1 = 10%, .0575 = 5.75%

F - Flat Fee dollar amount

M - Multiple Percentages has a semicolon as a delimiter. 3;7 = "3% or 7%"

Format is dependent on associated flag

Field Length: 20

Possible Values: .13, 15.00 or 3;7

P - Percentage; .1 = 10%, .0575 = 5.75%

F - Flat Fee dollar amount

373

Enterprise Tax Module columnName

NumberIPDsFound

Description

M - Multiple Percentages has a semicolon as a delimiter. 3;7 = "3% or 7%"

Number of IPDs returned.

374

Latitude/Longitude

The following table lists the output fields that contain latitude and longitude data. Latitude/Longitude data contains the coordinates for the address and additional information about how AssignGeoTAXInfo determined the latitude and longitude. To include latitude/longitude data in the output, set

GeoTAXOutputRecordType = L.

Table 143: Latitude/Longitude Output Fields columnName

Latitude

Latitude.Directional

LatLong

LatLong.MatchCode

LatLong.MatchLevel

Description

Seven-digit number in degrees and calculated to four decimal places

(in the format you specified).

Latitude directional.

North

South

Returned latitude/longitude, in the format you specified (up to 22 alphanumeric characters).

Level of match for the latitude/longitude.

ZIP + 2 centroid

ZIP + 4 Code centroid

ZIP Code centroid based on a ZIP + 4 code.

Z null

Block group centroid

Address-level based on street address

Census tract centroid

Address-level match using the GeoTAX Auxiliary

Database

ZIP Code centroid based on a five-digit ZIP code

No latitude/longitude determined

Level of match for the latitude/longitude.

Block

Block group centroid

Rooftop

Tract

Exact address match

Census tract centroid

ZIP

ZIP+2

ZIP+4

ZIP Code centroid

ZIP + 2 centroid

ZIP + 4 centroid

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Description

LatLong.StreetMatchCode

LatLong.StreetMatchLevel

Longitude

Longitude.Directional

Auxiliary

Address-level match using the GeoTAX

Auxiliary Database

Output street address return code.

House number not found on street

Latitude/longitude not determined on auxiliary match

Street not found in ZIP Code

N null

ZIP Code not found in street address database

Street-level matching option not selected

The street was successfully matched

Street level match used to determine the latitude/longitude.

FullMatch

Successful match

HouseNotFound

LatLongNotFound

StreetNotFound

ZipNotFound

House number not found on street

Latitude/longitude not determined on auxiliary match

Street not found in ZIP Code

NotUsed

ZIP Code not found in street address database

Street-level matching option not selected

Seven-digit number in degrees and calculated to four decimal places

(in the format specified).

Longitude directional.

East

West

Payroll System Tax Code

The following table lists the output fields that contain Payroll System Tax Code (PTC) data. For more information on payroll tax districts, see

AssignGeoTAXInfo

on page 357. To include this data in the output, set GeoTAXOutputRecordType = W.

Note:

AssignGeoTAXInfo returns up to six payroll tax codes per address.

Table 144: Payroll System Tax Code Output Fields columnName

NumberPTCsFound

PTC.MatchCode

API Guide

Description

Number of payroll system tax codes found for this address.

Indicates the level of match obtained for the address. In order from most specific match to least, the possible match codes are:

The address was matched to a specific Payroll District ID.

This is the most specific match.

375

Enterprise Tax Module columnName

PTCn.PayrollCode

PTCn.PayrollDescription

PTCn.PayrollFlag

StateCounty

Description

The address was matched to a GNIS Code.

The address was matched to a county's FIPS code.

The address was matched to a state's FIPS code. This is the least specific match.

A code that represents a taxing authority in a payroll application. This is a user-defined code. The specific codes are determined by the payroll application that utilizes the data returned by AssignGeoTAXInfo.

A description of the purpose of this payroll code.

A user-defined flag from the PTC database.

The state abbreviation and county name.

Payroll Tax District

The following table lists the output fields that contain Payroll Tax District (PAY) data. For more information on payroll tax districts, see

AssignGeoTAXInfo

on page 357. To include this data in the output, set

GeoTAXOutputRecordType = R.

Note:

AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.

Table 145: Payroll Tax District Output Fields

376 columnName Description

NumberPAYsFound

PAYn.BoundaryBuffer.BufferRelation

Number of PAYs returned.

Indicates where in the district the address resides in relation to the edge of the district.

One of the following:

The address is inside the district at a distance from the edge that is greater than the specified buffer width.

Buffer width is specified either by the option

DefaultBufferWidth or by the input field BufferWidth.

The address is inside the district but is close to the edge. This indicates that the address is in the buffer area specified either by the option DefaultBufferWidth or by the input field BufferWidth.

The address is outside the district but is close to the edge. This indicates that the address is in the buffer area specified either by the option DefaultBufferWidth or by the input field BufferWidth.

For more information, see

Buffering

on page 359.

PAYn.BoundaryBuffer.DistanceToBorder

Indicates the distance from the address to the border of the district. The distance is in the units specified by the option

DistanceUnits.

PAYn.DistrictID

PAY district ID.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

PAYn.DistrictName

PAYn.DistrictType

PAYn.ID

PAYn.MunicipalEMSTax

PAYn.MunicipalIncomeTax

PAYn.SchoolDistrictEMSTax

PAYn.SchoolDistrictIncomeTax

Description

PAY district name.

PAY district type.

PAY ID.

PAY municipality emergency municipal services tax.

The values for Pennsylvania are:

Levies the tax

Does not levy the tax

All other states are null.

PAY municipality income tax.

The values for Pennsylvania are:

Resident

Non-resident

Both

None

All other states are null.

PAY school district emergency municipal services tax.

The Values for Pennsylvania are:

Levies the tax

Does not levy the tax

All other states are null.

PAY school district income tax.

The values for Pennsylvania are:

Resident

Non-resident

Both

The values for Ohio are:

Resident

None

All other states are null.

Property Tax District

The following table lists the output fields that contain Property Tax District (PTD) data. For more information on property tax districts, see

AssignGeoTAXInfo

on page 357. To include this data in the output, set

GeoTAXOutputRecordType = P.

Note:

AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.

API Guide 377

Enterprise Tax Module

Table 146: Property Tax District Output Fields columnName Description

NumberPTDsFound

PTDn.BoundaryBuffer.BufferRelation

Number of PTDs returned.

Indicates where in the district the address resides in relation to the edge of the district.

One of the following:

The address is inside the district at a distance from the edge that is greater than the specified buffer width.

Buffer width is specified either by the option

DefaultBufferWidth or by the input field BufferWidth.

For more information, see

Buffering

on page 359.

PTDn.BoundaryBuffer.DistanceToBorder

Indicates the distance from the address to the border of the district. The distance is in the units specified by the option

DistanceUnits.

PTDn.DistrictID

PTD district ID.

PTDn.DistrictName

PTDn.DistrictType

PTD district name.

PTD district type. Only returned for Indiana.

Reporting district

Billing district

PTDn.JurisdictionID

PTDn.UpdateDate

PTD jurisdiction ID.

PTD update date.

378

Result Indicators

The following table lists the output fields that contain results data. Result indicators describe how well

AssignGeoTAXInfo matched the input address to a known address and assigned a location. These fields are always included in output from AssignGeoTAXInfo.

Table 147: Result Indicator Output Fields columnName

Confidence

Description

Indicates the confidence in the output provided; from 0 to 100. The higher the score, the higher the confidence in the match. Calculated based on the match results for individual output fields, using the following algorithm:

Spectrum

™

Technology Platform 9.0

columnName

GTX.ErrorCode

API Guide

Chapter 8: Module Services

Description

Census.MatchCode + Latlong.StreetMatchCode + LatLong.MatchCode

The maximum confidence score is 100, so if this calculation results in a value greater than 100, the Confidence score is returned as 100.

AssignGeoTAXInfo uses the following values:

• Census.MatchCode

• A = 85

• G = 85

• S = 85

• U = 85

• 9 = 65

• 5 = 45

• null = 0

• LatLong.StreetMatchCode

• H = 5

• S = 0

• L = 0

• Z = -10

• null = 10

• LatLong.MatchCode

• 2 = 0

• 4 = 5

• 5 = -5

• B = 2

• R = 10

• T = -2

• U = 10

• Z = -5

• null = -10

This field contains a return code if the GeoTAX engine experiences an abnormal termination.

Note:

This field contains the same set of codes returned by the standalone GeoTAX software and is intended for users who have migrated from GeoTAX to Spectrum

™

Technology

Platform.

The first character indicates the file (or set of files affected).

Auxiliary file

Base file

Boundary file

User defined boundary file

Street file

Logical I/O program abend

379

Enterprise Tax Module columnName

380

GTX.ErrorDescription

Description

State supplied files

GeoTAX Auxiliary file

Street and state files

The second position is one of the following:

Both Florida and TS158 state files are problematic

Expired database

Informational

If the GeoTAX engine experiences an abnormal termination, this field contains a text description of the reason. It is blank if GeoTAX terminated normally. The maximum length is 80.

Note:

This field contains the same set of descriptions returned by the standalone GeoTAX software and is intended for users who have migrated from GeoTAX to Spectrum

™

Technology

Platform.

SI-"TS158 FILES NOT FOUND"

SI-"TS158 FILES VINTAGE OR INCOMPLETE DB ERROR"

SI-"STATE FILES NOT FOUND"

SE-"STATE AND TS158 FILES NOT FOUND"

SE-"STATE NOT FOUND AND TS158 VINTAGE ERROR"

SI-"STATE FILES VINTAGE OR INCOMPLETE DB ERROR"

SE-"STATE VINTAGE ERROR AND TS158 NOT FOUND"

SE-"STATE AND TS158 FILES VINTAGE OR INCOMPLETE DB

ERROR"

GI-"STREET FILES NOT FOUND"

XI-"STREET AND TS158 FILES NOT FOUND"

XI-"STREET NOT FOUND AND TS158 FILES VINTAGE ERROR"

XI-"STREET AND STATE FILES NOT FOUND"

XE-"STREET STATE AND TS158 FILES NOT FOUND"

XE-"STREET AND STATE NOT FOUND AND TS158 VINTAGE

ERROR"

XI-"STREET NOT FOUND AND STATE VINTAGE ERROR"

XE-"STREET AND TS158 NOT FOUND AND STATE VINTAGE

ERROR"

XE-"STREET NOT FOUND AND STATE AND TS158 VINTAGE

ERROR"

GI-"STREET FILES VINTAGE OR INCOMPLETE DB ERROR"

XI-"STREET VINTAGE ERROR AND TS158 NOT FOUND"

XI-"STREET AND TS158 FILES VINTAGE OR INCOMPLETE DB

ERROR"

XI-"STREET VINTAGE ERROR AND STATE NOT FOUND"

XE-"STREET VINTAGE ERROR AND STATE AND TS158 NOT

FOUND"

XE-"STREET AND TS158 VINTAGE ERROR AND STATE NOT

FOUND"

XI-"STREET AND STATE FILES VINTAGE OR INCOMPLETE DB

ERROR"

XE-"STREET AND STATE VINTAGE ERROR AND TS158 NOT

FOUND"

Spectrum

™

Technology Platform 9.0

columnName

GTX.WarnCode

GTX.WarnDescription

Status

Status.Code

Status.Description

API Guide

Chapter 8: Module Services

Description

XE-"STREET STATE AND TS158 VINTAGE ERROR"

LF-"INVALID FUNCTION PASSED TO GTDBLIO : "

AI-"GENIO ERROR: FILE = G1GTAUX , FUNC = , ST = "

UI-"GENIO ERROR: FILE = G1GTAX2 , FUNC = , ST = "

XF-"The (DB Vintage) database has expired!"

XF-"The (SPD file Vintage) SPD File has expired!"

DI- "UNABLE TO VALIDATE BOUNDARY LICENSE"

DI- "UNABLE TO OPEN BOUNDARY FILE"

DI- "BOUNDARY FILE NOT FOUND"

FI- "UNABLE TO VALIDATE USER BOUNDARY LICENSE"

FI- "UNABLE TO OPEN USER BND FILE"

FI- "USER BND FILE NOT FOUND"

This field contains warning codes returned by the GeoTAX engine. It is blank if no warnings were issued. A value of WN indicates a database will expire next month.

Note:

This field contains the same set of codes returned by the standalone GeoTAX software and is intended for users who have migrated from GeoTAX to Spectrum

™

Technology

Platform.

A text description of any warnings returned by the GeoTAX engine.

Note:

This field contains the same set of descriptions returned by the standalone GeoTAX software and is intended for users who have migrated from GeoTAX to Spectrum

™

Technology

Platform.

Reports the success or failure of the match attempt.

null

Success

Failure. Some examples of failures are your license expired or you did not select any output record types and fields for

AssignGeoTAXInfo to return.

If AssignGeoTAXInfo could not process the address, this field will show the reason. Currently there is one possible value for this field: Invalid

Address.

If AssignGeoTAXInfo could not process the address, this field will show a description of the failure. One of the following:

TS158 FILES NOT FOUND

TS158 FILES VINTAGE OR INCOMPLETE DB ERROR

STATE FILES NOT FOUND

STATE AND TS158 FILES NOT FOUND

STATE NOT FOUND AND TS158 VINTAGE ERROR

STATE FILES VINTAGE OR INCOMPLETE DB ERROR

STATE VINTAGE ERROR AND TS158 NOT FOUND

STATE AND TS158 FILES VINTAGE OR INCOMPLETE DB ERROR

STREET FILES NOT FOUND

STREET AND TS158 FILES NOT FOUND

STREET NOT FOUND AND TS158 FILES VINTAGE ERROR

STREET AND STATE FILES NOT FOUND

STREET STATE AND TS158 FILES NOT FOUND

381

Enterprise Tax Module columnName Description

STREET AND STATE NOT FOUND AND TS158 VINTAGE ERROR

STREET NOT FOUND AND STATE VINTAGE ERROR

STREET AND TS158 NOT FOUND AND STATE VINTAGE ERROR

STREET NOT FOUND AND STATE AND TS158 VINTAGE ERROR

STREET FILES VINTAGE OR INCOMPLETE DB ERROR

STREET VINTAGE ERROR AND TS158 NOT FOUND

STREET AND TS158 FILES VINTAGE OR INCOMPLETE DB ERROR

STREET VINTAGE ERROR AND STATE NOT FOUND

STREET VINTAGE ERROR AND STATE AND TS158 NOT FOUND

STREET AND TS158 VINTAGE ERROR AND STATE NOT FOUND

STREET AND STATE FILES VINTAGE OR INCOMPLETE DB ERROR

STREET AND STATE VINTAGE ERROR AND TS158 NOT FOUND

STREET STATE AND TS158 VINTAGE ERROR

INVALID FUNCTION PASSED TO GTDBLIO :

GENIO ERROR: FILE = G1GTAUX , FUNC = , ST =

GENIO ERROR: FILE = G1GTAX2 , FUNC = , ST =

The (DB Vintage) database has expired!

The (SPD file Vintage) SPD File has expired!

UNABLE TO VALIDATE BOUNDARY LICENSE

UNABLE TO OPEN BOUNDARY FILE

BOUNDARY FILE NOT FOUND

UNABLE TO VALIDATE USER BOUNDARY LICENSE

UNABLE TO OPEN USER BND FILE

USER BND FILE NOT FOUND

Special Purpose Tax District

The following table lists the output fields that contain Special Purpose Tax District (SPD) data. For more information on special purpose tax districts, see

AssignGeoTAXInfo

on page 357. To include this data in the output, set GeoTAXOutputRecordType = S.

Note:

AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.

Table 148: Special Purpose Tax District Output Fields columnName Description

NumberSPDsFound

SPDn.BoundaryBuffer.BufferRelation

Number of SPDs returned.

Indicates where in the district the address resides in relation to the edge of the district.

One of the following:

The address is inside the district at a distance from the edge that is greater than the specified buffer width.

Buffer width is specified either by the option

DefaultBufferWidth or by the input field BufferWidth.

382 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Description

For more information, see

Buffering

on page 359.

SPDn.BoundaryBuffer.DistanceToBorder

Indicates the distance from the address to the border of the district. The distance is in the units specified by the option

DistanceUnits.

SPDn.CompiledDate

SPDn.DistrictCode

SPDn.DistrictName

SPDn.DistrictNumber

SPDn.EffectiveDate

SPDn.UpdateDate

SPDn.VersionDate

SPD compiled date.

3-digit district type code.

SPD name.

SPD district number.

SPD effective date.

SPD update date.

SPD version date.

Tax Jurisdiction

Tax jurisdiction data contains information about the "place" where the address resides. A "place" is a geographic area defined on the basis of population criteria that vary by state; or, an area recognized as significant because it is located in an incorporated municipality. Places are used to determine tax jurisdiction.

The following table lists the output fields that contain tax jurisdiction data. To include tax jurisdiction data in the output, set GeoTAXOutputRecordType = T.

Table 149: Tax Jurisdiction Output Fields columnName

County.PostalCode

Confidence

GeoTAXKey

Description

Indicates if the ZIP Code resides in the county.

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

Y null

ZIP Code not wholly contained in the county.

ZIP Code wholly contained in the county.

Unknown if ZIP Code is wholly contained in the county or a match was not made at the ZIP Code level.

Note:

Only available for 5-digit ZIP Code matches, not for street address matches.

The value in this field varies depending on the option you specified in the TaxKey option:

API Guide 383

Enterprise Tax Module columnName

GeoTAXKey.MatchCode

GeoTAXKey.MatchLevel

Place.ClassCode

Place.Code

Place.IncorporatedFlag

Description

If you specified T, GeoTAXKey contains the proprietary codes used in

ADP/Taxware tax compliance software. You can use this code in your

ADP/Taxware application to find out the tax rate for the jurisdiction.

If you specified Y or V, GeoTAXKey contains the proprietary Vertex

® jurisdiction code (comprised of a two-digit Vertex

® state code, three-digit

FIPS county code, and four-digit Vertex

® code in your Vertex

® city code). You can use this application to find out the tax rate for the jurisdiction.

Return code denoting the level of match obtained against the Vertex or

Taxware cross reference files.

Exact match using five fields: FIPS state code, FIPS county code, FIPS place code, ZIP Code, and FIPS place name.

Partial match using four fields: FIPS state code, FIPS county code, FIPS place code, and ZIP Code.

Alternate match using two fields: ZIP Code, FIPS place name.

This return code is available only when using Vertex.

N null

Record is default coded based on valid state code. This return code is available only when using Vertex.

No matching record found.

A description of the value returned in the GeoTAXKey.MatchCode field.

Exact

Exact match. See description in

GeoTAXKey.MatchCode.

Partial

Alternate

Partial match. See description in

GeoTAXKey.MatchCode.

Alternate match. See description in

GeoTAXKey.MatchCode.

DefaultCode

NoMatch

Record is default coded. See description in

GeoTAXKey.MatchCode.

No matching record found.

Place class code. Place class codes are used to determine the proper taxing jurisdictions

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

An identifier for a specific place. A "place" is a geographic area defined on the basis of population criteria that vary by state. Or, an area recognized as significant because it is located in an incorporated municipality.

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

Indicates whether the address is located in an incorporated or unincorporated place. A "place" is a geographic area defined on the basis of population criteria that vary by state. Or, an area recognized as significant because it is located in an incorporated municipality.

384 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

Place.LastAnnexedDate

Place.LastUpdatedDate

Place.LastVerifiedDate

Description

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

Inc

Uninc

Unknown

Incorporated place code.

Unincorporated place code.

Incorporation status unknown.

Last annexed date, in the format MM/YYYY, representing the month and year of the most recent boundary change or the most recent available boundary information.

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

Last updated date, in the format MM/YYYY, reflecting the month and year when TomTom updated the database to reflect attribute (name change, FIPS change, etc.) or boundary edits to the Place.

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

Last verified date, in the format MM/YYYY, representing the month and year that TomTom verified municipality change information.

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

Place.Name

The name of the "place" where the address is located. A "place" is a geographic area defined on the basis of population criteria that vary by state. Or, an area recognized as significant because it is located in an incorporated municipality.

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

Place.PostalCode Confidence Indicates if the ZIP Code resides in the place.

Note:

This field is always included in the output regardless of whether or not you choose to include tax jurisdiction data in the output.

Y null

ZIP Code not wholly contained in the place.

ZIP Code wholly contained in the place.

Unknown if the ZIP Code is wholly contained in the place or a match was not made at the ZIP Code level.

Only available for five-digit ZIP Code matches, not for street address matches.

User-Defined Boundary File

The following table lists the output fields that contain data returned from user-defined boundary files. To include this data in the output, set GeoTAXOutputRecordType = U.

Note:

AssignGeoTAXInfo can return up to 10 user-defined areas for each input address.

API Guide 385

Enterprise Tax Module

Table 150: Output Fields for User-Defined Boundary Files columnName Description

NumberUserBoundariesFound

UserBoundaryn.BoundaryDescription

UserBoundaryn.BoundaryID

Number of user-defined polygons returned.

A description of the polygon.

The ID of the polygon as specified in the user-defined boundary file.

UserBoundaryn.BufferRelation

Indicates where in the polygon the address resides in relation to the edge of the area.

One of the following:

The address is inside the polygon at a distance from the edge that is greater than the specified buffer width.

Buffer width is specified either by the option

DefaultBufferWidth or by the input field BufferWidth.

The address is inside the polygon but is close to the edge. This indicates that the address is in the buffer area specified either by the option DefaultBufferWidth or by the input field BufferWidth.

The address is outside the polygon but is close to the edge. This indicates that the address is in the buffer area specified either by the option DefaultBufferWidth or by the input field BufferWidth.

For more information, see

Buffering

on page 359.

UserBoundaryn.DistanceToBorder

Indicates the distance from the address to the border of the polygon. The distance is in the units specified by the option

DistanceUnits.

UserBoundaryn.SupplementalBoundaryID

A supplemental ID as specified in the user-defined boundary file.

Reports

To create the report, drag the Assign GeoTAX Info Summary Report icon to the canvas. You do not need to draw a connector to the report.

Assign GeoTAX Info Summary Report

The Assign GeoTAX Info Summary Report contains general information about the job, such as the settings, number of records processed, performance statistics, and the database used. It also contains detailed statistics about the results of the job. This report contains the following sections.

Job Summary

This section contains information about the software and databases used for the job.

• Software Version—The version of the underlying software used by AssignGeoTAXInfo. Note that this is not the same as the Spectrum

™

Technology Platform version number.

• Base Database Version—The version of the Base portion of the Master File database. For information on the Master File, see

What Is the Enterprise Tax Module?

on page 354.

386 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

• Advanced Database Version—The version of the Advanced portion of the Master File database. For information on the Master File, see

What Is the Enterprise Tax Module?

on page 354.

• Street Database Version—The version of the Street portion of the Master File database. For information on the Master File, see

What Is the Enterprise Tax Module?

on page 354.

• Cross Reference Database Version—The version of the cross-reference database used in this job.

Cross-reference databases are used to determine jurisdiction codes for use with third-party tax software.

For information on the Cross Reference databases, see

What Is the Enterprise Tax Module?

on page 354.

Address Matching Summary

This section describes the input address match counts.

• Total Match Attempts—Address matches attempted in this job.

• Total Records Matched—Input addresses that were matched to known locations.

• Total Unmatched Records—Input addresses that could not be matched to known addresses.

Address Matching Levels

This section describes how precisely AssignGeoTAXInfo matched an input address to a location. The more accurately AssignGeoTAXInfo determines a street segment for an input address, the more accurately it determines tax jurisdictions for the address.

• User-Defined Auxiliary File Matches—Addresses matched to the user-defined auxiliary file. For information on a user-defined auxiliary file, see

What Is the Enterprise Tax Module?

on page 354.

• GeoTAX Auxiliary File Matches—Addresses matched to the GeoTAX Auxiliary file. For information on the GeoTAX Auxiliary file, see

What Is the Enterprise Tax Module?

on page 354.

• State-Level Matches—Addresses matched to a state-supplied files.

• Street-Level Matches—Addresses matched to a specific street segment.

• ZIP-Level Matches—Addresses matched to a 5-digit ZIP Code.

• ZIP + 4-Level Matches—Addresses matched to a ZIP + 4 code.

GeoTAX Key Matching

This section describes how accurately AssignGeoTAXInfo determined GeoTAX keys. A GeoTAX key is used in conjunction with software from a third party to determine tax rates. If you do not choose to return a GeoTAX key, this section is blank.

• GeoTAX Cross Reference Match Attempts—Addresses that AssignGeoTAXInfo attempted to match to an cross reference file. These files are used to determine codes for use with third party tax software.

• Unsuccessful GeoTAX Cross Reference Matches—Addresses that AssignGeoTAXInfo attempted to determine a code but was unable.

• Successful GeoTAX Cross Reference Matches—Addresses that AssignGeoTAXInfo determined a code using a cross reference file. Addresses included in this count have a value in the GeoTAXKey output field.

• Exact Matches Achieved—Addresses matched exactly to a GeoTAX key. For more information about

GeoTAX key match levels, see the description of the GeoTAXKey.MatchCode output field under

Tax

Jurisdiction

on page 383.

• Partial Matches Achieved—Addresses partially matched to a GeoTAX key. For more information about GeoTAX key match levels, see the description of the GeoTAXKey.MatchCode output field under

Tax Jurisdiction

on page 383.

• Alternate Matches Achieved—Addresses matched to a GeoTAX key using an alternate, less accurate, method. For more information about GeoTAX key match levels, see the description of the

GeoTAXKey.MatchCode output field under

Tax Jurisdiction

on page 383.

• Default Matches Achieved—Addresses matched to a GeoTAX key only at the state level. For more information about GeoTAX key match levels, see the description of the GeoTAXKey.MatchCode output field under

Tax Jurisdiction

on page 383.

API Guide 387

Enterprise Tax Module

Latitude/Longitude Matching

This section describes how precisely AssignGeoTAXInfo determined latitude/longitude coordinates of an address. These counts are based on match codes. For more information, on match codes, see

Latitude/Longitude

on page 374.

• Total Lat/Long Matches—Addresses that AssignGeoTAXInfo determined latitude/longitude coordinates.

Addresses included in this count have any value other than null in the LatLong.MatchCode output field.

• Total Lat/Long Unmatched—Addresses that AssignGeoTAXInfo was unable to determine latitude/longitude. Addresses included in this count have a value of null in the LatLong.MatchCode output field.

• GeoTAX Auxiliary-level Matches—Latitude/longitude determined using the GeoTAX Auxiliary File.

• Address-Level Matches—The latitude/longitude represents the actual location of the address. This is the most accurate type of geocode. Addresses included in this count have a value of R in the

LatLong.MatchCode output field.

• ZIP + 4-Level Matches—The latitude/longitude represents the center of the ZIP + 4 code in which the address is located. Addresses included in this count have a value of 4 in the LatLong.MatchCode output field.

• Census Block Group-Level Matches—The latitude/longitude represents the center of the address's

Census block group. Addresses included in this count have a value of B in the LatLong.MatchCode output field.

• ZIP Sector-Level Matches—The latitude/longitude represents the center of the address's ZIP + 2 code. Addresses included in this count have a value of 2 in the LatLong.MatchCode output field.

• Census Tract-Level Matches—The latitude/longitude represents the center of the address's Census tract. Addresses included in this count have a value of T in the LatLong.MatchCode output field.

• ZIP Code-Level Matches—The latitude/longitude represents the center of the ZIP Code in which the address is located. Addresses included in this count have a value of Z or 5 in the LatLong.MatchCode output field.

Census Matching

This section describes how precisely AssignGeoTAXInfo determined an address location within the statistical areas defined by the U.S. Census.

• Census Tracts Determined—Addresses that AssignGeoTAXInfo determined a census tract. Addresses included in this count have a value in the Census.Tract output field.

• Census Tracts Not Determined—Addresses that AssignGeoTAXInfo was unable to determine a census tract. Addresses included in this count have no value in the Census.Tract output field.

• State Codes Determined—Addresses that AssignGeoTAXInfo determined a state. Addresses included in this count have a value in the StateCode output field.

• State Codes Not Determined—Addresses that AssignGeoTAXInfo did not determine a state. Addresses included in this count have no value in the StateCode output field.

• County Codes Determined—Addresses that AssignGeoTAXInfo determined a county. Addresses included in this count have a value in the County.Code output field.

• County Codes Not Determined—Addresses that AssignGeoTAXInfo did not determine a county.

Addresses included in this count have no value in the County.Code output field.

• Census Block Group Determined—Addresses that AssignGeoTAXInfo determined a block group.

Addresses included in this count have a value in the Census.BlockCode output field.

• Census Block Groups Not Determined—Addresses that AssignGeoTAXInfo was unable to determine a block group Addresses included in this count have no value in the Census.BlockCode output field.

• MSA Codes Determined—Addresses that AssignGeoTAXInfo determined a metropolitan statistical area (MSA). Addresses included in this count have a value in the MSA.Code output field.

• MSA Codes Not Determined—Addresses that AssignGeoTAXInfo did not determine a metropolitan statistical area (MSA). Addresses included in this count have no value in the MSA.Code output field.

388 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

• MCD/CCD Codes Determined—Addresses that AssignGeoTAXInfo determined a Minor Civil

Division/Census County Division code. Addresses included in this count have a value in the MCD.Code output field.

• MCD/CCD Codes Not Determined—Addresses that AssignGeoTAXInfo was unable to determine a

Minor Civil Division/Census County Division code. Addresses included in this count have no value in the MCD.Code output field.

Tax Jurisdiction Matching

This section describes how accurately AssignGeoTAXInfo determined an address place. The place information is used to determine tax jurisdictions.

• Place Codes Determined—Addresses that AssignGeoTAXInfo determined a place code. Addresses included in this count have a value in the Place.Code output field.

• Place Codes Not Determined—Addresses that AssignGeoTAXInfo was unable to determine a place code. Addresses included in this count have no value in the Place.Code output field.

• Place Names Determined—Addresses that AssignGeoTAXInfo determined a place name. Addresses included in this count have a value in the Place.Name output field.

• Place Class Codes Determined—Addresses that AssignGeoTAXInfo determined a place code.

Addresses included in this count have a value in the Place.ClassCode output field.

• Incorporated Places—Addresses that reside in an incorporated municipality. Addresses included in this count have a value of Inc in the Place.IncorporatedFlag output field.

• Unincorporated Places—Addresses that reside in a place that is not an incorporated municipality.

Addresses included in this count have a value of Uninc in the Place.IncorporatedFlag output field.

• Place Last Annexed Date Found—Places that AssignGeoTAXInfo determined the last date of annexation. Addresses included in this count have a value in the Place.LastAnnexedDate output field.

• Place Last Verified Date Found—Places that AssignGeoTAXInfo determined the last date that the place data was verified by the data provider. Addresses included in this count have a value in the

Place.LastVerifiedDate output field.

• Place Last Updated Date Found—Places that AssignGeoTAXInfo determined the date that the place data was last updated by the data provider. Addresses included in this count have a value in the

Place.LastUpdatedDate output field.

Tax District Matching

This section describes the number of matches to specific types of tax districts. The specific type of tax districts displayed in this section vary based the district type selected in the Tax district field.

Note:

If you specify a buffer width in the Tax district buffer field, a single location could be counted in more than one district due to buffering. For more information about buffering, see

Buffering

on page 359.

• Successful Payroll Tax File Matches—Addresses that AssignGeoTAXInfo determined a payroll tax code using the Payroll Tax District boundary file. For more information on Payroll Tax Districts, see

Payroll Tax District

on page 376.

• Unsuccessful Payroll Tax File Matches—Addresses that AssignGeoTAXInfo was unable to determine a payroll tax code using the Payroll Tax District boundary file. For more information on Payroll Tax

Districts, see

Payroll Tax District

on page 376.

• Locations in Special Purpose Districts—Addresses that reside in at least one Special Purpose

District. For more information on Special Purpose Districts, see

Special Purpose Tax District

on page 382.

• Locations in 1 Special Purpose District—Addresses that reside in a single Special Purpose District.

Addresses included in this count have a value of 1 in the NumberSPDsFound output field.

• Locations in 2 Special Purpose Districts—Addresses that reside in two overlapping Special Purpose

Districts. Addresses included in this count have a value of 2 in the NumberSPDsFound output field.

API Guide 389

Enterprise Tax Module

• Locations in 3 or 4 Special Purpose Districts—Addresses that reside in three or four overlapping

Special Purpose Districts. Addresses included in this count have a value of 3 or 4 in the

NumberSPDsFound output field.

• Locations in 5+ Special Purpose Districts—Addresses that reside in five or more overlapping Special

Purpose Districts. Addresses included in this count have a value of 5 or greater in the

NumberSPDsFound output field.

• Locations in User-Defined Districts—Addresses that reside in at least one user-defined district. For more information on user-defined districts, see

User-Defined Boundary File

on page 385.

• Locations in 1 User District—Addresses that reside in one user-defined district. Addresses included in this count have a value of 1 in the NumberUserBoundariesFound output field.

• Locations in 2 User Districts—Addresses that reside in two overlapping user-defined districts.

Addresses included in this count have a value of 2 in the NumberUserBoundariesFound output field.

• Locations in 3+ User Districts—Addresses that reside in three or more overlapping user-defined districts. Addresses included in this count have a value of 3 in the NumberUserBoundariesFound output field.

CalculateDistance

CalculateDistance takes two sets of latitude/longitude coordinates as input, calculates the distance between the coordinates, and returns the distance between the two points.

CalculateDistance is part of the Enterprise Tax Module.

Input

CalculateDistance takes latitude and longitude information as input.

Note:

Specify input using the DataTable class. For information on the DataTable class, see the "API

Fundamentals" section.

Table 151: CalculateDistance Input Data columnName Description

FirstLatitude

FirstLatitude.Directional

FirstLongitude

FirstLongitude.Directional

Latitude of the first point for which you want distance returned.

First latitude directional.

North

South

Longitude of the first point for which you want distance returned.

First longitude directional.

East

West

SecondLatitude

SecondLatitude.Directional

SecondLongitude

Latitude of the second point for which you want distance returned.

Second latitude directional.

North

South

Longitude of the second point for which you want distance returned.

390 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName Description

SecondLongitude.Directional

Second longitude directional.

East

West

Options

Table 152: Output Data and Format Options optionName

LatLongFormat

ReturnUnits

Description

Indicates the format of the input latitude/longitude. The options are:

DegMinSec

For example 90 00 00N180 00 00W.

PreZero

PreZeroDecimal

(090000000N180000000W). Default.

(090.000000N180.000000W)

Decimal

DecimalAssumed

(90.000000-180.000000)

(90000000-180000000)

Indicates the measurement units returned for distance calculation:

• Miles

• Km

• Feet

• Meters

Output

CalculateDistance always returns the Confidence field to indicate the confidence in the output provided.

If CalculateDistance fails to process the data, it returns the fields Status, Status.Code, and

Status.Descriptions. These fields provide information on why CalculateDistance failed to process the data. Some examples of failures are your license expired or you did not select any output record types and fields for CalculateDistance to return. The following table provides the record-level qualifiers and data outputs for CalculateDistance.

Table 153: CalculateDistance Output Fields columnName

Distance

Status

Status.Code

Description

Distance between the two input coordinates in the units of measurement that you specified.

Reports the success or failure of the match attempt:

null

Success

Failure

Reason for failure or error. If Status = F, Status.Code = Failure.

API Guide 391

Enterprise Tax Module columnName

Status.Description

Description

Description of the problem. If Status = F, Status.Description = Unable to compute distance.

Creating a User-Defined Auxiliary File

To enter data in a user-defined auxiliary file, use your own editor or data entry program. Sort the records by ascending ZIP Code, street name, street type, directional, low house range, and descending high house range to minimize the time required to street-level match.

The auxiliary file has a block size of 8K, key length of 47 bytes, and record length of 800 bytes. The sample file SEQAUX illustrates the layout of the file.

The following table describes the layout of the auxiliary file. After you create a file with this layout, install the file using the Enterprise Tax Module database load utility. For instructions, see the Spectrum

™

Technology Platform Installation Guide.

Table 154: User-Defined Auxiliary File Layout

Description Length Position Field Name

6-35

36-39

40-41

42-43

44-47

Input Key Area (Must be Unique)

1-5 G1GTAUX-ZIP-CODE

G1GTAUX-STREETNAME

G1GTAUX-STREET-TYPE

G1GTAUX-PRE-DIR

G1GTAUX-POST-DIR

G1GTAUX-SEQ

Output Area

48-58 G1GTAUX-OUTPUTRANGE-FROM

ZIP Code

Street name

Street type

Predirectional

Postdirectional

Sequence number, from

0001-9999

59-69

G1GTAUX-OUTPUTRANGE-TO

G1GTAUX-OUTPUTODD-EVEN

G1GTAUX-OUTPUTASC-DESC

First number in the house number range

(right adjusted, blankfilled)

Last number in the house number range

(right adjusted, blankfilled)

• O = Odd

• E = Even

• A = Ascending

• D = Descending

73-74

Reserved

G1GTAUX-STATE-CODE

392

FIPS State Code 2,0

Spectrum

™

Technology Platform 9.0

267-273

274-280

281-287

288-296

297-500

501-800

Position

75-77

78-83

85-92

93-94

95-119

120-124

125-164

165-168

169-218

219-223

224-263

264-265

266

Field Name

G1GTAUX-COUNTYCODE

G1GTAUX-CENSUSTRACT

G1GTAUX-BLOCKGROUP

Reserved

G1GTAUX-STATE-ABBV

G1GTAUX-COUNTYNAME

G1GTAUX-MCD-CODE

G1GTAUX-MCD-NAME

G1GTAUX-MSA-CODE

G1GTAUX-MSA-NAME

G1GTAUX-PLACE-CODE

G1GTAUX-PLACENAME

G1GTAUX-PLACECLASS-CODE

G1GTAUX-PLACE-INCFLAG

G1GTAUX-PLACE-LASTANNEXED

G1GTAUX-PLACE-LASTUPDATED

G1GTAUX-PLACE-LASTVERIFIED

G1GTAUX-PLACE-GNIS

Reserved

G1GTAUX-AUX-AREA

Chapter 8: Module Services

Description Length

FIPS County Code

6-digit Census Tract number

1-digit Block Group 1

USPS state abbreviation 2

3,0

6,0

County name

5-digit MCD Code

MCD Name

4-digit MSA Code

MSA Name

5-digit Place Code

Place Name 40

2-digit Place Class Code 2

• U - Unincorporated

• I - Incorporated

4,0

5,0

Place last annexed date, in the format MM/YYYY

Place last updated date, in the format MM/YYYY

Place last verified date, in the format MM/YYYY

GNIS Code

User-defined data

204

300

GeoConfidence Module

What Is the GeoConfidence Module?

The GeoConfidence Module is used to determine the probability that an address or street intersection is within a given area. The module takes an address or intersection's location (determined by Geocode

US Address), converts that location to a point, line, or polygon (depending on the precision of the match), then compares that shape with a database of known shapes to see if the two overlap, and the percentage overlap. For example, you could use the GeoConfidence Module to make decisions on a flood zone rating based on how much overlap there is between an address's location and the flood zone data.

API Guide 393

GeoConfidence Module

Anything greater than a 95% overlap with a 100-year flood zone may indicate that the address is in the flood zone. Conversely, anything less than 95% could cause your business process to send the address to exception processing that might include a manual review.

An address or intersection can be geocoded to a point, an address along a street segment (an array of street segment points), ZIP + 4 centroid, ZIP + 2 centroid, or ZIP Code centroid (polygons). You can use these shapes (points, lines, or polygons) to compare with other shapes to determine overlap, which can be used to determine a risk or probability.

Different geoconfidence polygons are generated depending on the GeoConfidence result returned by the Enterprise Geocoding Module. Refer to the Enterprise Geocoding Module documentation for more information about the GeoConfidence information returned by the Enterprise Geocoding Module.

The GeoConfidence Module supports U.S. locations only.

Note:

GeoConfidence uses services provided by the Enterprise Geocoding and Location Intelligence modules.

GeoConfidence Components

GeoConfidence deploys three dataflows that you can modify in Enterprise Designer. Each dataflow consists of various components that were installed with the Enterprise Geocoding and Location Intelligence modules.

For information about each component in the installed dataflows, see the relevant component chapter in the Spectrum

™

Technology Platform User's Guide.

The names of the dataflows are:

• GeoConfidenceSurface This is the dataflow that creates the geoconfidence surface that can be used for further analysis. The input is the GeoConfidence information that is returned from the Enterprise

Geocoding Module. Currently, only the Geocode US Address stage can return this information.

• CreatePointsConvexHull This is a subflow that is used by the GeoConfidenceSurface template. You should not need to make any changes to this subflow.

• FloodRiskAnalysis This is an example dataflow.

GeoConfidence Databases

GeoConfidence uses the same databases as the Enterprise Geocoding and Location Intelligence modules.

For information about how to add these databases, see the Spectrum

™

Administration Guide.

Technology Platform

In addition to these databases, the GeoConfidence Module includes a database of ZIP Code polygons.

This is used by GeoConfidenceSurface.

GeoConfidenceSurface

GeoConfidenceSurface returns geoconfidence polygons (also called surfaces) based on the quality of the geocode information generated by the Enterprise Geocoding Module. With the geoconfidence polygons generated, you can then overlap this polygon with other spatial data to determine a risk or probability.

This service is used by the GeoConfidence Module's FloodZoneAnalysis dataflow template.

Note:

GeoConfidence uses services provided by the Enterprise Geocoding and Location Intelligence modules.

Input

The input fields for GeoConfidenceSurface are the output fields returned by the GeoConfidence output category of the Enterprise Geocoding Module. These fields are described below.

394 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services columnName

Response Element

GeoConfidenceCode

StreetSegmentPoints

GeoConfidenceCentroidLatitude

GeoConfidenceCentroidLongitude

Description

The value returned in this field indicates which geoconfidence surface type has been returned.

Possible values are:

INTERSECTION

A geocode point for the intersection of two streets.

ADDRESS

POINT

POSTAL1

POSTAL2

An array of street segment points representing the street segment where the address is located.

If the geocoder was able to match the address using point data, the point geometry where the address is located.

A geocode point for the ZIP centroid.

POSTAL3

ERROR

An array of points for all street segments in the ZIP + 2 in which the address is located.

An array of points for street segments in the ZIP + 4 in which the address is located.

An error has occurred.

An array of latitude/longitude values that represent the street segment points.

Note:

This field contains values only if the

GeoConfidenceCode field returns a value of

ADDRESS

, POSTAL2, or POSTAL3.

The latitude of the centroid of the geoconfidence polygon.

The longitude of the centroid of the geoconfidence polygon.

Output

The GeoConfidenceSurface output field contains the geoconfidence polygon.

columnName

Geometry

Description

A geoconfidence polygon that represents the returned geometry.

Customizing the GeoConfidence Module

The GeoConfidence Module deploys three dataflow templates that you can modify in Enterprise Designer.

Each dataflow consists of various components that were installed with the Enterprise Geocoding and

Location Intelligence modules.

API Guide 395

Universal Addressing Module

The names of the dataflow templates are:

• GeoConfidenceSurface This is the template that creates the geoconfidence surface that can be used for further analysis. The input is the GeoConfidence information that is returned from the Enterprise

Geocoding Module. Currently, only the Geocode US Address stage can return this information. To customize this template, you must at minimum specify the 5-digit ZIP Code spatial source in the ZIP stage (Query Spatial).

• CreatePointsConvexHull This is a subflow that is used by the GeoConfidenceSurface template. You should not need to make any changes to this subflow.

• FloodRiskAnalysis This is an example template. To customize this template, you must at minimum specify Flood spatial source in the Find Nearest stage.

Universal Addressing Module

What Is the Universal Addressing Module?

The Universal Addressing Module is an address quality module that can standardize and validate addresses, improving the deliverability of mail. The Universal Addressing Module can ensure that your address data adheres to quality standards established by the postal authority. An address that adheres to these standards is more likely to be delivered in a timely manner. In addition, mailers who follow these standards can qualify for significant postage discounts. For information on discounts for U.S. mail, refer to the USPS Domestic Mail Manual (DMM) available at

www.usps.com

. For information on discounts for Canadian mail, refer to the Canada Post website at

www.canadapost.ca

. For information on discounts for Australian mail, refer to the Australia Post website at

www.auspost.com.au

The Universal Addressing Module can be used in batch mode, realtime mode, or as a hosted service, depending on which option you have licensed. The batch version of the Universal Addressing Module is CASS Certified

™ by the USPS

. It is also AMAS certified by Australia Post.

The Universal Addressing Module is one of two address quality modules available for Spectrum

™

Technology Platform. The other address quality module, the Address Now Module, provides enhanced support for addresses outside the U.S. and Canada, including validation for more countries and double-byte support. If you have a large amount of international address data, you may want to consider using the Address Now Module for address standardization and validation.

Universal Addressing Components

The Universal Addressing Module consists of the following components. These components can work with U.S., Canadian, Australian, and international addresses as long as you are licensed for the appropriate database (if you are running Universal Addressing in your own environment) or hosted service (if you are utilizing Universal Addressing through the Pitney Bowes Software hosted services).

• AutoCompleteLoqate—Offers real-time entry of address data and returns instant results based on each character entered into the form, ensuring only accurate data is entered into the database.

• GetCandidateAddresses—Returns a list of possible matches for a given address.

• GetCandidateAddressesLoqate—Returns a list of possible matches for a given address using a

Loqate engine and database.

• GetCityStateProvince—Returns the city and state/province for a given postal code.

• GetCityStateProvinceLoqate—Returns the city and state/province for a given postal code using a

Loqate engine and database.

• GetPostalCodes—Returns the postal codes for a given city.

• GetPostalCodesLoqate—Returns the postal codes for a given city using a Loqate engine and database.

• ValidateAddress—Standardizes and validates addresses using U.S., Canadian, and international postal data.

• ValidateAddressAUS—Standardizes and validates addresses using Australian postal data.

396 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

• ValidateAddressGlobal—ValidateAddressGlobal provides enhanced address standardization and validation for addresses outside the U.S. and Canada. ValidateAddressGlobal can also validate addresses in the U.S. and Canada but its strength is validation of addresses in other countries. If you process a significant number of addresses outside the U.S. and Canada, you should consider using

ValidateAddressGlobal.

• ValidateAddressLoqate—ValidateAddressLoqate standardizes and validates addresses using postal authority address data. ValidateAddress Loqate can correct information and format the address using the format preferred by the applicable postal authority. It also adds missing postal information, such as postal codes, city names, state/province names, and so on.

Universal Addressing Databases

The Universal Addressing Module uses a number of required and optional databases. The databases are installed on the Spectrum

™

Technology Platform server. Some of the databases are available by subscription from Pitney Bowes Software and are updated monthly or quarterly. Others are licensed from the USPS

. The following table lists the Universal Addressing databases.

Table 155: Universal Addressing Module Databases

Database Name & Description Required or

Optional

Supplier

U.S. Postal Database

The U.S. Postal Database is in a Pitney Bowes proprietary format. It contains every house number range in the United

States and is updated on a monthly basis. The database files contain the following information:

Required for U.S.

address processing

Pitney Bowes

Software monthly subscription

• ZIP + 4

Code

• Standardized address elements

• City and state information

The U.S. Postal Database also contains the data needed to perform Enhanced Street Matching (ESM) and All Street

Matching (ASM). ESM and ASM apply extra matching logic to any input address that is not matched through the regular address validation process.

Canadian Postal Database

The Canadian Postal database is in Pitney Bowes Software proprietary format. The database files contain the following information:

Required for

Canadian address processing

• Postal code

• Standardized address elements

• Municipality and province information

Pitney Bowes

Software monthly subscription

Australia Post Postal Address File Database

The Postal Address File is part of Australia Post's Address

Matching Approval System (AMAS) program. The database file contains the following information:

Required for

Australian address processing

Pitney Bowes

Software monthly subscription

• Postal code

• Standardized address elements

API Guide 397

Universal Addressing Module

Database Name & Description Required or

Optional

Supplier

International Postal Database

The International Postal Database is a collection of postal address data from around the world. Data from each country is categorized according to the level of data available. The categories are:

Required for

International address processing

Pitney Bowes

Software quarterly subscription

• Category A—Enables the validation and correction of an address's postal code, city name, state/county name, street address elements, and country name.

• Category B—Enables the validation and correction of an address's postal code, city name, state/county name, and country name. It does not support the validation or correction of street address elements.

• Category C—Enables the validation and correction of the country name, and the validation of the format of the postal code.

DPV

Database

The Delivery Point Validation database allows you to check the validity of an individual mailing address in the U.S. The

DPV database enhances the U.S. Postal database's ability to validate mailing addresses.

Optional, but required for CASS

Certified

™ processing; U.S.

addresses only

Note:

The DPV database also contains the data required for Commercial Mail Receiving Agency (CMRA) processing.

Pitney Bowes

Software monthly subscription

Each time an edition of the U.S. Postal database is released, a corresponding edition of the DPV database is released.

Although USPS licensing allows the use of the U.S. Postal database beyond the expiration date (with certain restrictions),

DPV lookups may not be performed after the expiration date of the DPV database.

USPS licensing prohibits using DPV data for the generation of addresses or address lists. To prevent the generation of address lists, the DPV database contains "false positive records." False positive records are artificially manufactured addresses. For each negative response that occurs in a DPV query, a query is made to the False/Positive table in the DPV database. A match to this table will stop DPV processing.

USPS licensing also prohibits exporting the DPV data outside the United States.

eLOT

Database

The Enhanced Line of Travel ( eLOT) database is a U.S.

address database that ensures that Enhanced Carrier Route mailings are sorted as close as possible to the actual delivery sequence. the eLOT database is required for certain types of postal discounts.

Optional; U.S.

addresses only

You will receive monthly updates to your eLOT database on the same media as the U.S. Postal database.

Pitney Bowes

Software monthly subscription

398 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Database Name & Description Required or

Optional

Supplier

You must install the U.S. Postal database and eLOT database from the same month (i.e., September eLOT data must be processed with a September U.S. Postal database). If the

U.S. Postal database and the eLOT database are not from the same month, there may be ZIP + 4

Codes for which eLOT numbers cannot be assigned. The ZIP Code

™

, ZIP +

4 Code, carrier route code, and the delivery point of an address must be provided to assign a eLOT code.

EWS Database

The Early Warning System (EWS) database prevents address validation errors that can result due to a delay in postal data reaching the U.S. Postal database.

Optional; U.S.

addresses only

The EWS database consists of partial address information limited to the ZIP Code

™

, street name, pre- and post-directionals, and a suffix. For an address record to be

EWS-eligible, it must be an address not present on the most recent monthly production U.S. Postal database.

The USPS

® refreshes the EWS file on a weekly basis

(Thursdays). You can download the EWS file from the USPS

® website at

ribbs.usps.gov

LACS

Link

Database

The LACS

Link database allows you to correct addresses that have changed as a result of a rural route address converting to street-style address, a PO Box renumbering, or a street-style address changing.

USPS licensing prohibits using LACS

Link for the generation of addresses or address lists. To prevent the generation of address lists, the LACS

Link database contains "false positive records." False positive records are artificially manufactured addresses. For each negative response that occurs in a

LACS

Link query, a query is made to the False/Positive table in the LACS

Link

LACS

Link database. A match to this table will stop processing.

USPS licensing also prohibits exporting the LACS

Link database outside the United States

Optional, but required for CASS

Certified

™ processing; U.S.

addresses only

RDI

™

Database

The Residential Delivery Indicator (RDI

™

) database contains data that can help you determine the best cost for shipping your packages.

Optional; U.S.

addresses only

RDI is similar to DPV in that the RDI data is supplied as hash tables. However, RDI is a much simpler process than DPV in that the standard hash algorithm is only determined for the

9-digit and 11-digit ZIP Code

™ rather than the entire address.

Suite

Link

™

Database

Suite

Link

™ corrects secondary address information for U.S.

business addresses whose secondary address information

Optional; U.S.

addresses only

Download for free from USPS

® website

Pitney Bowes

Software monthly subscription

License directly from USPS

Pitney Bowes

Software monthly subscription

API Guide 399

Universal Addressing Module

Database Name & Description

could not be validated. If Suite

Link processing is enabled,

ValidateAddress attempts to match the value in the FirmName field to a database of known firm names. ValidateAddress then supplies the correct secondary address information.

Required or

Optional

Supplier

AutoCompleteLoqate

AutoCompleteLoqate offers real-time entry of address data for fast, accurate results. Users are returned instant results based on each character entered into the form, ensuring only accurate data is entered into the database.

Input

The following table lists the input for AutoCompleteLoqate.

Table 156: Input Format columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

City

Country

FirmName

PostalCode

StateProvince

Description

The first address line.

The second address line.

The third address line.

The fourth address line.

The city name.

The country code or name, in any of the following formats:

• 2-digit ISO country code

• 3-digit UPU Country code

• English country name

For a list of ISO codes, see

Country ISO Codes and Module Support

The company or firm name.

The postal code for the address.

The state or province.

400 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Options

Table 157: AutoCompleteLoqate Options optionName

Database.Loqate

OutputCasing

HomeCountry

Description

Specifies the database to be used for address processing. Only databases that have been defined in the Database Resources panel in the Management Console are available.

Specifies the casing of the output data. One of the following:

The output in mixed case (default). For example:

123 Main St

Mytown FL 12345

The output in upper case. For example:

123 MAIN ST

MYTOWN FL 12345

Specifies the default country. You should specify the country where most of your addresses reside. For example, if most of the addresses you process are in Canada, specify Canada. The valid country names are:

Afghanistan, Albania, Algeria, American Somoa, Andorra, Angola,

Anguilla, Antigua And Barbuda, Argentina, Armenia, Aruba, Australia,

Austria, Azerbaijan, Bahamas, Bahrain, Bangladesh, Barbados, Belarus,

Belgium, Belize, Benin, Bermuda, Bhutan, Bolivia, Bosnia And

Herzegovina, Botswana, Brazil, British Virgin Islands, Brunei

Darussalam, Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon,

Canada, Cape Verde, Cayman Islands, Central African Republic, Chad,

Chile, China, Colombia, Comoros Islands, Congo, Cook Islands, Costa

Rica, Cote D'Ivoire, Croatia, Cuba, Cyprus, Czech Republic, Democratic

Republic Of Congo, Denmark, Djibouti, Dominica, Dominican Republic,

East Timor, Ecuador, Egypt, El Salvador, Equitorial Guinea, Eritrea,

Estonia, Ethiopia, Falkland Islands, Faroe Islands, Federated States Of

Micronesia, Fiji, Finland, France, French Guiana, Gabon, Gambia,

Germany, Ghana, Gibraltar, Greece, Greenland, Grenada, Guadeloupe,

Guam, Guatemala, Guinea, Guinea Bissau, Guyana, Haiti, Holy See,

Honduras, Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq,

Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan, Kenya,

Kiribati, Korea, Kuwait, Kyrgyzstan, Laos, Latvia, Lebanon, Lesotho,

Liberia, Libya, Liechtenstein, Lithuania, Luxembourg, Macau, Macedonia,

Madagascar, Malawi, Malaysia, Maldives, Mali, Malta, Marshall Islands,

Martinique, Mauritania, Mauritius, Mayotte, Mexico, Moldova, Monaco,

Mongolia, Monserrat, Morocco, Mozambique, Myanmar, Namibia, Nauru,

Nepal, Netherlands Antilles, New Caledonia, New Zealand, Nicaragua,

Niger, Nigeria, Niue, Norway, Oman, Pakistan, Palau, Panama, Papua

New Guinea, Paraguay, Peru, Philippines, Pitcairn Islands, Poland,

Portugal, Puerto Rico, Qatar, Republic Of Georgia, Republic Of Korea,

Republic Of Singapore, Reunion, Romania, Russia, Rwanda, Saint

Helena, Saint Kitts And Nevis, Saint Lucia, Saint Pierre And Miquelon,

Saint Vincent And The Grenadines, Samoa, San Marino, Sao Tome

And Principe, Saudi Arabia, Senegal, Seychelles, Sierra Leone, Slovakia,

API Guide 401

Universal Addressing Module optionName Description

OutputScript

Slovenia, Solomon Islands, Somalia, South Africa, Spain, Sri Lanka,

Sudan, Surivalue, Swaziland, Sweden, Switzerland, Syria, Tahiti, Taiwan,

Tajikistan, Tanzania, Thailand, The Netherlands, Togo, Tonga, Trinidad

And Tobago, Tristan Da Cunha, Tunisia, Turkey, Turkmenistan, Turks

And Caicos Islands, Tuvalu, Uganda, Ukraine, United Arab Emirates,

United Kingdom, United States, Uruguay, Uzbekistan, Vanuatu,

Venezuela, Vietnam, Virgin Islands (US), Wallis And Futuna, Yemen,

Yugoslavia, Zambia, Zimbabwe

Specifies the alphabet or script in which the output should be returned.

This option is bi-directional and generally takes place from Native to

Latin and Latin to Native.

Input

Do not perform transliteration and provide output in the same script as the input (default).

Native

Latn

Output in the native script for the selected country wherever possible.

Use English values.

MaximumResults The maximum number of addresses that AutoCompleteLoqate should return. The default is 10.

FailJobOnDataLicenseError Specifies how you want Spectrum Technology Platform to respond when a data license error occurs.

Fail the job

Fail the entire job if a data license error occurs.

Fail the record

Fail the record(s) for which the data license error occurs and continue processing.

402

Output

The output from AutoCompleteLoqate is optional and corresponds directly to the fields you selected in the Output Fields section of the AutoCompleteLoqate Options dialog box.

Table 158: AutoCompleteLoqate Output columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

City

Country

FirmName

HouseNumber

Description

The first address line.

The second address line.

The third address line.

The fourth address line.

The city name.

The three-character ISO 3116-1 Alpha-3 code for the country. For a list of ISO codes, see

Country ISO Codes and Module Support

The firm name.

The ending house number for the range in which the candidate address's house number falls.

Spectrum

™

Technology Platform 9.0

columnName

PostalCode

PostalCode.AddOn

ProcessedBy

StateProvince

Status

Status.Code

Status.Description

Chapter 8: Module Services

Description

The postal code.

The last four digits of the ZIP + 4

Code.

Indicates which address coder processed the address.

LOQATE

The Loqate coder processed the address.

The state or province abbreviation.

Reports the success or failure of the match attempt.

null

Success

Failure

The reason for failure, if there is one.

• DisabledCoder

• RequestFailed

• NoLookupAddressFound

A description of the problem, if there is one.

Did not return multiples

The input address matched only one address in the database.

AutoCompleteLoqate returns data only if multiple possible matches were found.

Not able to look up the address pattern

AutoCompleteLoqate is not able to process the partial address.

AutoCompleteLoqate Sample Web Application

You can access a sample web application that demonstrates the Auto Complete Loqate functionality.

When you enter a partial address, this application makes a call to the Auto Complete Loqate REST web service, which returns a suggested address.

Note:

Prior to using this feature, you must add an Auto Complete Loqate database resource in

Management Console and save the database resource in the Auto Complete Loqate Service.

1. Be sure the Spectrum

™

Technology Platform server is running.

2. Open a web browser and go to: http://<servername>:<port>/autocomplete. For example, if your server is named "myserver" and it uses the default HTTP port 8080, you would go to: http://myserver:8080/autocomplete

Note:

This site is best viewed in Internet Explorer 8.0 or later, Chrome, or Mozilla Firefox.

3. When the login screen appears, enter "guest" as the user name and leave the password field blank.

4. Press OK.

5. Select a country from the drop-down list.

6. Begin typing your address in any of the fields provided.

7. Select from the list of suggested addresses.

8. To begin a new call, click Reset, which will clear the fields you used in your previous call.

API Guide 403

Universal Addressing Module

GetCandidateAddresses

GetCandidateAddresses returns a list of addresses that are considered matches for a given input address.

GetCandidateAddresses returns candidate addresses only if the input address matches multiple addresses in the postal database. If the input address matches only one address in the postal database, then no address data is returned.

For addresses outside the U.S. and Canada, you may notice inconsistent results between the multiple matches returned by ValidateAddress and the results for that same address returned by

GetCandidateAddresses. If you experience inconsistent results, it is likely because you set the performance tuning setting in ValidateAddress to a value other than 100. To obtain consistent results between GetCandidateAddresses and ValidateAddress, set the performance tuning option to 100.

Note:

By default, GetCandidateAddresses does not match to individual house numbers. Rather, it uses house number ranges for each street. After GetCandidateAddresses has determined the street name, city name, state/province name, and postal code, it checks to make sure the input house number falls within one of the ranges of house numbers given for the matched street name. The same type of logic applies to unit numbers. If you want to determine that an individual house number is valid, you should use the ValidateAddress Delivery Point Validation (DPV) processing option. DPV processing is only available for U.S. addresses.

The Canadian coder contains a reverse lookup routine that takes as input a specific postal code and returns the street information stored in the database for that postal code. To use this function enter nothing but a Canadian postal code in the PostalCode field. See the second example to view the return from a sample postal code.

GetCandidateAddresses is part of the Universal Addressing Module.

Input

The following table lists the input for GetCandidateAddresses.

Table 159: Input Format columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

AddressLine5

City

StateProvince

Description

The first address line.

The second address line.

The third address line.

Does not apply to U.S. and Canadian addresses.

The fourth address line.

Does not apply to U.S. and Canadian addresses.

The fifth address line.

Applies only to U.K. addresses. May contain street name, unit number, building number, and so on.

The city name.

The state or province.

For U.S. addresses only, you may put the state in the City field instead of the StateProvince field.

404 Spectrum

™

Technology Platform 9.0

columnName

PostalCode

Country

FirmName

USUrbanName

Chapter 8: Module Services

Description

The postal code for the address. For U.S. addresses this is the ZIP

Code

™ in one of the following formats:

99999

99999-9999

A9A9A9

A9A 9A9

9999 999

Note:

For Canadian addresses you can complete just this field and have candidate address data returned. For other countries,

AddressLine1 and AddressLine2 must also be completed.

The country code or name, in any of the following formats:

• 2-digit ISO country code

• 3-digit UPU Country code

• English country name

• French country name

• German country name

• Spanish country name

For a list of ISO codes, see

Country ISO Codes and Module Support

The company or firm name.

U.S. address urbanization name. Used primarily for Puerto Rico addresses.

Options

Table 160: GetCandidateAddresses Options optionName

PerformUSProcessing

Description

Specifies whether or not to process U.S. addresses. If you enable U.S. address processing GetCandidateAddresses will attempt to retrieve candidate addresses for U.S. addresses.

If you disable U.S. address processing, U.S. addresses will fail, meaning they are returned with an "F" in the Status output field. The output field Status.Code will say "DisabledCoder."

If you are not licensed for U.S. address processing you must disable U.S. address processing in order for your jobs to complete successfully, regardless of whether or not they contain U.S. addresses.

Note:

You must have a valid license for U.S. address processing to successfully process U.S. addresses.

If you enable U.S. address processing but are not licensed for this feature, or your license has expired, you will receive an error.

Yes, process U.S. addresses (default).

API Guide 405

Universal Addressing Module optionName

406

Database.US

PerformCanadianProcessing

Database.Canada

PerformInternationalProcessing

Description

No, do not process U.S. addresses.

Specifies the database to be used for U.S. address processing. Only databases that have been defined in the

US Database Resources panel in the Management Console are available.

Specifies whether or not to process Canadian addresses. If you enable Canadian address processing

GetCandidateAddresses will attempt to retrieve candidate addresses for Canadian addresses. If you disable Canadian address processing, Canadian addresses will fail, meaning they are returned with an "F" in the Status output field. The output field Status.Code will say "DisabledCoder." If you are not licensed for Canadian address processing you must disable Canadian address processing in order for your jobs to complete successfully, regardless of whether or not they contain Canadian addresses.

Note:

You must have a valid license for Canadian address processing to successfully process Canadian addresses. If you enable Canadian address processing but are not licensed for this feature, or your license has expired, you will receive an error.

Yes, process Canadian addresses (default).

No, do not process Canadian addresses.

Specifies the database to be used for Canadian address processing. Only databases that have been defined in the

Canadian Database Resources panel in the Management

Console are available.

Specifies whether or not to process international addresses

(addresses outside the U.S. and Canada). If you enable international address processing GetCandidateAddresses will attempt to retrieve candidate addresses for international addresses. If you disable international address processing, international addresses will fail, meaning they are returned with an "F" in the Status output field. The output field

Status.Code will say "DisabledCoder." If you are not licensed for international address processing you must disable international address processing in order for your jobs to complete successfully, regardless of whether or not they contain international addresses.

Note:

You must have a valid license for international address processing to successfully process international addresses. If you enable international address processing but are not licensed for this feature, or your license has expired, you will receive an error.

Yes, process international addresses (default).

No, do not process international addresses.

Spectrum

™

Technology Platform 9.0

optionName

Database.International

OutputCasing

MaximumResults

OutputShortCityName

DualAddressLogic

StreetMatchingStrictness

API Guide

Chapter 8: Module Services

Description

Specifies the database to be used for international address processing. Only databases that have been defined in the

International Database Resources panel in the Management

Console are available.

Specifies the casing of the output data. One of the following:

The output is in mixed case (default). For example:

123 Main St

Mytown FL 12345

The output is in upper case. For example:

123 MAIN ST

MYTOWN FL 12345

The maximum number of candidate addresses that

GetCandidateAddresses should return. The default is 10. The maximum is 10.

For U.S. addresses, specifies whether or not to return the

USPS

-approved abbreviation for the city, if there is one. The

USPS

Yes, return the short city name.

No, do not return the short city name.

(U.S. addresses only). Controls whether

GetCandidateAddresses should return a street match or a

PO Box/Rural Route/Highway Contract match when the address contains both street and PO Box/Rural

Route/Highway Contract information. For more information, see

About Dual Address Logic

on page 433.

(Default) USPS

CASS

™ regulations determine the address returned based on the following order of priority:

1. PO Box

2. Firm

3. Highrise

4. Street

5. Rural Route

6. General Delivery

Return a street match, regardless of the address line.

Return a PO Box match, regardless of the address line.

The strictness of the street name match (U.S. addresses only).

407

Universal Addressing Module optionName

408

FirmMatchingStrictness

DirectionalMatchingStrictness

PerformESM

AddressLineSearchOnFail

Description

The input street name must match the database exactly.

The matching algorithm is "tight."

The matching algorithm is "medium" (default).

The matching algorithm is "loose".

The strictness of the firm name match (U.S. addresses only).

The input firm name must match the database exactly.

The matching algorithm is "tight."

The matching algorithm is "medium" (default).

The matching algorithm is "loose."

The strictness of the directional match.

The input directional must match the database exactly.

The matching algorithm is "tight."

The matching algorithm is "medium" (default).

The matching algorithm is "loose."

Specifies whether or not to perform Enhanced Street Matching

(ESM). ESM applies extra matching logic with additional data to any input address that is not matched through the regular address validation process. ESM applies to U.S. addresses only.

Yes, perform ESM processing.

No, do not perform ESM processing (default).

Specifies whether ValidateAddress will search address lines for the city, state/province, and postal code.

This option enables ValidateAddress to search the

AddressLine input fields for the city, state/province, postal code, and country when the address cannot be matched using the values in the City, StateProvince, and PostalCode input fields.

Consider enabling this option if your input addresses have the city, state/province, and postal code information in the

AddressLine fields.

Consider disabling this option if your input addresses use the

City, State/Province and PostalCode fields. If you enable this option and these fields are used, there is an increased possibility that ValidateAddress will fail to correct values in these fields (for example a misspelled city name).

Yes, search the address line fields (default).

No, do not search the AddressLine fields.

Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

Output

GetCandidateAddresses returns the following output.

Table 161: GetCandidateAddresses Output columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

AddressLine5

City

Country

FirmName

HouseNumberHigh

HouseNumberLow

HouseNumberParity

MatchLevel

PostalCode

PostalCode.AddOn

RecordType

Description

The first address line.

The second address line.

The third address line.

The fourth address line.

For U.K. addresses only. If the address was validated, the fifth line of the validated and standardized address. If the address could not be validated, the fifth line of the input address without any changes.

The city name.

The three-character ISO 3116-1 Alpha-3 code for the country. For a list of ISO codes, see

Country ISO Codes and Module Support

The firm name.

The ending house number for the range in which the candidate address's house number falls.

The beginning house number for the range in which the candidate address's house number falls.

Indicates the numbering scheme for the house numbers between

HouseNumberLow and HouseNumberHigh, as follows:

Only even values

Only odd values

Both

For addresses outside the U.S. and Canada, identifies the match level for the candidate address. U.S. and Canadian addresses are always

"A." One of the following:

The candidate matches the input address at the street level.

The candidate matches the input address at the state/province level.

The postal code. In the U.S. this is the ZIP Code

™

The last four digits of the ZIP + 4

Code. U.S. addresses only.

The type of address record, as defined by U.S. and Canadian postal authorities (U.S. and Canadian addresses only):

• FirmRecord

• GeneralDelivery

• HighRise

• PostOfficeBox

API Guide 409

Universal Addressing Module columnName

RecordType.Default

StateProvince

Status

Status.Code

Status.Description

UnitNumberHigh

UnitNumberLow

UnitNumberParity

USUrbanName

Description

• RRHighwayContract

• Normal

Code indicating the "default" match:

The address matches a default record.

null

The address does not match a default record.

The state or province abbreviation.

Reports the success or failure of the match attempt.

null

Success

Failure

The reason for failure, if there is one. There is only one possible value:

• DisabledCoder

• RequestFailed

A description of the problem, if there is one.

Did not return multiples

The input address matched only one address in the database.

GetCandidateAddresses only returns data if multiple possible matches were found.

Number of candidates is not greater than 1

The input address matched more than one address in the database but no addresses were returned.

PerformUSProcessing disabled

This value will appear if

Status.Code=DisabledCoder.

PerformCanadianProcessing disabled

This value will appear if

Status.Code=DisabledCoder.

PerformInternationalProcessing disabled

This value will appear if

Status.Code=DisabledCoder.

The ending unit number for the range in which the candidate address's unit number falls.

The beginning unit number for the range in which the candidate address's unit number falls.

Indicates the numbering scheme for the unit numbers between

UnitNumberLow and UnitNumberHigh, as follows:

Only even values

Only odd values

Both

The validated city urbanization name. Urbanization names are used primarily for Puerto Rico addresses.

410 Spectrum

™

Technology Platform 9.0

Chapter 8: Module Services

GetCandidateAddressesLoqate

GetCandidateAddressesLoqate returns a list of addresses that are considered matches for a given input address. GetCandidateAddressesLoqate returns candidate addresses only if the input address matches multiple addresses in the postal database. If the input address matches only one address in the postal database, then no address data is returned. The Country input field is required; if this field is blank, no output will be returned.

Note:

By default, GetCandidateAddressesLoqate does not match to individual house numbers. Rather, it uses house number ranges for each street. After GetCandidateAddressesLoqate has determined the street name, city name, state/province name, and postal code, it checks to make sure the input house number falls within one of the ranges of house numbers given for the matched street name. The same type of logic applies to unit numbers.

GetCandidateAddressesLoqate is part of the Universal Addressing Module.

Input

The following table lists the input for GetCandidateAddressesLoqate.

Table 162: Input Format columnName

AddressLine1

AddressLine2

AddressLine3

AddressLine4

City

Country

FirmName

PostalCode

StateProvince

Description

The first address line.

The second address line.

The third address line.

The fourth address line.

The city name.

The country code or name, in any of the following formats:

• 2-digit ISO country code

• 3-digit UPU Country code

• English country name

For a list of ISO codes, see

Country ISO Codes and Module Support

Note:

This field is required. If this field is blank, no output will be returned.

The company or firm name.

The postal code for the address. For U.S. addresses this is the ZIP

Code

™ in one of the following formats:

The state or province.

For U.S. addresses only, you may put the state in the City field instead of the StateProvince field.

API Guide 411

Universal Addressing Module

Options

Table 163: GetCandidateAddressesLoqate Options optionName

Database.Loqate

OutputCasing

HomeCountry

Description

Specifies the database to be used for address processing. Only databases that have been defined in the Management Console are available.

Specifies the casing of the output data. One of the following:

The output is in mixed case (default). For example:

123 Main St

Mytown FL 12345

The output is in upper case. For example:

123 MAIN ST

MYTOWN FL 12345

Specifies the default country. You should specify the country where most of your addresses reside. For example, if most of the addresses you process are in Canada, specify Canada.

GetCandidateAddressLoqate uses the country you specify to attempt validation when it cannot determine the country from the StateProvince,

PostalCode, and Country address fields. The valid country names are: