Location Intelligence Geographic Information Systems

MapMarker Plus

Version 31

Developer Guide Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of Pitney Bowes, 350 Jordan Road, Troy, New York 12180-8399. ©1994-2019 Pitney Bowes All rights reserved. MapInfo, Group 1 Software, Centrus, and MapMarker are trademarks of Pitney Bowes All other marks and trademarks are property of their respective holders.

Contact information for all Pitney Bowes Inc. offices is located at:: pitneybowes.com Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. The following trademarks are owned by the United States Postal Service: LACSLink, SuiteLink, DPV, ZIP + 4, ZIP Code, ZIP, CASS, CASS Certified, Post Office, P.O. Box USPS, U.S. Postal Service and United States Postal Service. Pitney Bowes is a non-exclusive DPV and LACSLink Licensee of the United States Postal Service® AD#1.08 Portions © January 2019 TomTom Inc. © 1987 - 2019 HERE. All rights reserved Shapefile C Library v. 1.2.10 is licensed under the MIT Style License. The license can be downloaded from: . © 1998 Frank Warmerdam. The source code for this library is available from . January 2019 Table of Contents

1 - Introduction 4 5 - Using the REST API 91

What Is Geocoding? 5 REST API Framework and Syntax 92 What Is MapMarker? 5 Usage Guidelines 99 MapMarker Features 6 REST API Examples 101 MapMarker Documentation Set 13 MapMarker Streets 14 6 - Deploying Applications 125 Getting Technical Support 15 Deploying MapMarker as a Servlet 126 2 - Designing Geocoding Applications16 Integration with MapMarker for Other Countries 127 Choosing a Development Tool 17 Defining the Geocoding Model 19 7 - Result Codes 131 Geocoding Application Design Overview 21 Understanding Result Codes 132 3 - Geocoding with MapMarker USA 29 Single Match (S category) 133 Best Match From Multiple Candidates (M Geocoding Terms 30 category) 139 Address Conventions for MapMarker USA 33 Postal Centroid Matches (Z category) 140 Geocoding with MapMarker USA 34 Geographic Matches (G category) 140 Sample Application Requirements and Setup34 Reverse Geocoded Matches (R category) 140 Running the Sample Application 35 Non-match Codes (N category) 141 Using the MapMarker USA Sample Application 35 A - Using the XML API 142 Street Geocoding 40 Postal Geocoding 46 Tips on Using the XSD Schemas 143 Geographic Geocoding 47 Geocoding Constraint Keys 144 Reverse Geocoding 48 Geocoding Request Types 148 Optimizing MapMarker USA – Usability and Performance Tips 50 B - JNI Adapter Configuration File Settings 151 4 - Using the MapMarker Java API 52 JVM Settings 152 Using the MapMarker Java USA API 53 Country Settings 152 Using the MapMarker Generic Java API 53 Using the JavaDocs API Documentation 53 Developing Geocoding Applications in Java 53 C - Using Database Extenders 153 Geocoding and Returning Candidate Information Geocoding Extenders for Database Developers 70 154 Creating a Reverse Geocoding Application in Java 78 Browsing Addresses 80 D - Error Messages 155 Geocoding To Postal Centroids 81 Geocoding to Geographic Centroids 82 MapMarker Java API Errors 156 Geocoding to Highway Exits 84 Geocoding to Airports 85 E - Match Codes and Location Codes161 DPV Related Actions 86 Returning Match Codes and Location Codes88 Match Codes 162 Standardizing Addresses 89 Location Codes 169 Creating a Web Geocoding Client in Java 90 Using Status Codes 181 184

MapMarker USA 31 Developer Guide 3 1 1 – Introduction

Welcome to MapMarker USA, one of the premier address matching and geocoding offerings from Pitney Bowes. MapMarker USA enables you to assign geographic coordinates to large tables of American address records in a single session.

In this chapter:

What Is Geocoding? 5 What Is MapMarker? 5 MapMarker Features 6 MapMarker Documentation Set 13 MapMarker Streets 14 Getting Technical Support 15 Introduction

What Is Geocoding?

Geocoding is the process of assigning geographic coordinates to data that contain addresses. The coordinates assigned to each address turn each record into a geographic object that can be displayed on a map using MapInfo Professional or MapXtreme. Geocoding turns ordinary data records containing address information into geographic objects that can be displayed on a map. A list of customers, stores, or anything with a street address or postal code may be matched using the comprehensive street and postal code files provided in the Address Dictionary. The result of geocoding is an X/Y coordinate linked to a specific address. When displayed, this enables you to better visualize the relationships in your data. You can display coordinates by creating maps in MapInfo Professional or via MapXtreme and add to other map objects to give your data a geographic reference. You can then perform a wide variety of functions to analyze your data in geographic terms. Data that once was only readable in column and row format can be now viewed with a whole new perspective, thereby disclosing patterns and clusters you never knew existed. Visualizing your records on a map can make the relationships among your data clearer. You can display your geocoded records against a street map, a postal centroid map, a local map, or whatever is most appropriate to your needs. You can then use the wide variety of functions available in MapInfo mapping software to perform querying, create thematic maps, create territories, and perform many other types of geographic analysis. Beyond visualizing data on a map, location data can be leveraged in many ways. See Location Intelligence Products and related parts of the Pitney Bowes web site for details on how your organization can use location information to make better decisions.

What Is MapMarker?

MapMarker is a powerful geocoding tool produced by Pitney Bowes MapMarker enables you to assign geographic coordinates to large tables of U.S.-based address records in a single session. This is a key step toward mapping and analyzing your business data. MapMarker adds geographic coordinates to every record in your database that it matches against its comprehensive Address Dictionary, a database of USPS® street addresses, street geometry and the latest ZIP + 4® centroids. MapMarker assigns coordinates to an address based on how well it matched in the Address Dictionary. The precision of the match can vary. For each address you geocode, you may get back a single perfect, street-level match or a list of street-level match candidates from which you choose the best match. You may get a less precise match, for example a ZIP Code centroid match if you provided a ZIP Code or a city-level centroid match. To identify the match precision, MapMarker also returns a result code for each address that it geocodes. The precision that you require for your geocoded records depends on how you plan to use your data.

MapMarker USA 31 Developer Guide 5 Introduction

In addition to being a powerful geocoder, MapMarker is also a suite of tools that allows you to standardize your U.S. addresses, add spatial information and create points for your records, develop standalone or client/server custom geocoding applications, and embed MapMarker functionality in existing applications. The MapMarker Desktop application, MapMarker server, and MapMarker developer tools have geocoding capabilities that allow you to add geocoding functionality to your own desktop or Web application.

MapMarker Features

MapMarker USA allows a great deal of flexibility in geocoding. This section briefly describes the major features of MapMarker USA. This does not completely summarize all the MapMarker features and capabilities. See the MapMarker USA Release Notes for new features, Address Dictionary updates, and behavioral changes that you may notice with MapMarker. The Release Notes also describe fixes to customer-reported issues and known issues that customers must be aware of. The MapMarker USA Release Notes are located at the Pitney Bowes Product Documentation site.

MapMarker Installer The MapMarker USA 31 installer is designed to simplify the installation and provide more feedback during installation. The installer accommodates: • Typical and custom installs • Upgrading software and data or upgrading data only • Silent installation and modification • Selecting and installing the JVM • Installing the sample application (for Server installation) • Selecting default and custom locations for installing software and data • Choosing shortcut locations • Uninstalling MapMarker Note: Note You must have administrator rights to install MapMarker software. This is true for all operating systems.

Street Level Geocoding If you select the street level geocoding operation, MapMarker will match your full address record against its Address Dictionary and/or User Dictionary (If you have created and selected a User Dictionary.). This process will correct misspelled street addresses and city/town names. It can also correct postal code information, or add postcodes if your data does not already include them. After MapMarker completes the address cleaning step, it will geocode your records in accordance with the other preferences you have set.

MapMarker USA 31 Developer Guide 6 Introduction

Addresses that are geocoded to a street level return an S or M result code. See Chapter 7 Result Codes for a description of these and other result codes.

Intersection Geocoding MapMarker USA can geocode to street intersections. Using any of several ways to designate a street intersection, MapMarker can find the position of the intersection of two street segments within a given postal code or city. See Intersection Geocoding on page 7. Addresses that are geocoded to an intersection return an SX result code. See Single Match (S category) on page 133 for a description of all result codes.

PlaceName Geocoding PlaceNames are included in the data and can be geocoded by MapMarker USA. PlaceNames can include business names, building names, government offices, or other companies and organizations that are included in the data source of the MapMarker USA Address Dictionary. See PlaceName Geocoding on page 7. PlaceName geocoding is also supported by User Dictionaries. You can create and implement User Dictionaries based on your own data or third-party data sources. Your custom data may include place names, intersections, airports, business or organization names, building names, or any other POI (Point of Interest) that you want to use for geocoding purposes. See Chapter 7 Custom User Dictionaries.

Unformatted (Single-line) Address Input MapMarker can geocode single line addresses, in which all address components appear on a single line rather than in separate fields.

Address Cleansing MapMarker USA can successfully geocode many addresses even if the addressing is less than perfect. For example, the USPS® may identify several official and unofficial locality names for a single postal code (especially in urban areas). MapMarker USA can interpret addresses that refer to official (gazetted) or unofficial locality names, but will return the official locality name in the address cleansing process.

Postcode Geocoding If you choose Postcode Geocoding, MapMarker will geocode your records based on their postal code in accordance with the other preferences you have set. You can also fallback to Postcode geocoding if a street level match was not possible. A postal code represents an area (polygon). A postal code can be related to one locality, or to multiple localities in metropolitan areas.

MapMarker USA 31 Developer Guide 7 Introduction

Addresses that are geocoded to a postal code return a Z result code. See Postal Centroid Matches (Z category) on page 140 for a description of Z result codes.

Geographic Geocoding If the input address consists of a valid combination of city and state, but no further address information, you can still geocode to the city centroid. You can also fallback to Geographic geocoding if a street level match was not possible. Addresses that are geocoded to a geography return a G result code. See Geographic Matches (G category) on page 140 for a description of G result codes.

Reverse Geocoding With reverse geocoding, you can provide X/Y (Longitude/Latitude) coordinates and MapMarker USA 31 returns the closest address for that location based on the Address Dictionary. The ReverseGeocodeAPI interface includes classes and methods that support reverse geocoding. Note: Reverse geocoding is available with the Developer (Server) edition and API, but not with the Desktop application. Reverse geocoding is separately licensed and must be covered in your license agreement. MapMarker USA v31 automatically installs two spatial index (gsx files) for each address dictionary. Generally no special user action is needed to configure reverse geocoding. See Reverse Geocoding on page 48 for information on enabling and using reverse geocoding. You can perform reverse geocoding using street segment or point address dictionaries. Addresses that are reverse geocoded return an RS result code. See Chapter 5 Result Codes for a description of all result codes.

Address Dictionaries The default Address Dictionary is based on TomTom Street data and USPS sources. This includes millions of American street addresses and placenames with corresponding address range, street geometry and postal code data and is used for matching addresses and assigning coordinates during the geocoding process. This Address Dictionary can be purchased and licensed for all of USA or for individual regions. A number of other street range and point-based Address Dictionaries are available. See the MapMarker USA Release Notes provided with your product. These Release Notes and other documentation are also located at the Pitney Bowes Product Documentation site for information on the available Address Dictionaries and data vintages for your version of MapMarker USA.

MapMarker USA 31 Developer Guide 8 Introduction

User Dictionaries A User Dictionary is similar to the provided Address Dictionary, but it is created by the user from their own source data. User-defined dictionaries can contain a variety of customized address-related data that may provide improved address matching rates and add value to the address validation and geocoding process. User Dictionaries can also be based on parcel/point data, which can provide an even higher level of geocoding accuracy. You can create any number of custom dictionaries. User Dictionaries can be used in combination with or in preference to the Address Dictionary.. See the MapMarker User Guide for instructions on creating user dictionary with the User Dictionary utility.

Multiple File Formats as Input Data MapMarker USA reads any MapInfo table (TAB format), CSV, delimited text files (TXT), fixed-width text files, or any dBASE (DBF) format table. MapMarker supports multiple character sets for dBASE files. In addition, MapMarker, via Open Database Connectivity (ODBC) can geocode data stored in remote databases, including Microsoft Access, Microsoft SQL Server, and Oracle using the X and Y data type.

Attribution You can add attribute values from other tables as part of a geocoding pass, or as a separate process. For example, MapMarker can attach information (such as lifestyle codes), stored in a boundary or point file to a record in your database when it makes a match. All that is necessary is a common link between the two tables.

Automatic and Interactive Geocoding MapMarker USA runs in both automatic and interactive mode. You can use either automatic or interactive geocoding or you can combine these techniques in multiple geocoding passes to optimize your results.

Batch Geocoding MapMarker USA supports batch geocoding for processing one or more tables without user interaction. This feature is useful for overnight processing of large databases or when a table is updated regularly.

Saving and Using Project Files You can create MapMarker projects to preserve all current geocoding settings, matching and fallback preferences, table attributes settings, and system preferences. Project files also provide a way to do batch geocoding on delimited text files and fixed-width text files.

MapMarker USA 31 Developer Guide 9 Introduction

See the MapMarker USA User Guide for information on opening a project and creating a project.

Display Geocoded Points on Map MapMarker can create point objects for geocoded records automatically. You can display the points using MapInfo mapping software (such as MapInfo Professional.). Optionally, MapMarker can write the X and Y coordinates directly to your table. Points created with MapMarker will overwrite any points already existing in the table. See the MapMarker USA User Guide for information on viewing candidates on a map.

Quick Find and Browsing The Quick Find Feature in the Desktop Application enables you to quickly geocode a single address or business name without using the Geocode dialog. The Quick Find dialog is located under the Search menu of the Desktop Application. Enter the address information in the Quick Find dialog and click Search. MapMarker returns geocoding results based on the currently set geocoding preferences. You can also use the Quick Find dialog to browse the Address Dictionary for the correct spelling of a street name or business. Provide the postal code and at least the first letter of the street or business and click Browse. The city/town and state fields are optional. MapMarker returns a list of streets or businesses that meet your criteria. Browsing does not geocode the record, but you can use the browse results to confirm and correct your address and then geocode based on this information. See the MapMarker USA User Guide for information on the Quick Find feature.

Result Codes MapMarker USA returns a result code for each record it attempts to match. This enables you to see whether a match was made, which dictionary was the source of the match, and how precisely each address component matched. The result codes are stored in your table. When the records display in a Map window, each result code is represented by a color- coded symbol. This allows you to visually recognize the precision level and distribution of the matches. See Understanding Result Codes in Chapter 7 on page 132.

Match Codes and Location Codes MapMarker USA returns match codes that indicate the parts of the address were matched (or what address parts were changed to achieve the match). MapMarker also returns location codes that indicate the locational accuracy of the assigned geocode. These codes are returned by the API but are not returned by the sample application. See Match Codes and Location Codes on page 161.

MapMarker USA 31 Developer Guide 10 Introduction

Segment IDs Segment IDs are numeric codes that uniquely identify each point or street centroid candidate. The MapMarker USA 31 geocoder returns the Segment ID for each S8, S7, S6, S5 and S4 candidate (providing that the segment ID information is available in the Address dictionary. Segment IDs are also returned for reverse geocoded candidates. See Getting the Segment ID on page 72 for more information. Note: Segment IDs are available through the Server API only (not with the Desktop Application).

Wide Search You can increase the probability of a match by using Relaxed mode in combination with wide search. Wide search considers all streets that begin with the first letter of the input street name, and therefore can identify many more potential candidates. Wide search is not implemented by default, but is supported at both the API level and in the Desktop application See Using the Wide Search Constraint on page 69 for an example using the Java API methods. See the MapMarker USA User Guide for information on the wide search feature.

Centerline Offset for Point Candidates If a point candidate is returned from a point dictionary, you can return the coordinates at a specified offset from the associated street segment (rather than at the original point). This feature is available if you are using a point-based Address Dictionary (Centrus Points, TomTom Points, HERE Point Addressing, or Master Location Data) in combination with a street segment dictionary. See Address Dictionaries on page 8 for an overview of the available Address Dictionaries. The centerline offset capability is disabled by default, but you can enable and control it using the APIs. See Using Centerline Offset for Point Candidates on page 68 to see how to implement this using the Java API.

Expanded Search MapMarker USA implements expanded search, which allows MapMarker to search for an address within a given radius of the input address. Expanded search helps to find a match when the input address contains limited or inaccurate city or ZIP Code information. Expanded search is not implemented by default, but is supported at both the API level and in the Desktop application.

MapMarker USA 31 Developer Guide 11 Introduction

Search Level Constraints for Finance Area and City 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. These constraints are supported at both the API level and in the Desktop application. CASS mode automatically uses the Finance Area constraint by default. All other match modes use City search level by defaults.

Expanded Search MapMarker USA implements expanded search, which allows MapMarker to search for an address within a given radius of the input address. Expanded search helps to find a match when the input address contains limited or inaccurate city or ZIP Code information. Expanded search is not implemented by default, but is supported at both the API level and in the Desktop application. See Using Expanded Search on page 70 for an example using the Java API methods.

MapMarker Desktop Application The MapMarker Desktop Application can be installed on a single machine, or on a network to be shared by other users. The Desktop Application gives you a great deal of control over the geocoding process. Following is a partial list of MapMarker features: • Supports a number of different file formats, including MapInfo TAB files, DBF files, CSV, delimited text files (TXT), and ESRI Shapefiles (SHP). • Geocode interactively (you make the final decision if it is a match) to maximize the number of matches and to control error rate. • Geocode a portion of your table using the Quick Geocode feature. • Geocode a large database of addresses in batch mode. • Geocode to street address ZIP Code centroids or to street intersections. • Identify result codes quickly tell how the address match was made and how precise the match is. • Standardize addresses to meet USPS Coding Accuracy Support System (CASS™.) standards. •Use DPV®. (Delivery Point Validation) to verify whether an address is a valid USPS delivery point. • Geocode remote tables via ODBC.

MapMarker Server MapMarker Server is a server-based engine that is designed to be integrated into business processes. The Server product enables multiple simultaneous geocoding requests to be served from a single MapMarker engine.

MapMarker USA 31 Developer Guide 12 Introduction

Developer Tools and REST API The MapMarker Server product includes developer tools provides a Java API and an XML (.NET Framework) API. Developers can use these tools to build and deploy client/server or standalone geocoding applications. MapMarker USA v31 provides a REST (Representational State Transfer) API. REST is a lightweight client/server architecture that allows you to easily send and receive geocoding requests and responses via HTTP. The MapMarker USA REST API also supports USA- specific constraints (related to CASS, DPV, LACSLink, Search Level, Wide Search, etc.)

Integration with MapInfo Professional MapInfo Professional users can run MapMarker USA or Envinsa 4.3.1 or later as a geocoding service from within MapInfo Professional 8.5 or later. This direct connection enables users to take advantage of MapMarker address validation and geocoding capabilities within the powerful MapInfo Professional mapping and analysis environment.

MapMarker Documentation Set

The documentation set for MapMarker includes PDF and online resources to help you make the most of the product. The set includes: • MapMarker USA User Guide in PDF format. • Online Help for the MapMarker Desktop Application. • MapMarker Developer Guide in PDF format. • Release Notes that provide updated information on new features, behavioral changes in the software, fixes for customer-reported issues, and known issues. To see these Release Notes and other MapMarker documentation, go to the Product Documentation page on the Pitney Bowes web site.

MapMarker USA User Guide The MapMarker USA User Guide is designed to help you use MapMarker to the fullest. It introduces you to the product and documentation set, gives installation instructions for the product components, and explains how to use the MapMarker Desktop Application. Coverage includes: • Geocoding in MapMarker • Using system preferences • Configuring match settings for optimum geocoding results • Explaining result codes • Geocoding remote tables • Creating a customized user dictionary

MapMarker USA 31 Developer Guide 13 Introduction

The MapMarker USA User Guide also contains a chapter on more specialized features, including CASS™ geocoding and DPV®; finding airports, highway exits, single address geocoding, batch geocoding, and table attribution.

Online Help In addition to the User Guide, MapMarker includes online help for the Desktop Application. Online help is instantly available while you are running MapMarker or the installation wizard. To access help, either select the Help menu, press the F1 key, or click Help for help about a dialog.

MapMarker USA Developer Guide This explains the server and API components of the developer product. This also describes and illustrates the sample application, a Java client that illustrates how to geocode American addresses.

MapMarker Release Notes The MapMarker Release Notes are posted to the Pitney Bowes Product Documentation web site, and contain a brief summary of the following: • New features • Operating requirements • Bug fixes • Known issues

Publications on the Web The MapMarker documentation and Release Notes are available from the Product Documentation page on the Pitney Bowes web site. Documentation on the web site may be updated if corrections are necessary or if new information becomes available.

MapMarker Streets

Once you have geocoded your table you can display geocoded points in the MapMarker Desktop Application through Candidate Visualization. You may want to add other layers of information to your map to give your records a geographic reference. MapMarker Streets is a U.S. network of fast displaying streets, highways, municipal boundaries, water features, and points of interest to complement your MapMarker geocoded data. MapMarker Streets is provided on separate media with your MapMarker product.

MapMarker USA 31 Developer Guide 14 Introduction

Getting Technical Support

Pitney Bowes offers a free support period on all new software purchases and upgrades, so you can be productive from the start. Remember to provide your serial number, partner number, or customer agreement number when contacting Technical Support. Contact the technical support personnel for your area by visiting our web site.

MapMarker USA 31 Developer Guide 15 2 2 – Designing Geocoding Applications

This chapter covers the high-level design decisions involved in writing a geocoding application and offers some guidance on some common geocoding techniques that you can use to build and organize your application.

In this chapter:

Choosing a Development Tool 17 Defining the Geocoding Model 19 Geocoding Application Design Overview 21 Designing Geocoding Applications

Choosing a Development Tool

When you create a geocoding application, your choice of development tool will have a direct effect on the design and deployment of your application. As you are evaluating tools, some questions to consider include: • What are the required location-based capabilities of the application? For example, will your application need to perform only geocoding, or will you also need to provide mapping and/or routing capabilities? • How will your application be deployed? Will users access it from the Web or will it be a desktop application? • In what operating system(s) do you anticipate deploying your application? • In what programming language(s) is the application to be written? Some examples include: •Java • .Net (C#, VB C++) • Web services •XML • Visual Studio 6 (C/C++, VB) Pitney Bowes offers several geocoding products that offer different design and deployment capabilities. The product you choose must be able to meet the high-level requirements of your design.

Geocoding Interoperability The diagram below shows the interoperability between several geocoding solutions: MapMarker, MapXtreme, and Envinsa.

The diagram indicates the level of communication between the clients, servers, and the geocoding engine. A MapXtreme client can communicate via an Envinsa server, or a MapMarker server. All servers use underlying geocoding components.

MapMarker USA 31 Developer Guide 17 Designing Geocoding Applications

The following table summarizes the geocoding solutions available.

Web/ Programmin Product Desktop* OS g Language Capabilities

MapMarker USA 31 Both Windows, Java Geocoding Solaris, HP- UNIX, Linux

MapXtreme Both (IIS) Windows .NET Geocoding, Mapping, Routing

Envinsa Both (App Windows, Java, XML, Geocoding, Server) Solaris, Linux .NET, and Mapping, Web Routing, and Services more

The following sections provide a summary of some of the features and design capabilities of geocoding offerings.

MapMarker 31 • Desktop and Developer Editions. The Desktop Edition includes the Desktop Application graphical user interface and Address Dictionary. You can purchase data for all 50 states (D.C. and Puerto Rico), regional state bundles, or individual state data, The Developer Edition includes the Desktop Application, the MapMarker SDK, Java API, a JNI Adapter to run the OLE Automation API and Data Dictionary API, and examples. A preconfigured Apache Tomcat servlet is provided to run MapMarker as a geocoding server. Both the Desktop and Developer Editions include complete documentation. JavaDocs is included with the Developer Edition to document the MapMarker Java API. See Using the JavaDocs API Documentation on page 53 for the location of the JavaDocs. • Utilizes Java geocoding engine. The advantages of using a Java geocoding engine is that it can be deployed and run on different operating systems without being recompiled. • Provides enhanced user dictionary capabilities. • Updates Java server geocoding features.

MapXtreme Developers using MapXtreme: • Create Windows desktop or IIS web applications • Use .NET programming languages • May require several location based capabilities • Perform client/server geocoding

MapMarker USA 31 Developer Guide 18 Designing Geocoding Applications

Envinsa Developers using Envinsa: • Develop geocoding applications as part of an enterprise level solution • Create Windows, Solaris, or Linux applications • Build and deploy web applications on a variety of application servers • Use .NET, Java, XML or web service programming languages • May require several location based capabilities (for example., reverse geocoding, which accepts an x, y position and returns address, intersection, postcode, city, or other location attribute information).

Defining the Geocoding Model

The MapMarker geocoding model uses a system of relative matching. It is governed by a set of weights that scores each portion of the address against candidate records (possible matches) in the Address Dictionary. The resulting scores are summed and the candidate’s total score is used to determine the best match or matches. An exact match is made when there is a candidate that scores well above other candidates. If there is no clear best match, several (non-close) candidates may be returned. Within this model, you have a certain amount of flexibility about the level of accuracy to which the address records are geocoded and how you execute the application.

Geocoding Constraints The geocoding model contains a set of geocoding constraints that specifies the conditions under which a close match is determined. These constraints either require specific matching conditions to be true, or allow those conditions to be relaxed. The combination of constraints that are required or relaxed affects how each candidate is scored and has an impact on the number of records that are geocoded, the matching accuracy of the geocoded addresses, and the positional accuracy of the geocoded point. For example, enabling a constraint that requires a match on a specific address element may restrict or filter returned candidate information. In the MapMarker USA desktop product, the default constraints include relaxing a match on street name and ZIP Code™, but requiring a match on the house number. This combination of constraints provides a high geocoding success rate with few erroneous matches (false positives). For information on Java API constraints and their uses, see Geocoding Constraints on page 55 and USA_GeocodeConstraints on page 60.

MapMarker USA 31 Developer Guide 19 Designing Geocoding Applications

Fallback Preferences Enabling fallback preferences allows for a candidate to be geocoded to a postal centroid when a street-level match is not found. The Java API and XML API also enable you to fall back to a geographic centroid (state, county, or city) Fallback preferences enable you to geocode more records, but at the sacrifice of some positional accuracy.

Use of Geocoded Data The intended use of the geocoded data will have a great deal of influence on how much geocoding precision capability to provide in the application. As you think about the design of your application, consider the following questions: • What level of matching accuracy are you looking for (unique address match, close match)? • What level of geographic accuracy is needed for your geocoded points (street level, postal centroid, ort centroid)? • Is your goal to geocode as many records as possible? For example, perhaps you have users who need to determine the location of a new retail store and need to know the distribution of current and potential customers. In this case, geocoding as many of these customers’ addresses as possible is more important than finding an exact street match for each one. In this instance, geocoding to ZIP + 4® centroid or ZIP Code centroid is the best way to accomplish the user’s task. On the other hand, some users may need to know where their customers are in relation to the location of something else. For example, a utility service coordinator needs to know where customers are in relation to neighborhood gas lines. In cases like this, the positional accuracy of each customer is of critical importance. Geocoding to street level with strict matching preferences would be the optimum way for these users to accomplish their tasks.

Executing the Application Geocoding applications can be executed using two methods: automatic and interactive. Your application can perform either automatic or interactive geocoding, or use both methods, depending on the design requirements of your application. In automatic geocoding, the matching process is pre-defined, and candidates are selected automatically. Many different preference scenarios can be used. In interactive geocoding, the user has more control over the matching process, as well as having the capability of selecting the match candidate from a list. Match restrictions can be relaxed, and falling back to a postal-centroid level of accuracy is also an option.

MapMarker USA 31 Developer Guide 20 Designing Geocoding Applications

Geocoding Application Design Overview

All geocoding applications use a common approach that is made up of a number of tasks: • Select a geocode type • Build input address • Set geocoding preferences • Send a request • Verify response • Use candidate information When you design your geocoding application, focus on each of the steps to determine the overall flow of the geocoding application.

Types of Geocoding MapMarker can perform street, postal, and geographic geocoding. The type of geocoding you want your application to perform depends on the needs of your users and how much positional accuracy they require.

Street Geocoding In street geocoding, candidate coordinates are interpolated along a street segment. Geocoding to street level is highly accurate, but not as not as accurate as parcel-level accuracy, which can be achieved with a point-level user dictionary. Several point-based Address Dictionaries are available. See the MapMarker USA Release Notes located at the Pitney Bowes Product Documentation site for information on the available Address Dictionaries and data vintages for your version of MapMarker USA. This image shows how a candidate’s point, 18 Long Branch Ave, is interpolated along a street segment. The street’s range is from 24 to 14. The geocoder interpolates the point’s position based on the candidate’s house number.

MapMarker USA 31 Developer Guide 21 Designing Geocoding Applications

Postal Geocoding Postal level geocoding is faster but not as geographically accurate. Urban and rural accuracy can produce different results. This image shows the location of postal centroids as red dots. You can see why they would be less accurate than points geocoded to street level. (The centroid positions are delivery point weighted.) This image does not show ZIP + 4® centroid values; ZIP + 4 centroids have better postal accuracy than ZIP Code™ centroids. The blue polygons in the image are postal boundaries. Rural area polygons cover larger area and therefore are less accurate than urban areas.

Geographic Geocoding If the input address includes a valid combination of city, county, and state (but no further address information), you can still geocode to the city, county, or state centroid. MapMarker returns the most precise geographic centroid that it can based on the user input. Geographic geocoding is less precise than street or postal geocoding, but may be suitable for certain applications. This image shows the geographic (city) centroids as blue circles.

MapMarker USA 31 Developer Guide 22 Designing Geocoding Applications

Building an Input Address The input address is the address to be geocoded. MapMarker uses two different kinds of input address objects: one is country-specific; the other can be used for multiple countries (generic address). Some geocoding APIs use different naming conventions. This table shows the correspondences between the address elements in the input address object for generic addresses and USA-specific addresses.

Country-Specific Generic Address Address (USA) Example (USA)

Building or Place Name Firm Pitney Bowes

Street or Main Address Street 1 Global Vw

Municipality or AreaName3 City Troy

Country Subdivision or State NY AreaName1

Primary Postcode or ZIP Code™ 12180 Postcode1

Secondary Postcode or ZIP + 4® 8337 Postcode2

Municipality Subdivision or Urbanization Parc Sabana (used in Puerto AreaName4 Rico) Urbanization is use for Puerto Rico. only. Leave blank if not geocoding Puerto Rican addresses.

*Country (required for Set by default USA generic)

*The Country property is required when using a generic input address object. For addresses in the United States, there are a number of input requirements. These are specific address elements that must be present so that the application can geocode the address.

MapMarker USA 31 Developer Guide 23 Designing Geocoding Applications

Desired Geocoding Level Required Input Fields Other Requirements

Street street and ZIP Code, or street, country required in generic city, and state address structure

Street Intersection street and ZIP Code, or street, city, and state Two intersecting street names should be separated by one of the following tokens: “and”, “at” “&”, “&&” (for example, "Global View at Jordan Road", or "42nd && Park")

Postal Centroid ZIP Code™ and/or ZIP + 4® country required in generic address structure

Geographic state required, with city and/or Available through Java API county optional

Using Constraints As explained in Geocoding Constraints on page 19, you can define the conditions under which a close match is determined. The geocoding application will match addresses according to these conditions. The conditions can be very precise to ensure more exact address matches and a high degree of positional accuracy, or they can be relaxed to ensure that as many records as possible are geocoded. MapMarker uses two types of preference objects: country-specific, and a generic or universal, which can be used for multiple countries. Some APIs use different naming conventions. There are some USA-specific versions of preference names. For example, the USA MustMatchStreet is equivalent to the generic MustMatchMainAddress, MustMatchCity is equivalent to the generic MustMatchAreaName3, and MustMatchZipcode is equivalent to the generic MustMatchPostalCode. Note: MustMatch constraints are described in Geocoding Constraints on page 55 and USA_GeocodeConstraints on page 60 (for the Java API).

Constraints Usage Examples Different constraints will return different candidate results. These examples illustrate how the returned candidates for an input address can change when you enable different constraints.

MapMarker USA 31 Developer Guide 24 Designing Geocoding Applications

Matching on Address Number When you enable the Must Match Address Number constraint, the input address: 350 Ocean Drive Key Biscayne, FL 33149 returns five possible candidates. Among these candidates, one candidate is a close match.

Matching on Address Number; Close Matches Only When you specify Close Matches in addition to the Must Match Address Number constraint, the input address: 350 Ocean Drive Key Biscayne, FL 33149 returns only the close match candidate. When Close Matches Only is enabled, only the close match candidate is returned.

Matching on Address Number, Close Match Only, Falling Back to Postal When you enable Close Matches Only, Must Match Address Number, and Fallback to Postal, the input address: 3050 Ocean Drive Key Biscayne, FL 33149 returns a postal candidate (Z1 result code) instead of a street candidate. The reason only a postal candidate is returned is that the Must Match Address Number constraint is enabled, and the input address number does not match a close match candidate’s address number. In this case, the Fallback to Postal preference is used and a postal candidate is returned.

Matching on Address Number, Close Match Only, Falling Back to Geographic When you enable Close Matches Only, Must Match Address Number, and Fallback to Geographic, the input address: 55 Upland Dr. Ithaca, NY

MapMarker USA 31 Developer Guide 25 Designing Geocoding Applications

returns Ithaca, NY as a close geographic match (G3 result code). Only a geographic candidate is returned because the Must Match Address Number constraint is enabled and there is no exact address match on 55 Upland Dr.

Sending a Request The geocode request contains all the information needed for the application to geocode an address. The geocode type, the input address, the geocoding constraints, and, if using a server, the URL or IP address comprise the information in the geocode request.

Verifying a Response The response you receive back from a geocode request contains the following information: • Exceptions • Returned candidate count • Candidate result code Exception error handling checks for system-level failures. Some examples of these include: • Invalid server URL or IP address • Server is down • Invalid address dictionary path If an exception occurs, the geocoding process should be halted until the error is corrected. The response to a successful geocode request also contains a returned candidate count. In a returned candidate count, keep in mind the following: • Possible candidates verses returned candidates • Use returned value when looping through candidates • Possible to receive no candidates Finally, every candidate will have a result code. The result code indicates how precisely the candidate matches the input address.

Using Geocode Result Information The result code consists of up to ten alphanumeric characters. For example, a result code might look like this: S5HPNTSCZA. Each character in the code describes something about the geocoded point: the type of geocoding, the positional accuracy of the point, the quality of the match of specific address elements, and the dictionary that the candidate matched on. This section provides a brief summary of what each character in the code indicates. For detailed information see Chapter 7 Result Codes.

MapMarker USA 31 Developer Guide 26 Designing Geocoding Applications

Geocode Type The first character in the result code indicates the geocoding type. The first character can be one of the following characters: • S – Street Type • Z – ZIP Code™ or postal code type • M – multiple street match • G – geographic type • N – non-match

Positional Accuracy The second character in the code reflects the positional accuracy of the candidate’s point. The character can be the numbers 0-8, or the letter X. • 8 – matched to a known addresses with exact latitude/longitude coordinates for each address. • 7 – matched to an interpolated point along the candidate’s street segment. • 6 – matched to a point ZIP centroid. A point ZIP is a 5-digit ZIP Code™ that represents P.O. Box™ ZIPs and other unique ZIPs such as a single site, building, or organization. • 5 – Street interpolated point • 4 – Street centroid point • 3,2,1 – Postal centroid point • 0 – no geometry available (extremely rare) • X – intersection point (no additional characters for SX return) • C – centerline offset result

Address Elements The characters in the third through the ninth positions in the result code describe the matches in the different elements in the address. • third position describes House or address number match (for example, 115) • fourth position describes street Prefix directional match (for example, North) • fifth position describes street Name or main address match (for example, School) • sixth position describes street Type match (for example, Avenue) • seventh position describes street Suffix Directional match (for example, NE) • eighth position describes City match (for example, Miami) • ninth position describes ZIP or postal match (for example, 80302)

MapMarker USA 31 Developer Guide 27 Designing Geocoding Applications

Dictionary Type The tenth and last character in the code describes the candidate’s dictionary type: A or U. • A – Address dictionary • U – User dictionary

Unmatched Elements in Input Address A dash "-" in the result code indicates that this element of the input address could not be matched. For example, in the result code: S5HPNTSC-A the dash appears instead of a Z. This means that the ZIP Code was not matched.

Optimizing Geocoding Performance Consider these guidelines for optimizing MapMarker Geocoding performance: • Use the fastest processor available to you. We recommend dual core processor or better. • Have enough memory so that the operating system can allocate some memory to your disk. cache. We recommend 4GB RAM or better. • Have at least 10 GB available disk space. • Sort your table by ZIP Code™ before geocoding. • Use Exact match mode if you have high quality address data. • Do not create points automatically. • Remove indexes on any table output columns before geocoding. • Store the Address Dictionary on a local hard drive. • In a multi-threaded server environment, use multiple engine instances to improve performance. See Optimizing Server Performance on page 51.

MapMarker USA 31 Developer Guide 28 3 3 – Geocoding with MapMarker USA

This chapter describes the major MapMarker USA 31 geocoding features. All country-specific MapMarker products have similar capabilities, but details depend on the addressing and postal conventions of the specific country. MapMarker USA 31 comes with a Java client sample application that illustrates how to geocode American addresses.

In this chapter:

Geocoding Terms 30 Address Conventions for MapMarker USA 33 Geocoding with MapMarker USA 34 Sample Application Requirements and Setup 34 Running the Sample Application 35 Using the MapMarker USA Sample Application 35 Street Geocoding 40 Postal Geocoding 46 Geographic Geocoding 47 Optimizing MapMarker USA – Usability and Performance Tips 50 Geocoding with MapMarker USA

Geocoding Terms

MapMarker products use a common set of geocoding terms.

Geocoding Terminology

Term Definition

address Information that identifies the location of a site, for example, a home or business. An address is either a street location or intersecting streets.

address dictionary The search dictionary used for matching addresses during geocoding.

address interpolation A mathematical means of estimating an address location based on a street segment and the address ranges associated with that segment. This method of interpolation assigns coordinates to address records in relation to the position of address point candidates in the data, providing greater positional accuracy to the geocoded points.

candidate An address record that is a potential match to the input address information. A candidate is returned by the geocoding process. See also geocoding on page 31.

CASS™ Coding Accuracy Support System. This is a process by which mailing addresses are standardized to meet U.S.Postal Service® requirements for bulk mailing discounts. When CASS mode is enabled, MapMarker will perform this address standardization under strict matching conditions set by the USPS® . Geocoding in CASS mode matches records to the exact house number, street name, and ZIP Code™. Other geocoding must match constraints are overridden.

MapMarker USA 31 Developer Guide 30 Geocoding with MapMarker USA

Geocoding Terminology (Continued)

Term Definition

centroid A point at the calculated center of a polygon, often used to attach attribute information to an area. The centroid is used for labeling and geocoding, for example. For an irregularly shaped area, region, or polygon, the centroid is derived mathematically and is weighted to locate the point at the approximate "center of gravity."

close match Status that indicates whether a candidate’s ranking is considered close enough to the input address.

CMRA Commercial Mail Receiving Agency. This is a private business that acts as the mail-receiving agent for clients.

DPV® Delivery Point Validation. DPV is technology available from the U.S. Postal Service®. Used in conjunction with CASS™ mode geocoding, DPV enables you to verify whether an address is a deliverable USPS® address.

geocoding The process by which the X and Y coordinates of a location are determined by its address. In MapMarker, the X and Y coordinates are longitude and latitude.

geographic geocoding Candidate coordinates are based on state, county, or city centroids. This not very precise, but may be suitable for certain applications.

LACSLink® Locatable Address Conversion System. LACSLink allows business mailers to electronically update their rural-style addresses with locatable street-style addresses resulting from 911 emergency response address conversions. For example, and address like RR 1 Box 32 might be converted to a street-style address like 141 Morrison Ave.

MapMarker USA 31 Developer Guide 31 Geocoding with MapMarker USA

Geocoding Terminology (Continued)

Term Definition

match strategy An approach to geocoding a table that achieves the desired geocoding results. For example, if geocoding hit rate is more important than accuracy, then geocoding criteria would be relaxed to ensure that more records in the table are geocoded. Or if you required greater accuracy, you could use stricter geocoding criteria, such as an exact match on street name and house number.

must match Must Match options are used for deciding whether returned candidates are Close Matches. A Must Match option still allows non-Close matches. For information on implementing must match constraints using the Java API, see Geocoding Constraints on page 55.

PMB Private Mailbox

postal geocoding Candidate coordinates are based on postal codes. This is faster but not as accurate as street-level geocoding. Also, postal geocoding of rural areas is generally less accurate than that of urban areas. For P.O. Box™ and rural route addresses, MapMarker automatically geocodes to a ZIP Code™ centroid, as required by CASS standards.

postcode A unique identifier for postal mailing zones. For the U.S.A. this is the ZIP Code system. See ZIP Code™ on page 33.

post-directional The letters following a street name that give a direction to the address, for example 18th Street N. This shows that the location is on the north side of 18th street. Not every address has a post-directional component.

post-type Street type that follows the street name. For example, Main St. Not every address has a post-type component.

MapMarker USA 31 Developer Guide 32 Geocoding with MapMarker USA

Geocoding Terminology (Continued)

Term Definition

pre-directional The letters preceding a street name that give a direction to the address, for example W 18th Street. This shows that the location is on the west side of 18th street. Not every address has a pre-directional component.

pre-type Street type that precedes the street name. For example, Avenue B. Not every address has a pre-type component.

result code An alphanumeric code that describes the type and accuracy of the geocoding match. These codes are returned when geocoding and allow you to identify the success of the geocoding request. These are described in more detail in Result Codes in Chapter 7 on page 131.

street level geocoding Candidate coordinates are interpolated along a street segment. This is a highly accurate level of geocoding.

street name The name of the street. For example, Main St.

user dictionary A customized search dictionary of addresses and coordinates that can be used in place of, or in addition to, the application’s address dictionary.

ZIP Code™ The system of 5-digit codes that identifies the individual post office or metropolitan area delivery station associated with an address.

Address Conventions for MapMarker USA

This section describes some address conventions for American addresses and MapMarker USA 31. For complete information on addressing practices and conventions see Addressing Tips & Tools on the USPS web site. For ZIP Codes, see the ZIP Code Lookup page/ lookup.

MapMarker USA 31 Developer Guide 33 Geocoding with MapMarker USA

Address Elements American addresses may contain some or all of the following address elements.

Address Elements

Address Element Description Example

Street Address Must include street name and 1 GLOBAL VW may include house number. The sample application uses the label of Street Name.

City/Town This is equivalent to AreaName3. TROY The sample application uses the label of City Name. Either City or a Postcode must be included in an input address.

State This is equivalent to AreaName1. NY The sample application uses the label of State.

Postcode Postcode should always be used 12180 for proper addressing, but MapMarker USA 31 will add the postcode if it is not provided on input. The sample application uses the label of Postal Code

Geocoding with MapMarker USA

The following sections describe some examples of geocoding. Features are illustrated using the sample application that is installed with MapMarker. However, note that the sample application does not expose every feature and is not a supported interface. It is for demonstration and learning purposes only.

Sample Application Requirements and Setup

Before you try to geocode an address using the application, make sure that you have access to a MapMarker USA server.

Windows users only On the Start menu, select the shortcut for MapMarker USA v29 Server.

MapMarker USA 31 Developer Guide 34 Geocoding with MapMarker USA

UNIX users only

Open the link Start_Mapmarker_USA_v29_Server or run startup.sh from the /sdk/tomcat/bin directory in the path where you installed MapMarker.

Running the Sample Application

The MapMarker sample application is a Java client that illustrates how to geocode USA addresses using the MapMarker USA 31 server.

Windows users only From the Start menu, navigate to the program shortcut for the MapMarker USA v29 Sample Application:

Unix users only Unix users must open MapMarker_USA_v29_Sample_Application or run MMJE_USA_Sample.class from the /sdk/examples directory in the path where you installed MapMarker.

Testing the Server The server must be running properly before you can perform any successful geocoding. To test the server: 1. Examine the sample application's URL server test area. The URL to the MapMarker USA server is already filled in. You can change the URL to the location of a different server. Click Test. 2. If you have successfully connected to a MapMarker USA server, the text under the URL displays Server: VALID. If the connection is not successful, then the text under the URL displays Server: INVALID.

Using the MapMarker USA Sample Application

The MapMarker sample application is a Java client that illustrates how to geocode USA addresses using the MapMarker USA 31 server. The sample application is provided for example and demonstration purposes and to help you become familiar with MapMarker USA 31. It does not illustrate every capability of MapMarker and it is not a supported interface. When you run the sample interface, you may not see the exact same results that are illustrated in this documentation. As part of the installation, the data dictionary properties file (USA_DataManagerSettings.properties) will be configured to use the installed dictionary files. The data dictionary properties file is located in:

/sdk/tomcat/webapps/mapmarker40/WEB-INF/classes

MapMarker USA 31 Developer Guide 35 Geocoding with MapMarker USA

By default, the properties file has the following entries related to the Address Dictionary:

DICTIONARY_COUNT=1 DICTIONARY_PATH1=/MapMarker_USA_v29_Data/

Setting Preferences There are a number of preferences you can set that modifies the results of the geocode process. • Close Match Only – specifies the geocoder return only those candidates that have been flagged as close matches to the input address. • Fall Back to Postal – the geocoder attempts to geocode to the postal centroid if no candidates were returned from an address geocode and a postal code was supplied. • Fall Back to Geographic – the geocoder attempts to geocode to the urban area centroid or the state centroid, depending on the data available. • Max Candidates – enables you to change the number of candidates returned from the server. • Dictionary Options – enables you to specify whether you want candidates to come from the Address Dictionary, user dictionaries, or both. If using both, you can also give preference to candidates from either the Address Dictionary or user dictionaries. • Geocode Type – enables you to specify whether to geocode to street, postal code, or geographic centroid. Note that the sample application does not demonstrate reverse geocoding.

Setting Must Match Constraints There are also several must match constraints that you can select to change the number of candidates returned from the server. These constraints specify that the returned candidates must match certain parts of an address. These include: • House Num (house number) •Street • State • ZIP Code •City • Input (all address input) For a complete description of these and other constraints, see Geocoding Constraints on page 55.

Setting Match Modes MapMarker USA 31 includes several Match Modes that allow you to easily control the level of matching precision.

MapMarker USA 31 Developer Guide 36 Geocoding with MapMarker USA

You can use match modes to control the variance allowed between an input address and the matched address. Less variance ensures the highest quality matches. More variance can provide high quality matches on badly formatted or incomplete input addresses, but requires additional processing time. The Match Modes table describes the Standard, Exact, and Relaxed Match Modes.

Match Modes

Mode Description

Default Mode This is equivalent to Standard mode in the Desktop application. Default mode generally provides the best balance of accurate geocoding, few false matches, and high performance. This requires a close (not necessarily exact) street name match. This is the default geocoding mode when you start MapMarker USA 31.

Exact Mode This is equivalent to Tight mode in the Desktop application. Exact mode uses the most strict matching rules and requires an exact street name match. In general, this returns the fewest number of candidates in the fastest processing time. There will be fewer non-close matches than are returned in Default or Relaxed mode. Exact mode is most suitable when your input addresses are complete, well standardized, and free of spelling errors. Exact mode is not equivalent to selecting Custom matching with all Exact Match criteria selected (House Number, Street Name, City Name, and ZIP Code).

MapMarker USA 31 Developer Guide 37 Geocoding with MapMarker USA

Match Modes (Continued)

Mode Description

Relaxed Mode This provides less strict matching rules. In general, Relaxed mode increases your chances of getting a close match but performance (geocoding speed) may not be as good. Relaxed mode: • allows the most variation in street name spelling, and therefore may return desirable candidates that are not returned in other modes. • is most suitable when your input addresses are not well standardized, incomplete, or may contain spelling errors. • is the only mode that does not respect street parity. • may return false positive candidates. • may (but does not always) return more candidates than other modes. • generally will perform more slowly than other modes. • is best used as a second or third geocoding pass. The User Guide describes several multiple pass strategies for optimizing match rate. • is best used if you examine the Match codes and Location codes to verify how the address was matched, what address elements were changed to achieve the match, and the locational accuracy of the assigned geocode. Relaxed mode is not equivalent to selecting Custom matching with all Exact Match criteria unselected.

MapMarker USA 31 Developer Guide 38 Geocoding with MapMarker USA

Match Modes (Continued)

Mode Description

CASS Mode This provides strict conformity to USPS® CASS™ regulations for CASS software. Use CASS mode to standardize your input for mailing. If you select CASS Mode, several other options are disabled and their values are overwritten by CASS rules. CASS mode requires a close name match. Unlike other modes, CASS does not match intersection addresses, building name, or street aliases. CASS also does not match based on a user dictionary or any data source that does not have USPS equivalent records. In other modes, a close match candidate may by identified very quickly and this candidate is returned without further processing. However, in CASS mode, the first identified close match may not be the best USPS candidate (for example it could be a building name while the preferred USPS candidate is a business name). A CASS mode search must continue to ensure that the best USPS candidate is returned. For this reason, CASS mode can return more records than in other modes.

MapMarker USA 31 Developer Guide 39 Geocoding with MapMarker USA

Match Modes (Continued)

Mode Description

Custom Custom allows you to select any combination of Exact Match constraints rather than relying on any of the match mode algorithms. This gives you very precise control over the matching. House Number. If checked, a candidate must match the building/house number in order for it to be considered a close match. Street Name. If checked, a candidate must match the street name in order for it to be considered a close match. City Name. If checked, a candidate must match the city name in order for it to be considered a close match. ZIP Code. If checked, a candidate must match the ZIP Code in order for it to be considered a close match. Note that requiring all constraints is not equivalent to Exact mode. Similarly, requiring none of these constraints is not equivalent to Relaxed mode.

For information on implementing match modes using the Java API, see Using Match Modes on page 65. The sample application does not illustrate match modes, but you may want to use these modes in your custom applications. The MapMarker USA Desktop application also uses match modes. For more detailed information on match modes, see the MapMarker USA User Guide.

Street Geocoding

If you provide a street address, and either a ort or a postcode, you can perform an address geocode. MapMarker USA 31 will match your full address record against the available dictionaries (Address Dictionary and/or User Dictionaries). Minor misspellings in street addresses and City names can be corrected in the returned candidates (depending on the geocoding constraints). MapMarker USA 31 can also correct postcode information or add ZIP Codes if your input does not already include them. MapMarker will geocode your records in accordance with the preferences you have set. See Setting Preferences on page 36 for information how the sample application allows you to control constraints.

MapMarker USA 31 Developer Guide 40 Geocoding with MapMarker USA

In the sample application interface, select Street from the Geocode Type drop-down list and click Geocode Address to geocode an address to the street level. The sample application returns street geocoded candidates according to the constraints that you have chosen. See Street Candidate Returns on page 41.

Street Candidate Returns The following table shows examples of the MapMarker USA Street Candidate Return Fields This is representative list from typical street geocoding example, but not all possible returns are shown. Note: See Match Codes and Location Codes on page 161 for coverage of the additional GeoStan codes. These (combined with the MapMarker result codes) help you evaluate detailed aspects of the candidate quality.

Street Candidate Return Fields

Return Description Example

addressNumber House Number 29

mainAddress Street name LONG

postThoroughfareType Street type AVE

postcode1 ZIP Code (five-digit) 12304

postcode2 ZIP+4 4700

country Country USA

areaName1 State NY

areaName2 County SCHENECTADY COUNTY

areaName3 City/town name. SCHENECTADY

RESULT_CODE Result code for returned S5HPNTS-ZA candidates. See Result Codes on page 131 for a description of the MapMarker result codes.

DPV_NO_STAT DPV No Status flag N

DPV_FN1 DPV Footnote 1 AA See the MapMarker USA User Guide topic on DPV Output Columns for a complete list of DPV Footnote Codes.

MapMarker USA 31 Developer Guide 41 Geocoding with MapMarker USA

Street Candidate Return Fields (Continued)

Return Description Example

DPV_FN2 DPV Footnote 2 BB

DPV_FN3 DPV Footnote 3 N1

CARRIER_ROUTE USPS Carrier route C007

CHECK_DIGIT Check Digit 8

DELIVERY_POINT USPS Delivery Point. This is a 29 two-digit code that, together with Check Digit, is used to form the delivery point barcode on mail pieces.

REC_TYPE Record Type S REC_TYPE is the record type of the street candidate's range. If it's a USPS match it will be one the following: F – Firm P – Post Office/PO BOX S – Street H – Highrise R – Rural Route G – General Delivery T – TIGER record match

DPV_NOSTAT Y – The address is vacant. N N –The address is not vacant. Blank – DPV is not loaded or DPV did not confirm (so vacancy is irrelevant).

MapMarker USA 31 Developer Guide 42 Geocoding with MapMarker USA

Street Candidate Return Fields (Continued)

Return Description Example

DPV_VACANT Y – The address was valid for Y computerized delivery sequence (CDS) pre-processing. N – The address not valid for CDS. Blank – The address is not presented to No Stat table or DPV data is not loaded.

DPV_CMRA Indicates whether the geocoded N address belongs to a (Commercial Mail Receiving Agencies (CMRA).

LACS L – identifies n address that L matched a ZIP+4 record with a LACS indicator

LACSLINK_INDICATOR Y – input address was LACSLink Y converted. N – no LACSLink converted address was found. S – address was converted when secondary information was dropped

F – false positive. LACSLink processing will be terminated.

LACSLINK_RESULT_CO provides information about the A DE LACSLink output address. This is always paired with LACS_LINK_ INDICATOR

MapMarker USA 31 Developer Guide 43 Geocoding with MapMarker USA

Street Candidate Return Fields (Continued)

Return Description Example

SUITELINK_RETCODE A – SuiteLink match. Secondary A information exists and was assigned to this record as a result of SuiteLink processing. 00 – SuiteLink no match. Lookup was attempted but no matching record could be found. blank – A SuiteLink lookup was not attempted because one of the following was true: • The address was not a highrise default according to CASS. • The address did not contain a firm.

SEGMENT_ID unique Segment ID 959436

CENSUS_BLOCK Census Block 360930329011005

DPV_CONF DPV Confirmation Code Y

USA_SHORT_ADDRESS CASS Abbreviated Address 29 LONG AVE LINE

USA_SHORT_CITYNAM CASS Short City Name SCHENECTADY E

Long Longitude (X Coordinates) -79.391177

Lat Latitude (Y Coordinates) 43.64351

Intersection Geocoding MapMarker allows you to geocode to street intersections. The two streets must be separated by one of the following tokens (delimiters): "&&", "&", "@", "at", "and". For example, the following input returns a close match candidate.

StreetName: Global View && Jordan Rd State: NY City: Troy The returned close match candidate includes the following output:

Address: Global View at Jordan Rd Lastline: Troy, NY 12180

MapMarker USA 31 Developer Guide 44 Geocoding with MapMarker USA

GeoResult: S5HPNTSCZA Long: -73.699899 Lat: 42.682433

PlaceName Geocoding For example, the following input returns a close match candidate. Instead of the postal code, you could provide the ort and state. Note: The sample application provided with the Developer edition uses Firmname as the input field.

FirmName: MapInfo City: Troy State: NY Postal Code: 12180 The returned close match candidate includes the following output:

PlaceName: Map Info Address: 1 Global Vw Lastline: Troy, NY 12180-8399 GeoResult: S5HP--S-ZA Long: -73.702914 Lat: 42.682858

Fallback to Postal If MapMarker USA 31 cannot return a close street level match when you attempt a street level geocode, you may be able to get a close postcode match by using the Fallback to Postal option. If street address geocoding did not return a close match candidate (and a postal code is supplied on input), MapMarker USA 31 attempts to geocode to the postal centroid. The following input does not return a close match candidate when you street geocode and require Must Match on House Number, Street, and ZIP Code. This is because the house number does not exist and therefore cannot be matched.

Street Address: 3050 Ocean Drive City: Key Biscayne State: FL Postal Code: 33149 However, if you select the Fallback to Postal option, you will get a close postcode match with a Z result code (postal centroid match). You can also directly geocode to a postcode centroid (rather than using the Fallback to Postal option). See Postal Geocoding on page 46.

MapMarker USA 31 Developer Guide 45 Geocoding with MapMarker USA

Fallback to Geographic If MapMarker USA 31 cannot return a close street level match when you attempt a street level geocode, you may be able to get a close geographic match by using the Fallback to Geographic option. If street address geocoding did not return a close match candidate (and ort is supplied on input), MapMarker USA 31 attempts to geocode to the geographic centroid. The following input does not return a close match candidate when you street geocode and require Must Match on House Number, Street, and ZIP Code. This is because the ZIP Code is incorrect.

Street Address: 55 Upland Dr City: Ithaca State: NY Postal Code: 14880 However, if you select the Fallback to Geographic option, you will get a close match with a G3 result code (ort centroid match). You can also directly geocode to a geographic centroid (rather than using the Fallback to Geographic option). See Geographic Geocoding on page 47.

Postal Geocoding

MapMarker USA 31 can perform Postal geocoding to postcode centroids. You can enter the five-digit or complete nine-digit ZIP Code. To perform a postal geocode, enter the postcode, and select Postal from the Geocode Type drop-down list. Then click Geocode Address. The following input can be geocoded to postal centroid:

Postal Code: 10451-2116 This returns a close match candidate of Bronx, NY 10451-2116 with a Z3 result code (ZIP+4 postal centroid match) You can also use Postal geocoding as a fallback option if a Street geocoding operation fails to return close match candidates. See Fallback to Postal on page 45

MapMarker USA 31 Developer Guide 46 Geocoding with MapMarker USA

Postal Candidate Returns Postal geocoding requests returns a single matching postcode. The following table shows the Postal Candidate Return Fields in the MapMarker USA 31 sample application. Census data may also be returned, but is not shown in this table.

Postal Candidate Return Fields

Column Name Contents and Description Example

Close Match T for close match or F for T non-close match.

ZIP Postal code (5-digit) 10461

ZIP4 ZIP +4 2116

Long Longitude (X Coordinates) -79.391177

Lat Latitude (Y Coordinates) 43.64351

Result Result code for returned Z3 candidate.

Geographic Geocoding

MapMarker USA 31 can perform Geographic geocoding to geographic centroids. To perform a geographic geocode, enter a ort and state Select Geography from the Geocode Type drop-down list. Then click Geocode Address. The following input can be geocoded to geographic centroid.

City: Moab State: UT This returns a close match candidate of Moab, UT with a G3 result code (city centroid match). You can also use Geographic geocoding as a fallback option if a Street geocoding operation fails to return close match candidates. If you Street geocoded the same input address with Fallback to Geo, you would get the same results. See Fallback to Geographic on page 46.

Geographic Candidate Returns Geographic geocoding requests returns a single matching postcode. The following table shows the Geographic Candidate Return Fields in the MapMarker USA 31 sample application. The other fields are not relevant to geographic geocoding, and will be empty for geographic geocoding candidates.

MapMarker USA 31 Developer Guide 47 Geocoding with MapMarker USA

Geographic Candidate Return Fields

Column Name Contents and Description Example

Close Match T for close match or F for T non-close match.

City Result code for returned Moab candidates. (AreaName3)

State State UT

Long X coordinate -109.54917

Lat Y coordinate 38.57333

Result Result code for returned G3 result codes indicate a candidate geography match on an City centroid.

Reverse Geocoding

If you provide X/Y (Longitude/Latitude) coordinates, MapMarker USA 31 returns the closest address for the given X/Y location based on the available Address Dictionaries. Note: Reverse geocoding is available with the Developer (Server) edition only. Reverse geocoding is not implemented in the Desktop application and is not available with User Dictionaries. This feature is also separately licensed and must be covered in your license agreement. Reverse geocoding supported by the APIs. See Reverse Geocode on page 123 for an example of reverse geocoding using the REST API. See Setting Reverse Geocoding Distance and Offset Constraints on page 79 for information on reverse geocoding using the Java API. The following input can be reverse geocoded:

Longitude (X): -79.391177 Latitude (Y): 43.643510

If multiple dictionaries are available, the closest possible match is returned by default, regardless of which point or street segment dictionary produced the candidate. However, you can set a USA reverse geocoding contraint to force a match to the nearest point record when at least one point address dictionary is available and the point is found within the search distance. See Setting Reverse Geocoding Find Nearest Point Constraint on page 79 for information. Note: Reverse geocoding is available for all covered states and territories except Guam.

MapMarker USA 31 Developer Guide 48 Geocoding with MapMarker USA

Using Spatial Index Files Each address dictionary includes two spatial index files (gsx files) to support reverse geocoding. The MapMarker USA v31 installer automatically creates two gsx files for each address dictionary. Typically, no other user action is needed to implement reverse geocoding.

Reverse Geocoding Candidate Returns Reverse geocoding returns the same type of address information as a traditional street address geocoding operation. Reverse geocoded candidates also include the exact latitude / longitude coordinates of the candidate. Along with this, reverse geocoded candidates also indicate the coordinate system (EPSG code) and the location precision value (a numeric value of 1, 2, or 16). For the following input coordinates, a close match candidate is returned from a street segment with a result code of RS5A.

X:-79.391177 Y: 43.64351 MapMarker USA v31 reverse geocoding returns the closest possible candidate that finds from all of the available dictionaries, regardless of whether it was from a point or street segment dictionary. Note: Range information is not returned with reverse geocoded candidates for MapMarker USA. The candidate must be available within the search distance. By default this is 150 meters. If you change the search distance constraint (setDistance method of the RevereseGeocodeLocation class) this can affect the reverse geocoded candidate that is returned. The street offset and corner offsets (setStreetOffset and setCornerOffset methods) can affect the exact house number that you get if the candidate comes from a street segment dictionary. Typically, only one reverse geocoding candidate is returned. Multiple candidates can be returned if more than one candidate is computed as the same distance from the input location. If a candidate includes ranges, then the range associated with the candidate’s house number is returned. By default, no range units are returned but you can request units (see CandidateRangeUnit class in the Javadocs). Additionally, for each reverse geocoding candidate: • A returned field indicates its distance from the input location. • Each candidate returns a result code that indicates the precision. See Reverse Geocoded Matches (R category) on page 140. • Candidates include a house number, if one is available. • Candidates from a street segment dictionary include range information for the segment.

MapMarker USA 31 Developer Guide 49 Geocoding with MapMarker USA

For an example of the XML output generated by reverse geocoding operation, see Reverse Geocode on page 123. MapMarker Server can also return identifying information on the datasource for each candidate. This information is returned by the getDBType method of the USA_UserCandidateAddress class. For example:

cand.getDBType() The returned DBType identifies the data source for the reverse geocoded candidate. For more information, see Returning Database Source Information on page 77 for detailed information.

Optimizing MapMarker USA – Usability and Performance Tips

You can use a number of strategies to improve the accuracy and speed of geocoding with MapMarker USA 31.

General Guidelines for Optimizing Geocoding MapMarker USA 31 has been optimized for high performance. Follow these guidelines to achieve even faster performance. In general, you will achieve faster and more accurate geocoding if you standardize and format your data. By reducing the ambiguity in the input data, MapMarker USA 31 will be able to find appropriate candidates faster. For complete information on addressing practices and conventions and ZIP Codes, see the ZIP Code Lookup page on the USPS web site. Also consider the following guidelines to optimize your results and performance. • Use the fastest processor available to you. Pitney Bowes recommends dual core processor or better. • Have enough memory so that the operating system can allocate some memory to your disk cache. Pitney Bowes recommends 4 GB RAM or better. • Have at least 10 GB available disk space. • Store the Address Dictionary on a local hard drive. • Sort your table by postal code before geocoding. • Use Must Match (exact match) criteria for the most precise geocoding results. However, note that this strategy requires more processing and may reduce performance. • Do not create points automatically. • Remove indexes on any table output columns before geocoding. • In a multi-threaded server environment, use multiple engine instances to improve performance. See Optimizing Server Performance on page 51.

MapMarker USA 31 Developer Guide 50 Geocoding with MapMarker USA

Batch Geocoding Guidelines In addition to General Guidelines for Optimizing Geocoding on page 50, the following guidelines will help you achieve the best results when you are geocoding in batch mode (using the server). • Use ZIP Codes in your input data. This can improve performance significantly depending on other factors. • The proper combination of postcode with City, will produce better performance. That is, make sure that the postcode is consistent with the named City. • Sort your input table by postcode before geocoding. • Use match modes carefully. Decide whether your primary goal is the most accurate geocoding possible or the fastest geocoding. For the best geocoding results, geocode your input file using Default Match Mode first. Then run the non-geocoded addresses in Relaxed Match Mode with Postal or Geographic fallback enabled. For best performance (speed), geocode your input file using Relaxed Match mode in the first geocoding pass. • Use the option to return "Close Matches Only". Also consider setting "Max Candidates" to 1 and "Max Ranges" to 0. These steps will reduce the data transfer between client and server. To achieve this, in JavaAPI, use the following methods: setCloseMatch setMaxCandidates(int) setMaxRanges(int) In the XML API, specify the following in the BaseConstraints: closeMatchOnly="true" 1 0

Optimizing Server Performance The DataManagerSettings.properties file includes an entry that you can use to improve performance in a multi-threaded server environment. By default, the entry is set to 1 (single-threaded).

GEOSTAN_INSTANCE_COUNT=1 You can change this entry to take advantage of multiple CPUs in a server environment.

MapMarker USA 31 Developer Guide 51 4 4 – Using the MapMarker Java API

This chapter shows you how to build a geocoding application using the MapMarker Java API. It also discusses how to deploy your application, as well as some of the geocoding features available in the API such as setting geocoding constraints, street, postal, and geographic geocoding, street or place name browsing, and reverse geocoding. You can use the generic Java API or the USA-specific Java API. Note: For complete coverage of API, refer to the API documentation. See Using the JavaDocs API Documentation on page 53.

In this chapter:

Using the MapMarker Java USA API 53 Using the MapMarker Generic Java API 53 Using the JavaDocs API Documentation 53 Developing Geocoding Applications in Java 53 Geocoding and Returning Candidate Information 70 Creating a Reverse Geocoding Application in Java 78 Browsing Addresses 80 Geocoding To Postal Centroids 81 Geocoding to Geographic Centroids 82 Geocoding to Highway Exits 84 Geocoding to Airports 85 DPV Related Actions 86 Returning Match Codes and Location Codes 88 Standardizing Addresses 89 Creating a Web Geocoding Client in Java 90 Using the MapMarker Java API

Using the MapMarker Java USA API

The MapMarker USA Java API is used to create geocoding applications specifically for USA addresses. The API uses common U.S. address terminology and is a good choice for developers who are geocoding U.S. addresses. For complete API documentation, see, Using the JavaDocs API Documentation.

Using the MapMarker Generic Java API

The MapMarker Generic Java API is used to create international geocoding applications. The Generic API can be used with any MapMarker country geocoder. The API uses common universal address terminology and is a good choice for a developer whose requirement is to geocode addresses from many different countries. For more information on deploying MapMarker as a servlet along with other MapMarker countries see Integration with MapMarker for Other Countries on page 127. For complete API documentation, see Using the JavaDocs API Documentation.

Using the JavaDocs API Documentation

For detailed information on all API packages, interfaces, and classes, refer to the API documentation (Javadocs) for MapMarker. the JavaDocs is located in /docs/usa folder, where represents your MapMarker installation directory. From this folder, run index.html to see the MapMarker Javadocs. The generic (core) geocoding constraints are in the com.mapinfo.mapmarker package. The USA-specific geocoding constraints are in the com.mapinfo.mapmarker.user package. If you are running the Web Application, you can also browse to http://localhost:8095 on a computer where the MapMarker Server is running. Then click on the link for the MapMarker USA Java API.

Developing Geocoding Applications in Java

You can use either the MapMarker USA Java API or the MapMarker Generic API to develop custom geocoding applications in Java. See Using the MapMarker Java USA API and Using the MapMarker Generic Java API for more information on which API to use for your particular situation. To use the Java API, a number of jar files must be in your classpath. A copy of the USA_DataManagerSettings.properties file also must be in your classpath with the correct location of the MapMarker data. Also make sure that encoding-map.xml is in your classpath. Both of these files are in the SDK\engine\lib\client\ folder under the directory where you installed MapMarker USA.

MapMarker USA 31 Developer Guide 53 Using the MapMarker Java API

Setting Import Statements Make sure that your application contains the import statements below. Use one set or the other, depending on whether you are using the USA-specific API or the Generic Java API. For the USA-specific API:

/* MapMarker USA Java API */ import com.mapinfo.mapmarker.user.MMJEngine; import com.mapinfo.mapmarker.user.ClientGeocodeResponse; import com.mapinfo.mapmarker.USA.USA_GeocodeConstraints; import com.mapinfo.mapmarker.USA.USA_UserCandidateAddress; import com.mapinfo.mapmarker.USA.USA_UserInputAddress;

For the Generic Java API. These are used instead of USA_UserInputAddress

/* MapMarker Generic Java API */ import com.mapinfo.mapmarker.user.MMJEngine; import com.mapinfo.mapmarker.user.ClientGeocodeResponse; import com.mapinfo.mapmarker.user.GeocodeConstraints; import com.mapinfo.mapmarker.common.AddressImpl; import com.mapinfo.mapmarker.common.Address; import com.mapinfo.mapmarker.CandidateAddress /* CandidateAddress object used instead of a USA_UserCandidateAddress

public class MMJ_US_Example {

private void geocode() { /* Set server url*/ String url = "http://localhost:8095/mapmarker40/servlet/mapmarker";

Setting the Input Address Following is an example of how to set the input address if you were using the MapMarker USA Java API.

/* Input address example */ String addr = "1 GLOBAL VIEW"; String postcode = "12180"; String city = "TROY"; String state = "NY";

USA_UserInputAddress inpAddr = new USA_UserInputAddress();

/* Set the input Address */ inpAddr.setStreet(addr); /* 'street' */ inpAddr.setCity(city); /* 'city' */ inpAddr.setState(state); /* 'state' */ inpAddr.setZipcode(postal code); /* ‘zipcode’ */

Alternatively, you could use more concise setPostAddress instead of city, state, postcode: inpAddr.setPostAddress("Troy NY 12180"); Or use setMainAddress as follows:

MapMarker USA 31 Developer Guide 54 Using the MapMarker Java API

inpAddr.setMainAddress("1 global view, troy ny 12180")

If you are using the MapMarker Generic API, use the Address class implemented with AddressImpl.

Address inpAddr = new AddressImpl();

/* Set the input Address */ inpAddr.setCountry("USA"); inpAddr.setMainAddress(addr); /* street */ inpAddr.setAreaName3(city); /* city */ inpAddr.setAreaName1(state); /* state' */ inpAddr.setPostCode1(postcode); /* zipcode */

Geocoding Constraints

com.mapinfo.mapmarker.user.GeocodeConstraints Geocoding constraints (or preferences) affect how MapMarker attempts to match a record. Choose matching conditions to fit your needs. The generic GeocodeConstraints are described in the following Geocode Constraints table. The USA-specific constraints are described in USA_GeocodeConstraints.

MapMarker USA 31 Developer Guide 55 Using the MapMarker Java API

Geocode Constraints

Key and Method Description Default

KEY_ADDRESS_POINT_ Determines whether "false" INTERPOLATION address point candidates are offset setUseAddressPointInterpolat from the associated ion(boolean flag) segment when possible. See Using Address Point Interpolation on page 67.

setGeocodeType(IGeocodeC Indicates what kind of GeocodeConstraints. onstraints) geocode is requested. TYPE_GEOCODE_MATCH_ Possible values are: ADDRESS TYPE_GEOCODE_MA TCH_ADDRESS TYPE_GEOCODE_MA TCH_POSTCODE TYPE_GEOCODE_MA TCH_GEOGRAPHIC TYPE_GEOCODE_MA TCH_BROWSE TYPE_GEOCODE_MA TCH_STANDARDIZE_ ONLY

KEY_CLIENT_CRS String describing the "epsg:4326" client coordinate setClientCoordinateSystem system. Accepted (String crsString) values include EPSG setClientCoordinateSystem SRS Names as well as (com.mapinfo.coordsys.Coor MAPINFO MAPBASIC dSys coordSys) Projection String SRS Names. (see com.mapinfo.coordsys. CoordSys). Default uses WGS 84.

KEY_CLIENT_LOCALE Indicates the client "en_US" locale, such as:en_US setClientLocale(String) or fr_CA.

KEY_CLOSEMATCHESONL Only close matches are "false" Y returned. setReturnCloseCandidatesOn ly(boolean bReturn)

MapMarker USA 31 Developer Guide 56 Using the MapMarker Java API

Geocode Constraints (Continued)

Key and Method Description Default

KEY_CORNEROFFSET Defines the offset "25" position of the setCornerOffset(double geocoded point with offset) respect to the corner.

KEY_CORNEROFFSETUNIT The units used in "ft" (feet) S KEY_CORNEROFFSE T (ft, m, mi, km, in, yd, setCornerOffsetUnits(String cm, and mm) units)

KEY_DICTIONARY_SEARC Sets a custom order for ordered by H_ searching configured DICTIONARY_PATH# ORDER address/user dictionaries. See the setDictionarySearchOrder IDictionarySearchOrder (IDictionarySearchOrder interface in the newOrder) JavaDocs (com.mapinfo.mapmark er.common). If multiple dictionaries are configured, it is possible to identify equally close candidates from more than one dictionary. This constraint allows you to which dictionary is used in a tie-breaking situation (the lowest number configured dictionary)

KEY_DICTIONARY_USAGE Returns the key for AD_AND_UD dictionary usage setDictionaryUsage(Dictionar preference. (AD_ONLY, yUsagePreference pref) UD_ONLY, AD_AND_UD, PREFER_AD, PREFER_UD) For a description of these values, see Dictionary Usage Preference on page 64.

MapMarker USA 31 Developer Guide 57 Using the MapMarker Java API

Geocode Constraints (Continued)

Key and Method Description Default

KEY_FALLBACK_TO_ If no close street level "false" GEOGRAPHIC candidates are found, return geographic setFallbackToGeographic(boo centroid for the input lean address. bFallback)

KEY_FALLBACK_TO_POST If no close street level "false" AL candidates are found, return postal centroid for setFallbackToPostal(boolean the input address. bFallback)

KEY_MATCH_MODE Contains the match null mode value. This must setMatchMode(String be one of the defined MMString) match modes. The possible key values are described in Using Match Modes on page 65.

KEY_MAXCANDIDATES Max candidates to "3" return. setMaxCandidates(int m_maxCandidates) (use "-1" to return all candidates).

KEY_MAXRANGES Max ranges per "0" candidate to return (use setMaxRanges(int "-1" to return all ranges). m_maxRanges)

KEY_MAXRANGEUNITS Max units per range to "0" return. (use "-1" to setMaxRangeUnits(int return all range units) m_maxRangeUnits)

KEY_MUST_MATCH_ADDR Only candidates "false" NUM matching address number are considered setMustMatchAddressNumbe close. r (boolean bMatch)

MapMarker USA 31 Developer Guide 58 Using the MapMarker Java API

Geocode Constraints (Continued)

Key and Method Description Default

KEY_MUST_MATCH_AREA1 Only candidates "false" matching a country setMustMatchArea1(boolean subdivision bMatch) (areaname1) are considered close (state for USA).

KEY_MUST_MATCH_AREA2 Only candidates "false" matching geographic setMustMatchArea2(boolean areaname 2 are bMatch) considered close.

KEY_MUST_MATCH_AREA3 Only candidates "false" matching a city or town setMustMatchArea3(boolean are considered close. bMatch)

KEY_MUST_MATCH_AREA4 Only candidates "false" matching geographic setMustMatchArea4(boolean area 4 are considered bMatch) close.

KEY_MUST_MATCH_COUN Only candidates "true" TRY matching teh country are considered close. setMustMatchCountry(bMatc h)

KEY_MUST_MATCH_INPUT Only candidates "false" matching all input areas setMustMatchInput(boolean (where MUST_MATCH bMatch) is defined) are considered close.

KEY_MUST_MATCH_MAINA Only candidates "false" DDR matching the main address are considered setMustMatchMainAddress(b close. oolean bMatch)

KEY_MUST_MATCH_POSTA Only candidates "false" L matching postal code are considered close. setMustMatchPostalCode(bo olean bMatch)

MapMarker USA 31 Developer Guide 59 Using the MapMarker Java API

Geocode Constraints (Continued)

Key and Method Description Default

KEY_STREETOFFSET Defines the position of "25" the geocoded point with setStreetOffset(double offset) respect to the centerline of the street.

KEY_STREETOFFSETUNIT The units used in "ft" (feet) S KEY_STREETOFFSET (ft, m, mi, km, in, yd, cm, setStreetOffsetUnits(String and mm). units)

POINT_CENTERLINE_OFFS Defines the offset "25" ET distance to use for point centerline interpolation. setCenterlineOffset(double value)

POINT_CENTERLINE_OFFS The units used in "ft" (feet) ET_ POINT_CENTERLINE_ UNITS OFFSET (ft, m, mi, km, in, yd, cm, and mm). setCenterlineOffsetUnit(String unit)

USE_POINT_CENTERLINE_ Determines whether "false" OFFSET centerline offset is used. See Using Centerline setUseCenterlineOffset(boole Offset for Point an flag) Candidates on page 68.

See Sample Code for Setting Geocoding Constraints on page 69 for examples of how to set some geocode constraints.

USA_GeocodeConstraints

com.mapinfo.mapmarker.USA.USA_GeocodeConstraints

MapMarker USA 31 Developer Guide 60 Using the MapMarker Java API

USA_GeocodeConstraints extend the GeocodeConstraints object. This provides both a default and copy constructor (no arguments or a GeocodeConstraints object as the argument). The keys are defined in the following USA_GeocodeConstraints table:

USA_GeocodeConstraints

Key and Method Description Default

KEY_ALTERNATE_LOOKUP Determines whether the STREET_FIR preferred lookup is to look for ST setAlternateLookupPreference streets first or firm name (places) first. See KEY_ALTERNATE_LOOKUP Values.

KEY_CASS_DPV Enable DPV. "false" setDPVMode

KEY_LACSLINK Enable LACSLink . "false" setUseLACSLink

KEY_MUST_MATCH_CITY Requires city/town match for a "false" close match. setMustMatchCity Base equivalent AREA3

KEY_MUST_MATCH_STREET Requires street name match "false" for a close match. setMustMatchStreet Base equivalent STREET.

KEY_MUST_MATCH_ZIPCODE Requires ZIP Code™ match "false" for a close match. setMustMatchZipcode Base equivalent POSTAL.

KEY_PREFER_USER_DICTIONA When using Address "false" RY Dictionary and User Dictionary together, prefer a setDictionaryUsage UD close match over an AD close match.

MapMarker USA 31 Developer Guide 61 Using the MapMarker Java API

USA_GeocodeConstraints (Continued)

Key and Method Description Default

KEY_ZIP_OVER_CITY Prefer ZIP Code match over a "false" city match. setPreferZipMatchOverCity The same street address can potentially be found in conflicting City and ZIP Codes. For example, consider the address: 200 Broadway, Troy NY, 10038. Normally this would match the Troy NY candidate and the conflicting ZIP Code would be ignored. But KEY_ZIP_OVER_CITY="true" would prefer the ZIP Code and the 200 Broadway address in Brooklyn, NY 10038 would be returned. This is not available in CASS mode.

KEY_SEARCH_LEVEL The setSearchLevel method setSearchLev can be used to set finance el is set to setSearchLevel area, city, or expanded search Finance Area setUseExpandedSearch levels. by default for (deprecated in v25) CASS mode See KEY_SEARCH_LEVEL and City for Values. all other The deprecated modes. setUseExpandedSearch method can be used to set expanded search. This is false by default.

SUITELINK Enable SuiteLink. SuiteLink "false" setUseSuiteLink will append the secondary (suite) information to a business address providing the input address is determined to be a highrise default record.

MapMarker USA 31 Developer Guide 62 Using the MapMarker Java API

USA_GeocodeConstraints (Continued)

Key and Method Description Default

WIDE_SEARCH Enables the wide search ."false" option. Wide search considers setUseWideSearch all records matching the first letter of the street name.

KEY_ALTERNATE_LOOKUP Values

VALUE_ALTERNATE_LOOKUP_ Only candidates matching on OFF street are considered. The value for KEY_ALTERNATE_LOOKUP = "STREET_ONLY"

Candidates matching on place VALUE_ALTERNATE_LOOKUP_P are preferred over street. LACE The value for KEY_ALTERNATE_LOOKUP = "PLACE_FIRST"

Candidates matching on VALUE_ALTERNATE_LOOKUP_S street are preferred over TREET place. The value for KEY_ALTERNATE_LOOKUP = "STREET_FIRST"

KEY_SEARCH_LEVEL Values

VALUE_SEARCH_LEVEL_EXPAN Enables the expanded search "false" DED feature. KEY_SEARCH_LEVEL = SEARCH_LEVEL_EXPANDE D

KEY_EXPANDED_SEARCH_RAD If expanded search is "25" IUS enabled, search a given radius (up to 99 miles) of the setExpandedSearchRadiusInMiles input address.

KEY_EXPANDED_SEARCH_LIMI If expanded search is "true" T_ enabled, limit the expanded TO_STATE search to the same state of the input address, regardless setExpandedSearchLimitToState of the mile radius.

MapMarker USA 31 Developer Guide 63 Using the MapMarker Java API

USA_GeocodeConstraints (Continued)

Key and Method Description Default

VALUE_SEARCH_LEVEL_FINAN Search the entire finance area Default for CE_ for possible streets CASS Mode. AREA KEY_SEARCH_LEVEL = VALUE_SEARCH_LEVEL_ FINANCE_AREA

VALUE_SEARCH_LEVEL_CITY Limit the search to streets Default for within the specified city. Relaxed, Exact, KEY_SEARCH_LEVEL = Default, or VALUE_SEARCH_LEVEL_CI Custom TY Modes.

USA_ReverseGeocodeConstraints

com.mapinfo.mapmarker.USA.USA_ReverseGeocodeConstraints USA_ReverseGeocodeConstraints extend the ReverseGeocodeConstraints object. This provides both a default and copy constructor (no arguments or a ReverseGeocodeConstraints object as the argument).

USA_ReverseGeocodeConstraints

Key and Method Description Default

FIND_CLOSEST_POINT The setFindClosestPoint "false" method can be used to force a setFindClosestPoint match to the nearest point record when at least one point data set is loaded and a point record is found within the search radius.

By default setFindClosestPoint is false, which means that the closest candidate is returned regardless of whether it is a point or street segment candidate.

Dictionary Usage Preference The DictionaryUsagePreference class describes whether the address dictionary or user dictionary are preferred or used exclusively. See KEY_DICTIONARY_USAGE on page 57.

MapMarker USA 31 Developer Guide 64 Using the MapMarker Java API

Dictionary Usage Preference Fields

Dictionary Usage Preference Description

AD_AND_UD Use both address dictionaries (AD) and user dictionaries (UD) with no preference for candidates from either dictionary.

AD_ONLY Use only address dictionaries (AD).

PREFER_AD Use both address dictionaries (AD) and user dictionaries (UD) but give preference to candidates from ADs.

PREFER_UD Use both address dictionaries (AD) and user dictionaries (UD) but give preference to candidates from UDs.

UD_ONLY Use only user dictionaries (UD).

Using Match Modes The following constants and methods are related to match modes. These are included in the GeocodeConstraints class, except for CASS_MODE which is specific to USA_GeocodeConstraints. Modes override Must Match criteria, except for MATCH_MODE_NONE, which means that custom settings (Must Match constraints) are used. See Setting Match Modes on page 36 for more information on match modes.

Match Mode Constants

Constant Value Description

RELAXED_MODE "RelaxedMode Sets Relaxed match mode. " setMatchMode()

EXACT_MODE "ExactMode" Sets Exact match mode. setMatchMode()

DEFAULT_MODE "DefaultMode" Sets Default match mode. setMatchMode()

CASS_MODE (USA only) "CASS_MODE Sets CASS match mode. " setMatchMode()

MapMarker USA 31 Developer Guide 65 Using the MapMarker Java API

Match Mode Constants (Continued)

Constant Value Description

MATCH_MODE_NONE null Indicates that match mode is not used. This means that setMatchMode() custom individual settings (MustMatch constraints) are used instead. See Geocoding Constraints on page 55.

KEY_MATCH_MODE Indicates which match mode is being used. setMatchMode()

Note: EXACT_MODE is equivalent to Tight Mode in the Desktop Application. DEFAULT_MODE is equivalent to Standard Mode in the Desktop Application. See the MapMarker User Guide for information on how match modes are implemented in the Desktop Application

Setting the Coordinate System A coordinate system is a recognized 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. MapMarker uses all of the coordinate systems supported by MapXtreme, including systems recognized by the European Petroleum Survey Group (EPSG). Coordinate systems are set through the USA_GeocodeConstraints method setClientCoordinateSystem. This class extends the GeocodeConstraints class, which implements IGeocodeConstraints.

USA_GeocodeConstraints constraints = new USA_GeocodeConstraints(); constraints.setClientCoordinateSystem(CoordSys.longLatWGS84); If a coordinate system is not defined, then MapMarker uses the Longitude / Latitude (WGS 84) coordinate system by default. The following table lists common coordinate systems used in the United States:

Description Datum String

Longitude / Latitude WGS 84 EPSG:4326

Longitude / Latitude NAD 83 EPSG:4269

Longitude / Latitude NAD 27 for EPSG:4267 Continental United States

MapMarker USA 31 Developer Guide 66 Using the MapMarker Java API

Using Address Point Interpolation This method of interpolation assigns coordinates to address records in relation to the position of address point candidates in the data, providing greater positional accuracy to the geocoded points. The geocoding engine can incorporate address point data in the position assignment and interpolation process. MapMarker uses address point data that may be present in the Address Dictionary, or supplied by the user in a customized dictionary. The most consistent results will be achieved by using a customized dictionary that contains address points for the area you are geocoding. To use address point interpolation, you must set the setUseAddressPointInterpolation method in the IGeocodeConstraints object to True. The following types of candidates can be returned: • The candidate to be returned is an address point candidate. If the candidate is itself an address point candidate, the unique point from the segment will be returned and the point precision will be set to 16 (CandidateAddress.ADDRESS_POINT_PRECISION). • The candidate to be returned is not an address point candidate, but another candidate on the same street is an address point candidate and shares the same house number (for example, the candidate to be returned was generated from the Address Dictionary and the other candidate from a user dictionary). In this case, the unique point from the second candidate is returned and the point precision is set to 16 (CandidateAddress.ADDRESS_POINT_PRECISION). See DPV Related Actions on page 86 for a complete list of CandidateAddressClass • The candidate to be returned is not an address point candidate and there are no address point candidates with a matching house number in the list of generated candidates. In these cases, all of the address point candidates are filtered for the following information: • A house number that is the same odd/even as the house number of the candidate to be returned. • A point that intersects the segment of the candidate to be returned. • A house number that is contained within the range defined for this candidate, for example, one of this candidate’s ranges must intersect the address point candidate’s house number. MapMarker then uses the filter information from the resulting list of address point candidates to interpolate the candidate’s point location. The precision for this type of interpolation is 17 (ADDRESS_POINT_INTERPOLATED). If no address point candidates are returned, the point is interpolated just as it would be without using address point interpolation.

MapMarker USA 31 Developer Guide 67 Using the MapMarker Java API

Using Centerline Offset for Point Candidates If you geocode using a point-based Address Dictionary, you can return candidates at a specified offset from the associated street segment (rather than at the original S8 coordinates). Where possible, the coordinates are offset perpendicularly from the segment. A street range Address Dictionary must also be available so that an offset from the segment is possible. If there is no street range dictionary in addition to the point-based dictionary, then the original point candidate is returned. The precision for this type of point interpolation is 18 (ADDRESS_POINT_PROJECTED). The centerline offset capability is controlled by the following GeocodeConstraints methods:

setUseCenterlineOffset() Set to true to specify that point candidates should be offset from the nearest segment. Default is false.

setCenterlineOffset(double offset) Specifies the offset distance from the segment toward the original point. This can be any number with a default of 25 (feet).

setCenterlineOffsetUnit(String Specifies the offset distance units. unit) The allowable units are: (ft, m, mi, km, in, yd, cm, and mm). Default is ft (feet). Internally, the distances are converted to feet.

For example, this specifies a centerline offset of 12 meters (which is internally converted to 39 feet):

m_constraints.setUseCenterlineOffset(true); m_constraints.setCenterlineOffset(12); m_constraints.setCenterlineOffsetUnit("m"); The USA_DataManagerSettings.properties file has a CENTERLINE_OFFSET entry that implements centerline offset in the Desktop application. For example, the following entry specifies a centerline offset of 20 feet. CENTERLINE_OFFSET=20 This optional entry controls the centerline offset for point data. By default, this entry is commented out. Uncomment it if you are using point data. If centerline offset is specified in both the USA_DataManagerSettings.properties file and via the API, the relationship is as follows: • If the USA_DataManagerSettings.properties file has a CENTERLINE_OFFSET value, then centerline offset is used.

MapMarker USA 31 Developer Guide 68 Using the MapMarker Java API

• If the API setUseCenterlineOffset offset method is true and the setCenterlineOffset value is set (any number), then centerline offset is used. The API settings override the properties file settings. • The USA_DataManagerSettings.properties file does not control offset units. This is controlled by the setCenterlineOffsetUnit method of the API. If that uses an alternative unit (such as meters), the distances are internally converted to feet for both the Server and Desktop application. • To disable centerline offset, the CENTERLINE_OFFSET entry must be absent (or commented) from the properties file and the setUseCenterlineOffset offset method must be false.

Sample Code for Setting Geocoding Constraints Following is an example of how to set constraints using the MapMarker USA Java API. This example sets a fallback to Postal Code if a close match could not be made and sets the CASS_MODE match mode. This uses the USA_GeocodeConstraints class.

USA_GeocodeConstraints geoCon = new USA_GeocodeConstraints(); /* Geocode Constraints: * Review Java docs for a complete constraint list and * default values */ geoCon.setMustMatchAddressNumber(true); geoCon.setMaxCandidates(1); geoCon.setReturnCloseCandidatesOnly(true); geoCon.setFallbackToPostal(false); geoCon.setMatchMode(USA_GeocodeConstraints.CASS_MODE); If you are using the MapMarker Generic API, use the GeocodeConstraints class:

GeocodeConstraints constraints =new GeocodeConstraints(); constraints.setMustMatchAddressNumber(true); constraints.setMaxCandidates(1); constraints.setReturnCloseCandidatesOnly(true); constraints.setFallbackToPostal(true); constraints.setMatchMode(GeocodeConstraints.CASS_MODE);

Using the Wide Search Constraint Use the USA_GeocodeConstraints wide search method to broaden your search based on a matching first letter. This makes it possible for MapMarker USA to identify candidates where the input street name was incorrect (as long as the first letter of the street is accurate). In the following example, the input is WEKIRA SPRINGS RD, when the actual candidate street name is WEKIVA SPRINGS RD. The wide search method makes it possible to retrieve this candidate.

m_constraints = new USA_GeocodeConstraints(); m_constraints.setMustMatchAddressNumber(true); m_constraints.setReturnCloseCandidatesOnly(true); m_constraints.setUseWideSearch(true); m_InpAddr.setStreet("195 WEKIRA SPRINGS RD"); m_InpAddr.setLastLine("LONGWOOD, FL 32779");

MapMarker USA 31 Developer Guide 69 Using the MapMarker Java API

m_gr = m_javaapi.geocode(0,m_InpAddr,m_constraints)

Examine wide search candidates carefully. The changed street name may not be the street that you intended. Also, wide search will slow the performance of MapMarker USA.

Using Expanded Search You can implement expanded search, which allows MapMarker to search for an address and return candidates within a given radius of the input address. Expanded search is not implemented by default, but is supported at both the API level and in the Desktop application. The following example shows the USA_GeocodeConstraints setSearchLevel and expanded search methods

m_constraints.setMustMatchMainAddress(true); m_constraints.setReturnCloseCandidatesOnly(false); m_constraints.setSearchLevel(USA_GeocodeConstraints.Searchlevel. SEARCH_LEVEL_EXPANDED; m_constraints.setExpandedSearchRadiusInMiles(5); m_constraints.setExpandedSearchLimitToState(true); The setExpandedSearchRadiusInMiles method can be set from 0 o 99 miles. The setExpandedSearchLimitToState method determines whether a state boundary can be crossed when using expanded search.

Using Search Levels You can implement search levels to search for candidates based on a finance area, or an area defined by the city, state, and ZIP Code. In the following example, candidates must be within the finance area of the input address.

m_constraints.setSearchLevel(USA_GeocodeConstraints.SearchLevel. SEARCH_LEVEL_FINANCE_AREA); m_InpAddr.setStreet("1217 Cleveland Ave"); m_InpAddr.setLastLine("LA GRANGE PK, IL 60526-1305"); Alternatively, SEARCH_LEVEL_CITY could be used to locate candidates within the city boundary only. For example:

m_constraints.setSearchLevel(USA_GeocodeConstraints.SearchLevel. SEARCH_LEVEL_CITY);

Geocoding and Returning Candidate Information

After you have set the input address, geocoding constraints, (and optionally other preferences such as the coordinate system, address point interpolation, or centerline offset), you are ready to geocode. Use the geocode method of the MMJEngine class as shown in this example. This class is used for geocoding with either the MapMarker USA Java API or the MapMarker Generic Java API. To geocode using the MMJClient class see Creating a Web Geocoding Client in Java on page 90.

MapMarker USA 31 Developer Guide 70 Using the MapMarker Java API

/* Geocode Address */ MMJEngine engine = new MMJEngine(); ClientGeocodeResponse geoRes = engine.geocode (com.mapinfo.mapmarker.user.MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS, inpAddr, geoCon);

Getting Candidates Your application can check to see how many candidates were found. You can do this by looking at the totalPossibleCandidates property of the ClientGeocodeResponse object.

if (geoRes.totalPossibleCandidates() >0) { /* [. . . ] */ } Out of all the candidates found, you can also see how many were close matches. You can do this by looking at the totalPossibleCloseMatchCandidates property and the of the ClientGeocodeResponse object.

if (geoRes.totalPossibleCloseMatchCandidates() >0) { /* [. . . ] */ } MapMarker only returns a subset of the total possible candidates that it has found. As a default MapMarker returns the first three candidates that are found. To see more of the candidates, call setMaxCandidates(x) where x is the maximum number of candidates desired. You can check to see how many candidates were actually returned by looking at the candidateCount property of the ClientGeocodeResponse object.

if (geoRes.candidateCount() >0) { /* [. . . ] */ } You can use USA_UserCandidateAddress to obtain detailed candidate information.

/* Get candidate count */ int candCount = geoRes.candidateCount();

/* * Get returned candidates */ if (candCount > 0) {

for (int i=0; i < candCount; i++) { /*Get candidate information */ USA_UserCandidateAddress usaCand = new USA_UserCandidateAddress (geoRes.candidateAt(i)); System.out.println(usaCand.toString()); System.out.println(usaCand.getLocation().toString()); } } You can also return range and unit information, although that is not demonstrated in this sample code. See Returning Range and Unit Information on page 75.

MapMarker USA 31 Developer Guide 71 Using the MapMarker Java API

Getting the Result Code As an output option, MapMarker returns a result code for every candidate it returns. The code indicates the success or failure of the geocoding operation and conveys information about the quality of the match. Each character of the code tells how precisely MapMarker matched each address component. The result code is obtained using the getPrecisionCode method of the USA_UserCandidateAddress class (com.mapinfo.mapmarker.USA_UserCandidateAddress). For more information on interpreting the geocoding results, see the Result Codes in Chapter 7 on page 131. MapMarker USA v31 also returns match codes and location codes. See Returning Match Codes and Location Codes on page 88.

Getting the Segment ID Segment IDs are numeric codes that uniquely identify each point or street centroid candidate. The MapMarker USA 31 geocoder returns the Segment ID for each S8, S7, S6, S5 and S4 candidate (if the segment ID information is available in the Address dictionary.) Segment IDs are also returned for reverse geocoded candidates. Segment IDs are available through the API only. The getSegmentID() method of the USA_UserCandidateAddress class (com.mapinfo.mapmarker.USA_UserCandidateAddress) returns the segment ID.

Getting Location Precision Location precision codes represent the precision of the candidate point that was returned by getLocation(). Location precision is obtained using the getLocationPrecision method of the USA_UserCandidateAddress class (com.mapinfo.mapmarker.USA_UserCandidateAddress). The Candidate Address Location Precision Values table shows the precision codes returned by the getLocationPrecision method.

Candidate Address Location Precision Values

Constant Value Description

ADDRESS_POINT_PROJECTED 18 Constant indicating that the original point was offset from the nearest segment using centerline offset

ADDRESS_POINT_INTERPOLATE 17 Constant indicating that the D result was generated by using address point data to modify the candidates segment data.

MapMarker USA 31 Developer Guide 72 Using the MapMarker Java API

Candidate Address Location Precision Values (Continued)

Constant Value Description

ADDRESS_POINT_PRECISION 16 Constant indicating that the result represents an Address Point.

GEOGRAPHIC_AREANAME1 8 Match level indicating that the candidate point represents an area name 1 centroid for this candidate address.

GEOGRAPHIC_AREANAME2 9 Match level indicating that the candidate point represents an area name 2 centroid for this candidate address.

GEOGRAPHIC_AREANAME3 10 Match level indicating that the candidate point represents an area name 3 centroid for this candidate address.

GEOGRAPHIC_AREANAME4 11 Match level indicating that the candidate point represents an area name 4 centroid for this candidate address.

LOCAL_CUSTOM_POINT_PRECIS 12 Constant indicating that the ION_1 candidate has a point ZIP precision (for USA only).

LOCAL_CUSTOM_POINT_PRECIS 13 Additional point precision for ION_2 unspecified custom item.

LOCAL_CUSTOM_POINT_PRECIS 14 Additional point precision for ION_3 unspecified custom item.

LOCAL_CUSTOM_POINT_PRECIS 15 Additional point precision for ION_4 unspecified custom item.

NO_COORDINATES_AVAILABLE 0 Match level indicating that no coordinate information is available for this candidate address.

POINT_OF_INTEREST 7 Match level indicating that the candidate point represents a point of interest for this candidate address.

MapMarker USA 31 Developer Guide 73 Using the MapMarker Java API

Candidate Address Location Precision Values (Continued)

Constant Value Description

POSTAL_LEVEL_POSTAL_CODE_ 3 Match level indicating that the 1 candidate point represents postal code 1 centroid for this candidate address.

POSTAL_LEVEL_POSTAL_CODE_ 5 Match level indicating that the 2 candidate point represents a centroid of a postal code 2 for this candidate address.

POSTAL_LEVEL_POSTAL_CODE_ 4 Match level indicating that the 2_ candidate point represents a PARTIAL centroid of a partial postal code 2 for this candidate address.

STREET_LEVEL_INTERPOLATED 1 Match level indicating that the candidate point represents an interpolated street address for this candidate address.

STREET_LEVEL_INTERSECTION 6 Match level indicating that the candidate point represents an intersection for this candidate address.

STREET_LEVEL_SHAPE_PATH 2 Match level indicating that the candidate point represents a street segment midpoint for this candidate address.

Getting Street Range Parity Information Candidate range constants in the Candidate Range Constants and Values table represent the street range parity of the geocoded candidate, if range data is associated with the address. This range information is obtained using the getLeftRightIndicator and getOddEvenIndicator methods of the USA_UserCandidateRange class (com.mapinfo.mapmarker.USA_UserCandidateRange).

MapMarker USA 31 Developer Guide 74 Using the MapMarker Java API

The following table shows the constants returned by the getLeftRightIndicator and getOddEvenIndicator methods.

Candidate Range Constants and Values

Constant Value Description

ODD_EVEN_BOTH 0 Range contains both odd and even house numbers.

ODD_EVEN_EVEN 2 Range contains even house numbers.

ODD_EVEN_ODD 1 Range contains odd house numbers.

ODD_EVEN_UNKNOWN -1 Unknown house number odd/even status for this range.

STREET_SIDE_LEFT 1 Range is on the left side of the street.

STREET_SIDE_RIGHT 2 Range is on the right side of the street.

STREET_SIDE_UNKNOWN 0 Unknown street side information for this range.

Returning Range and Unit Information You can return address range and range unit information. The classes USA_UserCandidateAddressRange and USA_UserCandidateAddressRangeUnit include the methods associated with ranges and range units. For complete API documentation, see Using the JavaDocs API Documentation. Following is an example:

/* Input address example */

USA_UserInputAddress inpAddr = new USA_UserInputAddress (); inpAddr.setStreet("Fictional"); inpAddr.setZipcode("12180"); To search, use the method of the MMJEngine class as shown in this example. This class is used for browsing with either the MapMarker MapMarker Java API or the MapMarker Generic Java API.

/* Search Address */ MMJEngine engine = new MMJEngine(); ClientGeocodeResponse geoRes = null; geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS, inpAddr, geoCon);

MapMarker USA 31 Developer Guide 75 Using the MapMarker Java API

After geocoding, you can use the getNumberOfCandidateRanges method to get range information.

/* Get candidate count */ int candCount = geoRes.candidateCount(); /* * Get returned candidates */ if (candCount > 0) { /*Get candidate information */ USA_UserCandidateAddress candAddr = new USA_UserCandidateAddress(geoRes.candidateAt(i)); System.out.println("Candidate") if (candAddr.getNumberOfCandidateRanges() > 0) { USA_UserCandidateRange candRange = new USA_UserCandidateRange(candAddr.getRangeAt(0)); System.out.println("Candidate Range :" + candRange); }

Returning Short Address Information You can return abbreviated city and address information that conforms with USPS CASS guidelines. The results are returned as strings using the following USA_UserCandidateAddress methods.

Short Address Methods and Keys

Description Method Key

Short city name (13 getShortCityName USA_SHORT_CITYNAME character maximum). This is an alternate form of the city name defined by the USPS.

Short street name getShortStreetName USA_SHORT_STREETNA returned. This is an ME alternate form of the street name defined by the USPS.

Short street type getShortStreetType USA_SHORT_STREETTYP returned. This is an E alternate form of the street type defined by the USPS.

MapMarker USA 31 Developer Guide 76 Using the MapMarker Java API

Short Address Methods and Keys (Continued)

Description Method Key

Short pre-directional getShortPreDir USA_SHORT_PREDIR returned. This is an alternate form of the street pre-directional defined by the USPS.

Short post-directional getShortPostDir USA_SHORT_POSDIR returned. This is an alternate form of the street post-directional defined by the USPS.

Short address returned. getShortAddressLine USA_SHORT_ADDRESSLI This is an alternate NE form of the lastline containing the short city name.

Returning Database Source Information You can return identifying information on the datasource for each candidate. The results are returned as a number using the getDBType method of the USA_UserCandidateAddress class. For example:

cand.getDBType()

Alternatively, using the getAdditionalFieldForKey method:

cand.getAdditionalFieldForKey(USA_CandidateConstants.USA_DB_TYPE) Or

cand.getAdditionalFieldForKey("USA_DB_TYPE") Each returned number corresponds to a specific data source as shown in the Data Source (DBType) Returned table. In the Desktop application, this number may be translated into a descriptive string.

Data Source (DBType) Returned

Number Database Type Description

0 USPS USPS data

1 TIGER TIGER data

MapMarker USA 31 Developer Guide 77 Using the MapMarker Java API

Data Source (DBType) Returned(Continued)

Number Database Type Description

2 TOMTOM TomTom street data

5 deprecated

6 HERE HERE NAVSTREETS™

7 TOMTOM_POINT TomTom point data

8 CENTRUS_POINT Centrus point data

10 USER_DICTIONARY User Dictionary

11 HERE_POINT HERE Point Addressing

12 MASTER_LOCATION Master Location data

Note: Database source information (DBType) is returned for street geocode or reverse geocode candidates only. Postal and geographic candidates do not return this information.

Getting Additional Candidate Information See the MapMarker USA v31 API (Javadocs) for comprehensive coverage of the CandidateAddress and USA_UserCandidateAddress classes and the methods and keys associated with those classes. See Using the JavaDocs API Documentation on page 53 for the location of the JavaDocs.

Creating a Reverse Geocoding Application in Java

Reverse geocoding accepts Longitude/Latitude input and returns address candidates.After you have set the input coordinates and the optional geocoding constraints, you are ready to reverse geocode. Note: Reverse geocoding is available with the Developer (Server) edition and API, but not with the Desktop application. Reverse geocoding is not available with User Dictionaries. Reverse geocoding is a separately licensed feature and must be covered in your license agreement.

Setting Import Statements Make sure that your application contains these import statements. The classes specific to Reverse Geocoding are highlighted in bold.

import com.mapinfo.mapmarker.user.ReverseGeocodeLocation; import com.mapinfo.mapmarker.user.MMJEngine; import com.mapinfo.mapmarker.user.MapMarkerJavaAPI; import com.mapinfo.mapmarker.user.ReverseGeocodeAPI;

MapMarker USA 31 Developer Guide 78 Using the MapMarker Java API

import com.mapinfo.mapmarker.user.ReverseGeocodeConstraints; import com.mapinfo.mapmarker.user.MapMarkerException; import com.mapinfo.mapmarker.user.MapMarkerFatalException; import com.mapinfo.mapmarker.user.ReverseGeocodeResponse; import com.mapinfo.mapmarker.user.ReverseGeocodeCandidateAddress; import com.mapinfo.mapmarker.USA.reverseGeocode.USA_ReverseGecodeFatalException import com.mapinfo.mapmarker.user.MMJClient; import com.mapinfo.util.DoublePoint; import com.mapinfo.coordsys.CoordSys; import com.mapinfo.mapmarker.USA.reverseGeocode.USA_ReverseGecodeFatalException import com.mapinfo.unit.Distance; import com.mapinfo.unit.LinearUnit;

import java.net.MalformedURLException;43.64351

Setting the Input Location For a reverse geocoding application, you must set the input location. You can also set the coordinate system and the distance to search from the input coordinates. The Distance specifies the distance (radius) to search from the input coordinates. The default distance is 150 meters and the maximum cannot exceed 1 mile.

DoublePoint inputLoc = new DoublePoint( -79.391177, 43.64351); ReverseGeocodeLocation rgLoc = new ReverseGeocodeLocation(inputLoc, CoordSys.longLatWGS84, setDistance);

Setting Reverse Geocoding Distance and Offset Constraints Set the geocoding constraints (or preferences). If no constraints are explicitly provided, MapMarker uses default settings.

ReverseGeocodeConstraints constraints = new ReverseGeocodeConstraints(); Distance setDistance = new Distance(150.0, LinearUnit.meter); constraints.setCornerOffset(new Distance(8.0, LinearUnit.meter)); constraints.setStreetOffset(new Distance(8.0, LinearUnit.meter));

Setting Reverse Geocoding Find Nearest Point Constraint You can set a USA reverse geocoding constraint to force a match to the nearest point record when at least one point address dictionary is available and the point is found within the search distance. If this constraint is set to true, then the coordinates of the nearest point candidate are returned, even if a street segment candidate is closer. By default, the constraint is false and closest candidate is returned regardless of whether it is a point or street segment candidate.

USA_ReverseGeocodeConstraints rgConstraints = new USA_ReverseGeocodeConstraints(); constraints.setFindClosestPoint(true);

MapMarker USA 31 Developer Guide 79 Using the MapMarker Java API

Reverse Geocoding After you have set the input location and reverse geocoding constraints, you are ready to reverse geocode. Use the reverseGeocode method of the MMJEngine class as shown in this example. This class is used for making reverse geocoding requests to either the MapMarker USA Java API or the MapMarker Generic Java API. To make geocoding requests to a MapMarker server, use the MMJClient class. See Creating a Reverse Geocoding Application in Java on page 78.

DoublePoint inputLoc = new DoublePoint(-79.391177, 43.64351); Distance searchDistance = new Distance(150.0, LinearUnit.meter); ReverseGeocodeLocation rgLoc = new ReverseGeocodeLocation(inputLoc, CoordSys.longLatWGS84, searchDistance); ReverseGeocodeConstraints constraints = new ReverseGeocodeConstraints(); ReverseGeocodeAPI rgAPI = new MMJEngine(); ReverseGeocodeResponse response = rgAPI.reverseGeocode("USA", rgLoc, constraints);

Reverse Geocoding Response After geocoding, get the geocoding response. This uses the ReverseGeocodeCandidateAddress Class. Result codes are returned by the getPrecisionCode method.

if (response.candidateCount() > 0) { ReverseGeocodeCandidateAddress candidate = response.candidateAt(0); System.out.println("Precision code: " + candidate.getPrecisionCode()); System.out.println("Street address: " + candidate.getFormattedStreetAddress()); System.out.println("Lastline: " + candidate.getFormattedLocationAddress()); System.out.println("Distance: " + candidate.getDistance()); System.out.println("Dictionary: " + candidate.getConfiguredDictionaryNumber()); candidate.getAdditionalFieldForKey(USA_CandidateConstants.USA_DB_TYPE) } Note that range information is not returned with reverse geocoded candidates for MapMarker USA. For more information on interpreting the geocoding results, see Geographic Matches (G category) on page 140.

Browsing Addresses

Browsing enables you to retrieve a list of possible address candidates from an address dictionary using a partial street or firm name with a city/state and/or ZIP Code™ as input. No geocoding occurs when you browse, but you are able to view the list of possible candidates. To browse an address, use MapMarker JavaAPI.GEOCODE_TYPE_BROWSE in the call. The candidates returned will be in the form of a UserCandidateAddress object, which will hold the street name information.

/* Input address example */

MapMarker USA 31 Developer Guide 80 Using the MapMarker Java API

USA_UserInputAddress inpAddr = new USA_UserInputAddress (); inpAddr.setStreet("G"); inpAddr.setZipcode("12180"); If you are using the MapMarker Generic API, use the AddressImpl class.

AddressImpl inpAddr = new AddressImpl(); inpAddr.setMainAddress("G"); inpAddr.setPostCode1("12180"); inpAddr.setCountry("USA"); To browse, use the method of the MMJEngine class as shown in this example. This class is used for browsing with either the MapMarker MapMarker Java API or the MapMarker Generic Java API.

/* Browse Address */ MMJEngine engine = new MMJEngine(); ClientGeocodeResponse geoRes = null; geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_BROWSE, inpAddr, geoCon); All of the streets that begin with the letter G in the ZIP Code 12180 will be returned. You can use the USA_UserCandidateRange to obtain detailed candidate information.

/* Get candidate count */ int candCount = geoRes.candidateCount(); /* * Get returned candidates */ if (candCount > 0) { for (int i=0; i < candCount; i++) { /*Get candidate information */ USA_UserCandidateAddress candAddr = new USA_UserCandidateAddress(geoRes.candidateAt(i)); System.out.println("Candidate") } }

Geocoding To Postal Centroids

The MapMarker USA API enables you to geocode records to postal centroids. To geocode your records to a postal centroid, use MapMarkerJavaAPI.GEOCODE_TYPE_POSTAL_CENTROID.

/* Input address example */

USA_UserInputAddress inpAddr = new USA_UserInputAddress (); inpAddr.setZipcode("63401"); inpAddr.setState("MO"); If you were using the MapMarker Generic API, use the AddressImpl class.

AddressImpl inpAddr = new AddressImpl(); inpAddr.setAreaName3("Hannibal"); inpAddr.setPostCode1("63401"); inpAddr.setCountry("USA");

MapMarker USA 31 Developer Guide 81 Using the MapMarker Java API

To geocode, use the geocode method of the MMJEngine class as shown in this example. This class is used for geocoding with either the MapMarker USA Java API or the MapMarker Generic Java API.

/* Geocode Address */ MMJEngine engine = new MMJEngine(); ClientGeocodeResponse geoRes = null; geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_POSTAL_CENTROID, inpAddr, geoCon); You can also specify a preference to fallback to postal centroid if a close match could not be made to a street-level geocode.

/*Set Fallback to Postal */ USA_GeocodeConstraints geoCon = new USA_GeocodeConstraints(); setFallbackToPostal(true) geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS, inpAddr, geoCon); After geocoding, you can use the USA_UserCandidateAddress to obtain detailed candidate information.

/* Get candidate count */ int candCount = geoRes.candidateCount();

/* Get returned candidates*/ if (candCount > 0) { for (int i=0; i < candCount; i++) { /*Get candidate information */ USA_UserCandidateAddress candAddr = new USA_UserCandidateAddress(geoRes.candidateAt(i)); } }

Geocoding to Geographic Centroids

The MapMarker USA API enables you to geocode records to geographic centroids. To geocode your records to a geographic centroid, use MapMarkerJavaAPI.GEOCODE_TYPE_GEOGRAPHIC_CENTROID.

/* Input address example */

USA_UserInputAddress inpAddr = new USA_UserInputAddress (); inpAddr.setCity("Hannibal"); inpAddr.setState("MO"); If you were using the MapMarker Generic API, use the AddressImpl class.

AddressImpl inpAddr = new AddressImpl(); inpAddr.setAreaName3("Hannibal"); inpAddr.setAreaName1("MO"); inpAddr.setCountry("USA");

MapMarker USA 31 Developer Guide 82 Using the MapMarker Java API

To geocode, use the geocode method of the MMJEngine class as shown in this example. This class is used for geocoding with either the MapMarker USA Java API or the MapMarker Generic Java API.

/* Geocode Address */ MMJEngine engine = new MMJEngine(); ClientGeocodeResponse geoRes = null; geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_GEOGRAPHIC_CENTROID, inpAddr, geoCon); You can also specify a preference to fallback to geographic centroid if a close match could not be made to a street-level geocode.

/*Set Fallback to Geographic */ USA_GeocodeConstraints geoCon = new USA_GeocodeConstraints(); setFallbackToGeographic(true) geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS, inpAddr, geoCon); After geocoding, you can use the USA_UserCandidateAddress to obtain detailed candidate information.

/* Get candidate count */ int candCount = geoRes.candidateCount();

/* Get returned candidates*/ if (candCount > 0) { for (int i=0; i < candCount; i++) { /*Get candidate information */ USA_UserCandidateAddress candAddr = new USA_UserCandidateAddress(geoRes.candidateAt(i)); } } Geographic centroid candidates may contain values for areaNames 1-3 (state, county, city), census block, rank, and location. The corresponding georesult codes are: G1 (state), G2 (county), and G3 (city). For deciding close matches, preference is given to the candidate in which the spelling of the city is closer to the input address. If more than one geographic area with the same name exists (for example, Springfield, VA exists in eight counties), preference is given to the higher ranking city. The rank of the city is determined from the source data. Each record is ranked from 1 to 7, with 1 being the most populous/important cities. A rank of 7 indicates a neighborhood level geographic area ("South Troy NY"). If two close candidates are compared, the one with the lower-numbered rank (bigger city) is kept as a close match and the other candidate is demoted to a non-close match.

MapMarker USA 31 Developer Guide 83 Using the MapMarker Java API

Geocoding to Highway Exits

Geocoding to highway exits using the MapMarker Java API returns candidates that are geocoded to ZIP Code™ centroid accuracy. You must supply the highway exit information, and the state abbreviation. This input information is put into an InputAddress object. It is parsed into two fields: • mainAddress field–holds the highway exit information. • state field–holds the state abbreviation. To geocode a highway exit, use MapMarkerJavaAPI.GEOCODE_TYPE_HIGHWAY_EXITS

/* Input address example */

USA_UserInputAddress inpAddr = new USA_UserInputAddress (); inpAddr.setStreet("I-90 Exit 8"); inpAddr.setState("NY"); If you were using the MapMarker Generic API, use the AddressImpl class.

AddressImpl inpAddr = new AddressImpl(); inpAddr.setMainAddress("I-90 Exit 8"); inpAddr.setAreaName1("NY"); inpAddr.setCountry("USA"); To geocode, use the geocode method of the MMJEngine class as shown in this example. This class is used for geocoding with either the MapMarker USA Java API or the MapMarker Generic Java API.

/* Geocode Address */ MMJEngine engine = new MMJEngine(); ClientGeocodeResponse geoRes = null; geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_HIGHWAY_EXITS, inpAddr, geoCon); After geocoding, you can use the USA_HighwayExitCandidateAddress to obtain detailed candidate information.

/* Get candidate count */ int candCount = geoRes.candidateCount();

/* Get returned candidates*/ if (candCount > 0) { for (int i=0; i < candCount; i++) { /*Get candidate information */ USA_HighwayExitCandidateAddress candAddr = new USA_HighwayExitCandidateAddress (geoRes.candidateAt(i)); } }

MapMarker USA 31 Developer Guide 84 Using the MapMarker Java API

Geocoding to Airports

To geocode to airports, make sure that your application contains these import statements.

import com.mapinfo.mapmarker.USA.USA_UserAirportCandidateAddress; import com.mapinfo.mapmarker.USA.USA_CustomGeocoder;

Finding Airports by State If you want to find all of the airports in a given state use the geocoding type:

USA_CustomGeocoder.GEOCODE_TYPE_AIRPORTS_BY_STATE.

/* Input address example */ String state = "NY"; USA_UserInputAddress inpAddr = new USA_UserInputAddress ();

/* Set the input Address */ inpAddr.setState(state); /* State 'NY' */

If you were using the MapMarker Generic Java API, use the AddressImpl class.

AddressImpl inpAddr = new AddressImpl();

/* Set the input Address */ String country="USA" inpAddr.setAreaName1(state); /* state 'NY' */ inpAddr.setCountry(country); /* country 'USA' */ Use the geocode method of the MMJEngine class as shown in this example. This class is used for geocoding with either the MapMarker USA Java API or the MapMarker Generic Java API.

/* Geocode Address */ MMJEngine engine = new MMJEngine(); ClientGeocodeResponse geoRes = null; geoRes = engine.geocode(USA_CustomGeocoder.GEOCODE_TYPE_AIRPORTS_BY_STATE, inpAddr, geoCon); All of the known airports located in the specified state will be returned. You can use the USA_UserAirportCandidateAddress to obtain detailed candidate information.

/* Get candidate count */ int candCount = geoRes.candidateCount(); /* * Get returned candidates */ if (candCount > 0) { for (int i=0; i < candCount; i++) { /*Get candidate information */ USA_UserAirportCandidateAddress candAddr = new USA_UserAirportCandidateAddress(geoRes.candidateAt(i)); } }

MapMarker USA 31 Developer Guide 85 Using the MapMarker Java API

Finding Airports by Code If you want to find a specific airport then use the geocoding type:

USA_CustomGeocoder.GEOCODE_TYPE_AIRPORTS_BY_CODE

/* Input address example */ String code = "ALB"; USA_UserInputAddress inpAddr = new USA_UserInputAddress ();

/* Set the input Address */ inpAddr.setStreet(code); /* Code 'ALB' */ If you were using the MapMarker Generic API, use the AddressImpl class.

AddressImpl inpAddr = new AddressImpl();

/* Set the input Address */ String country="USA" inpAddr.setMainAddress(code); /* code 'ALB' */ inpAddr.setCountry(country); /* country 'USA' */ Use the geocode method of the MMJEngine class as shown in this example. This class is used for geocoding with either the MapMarker USA Java API or the MapMarker Generic Java API.

/* Geocode Address */ MMJEngine engine = new MMJEngine(); ClientGeocodeResponse geoRes = null; geoRes = engine.geocode(USA_CustomGeocoder.GEOCODE_TYPE_AIRPORTS_BY_CODE, inpAddr, geoCon); The airport that matches the input code will be returned. You can use the USA_UserAirportCandidateAddress to obtain detailed candidate information.

USA_UserAirportCandidateAddress candAddr = new USA_UserAirportCandidateAddress(geoRes.candidateAt(0));

DPV Related Actions

The MapMarker USA API enables you to determine DPV® usability, status, and expiration. To obtain detailed information on DPV status (including usability and expiration date) geocode using the following custom geocode type:

USA_CustomGeocoder.GEOCODE_TYPE_DPV_STATUS The value is:

MapMarkerJavaAPI.GEOCODE_TYPE_CUSTOM_BASE+108

MapMarker USA 31 Developer Guide 86 Using the MapMarker Java API

To get the DPV® information, geocode using the custom type. The information is returned in the candidate addresses found in the response. The results are returned as strings using the following candidate methods.

Status code getGenericField1()

Description Message getGenericField2()

Expiration Date getGenericField3()

If referencing from a USA user candidate, the following methods can be used instead of the genericField# methods.

DPV Status code getDPVStatusCode()

DPV Description getDPVStatusMsg() Message

DPV Expiration Date getDPVExpDate()

Getting DPV Status The following sample code shows how to use the USA custom geocoding API.

/* Get DPV status (presence), status (usability), and expiration */

USA_Constraints usa_prefs = new USA_Constraints(); USA_UserInputAddress usaAddr = new USA_UserInputAddress(); MMJEngine engine = new MMJEngine(); ClientGeocodeResponse resp = engine.geocode(USA_CustomGeocoder.GEOCODE_TYPE_DPV_STATUS, usaAddr, usa_prefs); if (resp.totalPossibleCloseMatchCandidates() > 0) { CandidateAddress cand = resp.candidateAt(0); USA_UserCandidateAddress usaCand = new USA_UserCandidateAddress(cand); String statusCodeString = usaCand.getDPVStatusCode(); String messageString = usaCand.getDPVStatusMsg(); String expirationDate = usaCand.getDPVExpDate(); } If you are using the MapMarker Generic API, use the AddressImpl class. In this case, the country must be set in the input address. The following sample code shows generic use of the API (without USA references).

Generic use (Not using USA references)

GeocodeConstraints constraints = new GeocodeConstraints (); Address addr = new AddressImpl(); MMJEngine engine = new MMJEngine(); addr.setCountry("USA"); ClientGeocodeResponse resp = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_CUSTOM_BASE+108, addr, constraints);

MapMarker USA 31 Developer Guide 87 Using the MapMarker Java API

if (resp.totalPossibleCloseMatchCandidates() > 0) { CandidateAddress cand = resp.candidateAt(0); String statusCodeString = cand.getGenericField1(); String messageString = cand.getGenericField2(); String expirationDate = cand.getGenericField3(); } The status is returned in CandidateAddress, which contains the following information:

Status Code Message Returned

0 DPV® is enabled and usable

100 No DPV history file present

101 DPV files not present

102 DPV is not enabled

103 DPV data has expired

Returning Match Codes and Location Codes

You can return the detailed match codes and location codes for candidates. Match codes indicate the parts of the address that were matched (or what address parts were changed to achieve the match). Location codes indicate the locational accuracy of the assigned geocode. Note that an accurately placed candidate is not necessarily an ideal candidate. Examine the match codes and location codes in addition to result codes to best evaluate the overall quality of the candidate. For complete coverage of See Match Codes and Location Codes in Appendix E on page 161 for complete coverage of match codes and location codes and examples of how to use these codes to evaluate overall candidate quality. The results can be returned using the getAdditionalFieldForKey method of the USA_UserCandidateAddress class. (com.mapinfo.mapmarker.USA_UserCandidateAddress) For example, to get match codes:

cand.getAdditionalFieldForKey(USA_CandidateConstants.USA_MATCH_CODE) Or:

cand.getAdditionalFieldForKey("USA_MATCH_CODE") Similarly, you can get the location codes with the USA_LOCATION_CODE constant or string. You can also get Match Codes and Location Codes using the getMatchCode and getLocationCode methods of the USA_UserCandidateAddress class.

MapMarker USA 31 Developer Guide 88 Using the MapMarker Java API

For example, to get match codes and location codes:

String matchcode = cand.getMatchCode(); String loccode = cand.getLocationCode();

Standardizing Addresses

The MapMarker USA API enables you to standardize input addresses according to the format expected by MapMarker. You can potentially use this to create consistently formatted input addresses (regardless of whether those addresses are valid or can be successfully geocoded). Note: It is important to note that GEOCODE_TYPE_STANDARDIZE does not validate or cleanse addresses in any way; it simply returns input addresses in a uniformly standard format. It also does not geocode addresses. Remember the following guidelines if you use address standardization: • You must return the individual address fields to see the standardized output. For example, use getAddressNumber, getStreet, getCity, getZipcode, and getState. Returned formatted addresses are not standardized, but are returned exactly as input. • Misspellings in street name, type, City, and State are not corrected. For example, an input address of: One Glbal View (2 LINES) Troy, NY 12180 is standardized to “1 GLBAL VW, TROY, NY, 12180”. The misspelled street name “Glbal.” is not corrected.

• Omitted pieces of the input address are not populated in the output. For example, an input address of: One Global View NY, 12180 Is standardized to “1 GLOBAL VW, NY, 12180”, but the missing “TROY” is not added as the city name.

• Invalid pieces of the input address (such as wrong city name or wrong postal code) are not corrected. For example, the input address of: 1 Global View Troy, NY 12198; has an incorrect input postal code of 12198 and this same incorrect postal code is returned. Similarly, incorrect house numbers, street names, or directionals are not corrected or standardized.

• Other miscellaneous errors in the input address may not be corrected. For example, if the address is input as: 1 Global Veiw

MapMarker USA 31 Developer Guide 89 Using the MapMarker Java API

Troy. NY 12180 the misspelled street type “Veiw” is not recognized and is neither corrected nor standardized. The incorrect spelling of VEIW is returned as part of the street name.

Creating a Web Geocoding Client in Java

If you have deployed MapMarker USA as a servlet, you need to develop a web client application to send geocoding requests to the server. Follow all of the steps under Developing Geocoding Applications in Java on page 53, except use the MMJClient class instead of the MMJEngine class. The MMJClient geocode method requires the URL of the servlet.

/* Geocode Address */ String url = "http://localhost:8095/mapmarker40/servlet/mapmarker"); MMJClient m_client; ClientGeocodeResponse geoRes = m_client.geocode(0,inpAddr, geoCon, url); /* Change the host and port in the url to reflect your host and port */ Note: The default Tomcat server port number for MapMarker USA is 8095.

/* Geocode Address */ String url = new String("http://localhost:8095/mapmarker40/servlet/mapmarker"); MMJClient m_client; ClientGeocodeResponse geoRes = m_client.geocode (MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS,inpAddr, geoCon, url);/* Change the host and port in the url to reflect your host and port */ Make sure that your application contains the import statements described in Setting Import Statements on page 54.

MapMarker USA 31 Developer Guide 90 5 5 – Using the REST API

MapMarker USA 31 provides a REST (Representational State Transfer) API. REST is a lightweight client/server architecture that allows you to easily send and receive geocoding requests and responses via HTTP.

In this chapter:

REST API Framework and Syntax 92 Usage Guidelines 99 REST API Examples 101 Using the REST API

REST API Framework and Syntax

The REST API has a simple syntax that allows you to send any supported geocoding request and return candidates as XML or JSON format. The REST API is accessed by calling the server and passing parameters as part of a URL query. Geocoding Types and Subtypes Input Parameters Geocoding Constraints USA Geocoding Constraints Response Formats See also Usage Guidelines.

Geocoding Types and Subtypes Standard geocoding and reverse geocoding are supported. The following table summarizes the geocoding request types. The geocoding types are not case sensitive.

Geocoding Request Types

Geocode Type Description

GeocodeRequest Standard geocode request based on supplied address information. This is the default if no geocode type is specified in the URL request.

ReverseGeocode Geocode based on supplied X/Y coordinates.

Note: Reverse geocoding is available with the Developer (Server) edition and API, but not with the Desktop application. Reverse geocoding is not available with User Dictionaries. Reverse geocoding is a separately licensed feature and must be covered in your license agreement. In the request URL, the geocoding type is sent as:

type=[GeocodeRequest] [ReverseGeocode] The following geocoding subtypes apply to standard geocoding (GeocodeRequest). The ReverseGeocode type uses the 0 subtype only.

MapMarker USA 31 Developer Guide 92 Using the REST API

Geocoding Subtypes

Subtype Number Description

0 Street level geocode. This is the default if no geocode subtype is specified in the URL request.

1 Postal geocode

4 Geographic geocode

5 Standardize street address without geocoding

6 Browse without geocoding

In the request URL, the geocoding subtype is sent as:

subtype=# (where # is one of the above subtype numbers) For example, in the request URL postal geocoding is requested as:

type=GeocodeRequest&subtype=1 type= could be omitted, since GeocodeRequest is the default action

Input Parameters REST API requests use the following input parameters. The parameter names must be spelled correctly but they are not case sensitive.

MapMarker USA 31 Developer Guide 93 Using the REST API

Input Parameters

Parameter Description Used With Geocode Type Example

ctry country GeocodeRequest and ctry=USA ReverseGeocode. The country is required for all queries. You can specify the full country name or the country ISO country code at the beginning or end of single- line input or in the PostAddress of dual-line input. This will be used if the ctry= is not specified. However, if the ctry= input parameter is specified, that country name will be used.

str mainAddress GeocodeRequest str=5723+143+St+NW (single-line input is also passed here)

plc placeName GeocodeRequest plc=Museum of Natural History

code postcode1 GeocodeRequest code=12180

a1 areaName1 GeocodeRequest a1=NY

a2 areaName2 GeocodeRequest a2=Rensselaer

a3 areaName3 GeocodeRequest a3=Troy

a4 areaName4 GeocodeRequest a4=Urb Rio Plantation (used for Puerto Rico urbanizations only)

lastLine postAddress GeocodeRequest lastLine=Troy+NY+12180

gen1 generic field 1 GeocodeRequest used for AddressLine2 on input

gen2 generic field 2 GeocodeRequest not used

gen3 generic field 3 GeocodeRequest not used

gen4 generic field 4 GeocodeRequest not used

MapMarker USA 31 Developer Guide 94 Using the REST API

Input Parameters (Continued)

Parameter Description Used With Geocode Type Example

x the x value ReverseGeocode x= -73.699899 (longitude) of the point to reverse geocode

y the y value ReverseGeocode y=42.682433 (latitude) of the point to reverse geocode

d the distance ReverseGeocode d=10 value to limit the reverse geocode to.

unit the linear unit ReverseGeocode unit=m abbreviation that goes with 'd'.

Geocoding Constraints The following table summarizes the geocoding constraints that can be applied to the REST API geocoding request. The constraint names must be spelled correctly but they are not case sensitive.

Geocoding Constraints

Used with Geocode Constraint Description Type Example

mxCan Specifies the maximum number of GeocodeRequest mxCan=3 CandidateAddresses to return. Does not affect Browse. Default is 3.

close If true, only close match GeocodeRequest close=false CandidateAddresses will be returned. Default is false.

fbp If true, fallback to postal. Default is GeocodeRequest fpb=true false.

MapMarker USA 31 Developer Guide 95 Using the REST API

Geocoding Constraints (Continued)

Used with Geocode Constraint Description Type Example

fbg If true, fallback to geographic. GeocodeRequest fbg=true Default is false.

apIntrp If true, address point interpolation GeocodeRequest apIntrp=true will be used. Default is false.

centerline If true centerline offset will be used. GeocodeRequest centerline=false Default is false.

mode Specifies the match mode to use. GeocodeRequest mode=ExactMode (Default, Exact, Relaxed, CASS). If mode=RelaxedM mode is set, the Must Match ode constraints (mmA#) are ignored. mode=DefaultMo de mode=CASS_MO DE

dictPref Controls whether Address GeocodeRequest dictPref=AD_ONL Dictionary and/or User Dictionary Y candidates are preferred. Values are: AD_ONLY UD_ONLY PREFER_AD PREFER_UD AD_AND_UD) Default is AD_AND_UD (if UD is configured)

mmNum If true, must match address number GeocodeRequest mmNum=false

mmStr If true, must match mainAddress. GeocodeRequest mmStr=true Default is false.

mmA1 If true, must match areaName1. GeocodeRequest mmA1=false Default is false.

mmA2 If true, must match areaName2. GeocodeRequest mmA2=true Default is false.

MapMarker USA 31 Developer Guide 96 Using the REST API

Geocoding Constraints (Continued)

Used with Geocode Constraint Description Type Example

mmA3 If true, must match areaName3. GeocodeRequest mmA3=true Default is false.

mmA4 If true, must match areaName4. GeocodeRequest mmA4=true (used Default is false. for Puerto Rico addresses only).

mmCode If true, must match postcode1. GeocodeRequest mmCode=true Default is false.

mxRng Specifies the maximum number of GeocodeRequest mxRng=5 CandidateRanges to return on each CandidateAddress

mxUnit Specifies the maximum number of GeocodeRequest mxUnit=5 CandidateRangeUnits to return for and each range. ReverseGeocode

prj Specifies the coordinate system to, GeocodeRequest prj=epsg:4269 return points in. For reverse and this is NAD 83. geocoding, specifies the coordinate ReverseGeocode Encoded as system of the input X/Y points. epsg%3A4269

offsetValu Specifies the distance value for GeocodeRequest offsetValue=3 e corner offset, street offset, and if and selected, centerline offset. ReverseGeocode

offsetUnit Specifies the linear unit GeocodeRequest offsetUnits=m s abbreviation for the offsetValue. and ReverseGeocode

USA Geocoding Constraints The following table summarizes the USA-specific geocoding constraints that can be applied to the REST API geocoding request. The constraint names must be spelled correctly but they are not case sensitive.

MapMarker USA 31 Developer Guide 97 Using the REST API

USA Geocoding Constraints

Used with Constraint Description Geocode Type Example

searchLev SEARCH_LEVEL_EXPANDE GeocodeRequ searchLevel= el D Enables the expanded est SEARCH_LEVEL_EXPA search feature, which allows NDED MapMarker to search for searchLevel=SEARCH_L candidates within a given EVEL radius of the input address. _FINANCE_AREA False by default. searchLevel=SEARCH_L SEARCH_LEVEL_FINANCE_ EVEL AREA Search the entire _CITY finance area for possible streets. This is enabled by default for CASS mode, otherwise disabled by default. SEARCH_LEVEL_CITY Limit the search to streets within the specified city. This is enabled by default for Relaxed, Exact, or Default Modes.

expRadius If expanded search is enabled, GeocodeRequ expRadius=10 search a given radius (0 - 127 est miles) of the input address. Default is 25.

expState If expanded search is enabled, GeocodeRequ expState=false limit the expanded search to est the same state of the input address, regardless of the mile radius. True by default if expanded search is enabled.

wideSearc Considers all streets that begin GeocodeRequ widesearch=true h with the first letter of the input est street name False by default.

zipOverCit Prefer a ZIP Code match over GeocodeRequ zipOverCity=true y a city match. False by default. est

DPV Use Delivery Point Validation GeocodeRequ DPV=true (DPV) to verify whether an est address is a valid USPS delivery point. False by default.

MapMarker USA 31 Developer Guide 98 Using the REST API

USA Geocoding Constraints

Used with Constraint Description Geocode Type Example

LACSLink Use Locatable Address GeocodeRequ LACSLink=true Conversion System (LACS) to est convert convert rural style addresses into locatable to street-style addresses, typically for 911 emergency services. False by default.

suiteLink Provides suite numbers for GeocodeRequ suiteLink=true businesses located in high-rise est buildings. False by default.

Response Formats The REST API can return results in the XML or JSON formats. This is controlled by the format parameter (format=xml or format=json). The default response format is XML.

Response Formats

Format Parameter Description

xml Returns the response as XML. This uses the same format as used by the MapMarker client/server XML API. If the response format type is not specified in the URL request, the default is XML.

json Returns the response as a JSON object stream.

Usage Guidelines

The following topics summarize usage guidelines for the REST API. Sending Input via the API Character Encoding Match Modes and Must Match Constraints Using Server Side Constraints

Sending Input via the API The REST API is accessed by calling the server and passing parameters as part of a URL query. The format is:

MapMarker USA 31 Developer Guide 99 Using the REST API

http://server:port/mapmarker40/servlet/mapmarker? For example, the following represents a street geocoding request for 2600 Lake Austin Blvd, Apt 10108, Austin TX:

url=http://localhost:8095/mapmarker40/servlet/mapmarker?str=2600+Lake+Austin+Blvd +Apt.+10108&a3=Austin&a1=TX&code=78703&ctry=USA&close=true&format=xml&type=Geocod eRequest&subType=0 Note that the default startup port for MapMarker USA is 8095. In this example, the format, type, and subtype parameters are not required because they are the same as the default values (format=xml, type=GeocodeRequest, subtype=0). The space character is sent as a plus sign(+), consistent with HTML conventions. Close matches only are returned (close=true). This geocodes the American address:

2600 Lake Austin Blvd. Apartment 10108 Austin, Texas 78703 and returns the XML formatted candidates.

Character Encoding The REST API treats queries as UTF-8 encoded. The following alphanumeric characters are unchanged by UTF-8 encoding:

a through z A through Z 0 through 9 The following punctuation characters are also unchanged by UTF-8 encoding:

. , - * _ All other characters are first converted into one or more bytes using an encoding scheme. Then each byte is represented by the 3-character string "%xy", where xy is the two-digit hexadecimal representation of the byte. UTF-8 encoding is recommended, but if an encoding is not specified, then the default encoding of the platform is used for compatibility purposes. For example, consider the following input string: CALLE 8 BLOQUE 16 #5", BAYAMON, PR, 00961, URB RIO PLANTATION

street, city, state, zip, urbanization

After UTF-8 conversion, this string is:

CALLE%208%20BLOQUE%2016%20%235%22%2C%20BAYAMON%2C%20PR%20%2C%2000961%2C%20URB%20R IO%20PLANTATION

MapMarker USA 31 Developer Guide 100 Using the REST API

Match Modes and Must Match Constraints If you set a Match Mode (either DefaultMode, ExactMode, or RelaxedMode), then Must Match constraints are ignored. For example, if Relaxed Mode is set on server side or sent via the client API, a Must Match constraint sent from the client will be ignored and the Match Mode will be used. If no Match Mode is specified, then Must Match constraints are enforced. If you set neither a Match Mode nor any Must Match constraints, then only the country must be matched.

Using Server Side Constraints You can set constraints on the server if you routinely want to use certain constraints. For example, if you always want to require match on address number, you can set that requirement on the server. In that way, you will not have to repeatedly send “mmNum=true” with the API request. If you do not set constraints on the server, then you should explicitly send all constraints with each API request. You also can override server-side settings with constraints sent from the client via the API.

REST API Examples

Several REST API examples illustrate the API usage and returns. Typical Street Geocode Street Geocode with Must Match Constraints Street Geocoding with PlaceName Street Geocode with Match Mode Street Geocode with Search Level Constraint Street Geocode with Range and Unit Constraints Postal Geocode Geographic Geocode Reverse Geocode

XML Examples This section includes several examples to demonstrate the input and resulting XML output from the REST API.

MapMarker USA 31 Developer Guide 101 Using the REST API

The output includes result codes, match codes, and location codes that indicate details about the quality of the match, what parts of the address were matched, the locational accuracy.

Typical Street Geocode This is a typical street geocoding example:

10592 Wilkins Ave Los Angeles CA The following constraints are used: two maximum candidates (mxCan=2) and three maximum ranges per candidate (mxRng=3). The URL is sent as:

http://localhost:8095/mapmarker40/servlet/mapmarker?str=10592%20Wilkins%20Ave&a3= Los%20Angeles&a1=CA&ctry=USA&mxCan=2 Two candidates are returned (mxCan =2); one candidate close, the other is non-close. The following code shows a portion of the returned XML for the close match candidate (S5 result code).

-

- - GEOSTAN_POINT_ID 117880449 - GEOSTAN_SEGMENT_DIRECTION F - USA_SHORT_CITYNAME LOS ANGELES - USA_MATCH_CODE S90 - USA_LOCATION_CODE AP05 - CARRIER_ROUTE C041 - GEOSTAN_DATA_TYPE 7 - GEOSTAN_COUNTY_CODE 06037 - GEOSTAN_CBSA_DIVISION_NAME LOS ANGELES-LONG BEACH-GLENDALE, CA METROPOLITAN DIVISION

MapMarker USA 31 Developer Guide 102 Using the REST API

- CENSUS_BLOCK 060372656011004 - GEOSTAN_PREFERRED_CITY_NAME LOS ANGELES - GEOSTAN_CBSA_NAME LOS ANGELES-LONG BEACH-SANTA ANA, CA METROPOLITAN STATISTICAL AREA - USA_LOCATION_CODE AP05 - GEOSTAN_LOT_CODE D - CHECK_DIGIT 2 - GEOSTAN_CITY_CODE 060527001 - GEOSTAN_ALIAS_TYPE N01 - RESULT_CODE S8HPNTSCZA - GEOSTAN_CBSA_NUMBER 31100 - GEOSTAN_LOT_NUMBER 0006 - GEOSTAN_CBSA_DIVISION 31084 - GEOSTAN_CSA_NUMBER 348 - USA_SHORT_ADDRESSLINE 10592 WILKINS AVE - DELIVERY_POINT

MapMarker USA 31 Developer Guide 103 Using the REST API

92 - GEOSTAN_METRO_FLAG Y - USA_SHORT_STREETNAME WILKINS - REC_TYPE S - SEGMENT_ID 14502746 - USA_DB_TYPE 7 - GEOSTAN_ADDRESS_LINE1 10592 WILKINS AVE - GEOSTAN_STREET_SIDE L - GEOSTAN_CSA_NAME LOS ANGELES-LONG BEACH-RIVERSIDE, CA COMBINED STATISTICAL AREA - USA_SHORT_STREETTYPE AVE - USA_MATCH_CODE S90 10592 CA LOS ANGELES COUNTY LOS ANGELES USA WILKINS 90024 6033 AVE

- - -118.43111 34.057111 0

MapMarker USA 31 Developer Guide 104 Using the REST API

Street Geocode with Must Match Constraints Consider the following example, in which the city of Albuquerque is misspelled as Albaquerque.

200 Alameda Blvd NW Albaquerque NM The must match city constraint is used (mmA3). The URL is sent as:

hhttp://localhost:8095/mapmarker40/servlet/mapmarker?str=200%20Alameda%20Blvd%20N W%20Albaquerque%20NM&mmA3=true&ctry=usa This does not return a close match street candidate because Must Match on AreaName3 is required and Albuquerque is spelled incorrectly. If the mmA3 constraint is omitted, the close match candidate is returned.

The following non-close match is returned:

-

- - RESULT_CODE S5HPNTS-ZA - GEOSTAN_CBSA_NAME ALBUQUERQUE, NM METROPOLITAN STATISTICAL AREA - USA_LOCATION_CODE AS0 - GEOSTAN_CBSA_NUMBER 10740 - GEOSTAN_METRO_FLAG Y - GEOSTAN_CITY_CODE 350002000 - USA_SHORT_STREETTYPE BLVD - USA_LOCATION_CODE AS0 - GEOSTAN_ALIAS_TYPE N01 - USA_MATCH_CODE

MapMarker USA 31 Developer Guide 105 Using the REST API

TB0 - GEOSTAN_DATA_TYPE 2 - USA_SHORT_ADDRESSLINE 200 ALAMEDA BLVD NW - USA_SHORT_STREETNAME ALAMEDA - USA_DB_TYPE 2 - GEOSTAN_ADDRESS_LINE1 200 ALAMEDA BLVD NW - REC_TYPE T - GEOSTAN_SEGMENT_DIRECTION F - GEOSTAN_STREET_SIDE L - GEOSTAN_COUNTY_CODE 35001 - GEOSTAN_PREFERRED_CITY_NAME ALBUQUERQUE - CENSUS_BLOCK 350010036004007 - SEGMENT_ID 44112 - USA_MATCH_CODE TB0 - USA_SHORT_POSTDIR NW - USA_SHORT_CITYNAME

MapMarker USA 31 Developer Guide 106 Using the REST API

ALBUQUERQUE 200 NM BERNALILLO COUNTY ALBUQUERQUE USA ALAMEDA 87114 NW BLVD

- - -106.614069 35.188054 0

Street Geocode with Fallback to Postal Consider the following example, which includes a street address and postal code. In this example, the input house number (140) is incorrect.

449 Adams St Westborough, MA 01581 The must match house number constraint is used (mmNum=true) and fallback to postal is allowed (fbp=true). The URL is sent as:

http://localhost:8095/mapmarker40/servlet/mapmarker? str=449%20Adams%20St&a3=Westborough&a1=MA&code=01581&mmNum=true&fbp=true&ctry=USA This does not return a close match street candidate because Must Match on House Number is required (and the input house number is incorrect). However, a close match postal fallback candidate is returned. The following portion of the returned XML shows the Z1 close match.

-

- - CENSUS_BLOCK 25027 - RESULT_CODE Z1 - USA_MATCH_CODE Z0 - USA_LOCATION_CODE ZC5X

MapMarker USA 31 Developer Guide 107 Using the REST API

- USA_LOCATION_CODE ZC5X - USA_MATCH_CODE Z0 - GEOSTAN_COUNTY_CODE 25027 MA WORCESTER COUNTY WESTBOROUGH USA 01581

- - -71.6118 42.2702 0

Street Geocoding with PlaceName The following example includes a street name (without number), City, and PlaceName as input.

Museum of Natural History New York 10022 After encoding, the URL is sent as:

http://localhost:8095/mapmarker40/servlet/mapmarker?plc=Museum%20of%20Natural%20H istory&a3=New%20York&code=10022&ctry=USA&close=true The following portion of the returned XML shows the returned close match candidate (S5 result code). Note that the street address was not provided on input and the postcode was incorrect. This information is added and corrected in the output.

... -

- - GEOSTAN_SEGMENT_DIRECTION R - USA_SHORT_CITYNAME NEW YORK - USA_MATCH_CODE ADB

MapMarker USA 31 Developer Guide 108 Using the REST API

- USA_LOCATION_CODE AS2 - CARRIER_ROUTE C053 - GEOSTAN_DATA_TYPE 2 - GEOSTAN_COUNTY_CODE 36061 - GEOSTAN_CBSA_DIVISION_NAME NEW YORK-WHITE PLAINS-WAYNE, NY-NJ METROPOLITAN DIVISION - CENSUS_BLOCK 360610165001001 - GEOSTAN_PREFERRED_CITY_NAME NEW YORK - GEOSTAN_CBSA_NAME NEW YORK-NORTHERN NEW JERSEY-LONG ISLAND, NY-NJ-PA METROPOLITAN STATISTICAL AREA - USA_LOCATION_CODE AS2 - GEOSTAN_LOT_CODE D - CHECK_DIGIT 9 - GEOSTAN_CITY_CODE 360922000 - GEOSTAN_ALIAS_TYPE A03 - RESULT_CODE S5H---SC-A - GEOSTAN_CBSA_NUMBER 35620

MapMarker USA 31 Developer Guide 109 Using the REST API

- GEOSTAN_LOT_NUMBER 0021 - GEOSTAN_CBSA_DIVISION 35644 - GEOSTAN_CSA_NUMBER 408 - USA_SHORT_ADDRESSLINE 15 W 77TH ST - USA_SHORT_PREDIR W - DELIVERY_POINT 15 - GEOSTAN_METRO_FLAG Y - USA_SHORT_STREETNAME 77TH - REC_TYPE F - SEGMENT_ID 4257609 - USA_DB_TYPE 2 - GEOSTAN_ADDRESS_LINE1 15 W 77TH ST - GEOSTAN_STREET_SIDE L - GEOSTAN_CSA_NAME NEW YORK-NEWARK-BRIDGEPORT, NY-NJ-CT-PA COMBINED STATISTICAL AREA - USA_SHORT_STREETTYPE ST

MapMarker USA 31 Developer Guide 110 Using the REST API

- USA_MATCH_CODE ADB 15 NY NEW YORK COUNTY NEW YORK USA 77TH MUSEUM OF NATURAL HISTORY 10024 5193 ST W

- - -73.97479 40.78007 0

Street Geocode with Match Mode Consider the following example. The mmCode (must match postcode) constraint is set and the DefaultMode constraint is also set. After encoding, the URL is sent as:

http://localhost:8095/mapmarker40/servlet/mapmarker?str=1%20Global%20Vw &lastline=Troy%20NY%2012181&mmCode=true&ctry=usa&mode=DefaultMode The mmCode=true constraint would normally prevent a close match return because the postcode is entered incorrectly (12181 instead of the correct 12180). However, the DefaultMode constraint overrides the must match criteria and a close match is returned. The following portion of the returned XML shows the returned close match.

- - RESULT_CODE S5HPNTSC-A - GEOSTAN_CBSA_NAME ALBANY-SCHENECTADY-TROY, NY METROPOLITAN STATISTICAL AREA - USA_LOCATION_CODE AS0 - GEOSTAN_METRO_FLAG Y - GEOSTAN_CBSA_NUMBER

MapMarker USA 31 Developer Guide 111 Using the REST API

10580 - GEOSTAN_CITY_CODE 361322000 - GEOSTAN_LOT_CODE A - GEOSTAN_CSA_NUMBER 104 - CHECK_DIGIT 8 - DELIVERY_POINT 01 - USA_SHORT_STREETTYPE VW - USA_LOCATION_CODE AS0 - GEOSTAN_ALIAS_TYPE N01 - GEOSTAN_CSA_NAME ALBANY-SCHENECTADY-AMSTERDAM, NY COMBINED STATISTICAL AREA - USA_MATCH_CODE S90 - GEOSTAN_DATA_TYPE 2 - USA_SHORT_ADDRESSLINE 1 GLOBAL VW - USA_SHORT_STREETNAME GLOBAL - USA_DB_TYPE 2 - GEOSTAN_ADDRESS_LINE1

MapMarker USA 31 Developer Guide 112 Using the REST API

1 GLOBAL VW - GEOSTAN_LOT_NUMBER 0001 - CARRIER_ROUTE C099 - REC_TYPE S - GEOSTAN_SEGMENT_DIRECTION F - GEOSTAN_STREET_SIDE L - GEOSTAN_COUNTY_CODE 36083 - GEOSTAN_PREFERRED_CITY_NAME TROY - CENSUS_BLOCK 360830523018010 - SEGMENT_ID 856929 - USA_MATCH_CODE S90 - USA_SHORT_CITYNAME TROY 1 NY RENSSELAER COUNTY TROY USA GLOBAL 12180 8371 VW

- - -73.702914

MapMarker USA 31 Developer Guide 113 Using the REST API

42.682858 Note: Similarly, other match modes (including CASS Mode) override any must match criteria. Street Geocode with Search Level Constraint The following example shows the results of using the USA Search Level constraint for Finance Area. Plus signs designate spaces in the URL and the URL is sent as:

http://localhost:8095/mapmarker40/servlet/mapmarker?str=1217+Cleveland+ Ave&a3=La+Grange&a1=IL&ctry=USA&searchlevel=SEARCH_LEVEL_FINANCE_AREA The city was input inaccurately as La Grange. The correct city name is La Grange Pk. Because of this error, a close match would not typically be returned. However, the searchlevel constraint broadens the search to include he entire finance area and returns the following close match:

-

- - RESULT_CODE S5HPNTS-ZA - GEOSTAN_CBSA_NAME CHICAGO-JOLIET-NAPERVILLE, IL-IN-WI METROPOLITAN STATISTICAL AREA - USA_LOCATION_CODE AS0 - GEOSTAN_METRO_FLAG Y - GEOSTAN_CBSA_NUMBER 16980 - GEOSTAN_CITY_CODE 170576001 - GEOSTAN_CBSA_DIVISION 16974 - GEOSTAN_LOT_CODE A - GEOSTAN_CSA_NUMBER 176 - CHECK_DIGIT

MapMarker USA 31 Developer Guide 114 Using the REST API

4 - DELIVERY_POINT 17 - USA_SHORT_STREETTYPE AVE - USA_LOCATION_CODE AS0 - GEOSTAN_CBSA_DIVISION_NAME CHICAGO-JOLIET-NAPERVILLE, IL METROPOLITAN DIVISION - GEOSTAN_ALIAS_TYPE N01 - GEOSTAN_CSA_NAME CHICAGO-NAPERVILLE-MICHIGAN CITY, IL-IN-WI COMBINED STATISTICAL AREA - USA_MATCH_CODE SB0 - GEOSTAN_DATA_TYPE 2 - USA_SHORT_ADDRESSLINE 1217 CLEVELAND AVE - USA_SHORT_STREETNAME CLEVELAND - USA_DB_TYPE 2 - GEOSTAN_ADDRESS_LINE1 1217 CLEVELAND AVE - GEOSTAN_LOT_NUMBER 0033 - CARRIER_ROUTE C005 -

MapMarker USA 31 Developer Guide 115 Using the REST API

REC_TYPE S - GEOSTAN_SEGMENT_DIRECTION R - GEOSTAN_STREET_SIDE L - GEOSTAN_COUNTY_CODE 17031 - GEOSTAN_PREFERRED_CITY_NAME LA GRANGE PARK - CENSUS_BLOCK 170318186002041 - SEGMENT_ID 344960 - USA_MATCH_CODE SB0 - USA_SHORT_CITYNAME LA GRANGE PK 1217 IL COOK COUNTY LA GRANGE PK USA CLEVELAND 60526 1305 AVE

- - -87.859118 41.836764

Street Geocode with Range and Unit Constraints In this example, the following constraints are used: maximum of one returned candidate (mxCan=1), maximum of two ranges per candidate (mxRng=2), and maximum of five units for each range (mxUnit=5). The URL is sent as:

MapMarker USA 31 Developer Guide 116 Using the REST API

http://localhost:8095/mapmarker40/servlet/mapmarker?str=42 Hollandale Ln Apt C&a3=clifton+park&a1=ny&code=12065&mxCan=1&mxRng=2&mxUnit=5&ctry=USA The candidate has three ranges but only two are returned because of the mxRng=2 constraint. Up to five units per range can be returned, but the first range has only two rangeunits . The second returned range (address numbers 34 through 62) does not include any range units. The following portion of the returned XML shows the returned close match and highlights some of the range and unit information.

- - RESULT_CODE S5HPNTSCZA - GEOSTAN_CBSA_NAME ALBANY-SCHENECTADY-TROY, NY METROPOLITAN STATISTICAL AREA - USA_LOCATION_CODE AS0 - GEOSTAN_METRO_FLAG Y - GEOSTAN_CBSA_NUMBER 10580 - GEOSTAN_CITY_CODE 360262000 - GEOSTAN_LOT_CODE A - GEOSTAN_CSA_NUMBER 104 - GEOSTAN_HIGHRISE_DEFAULT N - CHECK_DIGIT 2 - DELIVERY_POINT 75 - MULTI_UNIT Y

MapMarker USA 31 Developer Guide 117 Using the REST API

- USA_SHORT_STREETTYPE LN - USA_LOCATION_CODE AS0 - GEOSTAN_ALIAS_TYPE N01 - GEOSTAN_CSA_NAME ALBANY-SCHENECTADY-AMSTERDAM, NY COMBINED STATISTICAL AREA - USA_MATCH_CODE S80 - GEOSTAN_DATA_TYPE 2 - USA_SHORT_ADDRESSLINE 42 HOLLANDALE LN APT C - USA_SHORT_STREETNAME HOLLANDALE - USA_DB_TYPE 2 - GEOSTAN_ADDRESS_LINE1 42 HOLLANDALE LN APT C - GEOSTAN_LOT_NUMBER 0255 - CARRIER_ROUTE R015 - REC_TYPE H - GEOSTAN_SEGMENT_DIRECTION R - GEOSTAN_STREET_SIDE L

MapMarker USA 31 Developer Guide 118 Using the REST API

- GEOSTAN_COUNTY_CODE 36091 - GEOSTAN_PREFERRED_CITY_NAME CLIFTON PARK - CENSUS_BLOCK 360910625032005 - SEGMENT_ID 917864 - USA_MATCH_CODE S80 - USA_SHORT_CITYNAME CLIFTON PARK 42 NY SARATOGA COUNTY CLIFTON PARK USA HOLLANDALE 12065 8202 LN APT C - - -73.78811 42.851915 3 - 42 42 1 2 -

NY CLIFTON PARK USA 12065 8202

- - REC_TYPE H

MapMarker USA 31 Developer Guide 119 Using the REST API

- CENSUS_BLOCK 360910625032005 - CARRIER_ROUTE R015 2 - A F -

USA 8202 APT

- - REC_TYPE H - CARRIER_ROUTE R015 - G M -

USA 8218 APT

- - REC_TYPE H - CARRIER_ROUTE R015 - 34 62 1 2 -

NY CLIFTON PARK USA 12065

MapMarker USA 31 Developer Guide 120 Using the REST API

5240

- - REC_TYPE S - CENSUS_BLOCK 360910625032005 - CARRIER_ROUTE R015 0

Postal Geocode Postal geocoding is requested by subtype 1. See the table of Geocoding Subtypes on page 93.

Postcode: 10451-2116 The URL is sent as: http://localhost:8095/mapmarker40/servlet/mapmarker?code=10451&ctry=USA &subtype=1 The following portion of the returned XML shows the detailed close match candidate (Z3 result code).

- - CENSUS_BLOCK 360050187001 - RESULT_CODE Z3 - USA_MATCH_CODE Z6 - USA_LOCATION_CODE ZC9D - USA_LOCATION_CODE ZC9D - USA_MATCH_CODE Z6 -

MapMarker USA 31 Developer Guide 121 Using the REST API

GEOSTAN_COUNTY_CODE 36005 NY BRONX COUNTY BRONX USA 10451 2116 - - -73.9271 40.8278 0

Geographic Geocode Geographic geocoding is requested by subtype 4. See the table of Geocoding Subtypes on page 93.

Key Biscayne, FL The URL is sent as:

http://localhost:8095/mapmarker40/servlet/mapmarker?a3=key biscayne& a1=FL&subtype=4&ctry=USA This returns a close match candidate. The following portion of the returned XML shows the detailed close match candidate information.

-

- - CENSUS_BLOCK 12086 - RESULT_CODE G3 - GEOGRAPHIC_RANK 6 - USA_MATCH_CODE G3 - USA_LOCATION_CODE GM - USA_LOCATION_CODE GM - USA_MATCH_CODE

MapMarker USA 31 Developer Guide 122 Using the REST API

G3 FL MIAMI-DADE KEY BISCAYNE USA

- - -80.16306 25.693329 0

Reverse Geocode The following example illustrates reverse geocoding. The X and Y coordinates are input.

X: -73.6907 Y: 42.723163 The URL is sent as:

http://localhost:8095/mapmarker40/servlet/mapmarker?x= -73.6907&y=42.723163&ctry=USA&type=ReverseGeocode

This returns a close match candidate, including range information. The following returned XML shows the returned close match with an RS5A result code.

- - - - -

- - RESULT_CODE RS5A - REC_TYPE S - USA_SHORT_ADDRESSLINE 266 4TH ST - USA_DB_TYPE 2 - CENSUS_BLOCK 360830408002025 - SEGMENT_ID

MapMarker USA 31 Developer Guide 123 Using the REST API

872939 - USA_SHORT_CITYNAME TROY 266 NY RENSSELAER COUNTY TROY USA 4TH 12180 4505 ST

7.68096 0 Note that range information is not returned with reverse geocoded candidates for MapMarker USA.

MapMarker USA 31 Developer Guide 124 6 6 – Deploying Applications

This chapter discusses how to deploy your application as a Web servlet and how you can integrate MapMarker USA 31 USA with other MapMarker country geocoders.

In this chapter:

Deploying MapMarker as a Servlet 126 Integration with MapMarker for Other Countries 127 Deploying Applications

Deploying MapMarker as a Servlet

A servlet is a Java program that runs as part of a network service, typically an HTTP server. The most common use for a servlet is to extend a web server by generating web content dynamically. MapMarker extends the Java servlet class which provides all of the necessary functionality for acting as a web server. MapMarker is J2EE compliant making it easy to deploy in most available application server software.

Using the Default Apache Tomcat Servlet Container MapMarker is installed in the Apache Tomcat servlet container. The installer provides this environment so that you can run the servlet and sample application immediately after finishing the installation. The servlet is installed as part of the Web Application feature. Simply use the default shortcut to start the server. The default shortcut is located where you chose to place the shortcut during installation. On Windows this is typically the Windows Start menu. The shortcut is called Start MapMarker USA v31 Server.

Deploying MapMarker Server in Other Web Environments For information about deploying servlet applications and for information on servlet container specific requirements, see the documentation that was delivered with your servlet container. For information about servlet technology and creating a war file, read the documentation on the Oracle Web site, http://www.oracle.com/technetwork/java/javaee/servlet/index.html. More information about the Tomcat Servlet Container can be found online at http://jakarta.apache.org/tomcat/index.html

Configuring Tomcat as a Windows Service To configure the MapMarker Tomcat Server as a Windows service, follow these steps: 1. Open a DOS window and navigate to the MapMarker Tomcat bin folder. If running, Windows , or Windows Server 2008, you .must run the CMD window as Administrator (right click > Run As Administrator). For example, navigate to: C:\Program Files\MapInfo\MapMarker USA 31\sdk\tomcat\bin

2. At the DOS command prompt, enter the following:

service install MMUSA

A message will confirm that the service MMUSA has been installed. 3. Start the MapMarker Service (from the Windows Start menu as follows:

MapMarker USA 31 Developer Guide 126 Deploying Applications

Control Panel > Administrative Tools > Services)

You will see Apache Tomcat MMUSA listed as a service. 4. Select Apache Tomcat MMUSA and Start the service. The Status column shows that the service is Started. 5. Start the MapMarker USA Sample Application. Click the Test button to verify that the server is valid. You can now geocode using MapMarker USA 31 server. For more detailed information, select one of the following links to the Apache Web site. Help with installing Tomcat as a Windows service.

Integration with MapMarker for Other Countries

If you plan on using multiple countries (for example., Canada and USA) with MapMarker, you have several integration options. The following options are discussed: • Running one Tomcat web server for each country. • Integrating multiple countries in one servlet context.

Running One Tomcat Web Server for Each Country The default HTTP port for MapMarker is 8095. You may use the default port for each country you install. If this is the case, the same URL is used for all Tomcat web servers. Therefore, only one Tomcat (country) web server may run at a time, since each Tomcat web server would be using the same port. To allow multiple Tomcat web servers to run simultaneously, you must specify a unique installation directory and unique HTTP startup and shutdown ports for each Tomcat web server. You can specify the installation directory and the HTTP startup and shutdown ports during installation. To alter the ports after installation, modify server.xml in sdk/tomcat/conf. This scenario allows unique URLs for each Tomcat web server. Note that running multiple web servers simultaneously may decrease performance.

Integrating Multiple Countries in One Servlet Context In order to allow multiple countries to run under one URL, do the following: 6. Install the first country. Expand the mapmarker war file created by the installer into the proper location for servlet contexts. Consult the Application Server's documentation for the proper servlet context location on the file system. 7. Install the subsequent countries. You must install, as a minimum, the Web Application feature and country data.

MapMarker USA 31 Developer Guide 127 Deploying Applications

8. For each country you wish to integrate into the existing servlet context, copy the country specific jar files and properties files from the server installation in the previous step into the servlet context for the first country. Country specific jar files are found under the lib directory in the servlet context; country specific property files can be found under the classes directory. Ensure the directory structure is maintained under the classes directory when copying files to a new location. If it is necessary to move the country data to a different location, you must update the property file path information located in the classes directory. 9. Verify settings (such as MapMarker data location, and library location) in the country specific properties files are appropriate for the given Application Server. 10.Restart the Application Server.

Integrating MapMarker USA and MapMarker Canada This section describes the integration of MapMarker USA v31 and MapMarker Canada v11 and assume that both products have been successfully installed. At a minimum, install the MapMarker server component and data for each country. The best strategy is to identify the which country web application that has the newest MapMarker Java core and integrate into that web application. This strategy will minimize the number of files that you have to copy.

Determining the Java Core Engine To determine the core version, you need to examine the MapMarker Java Server Status for each country. After starting the MapMarker server, select MapMarker CTY v## Server from the MapMarker program group (for example, MapMarker USA v31 Server). Then click the link that displays your machine name. Select the MapMarker Server Status link in the Administration category. The MapMarker Java Core version appears near the top of the status report. The country-specific MapMarker Java Plugin Version Information appears in the Product Specific Information category. After you examine both the MapMarker USA v31 and MapMarker Canada v11.1 server reports, you will know the core version number and build numbers for both products. For example:

MapMarker Java Core MapMarker Java Plugin MapMarker Country Version Version (Build Number)

MapMarker USA v31 5.0.0.9 31.0.0.7

MapMarker Canada 5.0.0.5 11.10.0.1 v11

Since MapMarker USA v31 uses the newer core (5.0.0.9), it is easier to integrate files from the CAN installation into the USA Tomcat.

MapMarker USA 31 Developer Guide 128 Deploying Applications

Now follow these steps: 1. Identify the CAN-specific jar files and properties files. By default, the locations are:

\sdk\tomcat\webapps\mapmarker40\WEB-INF\lib \sdk\tomcat\webapps\mapmarker40\WEB-INF\lib

Copy the following files from the MapMarker Canada installation into the corresponding USA WEB-INF\lib\ folder: miscp.jar mmj_can.jar 2. You must also copy several properties and license files. By default, these are in:

\sdk\tomcat\webapps\mapmarker40\WEB-INF\classes\ \sdk\tomcat\webapps\mapmarker40\WEB-INF\classes\

Copy the following files from the MapMarker Canada installation into the corresponding USA WEB-INF\classes\ folder: CAN_DataManagersettings.properties MMCANLicenseFactory.config MMCANLicenseProvider.config 3. Verify that the Tomcat server allocates at least 512 MB of RAM. Open catalina.bat (or catalina.sh for Solaris) in:

\sdk\tomcat\bin

and look for the entry:

set CATALINA_OPTS= -mx512m -server The maximum heap size should be at least 512 MB. This should be adequate for most country integrations, such as Canada and Canada. A heap size of 1 GB is recommended for optimum performance for a Canada and CAN integration. 4. Restart the USA server and re-examine the Java Server Status report as described in Determining the Java Core Engine on page 128. The Product Version Information shows the MapMarker Java Core version (for example, 5.0.0.9). The MapMarker Java Plugin Version Information near the bottom of the status report shows something similar to the following. This confirms that both the USA and Canada products are installed in the same Tomcat.

Plugin Version

United States (USA) 31.0.0.7

Canada (CAN) 11.10.0.1

You can now geocode both American and Canadian addresses within the same Tomcat instance.

MapMarker USA 31 Developer Guide 129 Deploying Applications

Integrating other MapMarker Server products into a single Tomcat instance: You can use this same strategy to integrate any number of MapMarker servers into one Tomcat instance. First determine which installed MapMarker has the most recent core version. Then determine which country-specific files need to be copied into the target web server. (It may help to diff the contents of the ...\WEB-INF\lib and ...\WEB-INF\classes folders.) For each country you wish to integrate into an existing Tomcat, copy the country-specific jar, properties, and license files into the Tomcat with the newest MapMarker Java core.

Performance of Tomcat integration strategy: Heap size of 512 MB is usually adequate, but 1 GB is recommended for optimum performance for a Canada and CAN integration. On 32 bit systems, 1.5 MB is the maximum heap size. Larger heap sizes can be allocated on 64 bit systems.

If you move country data: Country-specific data is located in directories named MapMarker_CTY_v##_Data (where CTY is the country identifies and v## is the version number). Each CTY_DataManagersettings.properties file (copied in step 2) includes a DICTIONARY_PATH# entry that points to the respective data file location. If you move country data to a different location, you must update the property file to point to the data location.

MapMarker USA 31 Developer Guide 130 7 7– Result Codes

In this chapter:

Understanding Result Codes 132 Single Match (S category) 133 Best Match From Multiple Candidates (M category) 139 Postal Centroid Matches (Z category) 140 Geographic Matches (G category) 140 Reverse Geocoded Matches (R category) 140 Non-match Codes (N category) 141 Result Codes

Understanding Result Codes

As an output option, MapMarker returns a georesult code for every record it attempts to match. The code indicates the success or failure of the geocoding operation and conveys information about the quality of the match. Each character of the code indicates the level of precision of each address component matched.

The result codes are written to a result column specified in the Select Output Columns dialog at the beginning of the geocoding process. You can either create this column before geocoding or have MapMarker create it automatically (default name Georesult) when you open your table. The result code is an alphanumeric code of 1–10 characters. The codes fall into the following categories: • Single unique match • Best match from multiple candidates • ZIP Code centroid match • Geographic match • Non-match The match precision depends on the match settings that you choose. Geocoding preferences and match modes are explained further in the topic Using Geocoding Options in the User Guide. Match precision also depends on the quality of the input address data and on the quality of the Address or User Dictionary. Each category is explained in the following topics. Single Match (S category) Best Match From Multiple Candidates (M category) Postal Centroid Matches (Z category) Geographic Matches (G category) Non-match Codes (N category)

MapMarker USA 31 Developer Guide 132 Result Codes

Single Match (S category)

Matches in the S category indicate that the record was matched to a single address candidate. The first character (S) reflects that MapMarker found a street address that matches your record. Within this category, a number of precision levels have been defined. The precision affects the location of the geocoded point on the map. An address matched to a street address position has greater positional accuracy than one matched to a ZIP Code™ centroid. Matches in the S category can have the following types of precision: • Address point – Using address point interpolation, address is matched to an address point position, or match is interpolated against a nearby address point candidate to arrive at a position along the street segment. Address point interpolation places geocoded points more accurately along the street segment and can prevent the “bunching” of points that can occur at either end of a street segment. See Chapter 7 Custom User Dictionaries for information on address point interpolation and address point data. • Street – Address is matched to a street address position. • ZIP– Address is matched to a ZIP Code centroid or point ZIP centroid position. Each of the S codes is defined below. The second position in the code reflects the positional accuracy of the resulting point for the geocoded record, as indicated below. • S1 – single match, point located at ZIP Code centroid. This is the same quality match as a Z1 result. • S2 – single match, point located at ZIP + 2 centroid. single match, point located at ZIP + 2 centroid. This is the same quality match as a Z2 result. • S3 – single match, point located at ZIP + 4®. This is the same quality match as a Z3 result. • S4 – single match, point located at a street centroid. • S5 – single match, point located at a street address position. Because only street segment data is available, the interpolation is not as accurate as an S7 return. See also Interpreting S5 Result Codes on page 138. • S6 – single match, point located at point ZIP centroid. See also Interpreting S6 Result Codes on page 138. • S7 – single match, located at an interpolated point along a street segment. Both a point/parcel dictionary and a street segment dictionary must be available. Because known point data is available, the S7 interpolation is more accurate than an S5 result. See Interpreting S7 Result Codes on page 138. • S8 – single match, 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. See also Interpreting S8 Result Codes on page 137. • SX – single match, point located at street intersection. • S0 – single match, no coordinates available (very rare occurrence).

MapMarker USA 31 Developer Guide 133 Result Codes

• SC – Single close match where the original point has been moved a specified distance (usually along a perpendicular line) toward or away from the associated street segment. This result code can be returned only when both a point/parcel dictionary and a street segment dictionary are available and when the centerline offset feature is used. The following table shows what census information is returned, if any, for specific geocoding result codes.

Geocoding Result Codes Related to Census Block Information

Result Code Census Block ID Output

S8 S8 results are matched to either the single point associated with an address point candidate, or to an address point candidate that shares the same house number. An S8 result is possible only if you are using a point dictionary. The S8 indicates that the address candidate corresponds to an exact point. No interpolation is required. An S8 result can also indicate a pre-assigned or static parcel centroids associated with Master Location Data. S8 results can return complete 15-character Census Block ID.

S7 S7 results are matched to an interpolated point along a street segment. An S7 result is possible only if you are using a point dictionary in addition to a street segment dictionary. Since the S7 interpolation is based on known point addresses, the interpolation is more accurate than interpolation based on a segment dictionary alone (which would produce an S5 result). S7 results can return a complete 15-character Census Block ID. You must enable address point interpolation to generate S7 result codes.

S6 S6 results are matched to a point ZIP centroid. A point ZIP is a 5-digit ZIP Code™ that represents a unique ZIP such as a single site, building, or organization. S6 is the same level of geocoding accuracy as a Z6 result.

MapMarker USA 31 Developer Guide 134 Result Codes

Geocoding Result Codes Related to Census Block Information

Result Code Census Block ID Output

S5 S5 results are matched to an interpolated point along a street segment. An S5 result is based on a street segment dictionary only. This interpolation is not a accurate as an S7 result. When using the Address Dictionary, this can return a complete 15-character Census Block ID.

S4 S4 results are matched to a street centroid point. S4 results can return complete 15-character Census Block ID, but only if the block groups on each side of the street are the same. A house number is also required for Census Block IDs.

S3 S3 results are matched to ZIP + 4® locations. S3 is the same level of geocoding accuracy as a Z3 result. S3 results can return complete 15-character Census Block ID if the ZIP + 4 location is contained in one Census Block. However a ZIP + 4 location may cover more than one Census Block, in which case S3 may return a 12-character Census Block Group number.

S2 S2 results are matched to ZIP + 2 locations. This may return partial census information if ZIP + 4 is supplied. S2 is the same level of geocoding accuracy as a Z2 result.

S1 S1 results are matched to ZIP centroid locations. This may return partial census information if ZIP + 4 is supplied. S1 is the same level of geocoding accuracy as a Z1 result.

SX SX results are matched to a point located at street intersection.

MapMarker USA 31 Developer Guide 135 Result Codes

Geocoding Result Codes Related to Census Block Information

Result Code Census Block ID Output

SC SC results represent a match where the original point has been moved a specified distance (usually along a perpendicular line) toward or away from the associated street segment. An SC result is possible only if you are using a point/parcel dictionary in addition to a street segment dictionary. This result code can be returned only when the centerline offset feature is used. See Centerline Offset for Point Candidates on page 11.

Z6 Z6 results are matched to a point ZIP centroid. Point ZIPs are 5-digit The Z6 code indicates that these special ZIPs are actual point locations, not an area. Point ZIPs include unique single sites, buildings, or organizations.

Z3 May return partial census information if ZIP + 4 is supplied. Z3 results are matched to ZIP + 4 locations.

Z2 May return partial census information if ZIP + 4 is supplied. Z2 results are matched to ZIP + 2 locations.

Z1 May return partial census information if ZIP + 4 is supplied. Z1 results are matched to ZIP centroid locations.

See the following topics: Interpreting Complete S and M Result Codes Interpreting S8 Result Codes Interpreting S7 Result Codes Interpreting S6 Result Codes Interpreting S5 Result Codes S and Z Result Codes: What is the Difference?

Interpreting Complete S and M Result Codes For S category result codes, eight additional characters describe how closely the address in your table matches an address in the Address Dictionary. The characters appear in the order listed in the following table. Any non-matched components are represented by a dash.

MapMarker USA 31 Developer Guide 136 Result Codes

Result Code Component Description Example

H House Number 110

P Street Prefix North

N Street Name Fletcher

T Street Type Place

S Street Suffix SE

C City Name Boulder

Z ZIP Code 80303

A or U Address Dictionary or User A Dictionary

For example, the result code S5- -N-SCZA is for a single close match that matched the street name, street suffix direction, city and ZIP Code™ exactly, but could not match the house number, street prefix direction, or the street type. The match came from the MapMarker Address Dictionary. This record would be geocoded to the street address position of the match candidate. M category result codes follow the same pattern, and are described in Best Match From Multiple Candidates (M category) on page 139.

Interpreting S8 Result Codes S8 results are matched to either the single point associated with an address point candidate, or to an address point candidate that shares the same house number. An S8 result can return a complete 15-character Census Block ID. An S8 georesult indicates that the address candidate is a point. No interpolation is required, so S8 result codes are returned regardless of whether address point interpolation is enabled. An S8 result can also indicate a pre-assigned or static parcel centroids associated with Master Location Data. If your S8 result is returned from Master Location Data, you should examine the Address Location Codes for more information. These will have values of AP22, AP23, or AP24. See Address Location Codes appendix in the MapMarker USA v31 User Guide for a description of the related Address Location Codes, including the AP point level match codes.

MapMarker USA 31 Developer Guide 137 Result Codes

Interpreting S7 Result Codes S7 results are matched to an interpolated point along the candidate’s street segment. An S7 result can return a complete 15-character Census Block ID. You must enable address point interpolation to generate S7 result codes. Both a point dictionary and a street segment dictionary must be available. An S7 candidate is not located exactly at a known point . However, because both point and segment data is available, the interpolation along the street segment can be very accurate. The geocoded candidate location is interpolated based on the nearest point candidates on the street segment. By using known address reference points on the street segment, the S7 interpolated point can be more accurate than an S5 result.

Interpreting S6 Result Codes An S6 code is returned from geocoding when the candidate is matched to a point ZIP centroid. A point ZIP is a 5-digit ZIP Code that represents unique ZIPs such as a single site, building, or organization. Point ZIPs do not cover an area, so they are shown as dots on a map rather than polygons, and have no geographic extent defined in terms of street segments. Because these points show actual locations, a different result code is used to distinguish them from other ZIP Centroid matches.

Interpreting S5 Result Codes S5 results are matched to an interpolated point along a street segment. This can return a complete 15-character Census Block ID. An S5 result is based on a street segment dictionary only. This interpolation is not a accurate as an S7 result, which can use point data to interpolate more accurately. If you receive an S5 match for a record that was geocoded to an unexpected place, analyze the result code to determine why. This situation can occur during a geocoding pass where the match conditions are relaxed; that is, you did not require an exact match on house number, street name, and/or ZIP Code. When MapMarker attempts to geocode the record with those settings, it searches larger areas than it would if the conditions were stricter. Under those conditions, it is possible to match the record to a distant address that has a similar name. For example, a typical result might look like this: S5-P--S--A. The missing components in the result code are represented by dashes. Even though MapMarker returned an S5 (it found a single match to a street address), it did not match the house number (H), street name (N), street type (T), city (C), or ZIP Code (Z). To minimize the matches that geocode to incorrect locations, geocode your table with stricter matching conditions. For stricter match settings and greatest matching accuracy, you can use CASS™ geocoding. Alternatively, you can use a parcel level dictionary to generate highly-accurate S8 single-point geocode matches.

MapMarker USA 31 Developer Guide 138 Result Codes

Note: You cannot use point dictionaries (or any user dictionary) in combination with CASS geocoding.

S and Z Result Codes: What is the Difference?

An S3 match is defined as a single close match with the point located at the ZIP + 4® centroid. The Z3 match is also geocoded to the ZIP + 4 centroid. The S3 and Z3 result codes indicate the identical postal centroid. There is no difference in the accuracy of S3 and Z3 matches. The only difference is how MapMarker arrives at the results. For the S3 record, MapMarker found a street address that matches, but the match record did not contain any street geometry information. MapMarker is, therefore, unable to interpolate where along the segment to place the record. The best it can do is to geocode to the ZIP + 4 centroid. A Z3 match is a direct match to the ZIP + 4 centroid. MapMarker could not find a street address match for one of several reasons: 1) you chose to geocode to the postal level; 2) there was no close street level match and you chose postal fallback; or 3) the address is a P.O. Box or rural route. Similarly, S2/Z2 (ZIP + 2 matches) and S1/Z1 (5-digit ZIP Code matches) indicate the identical postal centroids. There is no difference in the accuracy of these S and Z matches.

Best Match From Multiple Candidates (M category)

Matches in the M category indicate that there is more than one match candidate for the record and MapMarker has chosen the best one of those candidates. This category is used when you select Accept First, Pick Street Address over ZIP + 4, or Pick ZIP + 4 over Street Address in the Multiple Match tab and MapMarker finds more than one strong match candidate. As in the S category, the second position in the code of M category matches the positional accuracy of the resulting point object.j Note: M category matches can be returned for the Desktop Application only, not by the Server . • M1 – multiple matches, point located at ZIP Code centroid • M2 – multiple matches, point located at ZIP + 2 centroid • M3 – multiple matches, point located at ZIP + 4® centroid • M4 – multiple matches, point located at the center of a shape point path (shape points define the shape of the street polyline) • M5 – multiple matches, point located at a street address position (highest accuracy available) • M6 – multiple matches, point located at point ZIP location • MX – multiple matches, point located at street intersection • M0 – multiple matches, no coordinates available

MapMarker USA 31 Developer Guide 139 Result Codes

Postal Centroid Matches (Z category)

Matches in the Z category indicate that no street match was made, either: 1) because there is no close match and you allowed MapMarker to fall back to ZIP® Centroid; 2) the address is a P.O. Box or rural address; or 3) you set MapMarker to match to ZIP Centroids. The resulting point is located at the ZIP Code™ centroid with five possible accuracy levels. • Z1 – ZIP Code centroid match • Z2 – ZIP + 2 centroid match • Z3 – ZIP + 4 centroid match • Z0 – ZIP Code match, no coordinates available (very rare) • Z6 – ZIP Code centroid match for point ZIP A Z6 code is returned when the candidate is matched to a point ZIP centroid. Point ZIPs are 5-digit ZIP Codes that are points on a map rather than a polygon. Point ZIPs include unique ZIPs (single site, building, or organization). Instead of returning a Z1 result code, the Z6 code indicates that these special ZIPs are actual point locations, not an area.

Geographic Matches (G category)

Matches in the G category indicate that a match was made at the state, county, or city level. • G1 – State match, point located at the state centroid. • G2 – County match, point located at the county centroid. • G3 – City match, point located at the city centroid. A number of prominent U.S cities can be matched even if no other information is provided. For example, if you provide Chicago (city) but no state, the record is matched to Chicago, IL.

Reverse Geocoded Matches (R category)

Reverse geocoded candidates return a R result codes. The first three 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. This is always an A, indicating address dictionary; reverse geocoding is supported by the address dictionary only (not user dictionaries). Note: Reverse geocoding is supported in the Developer (Server) edition and API, but not in the Desktop application. Therefore, geocoded candidates in the Desktop application will not return R result codes. Reverse geocoding result codes are as follows: • RS8A – Point level match. Candidate returned from a point dictionary (such as Centrus Points, TomTom Points, Master Location). • RS5A – Street address match. Candidate returned from address dictionary. • RS4A – Street centroid match) Candidate returned from address dictionary.

MapMarker USA 31 Developer Guide 140 Result Codes

Non-match Codes (N category)

The following result codes indicate no match was made: • N – No close match. These records can be re-geocoded interactively or during subsequent automatic passes under different matching conditions. • NX – No close match for street intersections. • ND – MapMarker could not find the Address Dictionary for the given ZIP Code or city/state. These records can be re-generated once the Address Dictionary is available. An ND code can also appear in the fields of Zip + 4® output columns. For example, MapMarker can return 12180-23ND. In this case, the ND code is ZIP + 4 Codes associated with nondelivery areas such as vacant lots or other areas to which the US Postal Service does not deliver mail. • NG – The user marks these records during interactive geocoding as non-geocodable. MapMarker does not attempt to match these records again until the code is removed.

MapMarker USA 31 Developer Guide 141 A A –Using the XML API

MapMarker uses XML to communicate between clients and the MapMarker server. The MapMarker XML API allows developers

access to MapMarker functionality from virtually any development platform. This appendix provides some information on using the MapMarker schemas and the XML API.

In this appendix:

Tips on Using the XSD Schemas 143 Geocoding Constraint Keys 144 Geocoding Request Types 148

Tips on Using the XSD Schemas

The MapMarker schemas are installed by MapMarker in: \sdk\engine\schema, where is the installation folder. The schemas are: • MMJRequest.xsd – MapMarker request schema • MMJResponse.xsd – MapMarker response schema • MMJCommon.xsd – MapMarker common schema The schemas are largely self-explanatory, but some specific details are described below.

MapMarker Request Schema For the request schema, the element should always be "USA" If you are using XML to send batch requests, the request ID and address ID must be unique within the batch request. Note: Only the XML API supports batch request files. This feature is not available with the Java API Increasing the number of addresses in a batch file will improve performance. For example, submitting a batch file with from 25 to 50 addresses may increase geocoding speed by 50 percent compared to submitting separate request for each address. The optimal batch size varies depending on type of table, server hardware. or network conditions. In general, performance gains will level off between 25 and 35 addresses per file. Performance may decrease (or cause client/server out of memory errors) when the batch file gets extremely large. Setting maximum candidates = 1 in the XML batch request will also improve client/server performance.

MapMarker Response Schema For the response schema, the CfgOrder and some AddressRangeType elements are notable.

CfgOrder = integer The CfgOrder attribute identifies which configured dictionary this candidate was found in. The order is determined by the server upon startup based on the DICTIONARY_PATH# entries of the USA_DataManagerSettings.properties file.

rangeType = CandidateRange.getOddEvenIndicator() streetSide = CandidateRange.getLeftRightIndicator() The rangeType element contains information about the street range parity of the geocoded candidate. The streetSide element contains information about the left/right street side. See Candidate Range Constants and Values on page 75. for a description of the values associated with getLeftRightIndicator() and getOddEvenIndicator.

MapMarker Common Schema For the common schema, several DictionarySearchOrderListType attributes are notable.

CfgOrder = integer

MapMarker USA 31 Developer Guide 143

The CfgOrder attribute identifies which configured dictionary this candidate was found in. The order is determined by the server upon startup based on the DICTIONARY_PATH# entries of the USA_DataManagerSettings.properties file.

AllowSearch = boolean If true if this dictionary is searched for candidate matches.

UserPriority = integer User-specified order to search this dictionary.

MaxReturnValue (simple type) Any time a MaxReturnValue is used, -1 means to return all.

BaseConstraintsType

addrPntInterp = boolean If true, use Address Point Interpolation. For a description of this feature see DPV Related Actions on page 86.

Geocoding Constraint Keys

The Constraint Keys table describes the available constraints. The constraints recognize the following KEYS within . See the table of Geocode Constraints on page 56 and USA_GeocodeConstraints on page 60 for a complete description of the keys.

Constraint Keys

Name Description

"KEY_SEARCH_LEVEL" SEARCH_LEVEL_EXPANDED (Enable or disable expanded search.) SEARCH_LEVEL_FINANCE_AREA (Default for CASS mode) SEARCH_LEVEL_CITY (Default for Relaxed, Exact, Default, or Custom Modes)

"KEY_USE_EXPANDED_SEARCH" Enable or disable expanded search. Deprecated. Use "KEY_SEARCH_LEVEL" = SEARCH_LEVEL_EXPANDED

"KEY_EXPANDED_SEARCH_RADI Specify the expanded search radius. US"

MapMarker USA 31 Developer Guide 144

Constraint Keys (Continued)

Name Description

"KEY_EXPANDED_SEARCH_LIMIT Specify that expanded search candidates _TO_ should be limited to state regardless of STATE" search radius.

"KEY_CASS_DPV" Enable DPV

"LACSLINK" Enable LACSLink

"SUITELINK" Enable SuiteLink .

"ZIPOVERCITY" Specify that ZIP Code match is preferred over a city match. See KEY_ZIP_OVER_CITY on page 62.

"WIDE_SEARCH" Enable or disable the wide search feature. See Using the Wide Search Constraint on page 69.

"KEY_ALTERNATE_LOOKUP" Specify whether to prefer streets or firm name (places) for lookup. See KEY_ALTERNATE_LOOKUP on page 61.

"STREET_FIRST" Specify that candidates matching on street are preferred over place. See KEY_ALTERNATE_LOOKUP Values on page 63.

"PLACE_FIRST" Specify that candidates matching on place are preferred over street. See KEY_ALTERNATE_LOOKUP Values on page 63

"STREET_ONLY" Specify that only candidates matching on street are considered. See KEY_ALTERNATE_LOOKUP Values on page 63

"CASSMODE" Sets CASS match mode

"useCenterlineOffset" Enable or disable the centerline offset feature. See Using Centerline Offset for Point Candidates on page 68.

"centerlineOffset" Specify the distance used for centerline offset. See POINT_CENTERLINE_OFFSET on page 60.

MapMarker USA 31 Developer Guide 145

Constraint Keys (Continued)

Name Description

"centerlineOffsetUnits" Specify the units used for centerline offset. See POINT_CENTERLINE_OFFSET_ UNITS on page 60. (ft, m, mi, km, in, yd, cm, and mm)

"closeMatchesOnly" Specify that only close matches are returned.

"maxCandidatesReturned" Specify the maximum number of candidates to return. Use "-1" to return all candidates.

"maxRanges" Specify the maximum ranges per candidate to return. Use "-1" to return all candidates.

"maxRangeUnits" Specify the maximum units per ranges to return. Use "-1" to return all candidates.

"OffsetFromCorner" Specify the offset distance of the geocoded point with respect to the corner.

"OffsetFromStreet" Specify the offset distance of the geocoded point with respect to the centerline of the street.

"cornerOffsetUnits" Specify the corneroffset units.

"streetOffsetUnits" Specify the street offset units.

"centerlineOffset" Specify the distance used for centerline offset. See POINT_CENTERLINE_OFFSET on page 60.

"centerlineOffsetUnits" Specify the units used for centerline offset. See POINT_CENTERLINE_OFFSET_ UNITS on page 60. (ft, m, mi, km, in, yd, cm, and mm)

"ClientLocale" Specify the locale. ("en_US")

MapMarker USA 31 Developer Guide 146

Constraint Keys (Continued)

Name Description

"ClientCRS" Specify the coordinate reference system. Accepted values include EPSG SRS Names as well as MAPINFO MAPBASIC Projection String SRS Names. For example: "epsg:4326" to specify the EPSG Constant for default coordinate system.

"GeocodeRequestType" Specify the geocode request type. See Geocoding Request Types Values on page 148

"fallbackToPostal" Specify postal fallback if street geocoding did not return a close match candidate.

"fallbackToGeographic" Specify geographic fallback if street geocoding did not return a close match candidate.

"dictionaryUsage" Specify the dictionary usage preference (address dictionary, user dictionary, or both) See KEY_DICTIONARY_USAGE on page 57.

"dictionarySearchOrder" Specify the order in which the given dictionary will be searched. See KEY_DICTIONARY_SEARCH_ ORDER on page 57.

"addrPntInterp" Enable or disable address point interpolation. See DPV Related Actions on page 86.

"MatchMode" To specify the match mode, use the following constants: "RelaxedMode", "ExactMode", "DefaultMode". If no match mode is specified, then Must Match constraints are used. For a more complete description of match modes, see Using Match Modes on page 65.

"MustMatchAddrNum" If no match modes are set, specify that the address number must be matched.

MapMarker USA 31 Developer Guide 147

Constraint Keys (Continued)

Name Description

"MustMatchMainAddr" If no match modes are set, specify that the complete main address must be matched.

"MustMatchArea1" If no match modes are set, specify that state name must be matched.

"MustMatchArea2" If no match modes are set, specify that county name must be matched.

"MustMatchArea3" If no match modes are set, specify that city name must be matched.

"MustMatchArea4" If no match modes are set, specify that locality name must be matched.

"MustMatchPostalCode" If no match modes are set, specify that postal code must be matched.

"MustMatchInput" If no match modes are set, specify that all the input components must be matched.

Geocoding Request Types

The following table summarizes the geocoding request type values associated with the "GeocodeRequestType" string.

Geocoding Request Types Values

Geocode Request Type Value

Geocode Address 0 (default)

Geocode Postal Centroid 1

Geocode Geographic Centroid 4

Address Standardization (without geocoding) 5

Browse 6

Geocode Highway Exits 201

Geocode Airport by Code 202

Geocode Airport by State 203

DB Availability 205

MapMarker USA 31 Developer Guide 148

Geocoding Request Types Values (Continued)

Geocode Request Type Value

DPV Support 206

LACS LINK Supported 207

DPV Status 208

Candidate AdditIonal Field Values The following values can be returned with AdditionalFields statements.

Candidate Additional Field Values

Candidate Additional Field Values Example Country

RESULT_CODE S5HPNTSCZA All Countries

SEGMENT_ID 856929 All Countries

DELIVERY_POINT 01 USA

CENSUS_BLOCK 360830523018010 USA

CARRIER_ROUTE C034 USA

LACS L USA

CHECK_DIGIT 08 USA

REC_TYPE F USA

MULTI_UNIT Y USA

GEOGRAPHIC_RANK 1 USA

DPV_CONF Y USA

DPV_CMRA Y USA

DPV_FP Y USA

DPV_FN1 AA USA

DPV_FN2 AA USA

DPV_FN3 AA USA

MapMarker USA 31 Developer Guide 149

Candidate Additional Field Values (Continued)

Candidate Additional Field Values Example Country

DPV_NOSTAT Y – The address is vacant. USA N –The address is not vacant. Blank – DPV is not loaded or DPV did not confirm (so vacancy is irrelevant).

DPV_VACANT Y – The address was valid for USA computerized delivery sequence (CDS) pre-processing. N – The address not valid for CDS. Blank – The address is not presented to No Stat table or DPV data is not loaded.

DEFAULT_FLAG Y USA

LACSLINK_INDICATOR Y USA

LACSLINK_RESULT_CODE A USA

SUITELINK_RETCODE A – SuiteLink match. Secondary USA information exists and was assigned to this record as a result of SuiteLink processing. 00 – SuiteLink no match. Lookup was attempted but no matching record could be found. blank – A SuiteLink lookup was not attempted because one of the following was true:

MapMarker USA 31 Developer Guide 150 B B –JNI Adapter Configuration File Settings

This appendix explains the settings you can modify in the configuration file of the JNI adapter.

In this appendix:

JVM Settings 152 Country Settings 152

JVM Settings

The JVM settings are in the geojni.cfg file found in the installed Desktop directory (typically C:\Program Files\MapInfo\MapMarker_USA_v29\desktop\geojni.cfg). This configuration file controls the creation of the JVM in which the Java engine runs. The JVM settings are useful for changing the amount of memory used by the JVM. Here are the settings:

+numVmOptions= -Djava.class.path= -server–causes a server JVM to be created (Windows only) -Xms128m–minimum heap size for JVM to create when initialized (128 M) -Xmx256m–maximum size JVM heap can grow to (256 M) -Xmn40m–another memory related setting for the JVM

In this example, the +numVmOptions setting would be set to 5. The following options are used to create the JVM but are not strictly JVM settings:

+jvmVersion=0x00010004–the version of JVM to create, in this case 1.4 +jvmPath–the full file path to the jvm.dll (including the filename jvm.dll) (Windows only)

Country Settings

The following setting indicates the country that the adapter is going to use for geocoding.

+country= All classes for this country must be given in the –Djava.class.path setting in the JVM settings described in the previous section.

MapMarker USA 31 Developer Guide 152 C C –Using Database Extenders

Developers who want to include geocoding capabilities in their applications can take advantage of database extenders. These database extenders are shipped separately. If you require a database extender, contact your sales representative. In this appendix:

Geocoding Extenders for Database Developers 154

Geocoding Extenders for Database Developers

Developers who want to include geocoding capabilities in their applications can use their database product and an appropriate MapMarker geocoding extender. The table below describes these geocoding extenders and their status.

Geocoding Extenders

Product Description Status

MapMarker The Oracle Geocoding The Oracle Geocoding Geocoding Extender Extender product is a thin, Extender includes for Oracle pass-through layer on top of MapMarker USA the Java client classes, which functionality. This is provide a SQL interface for available on request. address geocoding to MapMarker Java server.

MapInfo Geocoding The SQL Server 2005 The Geocoding Extender Extender for SQL Extender product is for SQL includes MapMarker Server 2005 server database USA functionality. This is programmers. This product is available on request. a thin, pass-through layer on top of a .NET client which provides an SQL interface for address geocoding via XML to the MapMarker Java Server or Envinsa Location Utility service

MapMarker USA 31 Developer Guide 154 D D–Error Messages

This appendix provides a reference to error messages you may receive in the course of using MapMarker USA.

In this appendix:

MapMarker Java API Errors 156

MapMarker Java API Errors

MapMarker USA Java API errors are categorized as follows: • Engine Errors • Parser Errors • Data Access Exceptions • License Exceptions • General Geocoding Process Exceptions • Reverse Geocode Exception Codes • Client Exceptions • Server Exceptions

Engine Errors

Error Code Description

ERR_CANT_CREATE_GEOCODABLE_ADDRESS Engine unable to create an address object for the given country.

ERR_EXCEPTION_IN_ENGINE Engine encountered an exception.

ERR_UNKNOWN_GEOCODE_TYPE Engine was given an unknown geocode type.

ERR_ENGINE_RESET_NULL Engine returned null instead of a response object.

Parser Errors

Error Code Error # Description

ERROR_PARSER_INPUT_ADDRESS_ 2000 Input address is null. NULL

ERROR_PARSER_PARSED_ADDRESS 2001 Parsed address is null. _NULL

ERROR_PARSER_INITIALIZATION 5000 Unable to initialize parser.

MapMarker USA 31 Developer Guide 156

Data Access Exceptions

Error Code Error # Description

ERROR_DATA_ACCESS_INVALID_REQUE 2100 Invalid request made during ST data access.

ERROR_DATA_ACCESS_DATA_CORRUP 2101 Data corruption encountered TED during data access.

ERROR_DATA_ACCESS_IO 2102 IO error encountered during data access.

ERROR_DATA_ACCESS_NO_DICTIONAR 2103 The data manager failed to find Y any usable dictionaries, based on the system preferences and settings.

ERROR_DATA_ACCESS_NO_SAC 2104 No search area codes found for given location information.

ERROR_DATA_ACCESS_NO_STREET_BA 2105 No street base available for SE given street name.

ERROR_DATA_ACCESS_NO_SAC_DATA 2106 Data construction is not optimized. No data files found for given search area code: {0}.

ERROR_DATA_ACCESS_MISSING_FILE 2107 Data file missing.

ERROR_DATA_ACCESS_DATA_NOT_LIC 2108 Data not licensed. ENSED

ERROR_DATA_ACCESS_MISSING_FILE 5100 Missing file: {0}.

License Exceptions

Error Code Error # Description

ERROR_LICENSE_INVALID_PASSWORD 5202 Invalid License Password or Invalid License file.

ERROR_DATA_HAS_EXPIRED 5203 One or more specified data dictionaries has expired.

ERROR_LICENSE_FILE_INVALID_DOES_ 5204 License does not match the NOT_ current machine. MATCH_MACHINE

MapMarker USA 31 Developer Guide 157

Error Code Error # Description

ERROR_LICENSE_FILE_NOT_FOUND 5205 License specified does not exist.

ERROR_SOFTWARE_LICENSE_EXPIRED 5206 Software license has expired.

General Geocoding Process Exceptions

Error Code Error # Description

ERROR_GAC_RESOURCE 2300 Unable to find resource bundle for error messages.

ERROR_GAC_FACTORY_INSTANTIATION 2301 Unable to instantiate geocodable address factory for country code {0}.

ERROR_NULL_RESULT 2302 The geocoding engine was unable to return a result.

ERROR_GEO_TYPE_UNSUPPORTED 2303 Unsupported geocode type: {0}

ERROR_NO_PARSE_RESULT 2304 No result received from parser.

ERROR_GAC_PARSER_INIT_FAILED 2305 Error initializing parser.

ERROR_GAC_DATA_MANAGER_INIT_FAI 2306 Error initializing data manager. LED Check MMUSALicenseProvider.config for correct license path.

ERROR_NO_IMPLEMENTATION 2307 Engine method not implemented.

ERROR_UNEXPECTED_ERROR 2308 Unexpected error encountered.

ERROR_BATCH_SIZE_EXCEEDED 2309 Maximum batch size exceeded.

ERROR_UNSUPPORTED_XML_PROTOC 2310 Unsupported XML Protocol OL request.

MapMarker USA 31 Developer Guide 158

Reverse Geocode Exception Codes

Error Code Error # Description

RG_ERROR_FAILED_TO_CREATE_ 5350 Unable to get Geostan pool. SUBHANDLER_NOPOOL

RG_ERROR_FAILED_TO_CREATE_ 5351 Invalid Geostan pool present. SUBHANDLER_BADPOOL

RG_ERROR_GEOSTAN_FIND_ERROR 5352 No Spatial Index files

ERROR_GEOSTAN_UNABLE_TO_LOAD_ 5353 Unable to load the Spatial SPATIAL_INDEX Index. The Spatial index files may be missing or the dictionaries in use do not match those that were used in the search path during creation of gsx files.

RG_ERROR_GEOSTAN_REVERSE_GEO 5354 Reverse geocoding is not CODING_NOT_LICENSED enabled in the current license file.

Client Exceptions

Error Code Error # Description

ERROR_CLIENT_BAD_URL 2400 Malformed URL.

ERROR_CLIENT_HTTP_ERROR 2401 HTTP Error: {0}.

ERROR_CLIENT_JDOM 2402 JDom Exception encountered.

ERROR_CLIENT_XML_TRANSFORM 2403 Error during XML transformation.

ERROR_CLIENT_IO 2404 IO Error.

ERROR_CLIENT_MISSING_URL 2405 The URL to the servlet has not been set. Please try again with a servlet URL.

ERROR_CLIENT_MISSING_RESPONSE 2406 No response was returned from server.

MapMarker USA 31 Developer Guide 159

Server Exceptions

ERROR_SERVER_JDOM 2600 The server was unable to process the request.

ERROR_SERVER_INVALID_REQUEST_T 2601 An invalid request type was YPE provided.

MapMarker USA 31 Developer Guide 160 E E –Match Codes and Location Codes

This appendix includes the complete list of Match Codes and Location Codes.

In this Appendix Match Codes 162 Location Codes 169 Using Status Codes 181

Match Codes

GeoStan returns match codes that indicate the parts of the address were matched (or what address parts were changed to achieve the match). If no match was made, the match code begins with E and the remaining digits indicate why the address did not match.

See also: Match Code Values Hex Digits Associated with Match Codes Corrected Lastline Match Codes Error and No Match Codes

Match Code Values The following Match Code Values table contains the match code values, where h represents a hex code digit. See the table of Match Code Hex Digits for descriptions of the hex digits associated with these match codes.

Match Code Values

Code Description

Ahh Same as Shh, but indicates match to an alias name record or an alternate record.

Chh Street address did not match, but located a street segment based on the input ZIP Code or city.

D00 Matched to a small town with P.O. Box or General Delivery only.

Hhh House number was changed.

Jhh Matched to a User Dictionary.

Qhh Matched to USPS range records with unique ZIP Codes. CASS rules prohibit altering an input ZIP if it matches a unique ZIP Code value.

Rhh Matched to a ranged address.

Shh 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.

MapMarker USA 31 Developer Guide 162

Match Code Values(Continued)

Code Description

Thh 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.

Uhh 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.

Xhhh 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. The USPS does not allow intersections as a valid deliverable address.

Yhhh Same as Xhhh, but an alias name record was used for one or both streets.

Z No address given, but verified the provided ZIP Code.

Hex Digits Associated with Match Codes The following table describes the Match Code Hex Digits hex digits associated the match code values.

Match Code Hex Digits

In second and third hex position Code In first hex position means: means:

0 No change in last line. No change in address line.

1 ZIP Code changed. Street type changed.

2 City changed. Predirectional changed.

3 City and ZIP Code changed. Street type and predirectional changed.

4 State changed. Postdirectional changed.

MapMarker USA 31 Developer Guide 163

Match Code Hex Digits (Continued)

In second and third hex position Code In first hex position means: means:

5 State and ZIP Code changed. Street type and postdirectional changed.

6 State and City changed. Predirectional and postdirectional changed.

7 State, City, and ZIP Code Street type, predirectional, and changed. postdirectional changed.

8 ZIP + 4 changed. Street name changed.

9 ZIP and ZIP + 4 changed. Street name and street type changed.

A City and ZIP + 4 changed. Street name and predirectional changed.

B City, ZIP, and ZIP + 4 changed. Street name, street type, and predirectional changed.

C State and ZIP + 4 changed. Street name and postdirectional changed.

D State, ZIP, and ZIP + 4 Street name, street type, and changed. postdirectional changed.

E State, City, and ZIP + 4 Street name, predirectional, and changed. postdirectional changed.

F State, City, ZIP, and ZIP + 4 Street name, street type, changed. predirectional, and postdirectional changed.

Corrected Lastline Match Codes Lastline correction can correct elements of the output last line, providing a good ZIP Code, city name, or close match on the soundex even if the address would not match or was non- existent. The table of Lastline Correction Codes describes the specific corrections made to the last line of the output address.

MapMarker USA 31 Developer Guide 164

l Lastline Correction Codes

Code Description

Zh No address given, but verified the provided ZIP Code.

h = 0 No change in last line.

h = 1 ZIP Code changed.

h = 2 City changed.

h = 3 City and ZIP Code changed.

h = 4 State changed.

h = 5 State and ZIP Code changed.

h = 6 State and City changed.

h = 7 State, City, and ZIP Code changed.

h = 8 ZIP + 4 changed.

h = 9 ZIP and ZIP + 4 changed.

h = A City and ZIP + 4 changed.

h = B City, ZIP, and ZIP + 4 changed.

h = D State, ZIP, and ZIP + 4 changed.

h = E State, City, and ZIP + 4 changed.

Ehnn 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 second digit of the error code is a hex digit which details the changes that were made to the last line information to correct the last line. The last two digits of an error code indicate which parts of an address the application could not match to the database.

MapMarker USA 31 Developer Guide 165

Lastline Correction Codes (Continued)

Code Description

h = 0 No change in last line.

h = 2 City changed.

h = 3 City and ZIP Code changed.

h = 4 State changed.

h = 5 State and ZIP Code changed.

h = 6 State and City changed.

h = 7 State, City, and ZIP Code changed.

h = 8 ZIP + 4 changed.

h = 9 ZIP and ZIP + 4 changed.

h = A City and ZIP + 4 changed.

h = B City, ZIP, and ZIP + 4 changed.

h = C State and ZIP + 4 changed.

h = D State, ZIP, and ZIP + 4 changed.

nn = 00 No match made.

nn = 01 Low level error.

nn = 02 Could not find data file.

nn = 03 Incorrect GSD file signature or version ID.

nn = 04 GSD file out of date. Only occurs in CASS mode.

nn = 11 Input ZIP not in the directory.

nn = 12 Input city not in the directory.

nn = 13 Input city not unique in the directory.

nn = 15 Record count is depleted and license has expired.

nn = 20 No matching streets found in directory.

MapMarker USA 31 Developer Guide 166

Lastline Correction Codes (Continued)

Code Description

nn = 21 No matching cross streets for an intersection match.

nn = 22 No matching segments.

nn = 23 Unresolved match.

nn = 24 No matching segments. [Same as 022]

nn = 25 Too many possible cross streets for intersection matching.

nn = 26 No address found when attempting a multiline match.

nn = 27 Invalid directional attempted.

nn = 28 Record also matched EWS data, therefore the application denied the match.

nn = 29 No matching range, single street segment found

nn = 30 No matching range, multiple street segments found

MapMarker USA 31 Developer Guide 167

Error and No Match Codes The table of Error or No Match Codes describes the values returned when MapMarker cannot return a successful match code. If no match was made, 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.

Error or No Match Codes

Code Description

Ennn 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.

nnn = 000 No match made.

nnn = 001 Low level error.

nnn = 002 Could not find data file.

nnn = 003 Incorrect GSD file signature or version ID.

nnn = 004 GSD file out of date. Only occurs in CASS mode.

nnn = 010 No city and state or ZIP Code found.

nnn = 011 Input ZIP not in the directory.

nnn = 012 Input city not in the directory.

nnn = 013 Input city not unique in the directory.

nnn = 014 Out of licensed area. Only occurs if using Group 1 licensing technology.

nnn = 015 Record count is depleted and license has expired.

nnn = 020 No matching streets found in directory.

nnn = 021 No matching cross streets for an intersection match.

nnn = 022 No matching segments.

nnn = 023 Unresolved match.

nnn = 024 No matching segments. (Same as 022.)

nnn = 025 Too many possible cross streets for intersection matching.

MapMarker USA 31 Developer Guide 168

Error or No Match Codes (Continued)

Code Description

nnn = 026 No address found when attempting a multiline match.

nnn = 027 Invalid directional attempted.

nnn = 028 Record also matched EWS data, therefore the application denied the match.

nnn = 029 No matching range, single street segment found

nnn = 030 No matching range, multiple street segments found

Location Codes

GeoStan returns location codes that indicate the locational accuracy of the assigned geocode. Note that an accurately placed candidate is not necessarily an ideal candidate. Examine the match codes and result codes in addition to location codes to best evaluate the overall quality of the candidate. See Match Codes on page 162 and Result Codes on page 131.

See also: Address Location Codes Street Centroid Location Codes ZIP +4 Code Location Codes Geographic Location Codes Location Code Not Available

Address Location Codes Address location codes provide details about the known qualities about the geocoded address. The Structure of Address Location Codes table shows the basic format of address location codes.

Structure of Address Location Codes

Character Description

1st Always an A indicating an address location. character

2nd May be one of the following character

C Interpolated address point location.

MapMarker USA 31 Developer Guide 169

Structure of Address Location Codes (Continued)

Character Description

I Application infers the correct segment from the candidate records

P Point-level data location

R Location represents a ranged address.

S Location on a street range

X Location on an intersection of two streets

3rd and 4th Digit indicating other See the table of Address characters qualities about the Location Codes (A Codes) location.

The Address Location Codes (A Codes) table provides a detailed description of the numeric part of Address Location Codes. These codes always begin with the letter A.

Address Location Codes (A Codes)

Code Description

n = 3 The geocode is the midpoint of the street segment.

APnn Indicates a point-level geocode match representing the center of a parcel or building, where nn is one of the following values:

nn = 00 User Dictionary centroid. Geocode returned by a User Dictionary.

nn = 02 Parcel centroid. Indicates the center of an assessor’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.

nn = 04 Address point. Represents field-collected GPS points with field- collected address data.

MapMarker USA 31 Developer Guide 170

Address Location Codes (A Codes)(Continued)

Code Description

nn = 05 Structure point. Indicates a location within a building footprint polygon that is associated with the matched address. Usually, residential addresses consist of a single building. For houses with outbuildings (detached garages, sheds, barns, etc.), the structure point will typically fall on the primary structure. Condominiums and duplexes have multiple, individual addresses and may have multiple structure points for each building. Multi-unit buildings are typically represented by a single structure point associated with the primary/base address, rather than discrete structure points for each unit. Shopping malls, industrial complexes, and academic or medical center campuses are commonly represented by a single structure point associated with the primary/base address for the entire complex. When multiple addresses are assigned to multiple buildings within one complex, multiple structure points may be represented within the same complex.

nn = 07 Manually placed. Address points are manually placed to coincide with the midpoint of an assessor’s parcel’s street frontage at a distance from the center line.

nn = 08 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.

nn = 09 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.

MapMarker USA 31 Developer Guide 171

Address Location Codes (A Codes)(Continued)

Code Description

nn = 10 Street access point. Represents the primary point of access from the street network. This address point type is located where the driveway or other access road intersects the main roadway.

n=21 The Centrus point data includes individual parcels that may be "stacked".These stacked parcels are individually identified by their unit or suite number, and GeoStan is able to match to this unit number and return the correct APN.If an input address is for a building or complex, without a unit number.The "base" parcel information returns and will not standardize to a unit number or return additional information such as an APN.

AIn The correct segment is inferred from the candidate records at match time.

ASn House range address geocode. This is the most accurate geocode available.

AIn, ASn, and ACnh share the same qualities for the 3rd character n as follows:

n = 0 Best location.

n = 1 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.

n = 2 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.

n = 3 Both 1 and 2.

MapMarker USA 31 Developer Guide 172

Address Location Codes (A Codes)(Continued)

Code Description

n = 7 Placeholder. Used when starting and ending points of segments contain the same value and shape data is not available.

ACnh The ACnh 4th digit characteristics are as follows:

h = 0 Represents the interpolation between 2 points, both coming from User Dictionaries.

h = 1 Represents the interpolation between 2 points. The low boundary came from a User Dictionary and the high boundary, from a non-User Dictionary.

h = 2 Represents the interpolation between 1 point and 1 street segment end point, both coming from User Dictionaries.

h = 3 Represents the interpolation between 1 point (low boundary) and 1 street segment end point (high boundary). The low boundary came from a User Dictionary and the high boundary from a non-User Dictionary.

h = 4 Represents the interpolation between 2 points. The low boundary came from a non-User Dictionary and the high boundary from a User Dictionary.

h = 5 Represents the interpolation between 2 points, both coming from non-User Dictionaries.

h = 6 Represents the interpolation between 1 point (low boundary) and 1 street segment end point (high boundary). The low boundary came from a non-User Dictionary and the high boundary from a User Dictionary.

h = 7 Represents the interpolation between 1 point and 1 street segment end point and both came from non- User Dictionaries.

h = 8 Represents the interpolation between 1 street segment end point and1 point, both coming from User Dictionaries.

MapMarker USA 31 Developer Guide 173

Address Location Codes (A Codes)(Continued)

Code Description

h = 9 Represents the interpolation between 1 street segment end point (low boundary) and1 point (high boundary). The low boundary came from a User Dictionary and the high boundary from a non-User Dictionary.

h = A Represents the interpolation between 2 street segment end points, both coming from User Dictionaries.

h = B Represents the interpolation between 2 street segment end points. The low boundary came from a User Dictionary and the high boundary from a non-User Dictionary.

h = C Represents the interpolation between 1 street segment end point (low boundary) and1 point (high boundary). The low boundary came from a non-User Dictionary and the high boundary from a User Dictionary.

h = D Represents the interpolation between 1 street segment end point and1 point, both coming from non-User Dictionary.

h = E Represents the interpolation between 2 street segment end points. The low boundary came from a non-User Dictionary and the high boundary from a User Dictionary.

h = F Represents the interpolation between 2 street segment end points, both coming from non-User Dictionaries.

ARn Ranged address geocode, where n is one of the following:

n = 1 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.

n = 2 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.

MapMarker USA 31 Developer Guide 174

Address Location Codes (A Codes)(Continued)

Code Description

n = 4 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.

n = 7 Placeholder. Used when the starting and ending points of the matched segment contain the same value and shape data is not available.

AXn Intersection geocode, where n is one of the following:

n = 3 Standard single-point intersection computed from the center lines of street segments.

n = 8 Interpolated (divided-road) intersection geocode. Attempts to return a centroid for the intersection.

Street Centroid Location Codes Street centroid location codes indicate the Census ID accuracy and the position of the geocode on the returned street segment. The Structure of Street Centroid Location Codes shows how street centroid location codes are formatted.

Structure of Street Centroid Location Codes

Character Position Description

1st character Always C indicating a location derived from a street segment.

2nd character Census ID accuracy based on the search area used to obtain matching Street Segment.

3rd character Location of geocode on the returned street segment.

MapMarker USA 31 Developer Guide 175

The Street Centroid Location Codes (C Codes) table provides a detailed description of the street centroid location codes. These always begin with the letter C.

Street Centroid Location Codes (C Codes)

Character position Code Description

2nd Census ID Accuracy Character

B Block Group accuracy (most accurate). Based on input ZIP Code.

T Census Tract accuracy. Based on input ZIP Code.

C Unclassified Census accuracy. Normally accurate to at least the County level. Based on input ZIP Code.

F Unknown Census accuracy. Based on Finance area.

P Unknown Census accuracy. Based on input City.

3rd Character Location of candidate on segment.

C Segment Centroid.

L Segment low-range end point.

H Segment high-range end point.

ZIP +4 Code Location Codes

ZIP + 4® centroid location codes indicate the quality of two location attributes: Census ID accuracy and positional accuracy. The Structure of ZIP+4 Location Codes table shows how the ZIP+4 centroid location codes are formatted.

Structure of ZIP+4 Location Codes

Character Position Description

1st character Always Z indicating a location derived from a ZIP centroid.

2nd character Census ID accuracy.

MapMarker USA 31 Developer Guide 176

Structure of ZIP+4 Location Codes (Continued)

Character Position Description

3rd character Location type.

4th character How the location and Census ID was defined. Provided for completeness, but may not be useful for most applications.

The ZIP +4 Centroid Location Codes (Z Codes) table provides a detailed description of the ZIP+4 centroid location codes. These always begin with the letter Z.

ZIP +4 Centroid Location Codes (Z Codes)

Character position Code Description

2nd Character

B Block Group accuracy (most accurate).

T Census Tract accuracy.

C Unclassified Census accuracy. Normally accurate to at least the County level.

3rd Character

5 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.

7 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.

9 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.

4th Character

MapMarker USA 31 Developer Guide 177

ZIP +4 Centroid Location Codes (Z Codes) (Continued)

Character position Code Description

A Address matched to a single segment. Location assigned in the middle of the matched street segment, offset to the proper side of the street.

a 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.

B 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.

b 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.

C 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.

c 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.

MapMarker USA 31 Developer Guide 178

ZIP +4 Centroid Location Codes (Z Codes) (Continued)

Character position Code Description

D 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.

d 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 the street, as address ranges increase.

E 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.

F 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.

G 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.

H Same as methodology G, but some segments are not in the same County. Used for less than .05% of the centroids.

I 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.

MapMarker USA 31 Developer Guide 179

ZIP +4 Centroid Location Codes (Z Codes) (Continued)

Character position Code Description

J 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.

K 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.

L Created ZIP + 2 cluster centroid as defined by methodology E. All centroids in this ZIP + 2 cluster have the same Block Group. Location assigned to the ZIP + 2 centroid.

M 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.

N Created ZIP + 2 cluster centroid as defined by methodology E, F, G, and H. Location assigned to the ZIP + 2 centroid.

V Over 95% of addresses in this ZIP Code are in a single Census Tract. Location assigned to the ZIP Code centroid.

W 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.

X 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.

Y Rural or sparsely populated area. Census code is uncertain. Location based upon the USGS places file.

Z 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

MapMarker USA 31 Developer Guide 180

Geographic Location Codes Geographic centroid location codes indicate the quality of two location attributes: the geographic location and area type.The Structure of Geographic Location Codes table shows how the geographic centroid location codes are formatted.

Structure of Geographic Location Codes

Character Position Description

1st character Always G indicating a location derived from a geographic centroid.

2nd character Geographic area type.

The Geographic Location Codes (G Codes) table provides a detailed description of the geographic centroid location codes. These always begin with the letter G.

Geographic Location Codes (G Codes)

Character position Code Description

2nd Character

M Municipality (city).

C County.

S State.

Location Code Not Available A Location Code of E indicates a location code is not available. This usually occurs when you have requested ZIP Code centroids of a high quality, and one is not available for that match. This occurs infrequently when the address dictionary does not have a 5-digit centroid location. An E Location code is also returned when the input address cannot be standardized and there is no input ZIP Code. In that case, because the ZIP Code returned with the non-standardized address may not be correct, GeoStan does not return geocoding or Census Block information.

Using Status Codes

In the Desktop application, geocoded tables can include output columns for Result Codes, Match Codes, and Location Codes (if the appropriate output address columns are mapped). See Using the Georesult Dialog on page 102.

MapMarker USA 31 Developer Guide 181

Result Codes are the 1-10 character alphanumeric codes that provide detailed information on how the candidate match was made. Successfully geocoded candidates begin with either: S or M (street geocode), Z (postcode geocode), or G (geographic geocode). See Result Codes in Chapter 5 on page 95 for a complete explanation of Result Codes. Match Codes and Location Codes give you a more granular and detailed representation of geocode quality. When used together, these codes provide a very effective means of evaluating the accuracy and quality of close match candidates. The Match Codes and Location Codes are described in this appendix (Match Codes on page 162 and Location Codes on page 169).

See also: Match Codes on page 162 Location Codes on page 169 Result Codes on page 131

Evaluating Candidate Match Quality Examine and compare Result Codes, Match Codes, and Location Codes for a comprehensive view of candidate quality. Result Codes can be used independently. See Result Codes in Chapter 7 on page 131 for complete coverage of Result Codes. . Following are several examples that illustrate how Result Codes, Match Codes, and Location Codes can be used together to evaluate candidate quality. Note: In the following examples, Standard Match Mode is used. Results would be different if you used more restrictive or less restrictive matching. See Setting Match Modes on page 36 for a description of match modes and how they are best used to meet your application requirements and input data quality. Also see Chapter 4 Match Settings and Strategies

Good Match Code but Result Code and Location Code quality is low. Consider the following input example.

StreetAddress: RD 1 Box 502 City: Massena State: NY ZIP: 13662-9750 Using Standard Match Mode, this returns the following close match candidate:

MainAddress: PO BOX 502 City: MASSENA State: NY ZIP:13662 ZIP+4: 0502 Result Code: S1HPNTSCZA Match Code: S80 Location Code: ZC5X S1 Result Code: indicates ZIP Code accuracy only.

MapMarker USA 31 Developer Guide 182

S80 Match Code: S indicates a direct match to a known street address in the USPS data. 8 indicates that the ZIP+4 changed 0 indicates no change in the last line of the input address. ZC5X Location Code: indicates ZIP centroid with county accuracy. The X in the fourth position indicates that the Census ID is uncertain. This is the best close match given the input data and your business rules and match preferences. While this is not a highly accurate candidate placement (ZIP centroid within the county), this may be suitable for your business application.

Good Location Code and Result Code but Match Code is low quality. Consider the following input example.

9300 Main Kansas City, MO 66109 Using Standard Match Mode, this returns the following close match candidate:

MainAddress: 9300 MAIN ST City: KANSAS CITY State: KS ZIP: 66109 Result Code: S5HPN-SCZA Match Code: TC1 Location Code: AS0 S5 Result Code: indicates a single close match along the street segment. TC1 Match Code: T indicates a match to a non-USPS record. C means that the State and ZIP+4 were changed 1 means that the street type was changed. AS0 Location Code: indicates a best possible location address location on a street range. This candidate is the best available match given the user criteria and input. The Match Code indicates that several address elements were changed to achieve the match (including the changed state). Depending on your business application and rules, this candidate may or may not be suitable. Use the Match and Location Codes to evaluate the returned candidates and decide whether you should accept candidates, based on your business rules. In some cases, you may want to consider more restrictive matching preferences (such as Must Match State) to get candidates that are more suitable for your application.

Good Match Code but the quality of the geocode is low. Consider the following input example.

70 Indian Mt Lakes Albrightsville, PA 18210 Using Standard Match Mode, this returns the following close match candidate:

MainAddress: 70 INDIAN MOUNTAIN LKS City: ALBRIGHTSVILLE

MapMarker USA 31 Developer Guide 183

State: PA ZIP: 18210-3004 Result Code: S1HP-TSCZA Match Code: A88 Location Code: ZC5W S1 Result Code: ZIP Code accuracy only. A88 Match Code: A indicates matched to USPS data with alias street name. 8 indicates ZIP+4 was changed to achieve the match. 8 indicates Street name was changed to achieve the match. ZC5W Location Code: indicates unclassified Census accuracy with the location assigned to the ZIP Code centroid. This geocoded candidate is suitable for some applications, such as address standardization. However it may not be a suitable candidate if your application demands highly accurate address placement.

Good Match, Location, and Result Codes for high quality candidate. Consider the following input example.

2762 S King Street Denver, CO 80236 Using Standard Match Mode, this returns the following close match candidate:

2762 S KING ST DENVER, CO 80236-2514 Result Code: S8HPNTSCZA Match Code: S80 Location Code: AP02 S8 Result Code indicates a single close match to point data. S80 Match Code: S indicates a direct match to a known street address in the USPS data. 8 indicates ZIP+4 was changed. 0 indicates no change made in address line. AP02 Location Code: indicates point level geocode to a parcel centroid. This is a high quality match with a high quality geocode, as measured by all criteria (Result Code, Match Code, Location Code).

MapMarker USA 31 Developer Guide 184 Index

A creating web client sample code 90 creating web geocoding client 53 address cleansing 7 address dictionary D available 8 definition 30 address matching data source information geocoding 5 returning 77 address point interpolation 67, 133 database development tools 154 address standardization 89 DataManagerSettings addresses address dictionary path 35 browsing 80 centerline offset entry 68 input 23, 24 configuring 35, 51 result code information 27 multi-threaded environment 51 airport geocoding 85 deployment as servlet 126 airports dictionary result information 28 finding by code 86 dictionary usage preference finding by state 85 64 alternate lookup values DPV USA_GeocodeConstraints 63 availability and status 86 B E

best match from multiple candidates Envinsa 19 result codes 139 error message reference 156 browsing addresses 80 Exact Match Mode 37 expanded search results C returning 70 F candidate quality evaluating 181 candidates fallback preferences 20 definition 30 fallback to geographic 58 retrieving 71 fallback to postal centerline offset GeocodeConstraints 58 in properties file 68 using 68 G centroid definition 31 generic preferences 24 city geocode requests geographic candidate returns 48 contents of 26 close match geocode subtypes definition 31 REST API 92 closematch key 56 geocode types 21, 27 CMRA REST API 92 definition 31 GeocodeConstraints 55, 58, 69 common schema 143 fallback to geographic 58 configuration file fallback to postal 58 JNI adapter 152 maximum candidates 58 constants must match 58 match mode 65 geocoding constraints 60 airports 85 geocoding 19, 55 constraints 19 coordinate systems geographic centroids 82, 83 JNI adapter configuration file settings 152 highway exits 84 setting in applications 66 model 19, 20 country settings 152

MapMarker USA 31 Developer Guide 185 Index result codes 26, 27 M geocoding applications choosing development tool 17, 18 XML programming in .NET 92 MapMarker geocoding constraints 60 features 13 geocoding request types 148 technical support 15 geocoding results MapMarker server result codes 132, 141 deploying in Web environments 126 geocoding terms 30 MapMarker Streets geographic candidate using with MapMarker 14 return fields 47 MapXtreme 18 geographic centroid geocoding 82, 83 match codes 162 geographic geocoding 47 evaluating candidates 181 getDBType method 77 hex digits 163 getPrecisionCode method 80 lastline corrections 164 getsegmentID method 72 returning 88 values 162 H match mode constants and methods 65 matching addresses with geographic data 5 highway exit geocoding 84 maximum candidates GeocodeConstraints 58 I methods match mode 65 input addresses MMJCommon.xsd 143 building 23, 24 MMJRequest.xsd 143 setting 54 MMJResponse.xsd 143 integrating multiple country geocoders 127 multiple country integration 127 must match J definition 32 GeocodeConstraints 58 USA_GeocodeConstraints 61 Java API creating an application 53 N Java Generic API 53 Java USA API 53 JavaDocs location 53 non-match result codes 141 JNI adapter configuration file settings 152 O JVM settings 152 optimizing server performance 51 K Oracle geocoding extender 154 key P closematch 56 performance L optimizing 28 PMB latitude definition 32 street candidate returns 44, 47 positional accuracy of points location codes 169 result code information 27 address location 169 postal candidate evaluating candidates 181 return fields 47 geographic location 181 postal centroid match returning 88 result codes 140 street centroid location 175 postal geocoding 22, 46 ZIP centroid location 176 definition 32 longitude post-Directional street candidate returns 44, 47 definition 32 postType definition 32

MapMarker USA 31 Developer Guide 186 Index pre-Directional S8 result 134 definition 33 sample application preferences MapMarker 29 generic and U.S. 24 requirements 34 sample application 36 testing the server 35 usage examples 24, 25 using 34–35, 40, 47 preType sample code definition 33 creating web client 90 SC 136 R schemas MapMarker 143 search level values range information USA_GeocodeConstraints 63 returning 75 segment ID 72 range unit information sending geocode requests 26 returning 75 servlet deployment 126 Relaxed Match Mode 38 setting request schema 143 geocoding constraints 60 request types 148 input address 54 response schema 143 short address information REST API returning 76 character encoding 100 single match result codes 133 constraints 95, 97 SQL Server geocoding extender 154 input parameters 93 Standard Match Mode 37 response 99 standardizing addresses 89 using 91 street address XML 101 street candidate returns 41 result codes street geocoding 40 address point interpolation 133 street geocoding candidates 41 best match from multiple candidates 139 street level geocoding complete M code 136 definition 33 complete S code 136 street name definition 33 definition 33 G category 140 street-level geocoding 21 geographic candidate returns 48 support geographic matches 140 technical support 15 interpreting 26, 27 M category 139 N category 141 T non-match codes 141 postal candidate returns 47 technical support 15 postal centroid matches 140 Tomcat returning 72 configuring as a Windows service 126 S category 133 tomcat servlet container 126 S3 and Z3 comparison 139 S5 138 U S6 138 S7 138 USA_GeocodeConstraints 60 S8 137 must match 61 single close match 133 user dictionary 61 Z category 140 user dictionary reverse geocoding 48 definition 33 reverse geocoding candidate USA_GeocodeConstraints 61 return fields 49 reverseGeocode method 80 W S war files 126 Web environments 126 S1 result 135 web geocoding client S3 result 135 creating 53 S5 result 134, 135 WebLogic 126 S6 result 134

MapMarker USA 31 Developer Guide 187 Index

WebSphere 126 wide search 69 Windows service configuring Tomcat as a service 126 X

XML geocoding constraint keys 144 schemas 143 XML API 92 overview 142 Z

Z1 result 136 Z2 result 136 Z3 result 136 Z6 result 136

MapMarker USA 31 Developer Guide 188