mapmarker usa v29 developer guide

Location IntelligenceGeographic Information Systems

MapMarker PlusVersion 29

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, One Global View, Troy, New York 12180-8399.©1994-2016 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:: www.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.08Portions © 2016 TomTom Inc.© 1987 - 2014 HERE. All rights reservedShapefile C Library v. 1.2.10 is licensed under the MIT Style License. The license can be downloaded from: http://shapelib.maptools.org/license.html. © 1998 Frank Warmerdam. The source code for this library is available from http://shapelib.maptools.org/.August 2016

http://shapelib.maptools.org/license.html

http://shapelib.maptools.org/

http://www.pb.com/contact-us/

Table of Contents

MapMarker USA 29 Developer Guide 3

1 - Introduction 4

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

2 - Designing Geocoding Applications17

Choosing a Development Tool 18Defining the Geocoding Model 20Geocoding Application Design Overview 22

3 - Geocoding with MapMarker USA 30

Geocoding Terms 31Address Conventions for MapMarker USA 34Geocoding with MapMarker USA 35Sample Application Requirements and Setup35Running the Sample Application 36Using the MapMarker USA Sample Application36Street Geocoding 41Postal Geocoding 47Geographic Geocoding 48Reverse Geocoding 49Optimizing MapMarker USA – Usability and Performance Tips 51

4 - Using the MapMarker Java API 53

Using the MapMarker Java USA API 54Using the MapMarker Generic Java API 54Using the JavaDocs API Documentation 54Developing Geocoding Applications in Java 54Geocoding and Returning Candidate Information71Creating a Reverse Geocoding Application in Java 80Browsing Addresses 82Geocoding To Postal Centroids 83Geocoding to Geographic Centroids 84Geocoding to Highway Exits 86Geocoding to Airports 87DPV Related Actions 88Returning Match Codes and Location Codes90Standardizing Addresses 91Creating a Web Geocoding Client in Java 92

5 - Using the REST API 93

REST API Framework and Syntax 94Usage Guidelines 101REST API Examples 103

6 - Deploying Applications 127

Deploying MapMarker as a Servlet 128Integration with MapMarker for Other Countries129

7 - Result Codes 133

Understanding Result Codes 134Single Match (S category) 135Best Match From Multiple Candidates (M category) 141Postal Centroid Matches (Z category) 142Geographic Matches (G category) 142Reverse Geocoded Matches (R category) 142Non-match Codes (N category) 143

A - Using the XML API 144

Tips on Using the XSD Schemas 145Geocoding Constraint Keys 146Geocoding Request Types 150

B - JNI Adapter Configuration File Settings 153

JVM Settings 154Country Settings 154

C - Using Database Extenders 155

Geocoding Extenders for Database Developers 156

D - Error Messages 157

MapMarker Java API Errors 158

E - Match Codes and Location Codes163

Match Codes 164Location Codes 171Using Status Codes 183

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? 5What Is MapMarker? 5MapMarker Features 6MapMarker Documentation Set 13MapMarker Streets 14Getting 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.


http://www.pitneybowes.com/us/location-intelligence.html?products-tab#location-intelligence-software

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 FeaturesMapMarker 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 InstallerThe MapMarker USA 29 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 GeocodingIf 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.


http://www.pbinsight.com/support/product-documentation/details/mapmarker-mapmarker-plus-us

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 GeocodingMapMarker 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 135 for a description of all result codes.

PlaceName GeocodingPlaceNames 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 InputMapMarker can geocode single line addresses, in which all address components appear on a single line rather than in separate fields.

Address CleansingMapMarker 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 GeocodingIf 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.


Introduction

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

Geographic GeocodingIf 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 142 for a description of G result codes.

Reverse GeocodingWith reverse geocoding, you can provide X/Y (Longitude/Latitude) coordinates and MapMarker USA 29 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 v29 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 49 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 DictionariesThe 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.



Introduction

User DictionariesA 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 DataMapMarker 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.

AttributionYou 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 GeocodingMapMarker 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 GeocodingMapMarker 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 FilesYou 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.


Introduction

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

Display Geocoded Points on MapMapMarker 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 BrowsingThe 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 CodesMapMarker 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 134.

Match Codes and Location CodesMapMarker 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 163.


Introduction

Segment IDsSegment IDs are numeric codes that uniquely identify each point or street centroid candidate. The MapMarker USA 29 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 73 for more information.

Note: Segment IDs are available through the Server API only (not with the Desktop Application).

Wide SearchYou 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 70 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 CandidatesIf 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, NAVTEQ 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 69 to see how to implement this using the Java API.

Expanded SearchMapMarker 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.


Introduction

Search Level Constraints for Finance Area and CityYou 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 SearchMapMarker 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 71 for an example using the Java API methods.

MapMarker Desktop ApplicationThe 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 ServerMapMarker 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.


Introduction

Developer Tools and REST APIThe 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 v29 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 ProfessionalMapInfo 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 SetThe 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 GuideThe 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


http://www.pbinsight.com/support/product-documentation/m/details/mapmarker-mapmarker-plus-us


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 HelpIn 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 GuideThis 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 NotesThe 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 WebThe 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 StreetsOnce 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.





Introduction

Getting Technical SupportPitney 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:

The Americas

Support: 800 552 2511Fax: 518.285.6080 E-mail: [email protected]: Monday - Friday from 8:00am - 7:00pm EST, excluding company holidays.

Europe/Middle East/Africa:

Support: +44 1634.880.141Fax: +44 1634.880.383 E-mail: [email protected]: Monday - Friday from 9am to 5pm GMT, excluding company holidays.

Asia-Pacific Headquarters

Support: 1800 648 899Hours: Monday–Friday from 8:00am and 6:00pm (EST) Australian Eastern Standard Time, excluding company holidays.

Fax: 61.2.9439.1773Main Office Phone (Sydney): 61. 2.9437.6255E-mail: [email protected]

Before You Call

Please have the following information ready when contacting us for assistance on MapMarker USA.

1. Serial Number. You must have a registered serial number to receive Technical Support.

2. Your name and organization. The person calling must be the contact person listed on the support agreement.

3. Version of the product you are calling about.

4. The operating system name and version.

5. A brief explanation of the problem. Some details that can be helpful in this context are:

• Error messages• Context in which the problem occurs• Consistency – is the problem reoccurring or occurring erratically?


mailto:[email protected]



Introduction

The Support Tracking System

The Support Tracking System is used internally by the Technical Support department to manage and track customer issues. The system also provides the ability to track calls with accountability. This system helps Tech Support respond to all customer issues effectively, efficiently, and fairly.

Expected Response Time

Most issues can be resolved during the customer’s initial call. If this is not possible, a response will be issued before the end of the business day. A Technical Support representative will provide a status each business day until the issue is resolved.

Support requests submitted by e-mail are handled using the same guidelines as telephone support requests; however, there is an unavoidable delay of up to several hours for message transmission and recognition.

Exchanging Information

Occasionally a Technical Support representative will ask you to provide sample data in order to duplicate your scenario. In the case of our developer tools (such as MapXtreme), a small subset of sample code may be requested to help duplicate the issue.

The preferred method of exchanging information is either via e-mail or our FTP site. Use the following e-mail address:

• Globally – [email protected]

Accessing the FTP site

For information regarding our FTP site, please contact Technical Support. If information cannot be provided electronically, we also accept information in the following media formats:

• CD• DVD

Software Defects

If the issue is deemed to be a bug in the software, the representative will log the issue in our bug base and provide you with an incident number that can be used to track the bug.



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 18Defining the Geocoding Model 20Geocoding Application Design Overview 22

Designing Geocoding Applications

Choosing a Development ToolWhen 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 InteroperabilityThe 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.



The following table summarizes the geocoding solutions available.

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

MapMarker 29• 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 54 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

ProductWeb/

Desktop* OSProgramming Language Capabilities

MapMarker USA 29 Both Windows, Solaris, HP-UNIX, Linux

Java Geocoding

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

Envinsa Both (App Server)

Windows, Solaris, Linux

Java, XML, .NET, and Web Services

Geocoding, Mapping, Routing, and more



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 ModelThe 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 ConstraintsThe 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 56 and USA_GeocodeConstraints on page 61.



Fallback PreferencesEnabling 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 DataThe 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 ApplicationGeocoding 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.



Geocoding Application Design OverviewAll 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 GeocodingMapMarker 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.




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.



Building an Input AddressThe 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.

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

Generic AddressCountry-Specific 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 AreaName1

State NY

Primary Postcode or Postcode1

ZIP Code™ 12180

Secondary Postcode or Postcode2

ZIP + 4® 8337

Municipality Subdivision or AreaName4

Urbanization Parc Sabana (used in Puerto Rico)

Urbanization is use for Puerto Rico. only. Leave blank if not geocoding Puerto Rican addresses.

*Country (required for generic)

Set by default USA



Using ConstraintsAs explained in Geocoding Constraints on page 20, 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 56 and USA_GeocodeConstraints on page 61 (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.

Desired Geocoding Level Required Input Fields Other Requirements

Street street and ZIP Code, or street, city, and state

country required in generic 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 county optional

Available through Java API



Matching on Address Number

When you enable the Must Match Address Number constraint, the input address:

350 Ocean DriveKey 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:


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:


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



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 RequestThe 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 ResponseThe 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 InformationThe 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.



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)



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 PerformanceConsider 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 52.


3
3 – Geocoding with
MapMarker USA

This chapter describes the major MapMarker USA 29 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 29 comes with a Java client sample application that illustrates how to geocode American addresses.

In this chapter:

Geocoding Terms 31Address Conventions for MapMarker USA 34Geocoding with MapMarker USA 35Sample Application Requirements and Setup 35Running the Sample Application 36Using the MapMarker USA Sample Application 36Street Geocoding 41Postal Geocoding 47Geographic Geocoding 48Optimizing MapMarker USA – Usability and Performance Tips 51

Geocoding with MapMarker USA

Geocoding TermsMapMarker 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 32.

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.



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.

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

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

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.


Term Definition



Address Conventions for MapMarker USAThis section describes some address conventions for American addresses and MapMarker USA 29.

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.

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

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.


Term Definition


http://www.usps.com/send/preparemailandpackages/labelsandaddressing/usingthecorrectaddress.htm

http://www.usps.com/send/preparemailandpackages/labelsandaddressing/usingthecorrectaddress.htm

http://zip4.usps.com/zip4/welcome.jsp


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

Geocoding with MapMarker USAThe 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 SetupBefore 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.

Address Elements

Address Element Description Example

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

1 GLOBAL VW

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

TROY

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

NY

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

12180



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 ApplicationThe MapMarker sample application is a Java client that illustrates how to geocode USA addresses using the MapMarker USA 29 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 ServerThe 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 ApplicationThe MapMarker sample application is a Java client that illustrates how to geocode USA addresses using the MapMarker USA 29 server.

The sample application is provided for example and demonstration purposes and to help you become familiar with MapMarker USA 29. 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:

<install>/sdk/tomcat/webapps/mapmarker40/WEB-INF/classes



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

DICTIONARY_COUNT=1DICTIONARY_PATH1=<install>/MapMarker_USA_v29_Data/

See also About the Address Dictionary on page 24.

Setting PreferencesThere 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 ConstraintsThere 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 56.

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



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

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



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.

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.


Mode Description



For information on implementing match modes using the Java API, see Using Match Modes on page 66.

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 GeocodingIf you provide a street address, and either a ort or a postcode, you can perform an address geocode. MapMarker USA 29 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 29 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 37 for information how the sample application allows you to control constraints.

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.


Mode Description



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

Street Candidate ReturnsThe 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 163 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 candidates. See Result Codes on page 133 for a description of the MapMarker result codes.

S5HPNTS-ZA

DPV_NO_STAT DPV No Status flag N

DPV_FN1 DPV Footnote 1

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

AA



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 two-digit code that, together with Check Digit, is used to form the delivery point barcode on mail pieces.

29

REC_TYPE Record Type

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

S

DPV_NOSTAT Y – The address is vacant.

N –The address is not vacant.

Blank – DPV is not loaded or DPV did not confirm (so vacancy is irrelevant).

N

Street Candidate Return Fields (Continued)




DPV_VACANT Y – The address was valid for 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.

Y

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

N

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

L

LACSLINK_INDICATOR Y – input address was LACSLink 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.

Y

LACSLINK_RESULT_CODE

provides information about the LACSLink output address. This is always paired with LACS_LINK_INDICATOR

A





Intersection GeocodingMapMarker 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 RdState: NYCity: Troy

The returned close match candidate includes the following output:

Address: Global View at Jordan RdLastline: Troy, NY 12180

SUITELINK_RETCODE A – SuiteLink match. Secondary 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.

A

SEGMENT_ID unique Segment ID 959436

CENSUS_BLOCK Census Block 360930329011005

DPV_CONF DPV Confirmation Code Y

USA_SHORT_ADDRESSLINE

CASS Abbreviated Address 29 LONG AVE

USA_SHORT_CITYNAME

CASS Short City Name SCHENECTADY

Long Longitude (X Coordinates) -79.391177

Lat Latitude (Y Coordinates) 43.64351





GeoResult: S5HPNTSCZALong: -73.699899</X>Lat: 42.682433

PlaceName GeocodingFor 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: MapInfoCity: TroyState: NYPostal Code: 12180

The returned close match candidate includes the following output:

PlaceName: Map InfoAddress: 1 Global VwLastline: Troy, NY 12180-8399GeoResult: S5HP--S-ZALong: -73.702914Lat: 42.682858

Fallback to PostalIf MapMarker USA 29 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 29 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 DriveCity: Key BiscayneState: FLPostal 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 47.



Fallback to GeographicIf MapMarker USA 29 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 29 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 DrCity: IthacaState: NYPostal 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 48.

Postal GeocodingMapMarker USA 29 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 46



Postal Candidate ReturnsPostal geocoding requests returns a single matching postcode.

The following table shows the Postal Candidate Return Fields in the MapMarker USA 29 sample application. Census data may also be returned, but is not shown in this table.

Geographic GeocodingMapMarker USA 29 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: MoabState: 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 47.

Geographic Candidate ReturnsGeographic geocoding requests returns a single matching postcode.

The following table shows the Geographic Candidate Return Fields in the MapMarker USA 29 sample application. The other fields are not relevant to geographic geocoding, and will be empty for geographic geocoding candidates.

Postal Candidate Return Fields

Column Name Contents and Description Example

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

T

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

Z3



Reverse GeocodingIf you provide X/Y (Longitude/Latitude) coordinates, MapMarker USA 29 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 125 for an example of reverse geocoding using the REST API.

See Setting Reverse Geocoding Distance and Offset Constraints on page 81 for information on reverse geocoding using the Java API.

The following input can be reverse geocoded:

Longitude (X): -79.391177Latitude (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 81 for information.

Note: Reverse geocoding is available for all covered states and territories except Guam.

Geographic Candidate Return Fields

Column Name Contents and Description Example

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

T

City Result code for returned candidates. (AreaName3)

Moab

State State UT

Long X coordinate -109.54917

Lat Y coordinate 38.57333

Result Result code for returned candidate

G3 result codes indicate a geography match on an City centroid.



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

Reverse Geocoding Candidate ReturnsReverse 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.391177Y: 43.64351

MapMarker USA v29 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 142.• Candidates include a house number, if one is available.• Candidates from a street segment dictionary include range information for the segment.



For an example of the XML output generated by reverse geocoding operation, see Reverse Geocode on page 125.

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 79 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 29.

General Guidelines for Optimizing GeocodingMapMarker USA 29 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 29 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 52.


http://zip4.usps.com/zip4/welcome.jsp


Batch Geocoding GuidelinesIn addition to General Guidelines for Optimizing Geocoding on page 51, 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:setCloseMatchsetMaxCandidates(int)setMaxRanges(int)

In the XML API, specify the following in the BaseConstraints:closeMatchOnly="true"<maxCandidates>1</maxCandidates><maxRanges>0</maxRanges>

Optimizing Server PerformanceThe 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.


http://reference1.mapinfo.com/Data/World PPOI Data/2016.07 V3.2/WPPOIVer3.2Micode_Lookup.xlsx

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

In this chapter:

Using the MapMarker Java USA API 54Using the MapMarker Generic Java API 54Using the JavaDocs API Documentation 54Developing Geocoding Applications in Java 54Geocoding and Returning Candidate Information 71Creating a Reverse Geocoding Application in Java 80Browsing Addresses 82Geocoding To Postal Centroids 83Geocoding to Geographic Centroids 84Geocoding to Highway Exits 86Geocoding to Airports 87DPV Related Actions 88Returning Match Codes and Location Codes 90Standardizing Addresses 91Creating a Web Geocoding Client in Java 92

Using the MapMarker Java API

Using the MapMarker Java USA APIThe 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 APIThe 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 129.

For complete API documentation, see Using the JavaDocs API Documentation.

Using the JavaDocs API DocumentationFor detailed information on all API packages, interfaces, and classes, refer to the API documentation (Javadocs) for MapMarker.

the JavaDocs is located in <install >/docs/usa folder, where <install> 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 JavaYou 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. See Required Files on page 27 for a complete list of required jar files.

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.

Setting Import StatementsMake 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 AddressFollowing 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:

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



Geocode Constraints

Key and Method Description Default

KEY_ADDRESS_POINT_INTERPOLATION

setUseAddressPointInterpolation(boolean flag)

Determines whether address point candidates are offset from the associated segment when possible. See Using Address Point Interpolation on page 68.

"false"

setGeocodeType(IGeocodeConstraints)

Indicates what kind of geocode is requested. Possible values are:TYPE_GEOCODE_MATCH_ADDRESSTYPE_GEOCODE_MATCH_POSTCODETYPE_GEOCODE_MATCH_GEOGRAPHICTYPE_GEOCODE_MATCH_BROWSETYPE_GEOCODE_MATCH_STANDARDIZE_ONLY

GeocodeConstraints.TYPE_GEOCODE_MATCH_ADDRESS

KEY_CLIENT_CRS

setClientCoordinateSystem(String crsString)

setClientCoordinateSystem(com.mapinfo.coordsys.CoordSys coordSys)

String describing the client coordinate system. Accepted values include EPSG SRS Names as well as MAPINFO MAPBASIC Projection String SRS Names. (see com.mapinfo.coordsys.CoordSys). Default uses WGS 84.

"epsg:4326"

KEY_CLIENT_LOCALE

setClientLocale(String)

Indicates the client locale, such as:en_US or fr_CA.

"en_US"

KEY_CLOSEMATCHESONLY

setReturnCloseCandidatesOnly(boolean bReturn)

Only close matches are returned.

"false"



KEY_CORNEROFFSET

setCornerOffset(double offset)

Defines the offset position of the geocoded point with respect to the corner.

"25"

KEY_CORNEROFFSETUNITS

setCornerOffsetUnits(String units)

The units used in KEY_CORNEROFFSET (ft, m, mi, km, in, yd, cm, and mm)

"ft" (feet)

KEY_DICTIONARY_SEARCH_ORDER

setDictionarySearchOrder (IDictionarySearchOrder newOrder)

Sets a custom order for searching configured address/user dictionaries. See the IDictionarySearchOrder interface in the JavaDocs (com.mapinfo.mapmarker.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)

ordered by DICTIONARY_PATH#

KEY_DICTIONARY_USAGE

setDictionaryUsage(DictionaryUsagePreference pref)

Returns the key for dictionary usage preference. (AD_ONLY, UD_ONLY, AD_AND_UD, PREFER_AD, PREFER_UD)

For a description of these values, see Dictionary Usage Preference on page 65.

AD_AND_UD

Geocode Constraints (Continued)




KEY_FALLBACK_TO_GEOGRAPHIC

setFallbackToGeographic(booleanbFallback)

If no close street level candidates are found, return geographic centroid for the input address.

"false"

KEY_FALLBACK_TO_POSTAL

setFallbackToPostal(booleanbFallback)

If no close street level candidates are found, return postal centroid for the input address.

"false"

KEY_MATCH_MODE

setMatchMode(String MMString)

Contains the match mode value. This must be one of the defined match modes. The possible key values are described in Using Match Modes on page 66.

null

KEY_MAXCANDIDATES

setMaxCandidates(int m_maxCandidates)

Max candidates to return.

(use "-1" to return all candidates).

"3"

KEY_MAXRANGES

setMaxRanges(int m_maxRanges)

Max ranges per candidate to return (use "-1" to return all ranges).

"0"

KEY_MAXRANGEUNITS

setMaxRangeUnits(int m_maxRangeUnits)

Max units per range to return. (use "-1" to return all range units)

"0"

KEY_MUST_MATCH_ADDRNUM

setMustMatchAddressNumber(boolean bMatch)

Only candidates matching address number are considered close.

"false"





KEY_MUST_MATCH_AREA1

setMustMatchArea1(boolean bMatch)

Only candidates matching a country subdivision (areaname1) are considered close (state for USA).

"false"



Only candidates matching geographic areaname 2 are considered close.

"false"



Only candidates matching a city or town are considered close.

"false"



Only candidates matching geographic area 4 are considered close.

"false"

KEY_MUST_MATCH_COUNTRY

setMustMatchCountry(bMatch)

Only candidates matching teh country are considered close.

"true"

KEY_MUST_MATCH_INPUT

setMustMatchInput(boolean bMatch)

Only candidates matching all input areas (where MUST_MATCH is defined) are considered close.

"false"

KEY_MUST_MATCH_MAINADDR

setMustMatchMainAddress(boolean bMatch)

Only candidates matching the main address are considered close.

"false"

KEY_MUST_MATCH_POSTAL

setMustMatchPostalCode(boolean bMatch)

Only candidates matching postal code are considered close.

"false"





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

USA_GeocodeConstraintscom.mapinfo.mapmarker.USA.USA_GeocodeConstraints

KEY_STREETOFFSET

setStreetOffset(double offset)

Defines the position of the geocoded point with respect to the centerline of the street.

"25"

KEY_STREETOFFSETUNITS

setStreetOffsetUnits(String units)

The units used in KEY_STREETOFFSET (ft, m, mi, km, in, yd, cm, and mm).

"ft" (feet)

POINT_CENTERLINE_OFFSET

setCenterlineOffset(double value)

Defines the offset distance to use for point centerline interpolation.

"25"

POINT_CENTERLINE_OFFSET_UNITS

setCenterlineOffsetUnit(String unit)

The units used in POINT_CENTERLINE_OFFSET (ft, m, mi, km, in, yd, cm, and mm).

"ft" (feet)

USE_POINT_CENTERLINE_OFFSET

setUseCenterlineOffset(boolean flag)

Determines whether centerline offset is used. See Using Centerline Offset for Point Candidates on page 69.

"false"





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_ALTERNATE_LOOKUP

setAlternateLookupPreference

Determines whether the preferred lookup is to look for streets first or firm name (places) first.

See KEY_ALTERNATE_LOOKUP Values.

STREET_FIRST

KEY_CASS_DPV

setDPVMode

Enable DPV. "false"

KEY_LACSLINK

setUseLACSLinkEnable LACSLink. "false"

KEY_MUST_MATCH_CITY

setMustMatchCity

Requires city/town match for a close match.

Base equivalent AREA3

"false"

KEY_MUST_MATCH_STREET

setMustMatchStreet

Requires street name match for a close match.

Base equivalent STREET.

"false"

KEY_MUST_MATCH_ZIPCODE

setMustMatchZipcode

Requires ZIP Code™ match for a close match.

Base equivalent POSTAL.

"false"

KEY_PREFER_USER_DICTIONARY

setDictionaryUsage

When using Address Dictionary and User Dictionary together, prefer a UD close match over an AD close match.

"false"



KEY_ZIP_OVER_CITY

setPreferZipMatchOverCity

Prefer ZIP Code match over a city match.

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.

"false"

KEY_SEARCH_LEVEL

setSearchLevel

setUseExpandedSearch(deprecated in v25)

The setSearchLevel method can be used to set finance area, city, or expanded search levels.

See KEY_SEARCH_LEVEL Values.

The deprecated setUseExpandedSearch method can be used to set expanded search. This is false by default.

setSearchLevel is set to Finance Area by default for CASS mode and City for all other modes.

SUITELINK

setUseSuiteLinkEnable SuiteLink. SuiteLink will append the secondary (suite) information to a business address providing the input address is determined to be a highrise default record.

"false"

USA_GeocodeConstraints (Continued)




WIDE_SEARCH

setUseWideSearch

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

."false"

KEY_ALTERNATE_LOOKUP Values

VALUE_ALTERNATE_LOOKUP_OFF

Only candidates matching on street are considered.

The value for KEY_ALTERNATE_LOOKUP = "STREET_ONLY"

VALUE_ALTERNATE_LOOKUP_PLACE

Candidates matching on place are preferred over street.

The value for KEY_ALTERNATE_LOOKUP = "PLACE_FIRST"

VALUE_ALTERNATE_LOOKUP_STREET

Candidates matching on street are preferred over place.

The value for KEY_ALTERNATE_LOOKUP = "STREET_FIRST"

KEY_SEARCH_LEVEL Values

VALUE_SEARCH_LEVEL_EXPANDED

Enables the expanded search feature.

KEY_SEARCH_LEVEL = SEARCH_LEVEL_EXPANDED

"false"

KEY_EXPANDED_SEARCH_RADIUS

setExpandedSearchRadiusInMiles

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

"25"

KEY_EXPANDED_SEARCH_LIMIT_TO_STATE

setExpandedSearchLimitToState

If expanded search is enabled, limit the expanded search to the same state of the input address, regardless of the mile radius.

"true"





USA_ReverseGeocodeConstraintscom.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).

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 PreferenceThe DictionaryUsagePreference class describes whether the address dictionary or user dictionary are preferred or used exclusively. See KEY_DICTIONARY_USAGE on page 58.

VALUE_SEARCH_LEVEL_FINANCE_AREA

Search the entire finance area for possible streets

KEY_SEARCH_LEVEL = VALUE_SEARCH_LEVEL_FINANCE_AREA

Default for CASS Mode.

VALUE_SEARCH_LEVEL_CITY Limit the search to streets within the specified city.

KEY_SEARCH_LEVEL = VALUE_SEARCH_LEVEL_CITY

Default for Relaxed, Exact, Default, or Custom Modes.



USA_ReverseGeocodeConstraints


FIND_CLOSEST_POINT

setFindClosestPoint

The setFindClosestPoint method can be used to force a 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.

"false"



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 37 for more information on match modes.

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

Match Mode Constants

Constant Value Description

RELAXED_MODE

setMatchMode()

"RelaxedMode"

Sets Relaxed match mode.

EXACT_MODE

setMatchMode()

"ExactMode" Sets Exact match mode.

DEFAULT_MODE

setMatchMode()

"DefaultMode" Sets Default match mode.

CASS_MODE (USA only)

setMatchMode()

"CASS_MODE"

Sets CASS match mode.



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 SystemA 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:

MATCH_MODE_NONE

setMatchMode()

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

KEY_MATCH_MODE

setMatchMode()

Indicates which match mode is being used.

Match Mode Constants (Continued)


Description Datum String

Longitude / Latitude WGS 84 EPSG:4326

Longitude / Latitude NAD 83 EPSG:4269

Longitude / Latitude NAD 27 for Continental United States

EPSG:4267



Using Address Point InterpolationThis 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 88 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.



Using Centerline Offset for Point CandidatesIf 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:

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.

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

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



• 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 ConstraintsFollowing 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 ConstraintUse 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");



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 SearchYou 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 LevelsYou 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 InformationAfter 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 92.



/* Geocode Address */MMJEngine engine = new MMJEngine();ClientGeocodeResponse geoRes = engine.geocode

(com.mapinfo.mapmarker.user.MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS,inpAddr, geoCon);

Getting CandidatesYour 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 77.



Getting the Result CodeAs 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 133.

MapMarker USA v29 also returns match codes and location codes. See Returning Match Codes and Location Codes on page 90.

Getting the Segment IDSegment IDs are numeric codes that uniquely identify each point or street centroid candidate. The MapMarker USA 29 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 PrecisionLocation 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


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

ADDRESS_POINT_INTERPOLATED

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



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.




LOCAL_CUSTOM_POINT_PRECISION_1

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


13 Additional point precision for 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.

Candidate Address Location Precision Values (Continued)




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






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







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.





Getting Street Range Parity InformationCandidate 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).

POSTAL_LEVEL_POSTAL_CODE_1

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

POSTAL_LEVEL_POSTAL_CODE_2

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

POSTAL_LEVEL_POSTAL_CODE_2_PARTIAL

4 Match level indicating that the candidate point represents a 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.





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

Returning Range and Unit InformationYou 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);

Candidate Range Constants and Values


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.



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 = newUSA_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 InformationYou 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 character maximum). This is an alternate form of the city name defined by the USPS.

getShortCityName USA_SHORT_CITYNAME

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

getShortStreetName USA_SHORT_STREETNAME

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

getShortStreetType USA_SHORT_STREETTYPE



Returning Database Source InformationYou 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.

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

getShortPreDir USA_SHORT_PREDIR

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

getShortPostDir USA_SHORT_POSDIR

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

getShortAddressLine USA_SHORT_ADDRESSLINE

Short Address Methods and Keys (Continued)

Description Method Key

Data Source (DBType) Returned

Number Database Type Description

0 USPS USPS data

1 TIGER TIGER 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 InformationSee the MapMarker USA v29 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 54 for the location of the JavaDocs.

Creating a Reverse Geocoding Application in JavaReverse 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 StatementsMake 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;

2 TOMTOM TomTom street data

5 deprecated

6 NAVTEQ NAVTEQ NAVSTREETS™

7 TOMTOM_POINT TomTom point data

8 CENTRUS_POINT Centrus point data

10 USER_DICTIONARY User Dictionary

11 NAVTEQ_POINT NAVTEQ Point Addressing

12 MASTER_LOCATION Master Location data

Data Source (DBType) Returned(Continued)

Number Database Type Description



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_ReverseGecodeFatalExceptionimport com.mapinfo.mapmarker.user.MMJClient;import com.mapinfo.util.DoublePoint;import com.mapinfo.coordsys.CoordSys;import com.mapinfo.mapmarker.USA.reverseGeocode.USA_ReverseGecodeFatalExceptionimport com.mapinfo.unit.Distance;import com.mapinfo.unit.LinearUnit;

import java.net.MalformedURLException;43.64351

Setting the Input LocationFor 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 ConstraintsSet 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 ConstraintYou 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);



Reverse GeocodingAfter 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 80.

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 ResponseAfter 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 142.

Browsing AddressesBrowsing 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.




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 = newUSA_UserCandidateAddress(geoRes.candidateAt(i));System.out.println("Candidate")}

}

Geocoding To Postal CentroidsThe 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.


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");



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 returned candidates*/if (candCount > 0){


/*Get candidate information */USA_UserCandidateAddress candAddr = new

USA_UserCandidateAddress(geoRes.candidateAt(i));}

}

Geocoding to Geographic CentroidsThe 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.


USA_UserInputAddress inpAddr = new USA_UserInputAddress ();inpAddr.setCity("Hannibal");inpAddr.setState("MO");


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




/* 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 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.



Geocoding to Highway ExitsGeocoding 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


USA_UserInputAddress inpAddr = new USA_UserInputAddress ();inpAddr.setStreet("I-90 Exit 8");inpAddr.setState("NY");


AddressImpl inpAddr = new AddressImpl();inpAddr.setMainAddress("I-90 Exit 8");inpAddr.setAreaName1("NY");inpAddr.setCountry("USA");


/* 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 information */USA_HighwayExitCandidateAddress candAddr = new

USA_HighwayExitCandidateAddress (geoRes.candidateAt(i));}

}



Geocoding to AirportsTo 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 StateIf 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)); }}



Finding Airports by CodeIf 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' */


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 = newUSA_UserAirportCandidateAddress(geoRes.candidateAt(0));

DPV Related ActionsThe 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



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.

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

Getting DPV StatusThe 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);

Status code getGenericField1()

Description Message getGenericField2()

Expiration Date getGenericField3()

DPV Status code getDPVStatusCode()

DPV Description Message

getDPVStatusMsg()

DPV Expiration Date getDPVExpDate()



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:

Returning Match Codes and Location CodesYou 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 163 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.

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



For example, to get match codes and location codes:

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

Standardizing AddressesThe 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 ViewNY, 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 ViewTroy, 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



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 JavaIf 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 54, 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 55.


5
5 – Using the REST API
MapMarker USA 29 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 94Usage Guidelines 101REST API Examples 103

Using the REST API

REST API Framework and SyntaxThe 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 SubtypesStandard geocoding and reverse geocoding are supported. The following table summarizes the geocoding request types. The geocoding types are not case sensitive.

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.

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.


Using the REST API

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 ParametersREST API requests use the following input parameters. The parameter names must be spelled correctly but they are not case sensitive.

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


Using the REST API

Input Parameters

Parameter Description Used With Geocode Type Example

ctry country GeocodeRequest and 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.

ctry=USA

str mainAddress (single-line input is also passed here)

GeocodeRequest str=5723+143+St+NW

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




Using the REST API

Geocoding ConstraintsThe 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.

x the x value (longitude) of the point to reverse geocode

ReverseGeocode x= -73.699899

y the y value (latitude) of the point to reverse geocode

ReverseGeocode y=42.682433

d the distance value to limit the reverse geocode to.

ReverseGeocode d=10

unit the linear unit abbreviation that goes with 'd'.

ReverseGeocode unit=m

Input Parameters (Continued)

Parameter Description Used With Geocode Type Example

Geocoding Constraints

Constraint DescriptionUsed with Geocode

Type Example

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

GeocodeRequest mxCan=3

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

GeocodeRequest close=false

fbp If true, fallback to postal. Default is false.

GeocodeRequest fpb=true


Using the REST API

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

GeocodeRequest fbg=true

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

GeocodeRequest apIntrp=true

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

GeocodeRequest centerline=false

mode Specifies the match mode to use. (Default, Exact, Relaxed, CASS). If mode is set, the Must Match constraints (mmA#) are ignored.

GeocodeRequest mode=ExactMode

mode=RelaxedMode

mode=DefaultMode

mode=CASS_MODE

dictPref Controls whether Address Dictionary and/or User Dictionary 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)

GeocodeRequest dictPref=AD_ONLY

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

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

GeocodeRequest mmStr=true

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

GeocodeRequest mmA1=false


GeocodeRequest mmA2=true

Geocoding Constraints (Continued)


Type Example


Using the REST API

USA Geocoding ConstraintsThe 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.


GeocodeRequest mmA3=true


GeocodeRequest mmA4=true (used for Puerto Rico addresses only).

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

GeocodeRequest mmCode=true

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

GeocodeRequest mxRng=5

mxUnit Specifies the maximum number of CandidateRangeUnits to return for each range.

GeocodeRequest and ReverseGeocode

mxUnit=5

prj Specifies the coordinate system to, return points in. For reverse geocoding, specifies the coordinate system of the input X/Y points.


prj=epsg:4269

this is NAD 83. Encoded as epsg%3A4269

offsetValue

Specifies the distance value for corner offset, street offset, and if selected, centerline offset.


offsetValue=3

offsetUnits

Specifies the linear unit abbreviation for the offsetValue.


offsetUnits=m

Geocoding Constraints (Continued)


Type Example


Using the REST API


Constraint DescriptionUsed with

Geocode Type Example

searchLevel

SEARCH_LEVEL_EXPANDED Enables the expanded search feature, which allows MapMarker to search for candidates within a given radius of the input address. False by default.

SEARCH_LEVEL_FINANCE_AREA Search the entire 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.

GeocodeRequest

searchLevel=SEARCH_LEVEL_EXPANDED

searchLevel=SEARCH_LEVEL_FINANCE_AREA

searchLevel=SEARCH_LEVEL_CITY

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

GeocodeRequest

expRadius=10

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

GeocodeRequest

expState=false

wideSearch

Considers all streets that begin with the first letter of the input street name False by default.

GeocodeRequest

widesearch=true

zipOverCity

Prefer a ZIP Code match over a city match. False by default.

GeocodeRequest

zipOverCity=true

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

GeocodeRequest

DPV=true


Using the REST API

Response FormatsThe 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.

Usage GuidelinesThe 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 APIThe REST API is accessed by calling the server and passing parameters as part of a URL query. The format is:

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

GeocodeRequest

LACSLink=true

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

GeocodeRequest

suiteLink=true


Constraint DescriptionUsed with

Geocode Type Example

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.


Using the REST API

http://server:port/mapmarker40/servlet/mapmarker?<parameters>

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=GeocodeRequest&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 10108Austin, Texas 78703

and returns the XML formatted candidates.

Character EncodingThe 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%20RIO%20PLANTATION


Using the REST API

Match Modes and Must Match ConstraintsIf 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 ConstraintsYou 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 ExamplesSeveral 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 ExamplesThis section includes several examples to demonstrate the input and resulting XML output from the REST API.


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 AveLos AngelesCA

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

- <Address>- <AdditionalFields>- <KeyValuePair> <Key>GEOSTAN_POINT_ID</Key> <Value>117880449</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_SEGMENT_DIRECTION</Key> <Value>F</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_CITYNAME</Key> <Value>LOS ANGELES</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>S90</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>AP05</Value> </KeyValuePair>- <KeyValuePair> <Key>CARRIER_ROUTE</Key> <Value>C041</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_DATA_TYPE</Key> <Value>7</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_COUNTY_CODE</Key> <Value>06037</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CBSA_DIVISION_NAME</Key> <Value>LOS ANGELES-LONG BEACH-GLENDALE, CA METROPOLITAN DIVISION</Value>


Using the REST API

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


Using the REST API

<Value>92</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_METRO_FLAG</Key> <Value>Y</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_STREETNAME</Key> <Value>WILKINS</Value> </KeyValuePair>- <KeyValuePair> <Key>REC_TYPE</Key> <Value>S</Value> </KeyValuePair>- <KeyValuePair> <Key>SEGMENT_ID</Key> <Value>14502746</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_DB_TYPE</Key> <Value>7</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_ADDRESS_LINE1</Key> <Value>10592 WILKINS AVE</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_STREET_SIDE</Key> <Value>L</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CSA_NAME</Key> <Value>LOS ANGELES-LONG BEACH-RIVERSIDE, CA COMBINED STATISTICAL AREA</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_STREETTYPE</Key> <Value>AVE</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>S90</Value> </KeyValuePair> </AdditionalFields> <AddressNumber>10592</AddressNumber> <AreaName1>CA</AreaName1> <AreaName2>LOS ANGELES COUNTY</AreaName2> <AreaName3>LOS ANGELES</AreaName3> <Country>USA</Country> <MainAddress>WILKINS</MainAddress> <postCode1>90024</postCode1> <postCode2>6033</postCode2> <postThoroughfareType>AVE</postThoroughfareType> </Address>- <Point srsName="epsg:4326">- <coord> <X>-118.43111</X> <Y>34.057111</Y> </coord> </Point> <TotalRangesFound>0</TotalRangesFound>


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%20NW%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:

- <Address>- <AdditionalFields>- <KeyValuePair> <Key>RESULT_CODE</Key> <Value>S5HPNTS-ZA</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CBSA_NAME</Key> <Value>ALBUQUERQUE, NM METROPOLITAN STATISTICAL AREA</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>AS0</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CBSA_NUMBER</Key> <Value>10740</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_METRO_FLAG</Key> <Value>Y</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CITY_CODE</Key> <Value>350002000</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_STREETTYPE</Key> <Value>BLVD</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>AS0</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_ALIAS_TYPE</Key> <Value>N01</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key>


Using the REST API

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


Using the REST API

<Value>ALBUQUERQUE</Value> </KeyValuePair> </AdditionalFields> <AddressNumber>200</AddressNumber> <AreaName1>NM</AreaName1> <AreaName2>BERNALILLO COUNTY</AreaName2> <AreaName3>ALBUQUERQUE</AreaName3> <Country>USA</Country> <MainAddress>ALAMEDA</MainAddress> <postCode1>87114</postCode1> <postDirectional>NW</postDirectional> <postThoroughfareType>BLVD</postThoroughfareType> </Address>- <Point srsName="epsg:4326">- <coord> <X>-106.614069</X> <Y>35.188054</Y> </coord> </Point> <TotalRangesFound>0</TotalRangesFound> </Candidate>

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 StWestborough, MA01581

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.

- <Address>- <AdditionalFields>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>25027</Value> </KeyValuePair>- <KeyValuePair> <Key>RESULT_CODE</Key> <Value>Z1</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>Z0</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>ZC5X</Value>


Using the REST API

</KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>ZC5X</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>Z0</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_COUNTY_CODE</Key> <Value>25027</Value> </KeyValuePair> </AdditionalFields> <AreaName1>MA</AreaName1> <AreaName2>WORCESTER COUNTY</AreaName2> <AreaName3>WESTBOROUGH</AreaName3> <Country>USA</Country> <postCode1>01581</postCode1> </Address>- <Point srsName="epsg:4326">- <coord> <X>-71.6118</X> <Y>42.2702</Y> </coord> </Point> <TotalRangesFound>0</TotalRangesFound>

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

Museum of Natural HistoryNew York10022

After encoding, the URL is sent as:

http://localhost:8095/mapmarker40/servlet/mapmarker?plc=Museum%20of%20Natural%20History&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.

...- <Address>- <AdditionalFields>- <KeyValuePair> <Key>GEOSTAN_SEGMENT_DIRECTION</Key> <Value>R</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_CITYNAME</Key> <Value>NEW YORK</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>ADB</Value> </KeyValuePair>


Using the REST API

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


Using the REST API

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


Using the REST API

</KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>ADB</Value> </KeyValuePair> </AdditionalFields> <AddressNumber>15</AddressNumber> <AreaName1>NY</AreaName1> <AreaName2>NEW YORK COUNTY</AreaName2> <AreaName3>NEW YORK</AreaName3> <Country>USA</Country> <MainAddress>77TH</MainAddress> <placeName>MUSEUM OF NATURAL HISTORY</placeName> <postCode1>10024</postCode1> <postCode2>5193</postCode2> <postThoroughfareType>ST</postThoroughfareType> <preDirectional>W</preDirectional> </Address>- <Point srsName="epsg:4326">- <coord> <X>-73.97479</X> <Y>40.78007</Y> </coord> </Point> <TotalRangesFound>0</TotalRangesFound>

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.

<Address>- <AdditionalFields>- <KeyValuePair> <Key>RESULT_CODE</Key> <Value>S5HPNTSC-A</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CBSA_NAME</Key> <Value>ALBANY-SCHENECTADY-TROY, NY METROPOLITAN STATISTICAL AREA</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>AS0</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_METRO_FLAG</Key> <Value>Y</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CBSA_NUMBER</Key>


Using the REST API

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


Using the REST API

<Value>1 GLOBAL VW</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_LOT_NUMBER</Key> <Value>0001</Value> </KeyValuePair>- <KeyValuePair> <Key>CARRIER_ROUTE</Key> <Value>C099</Value> </KeyValuePair>- <KeyValuePair> <Key>REC_TYPE</Key> <Value>S</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_SEGMENT_DIRECTION</Key> <Value>F</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_STREET_SIDE</Key> <Value>L</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_COUNTY_CODE</Key> <Value>36083</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_PREFERRED_CITY_NAME</Key> <Value>TROY</Value> </KeyValuePair>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>360830523018010</Value> </KeyValuePair>- <KeyValuePair> <Key>SEGMENT_ID</Key> <Value>856929</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>S90</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_CITYNAME</Key> <Value>TROY</Value> </KeyValuePair> </AdditionalFields> <AddressNumber>1</AddressNumber> <AreaName1>NY</AreaName1> <AreaName2>RENSSELAER COUNTY</AreaName2> <AreaName3>TROY</AreaName3> <Country>USA</Country> <MainAddress>GLOBAL</MainAddress> <postCode1>12180</postCode1> <postCode2>8371</postCode2> <postThoroughfareType>VW</postThoroughfareType> </Address>- <Point srsName="epsg:4326">- <coord> <X>-73.702914</X>


Using the REST API

<Y>42.682858</Y> </coord> </Point>

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:

- <Address>- <AdditionalFields>- <KeyValuePair> <Key>RESULT_CODE</Key> <Value>S5HPNTS-ZA</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CBSA_NAME</Key> <Value>CHICAGO-JOLIET-NAPERVILLE, IL-IN-WI METROPOLITAN STATISTICAL AREA</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>AS0</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_METRO_FLAG</Key> <Value>Y</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CBSA_NUMBER</Key> <Value>16980</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CITY_CODE</Key> <Value>170576001</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CBSA_DIVISION</Key> <Value>16974</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_LOT_CODE</Key> <Value>A</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_CSA_NUMBER</Key> <Value>176</Value> </KeyValuePair>- <KeyValuePair> <Key>CHECK_DIGIT</Key>


Using the REST API

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


Using the REST API

<Key>REC_TYPE</Key> <Value>S</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_SEGMENT_DIRECTION</Key> <Value>R</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_STREET_SIDE</Key> <Value>L</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_COUNTY_CODE</Key> <Value>17031</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_PREFERRED_CITY_NAME</Key> <Value>LA GRANGE PARK</Value> </KeyValuePair>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>170318186002041</Value> </KeyValuePair>- <KeyValuePair> <Key>SEGMENT_ID</Key> <Value>344960</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>SB0</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_CITYNAME</Key> <Value>LA GRANGE PK</Value> </KeyValuePair> </AdditionalFields> <AddressNumber>1217</AddressNumber> <AreaName1>IL</AreaName1> <AreaName2>COOK COUNTY</AreaName2> <AreaName3>LA GRANGE PK</AreaName3> <Country>USA</Country> <MainAddress>CLEVELAND</MainAddress> <postCode1>60526</postCode1> <postCode2>1305</postCode2> <postThoroughfareType>AVE</postThoroughfareType> </Address>- <Point srsName="epsg:4326">- <coord> <X>-87.859118</X> <Y>41.836764</Y> </coord> </Point>

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:


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 <TotalRangesFound> 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 <TotalRangeUnitsFound>. 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.

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


Using the REST API

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


Using the REST API

- <KeyValuePair> <Key>GEOSTAN_COUNTY_CODE</Key> <Value>36091</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOSTAN_PREFERRED_CITY_NAME</Key> <Value>CLIFTON PARK</Value> </KeyValuePair>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>360910625032005</Value> </KeyValuePair>- <KeyValuePair> <Key>SEGMENT_ID</Key> <Value>917864</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>S80</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_CITYNAME</Key> <Value>CLIFTON PARK</Value> </KeyValuePair> </AdditionalFields> <AddressNumber>42</AddressNumber> <AreaName1>NY</AreaName1> <AreaName2>SARATOGA COUNTY</AreaName2> <AreaName3>CLIFTON PARK</AreaName3> <Country>USA</Country> <MainAddress>HOLLANDALE</MainAddress> <postCode1>12065</postCode1> <postCode2>8202</postCode2> <postThoroughfareType>LN</postThoroughfareType> <unitType>APT</unitType> <unitValue>C</unitValue> </Address>- <Point srsName="epsg:4326">- <coord> <X>-73.78811</X> <Y>42.851915</Y> </coord> </Point> <TotalRangesFound>3</TotalRangesFound> - <Range> <lowAddressNumber>42</lowAddressNumber> <highAddressNumber>42</highAddressNumber> <streetSide>1</streetSide> <rangeType>2</rangeType> - <Address> <AreaName1>NY</AreaName1> <AreaName3>CLIFTON PARK</AreaName3> <Country>USA</Country> <postCode1>12065</postCode1> <postCode2>8202</postCode2> </Address>- <AdditionalFields>- <KeyValuePair> <Key>REC_TYPE</Key> <Value>H</Value>


Using the REST API

</KeyValuePair>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>360910625032005</Value> </KeyValuePair>- <KeyValuePair> <Key>CARRIER_ROUTE</Key> <Value>R015</Value> </KeyValuePair> </AdditionalFields> <TotalRangeUnitsFound>2</TotalRangeUnitsFound> - <RangeUnit> <lowUnit>A</lowUnit> <highUnit>F</highUnit> - <Address> <Country>USA</Country> <postCode2>8202</postCode2> <unitType>APT</unitType> </Address>- <AdditionalFields>- <KeyValuePair> <Key>REC_TYPE</Key> <Value>H</Value> </KeyValuePair>- <KeyValuePair> <Key>CARRIER_ROUTE</Key> <Value>R015</Value> </KeyValuePair> </AdditionalFields> </RangeUnit>- <RangeUnit> <lowUnit>G</lowUnit> <highUnit>M</highUnit> - <Address> <Country>USA</Country> <postCode2>8218</postCode2> <unitType>APT</unitType> </Address>- <AdditionalFields>- <KeyValuePair> <Key>REC_TYPE</Key> <Value>H</Value> </KeyValuePair>- <KeyValuePair> <Key>CARRIER_ROUTE</Key> <Value>R015</Value> </KeyValuePair> </AdditionalFields> </RangeUnit> </Range>- <Range> <lowAddressNumber>34</lowAddressNumber> <highAddressNumber>62</highAddressNumber> <streetSide>1</streetSide> <rangeType>2</rangeType> - <Address> <AreaName1>NY</AreaName1> <AreaName3>CLIFTON PARK</AreaName3> <Country>USA</Country> <postCode1>12065</postCode1>


Using the REST API

<postCode2>5240</postCode2> </Address>- <AdditionalFields>- <KeyValuePair> <Key>REC_TYPE</Key> <Value>S</Value> </KeyValuePair>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>360910625032005</Value> </KeyValuePair>- <KeyValuePair> <Key>CARRIER_ROUTE</Key> <Value>R015</Value> </KeyValuePair> </AdditionalFields> <TotalRangeUnitsFound>0</TotalRangeUnitsFound> </Range> </Candidate>

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

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

- <AdditionalFields>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>360050187001</Value> </KeyValuePair>- <KeyValuePair> <Key>RESULT_CODE</Key> <Value>Z3</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>Z6</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>ZC9D</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>ZC9D</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>Z6</Value> </KeyValuePair>- <KeyValuePair>


Using the REST API

<Key>GEOSTAN_COUNTY_CODE</Key> <Value>36005</Value> </KeyValuePair> </AdditionalFields> <AreaName1>NY</AreaName1> <AreaName2>BRONX COUNTY</AreaName2> <AreaName3>BRONX</AreaName3> <Country>USA</Country> <postCode1>10451</postCode1> <postCode2>2116</postCode2> </Address>- <Point srsName="epsg:4326">- <coord> <X>-73.9271</X> <Y>40.8278</Y> </coord> </Point> <TotalRangesFound>0</TotalRangesFound>

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

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.

- <Address>- <AdditionalFields>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>12086</Value> </KeyValuePair>- <KeyValuePair> <Key>RESULT_CODE</Key> <Value>G3</Value> </KeyValuePair>- <KeyValuePair> <Key>GEOGRAPHIC_RANK</Key> <Value>6</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key> <Value>G3</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>GM</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_LOCATION_CODE</Key> <Value>GM</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_MATCH_CODE</Key>


Using the REST API

<Value>G3</Value> </KeyValuePair> </AdditionalFields> <AreaName1>FL</AreaName1> <AreaName2>MIAMI-DADE</AreaName2> <AreaName3>KEY BISCAYNE</AreaName3> <Country>USA</Country> </Address>- <Point srsName="epsg:4326">- <coord> <X>-80.16306</X> <Y>25.693329</Y> </coord> </Point> <TotalRangesFound>0</TotalRangesFound>

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

X: -73.6907Y: 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.

- <ResponseEnvelope>- <ReverseGeocodeResponse>- <ReverseGeocodeResult dataLicensed="true">- <Candidate CfgOrder="1" fmtdAddr="266 4TH ST" fromUserDictionary="false" fmtdLoc="TROY, NY 12180-4505">- <Address>- <AdditionalFields>- <KeyValuePair> <Key>RESULT_CODE</Key> <Value>RS5A</Value> </KeyValuePair>- <KeyValuePair> <Key>REC_TYPE</Key> <Value>S</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_ADDRESSLINE</Key> <Value>266 4TH ST</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_DB_TYPE</Key> <Value>2</Value> </KeyValuePair>- <KeyValuePair> <Key>CENSUS_BLOCK</Key> <Value>360830408002025</Value> </KeyValuePair>- <KeyValuePair> <Key>SEGMENT_ID</Key>


Using the REST API

<Value>872939</Value> </KeyValuePair>- <KeyValuePair> <Key>USA_SHORT_CITYNAME</Key> <Value>TROY</Value> </KeyValuePair> </AdditionalFields> <AddressNumber>266</AddressNumber> <AreaName1>NY</AreaName1> <AreaName2>RENSSELAER COUNTY</AreaName2> <AreaName3>TROY</AreaName3> <Country>USA</Country> <MainAddress>4TH</MainAddress> <postCode1>12180</postCode1> <postCode2>4505</postCode2> <postThoroughfareType>ST</postThoroughfareType> </Address> <distance unitsOfMeasure="m">7.68096</distance> <TotalRangesFound>0</TotalRangesFound> </Candidate></ReverseGeocodeResult> </ReverseGeocodeResponse> </ResponseEnvelope>

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


6
6 – Deploying Applications
This chapter discusses how to deploy your application as a Web servlet and how you can integrate MapMarker USA 29 USA with other MapMarker country geocoders.

In this chapter:

Deploying MapMarker as a Servlet 128Integration with MapMarker for Other Countries 129

Deploying Applications

Deploying MapMarker as a ServletA 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 ContainerMapMarker 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 v29 Server.

Deploying MapMarker Server in Other Web EnvironmentsFor 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 ServiceTo 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 29\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:


http://jakarta.apache.org/tomcat/index.html

http://www.oracle.com/technetwork/java/javaee/servlet/index.html


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 29 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 CountriesIf 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.


http://tomcat.apache.org/tomcat-8.0-doc/windows-service-howto.html


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 v29 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 v29 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 v29 and MapMarker Canada v11.1 server reports, you will know the core version number and build numbers for both products. For example:

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

MapMarker CountryMapMarker Java Core

VersionMapMarker Java Plugin Version (Build Number)

MapMarker USA v29 5.0.0.9 29.0.0.7

MapMarker Canada v11

5.0.0.5 11.10.0.1



Now follow these steps:

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

<MM_CAN_install>\sdk\tomcat\webapps\mapmarker40\WEB-INF\lib<MM_USA_install>\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.jarmmj_can.jar

2. You must also copy several properties and license files. By default, these are in:

<MM_CAN_install>\sdk\tomcat\webapps\mapmarker40\WEB-INF\classes\<MM_USA_install>\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.propertiesMMCANLicenseFactory.configMMCANLicenseProvider.config

3. Verify that the Tomcat server allocates at least 512 MB of RAM. Open catalina.bat (or catalina.sh for Solaris) in:

<Install>\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 130. 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.

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

Plugin Version

United States (USA) 29.0.0.7

Canada (CAN) 11.10.0.1



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.


7
7 – Result Codes
In this chapter:

Understanding Result Codes 134Single Match (S category) 135Best Match From Multiple Candidates (M category) 141Postal Centroid Matches (Z category) 142Geographic Matches (G category) 142Reverse Geocoded Matches (R category) 142Non-match Codes (N category) 143

Result Codes

Understanding Result CodesAs 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)


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

• S6 – single match, point located at point ZIP centroid. See also Interpreting S6 Result Codes on page 140.

• 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 140.

• 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 139.

• SX – single match, point located at street intersection.• S0 – single match, no coordinates available (very rare occurrence).


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.


Result Codes

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.


S1 S1 results are matched to ZIP centroid locations. This may return partial census information if ZIP + 4 is supplied.


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




Result Codes

See the following topics:

Interpreting Complete S and M Result Codes

Interpreting S8 Result Codes




S and Z Result Codes: What is the Difference?

Interpreting Complete S and M Result CodesFor 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.

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.




Result Codes

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

Interpreting S8 Result CodesS8 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 v29 User Guide for a description of the related Address Location Codes, including the AP point level match 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 Dictionary

A


Result Codes

Interpreting S7 Result CodesS7 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 CodesAn 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 CodesS5 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.


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


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.


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.


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 145Geocoding Constraint Keys 146Geocoding Request Types 150

Tips on Using the XSD SchemasThe MapMarker schemas are installed by MapMarker in:

<install>\sdk\engine\schema, where <install> 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 <country> 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 77. 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


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

Geocoding Constraint KeysThe Constraint Keys table describes the available constraints. The constraints recognize the following KEYS within <KeyValuePairType>.

See the table of Geocode Constraints on page 57 and USA_GeocodeConstraints on page 61 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"

Deprecated. Use "KEY_SEARCH_LEVEL" = SEARCH_LEVEL_EXPANDED

Enable or disable expanded search.

"KEY_EXPANDED_SEARCH_RADIUS"

Specify the expanded search radius.


"KEY_EXPANDED_SEARCH_LIMIT_TO_STATE"

Specify that expanded search candidates should be limited to state regardless of 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 63.

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

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

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

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

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

"CASSMODE" Sets CASS match mode

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

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

Constraint Keys (Continued)

Name Description


"centerlineOffsetUnits" Specify the units used for centerline offset. See POINT_CENTERLINE_OFFSET_ UNITS on page 61.

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


"maxRangeUnits" Specify the maximum units per ranges to return.


"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 61.

"centerlineOffsetUnits" Specify the units used for centerline offset. See POINT_CENTERLINE_OFFSET_ UNITS on page 61.

(ft, m, mi, km, in, yd, cm, and mm)

"ClientLocale" Specify the locale.

("en_US")


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 150

"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 58.

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

"addrPntInterp" Enable or disable address point interpolation.

See DPV Related Actions on page 88.

"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 66.

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


Name Description


Geocoding Request TypesThe following table summarizes the geocoding request type values associated with the "GeocodeRequestType" string.

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


Name Description

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


Candidate AdditIonal Field ValuesThe following values can be returned with AdditionalFields <KeyValuePair> statements.

DPV Support 206

LACS LINK Supported 207

DPV Status 208

Geocoding Request Types Values (Continued)

Geocode Request Type Value

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


DPV_NOSTAT Y – The address is vacant.

N –The address is not vacant.

Blank – DPV is not loaded or DPV did not confirm (so vacancy is irrelevant).

USA

DPV_VACANT Y – The address was valid for 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.

USA

DEFAULT_FLAG Y USA

LACSLINK_INDICATOR Y USA

LACSLINK_RESULT_CODE A USA

SUITELINK_RETCODE A – SuiteLink match. Secondary 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:

USA

Candidate Additional Field Values (Continued)

Candidate Additional Field Values Example Country


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 154Country Settings 154

JVM SettingsThe 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=<the number of settings for the JVM>-Djava.class.path=<the series of jar files required to geocode addresses in the selected country>-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 SettingsThe following setting indicates the country that the adapter is going to use for geocoding.

+country=<the country this configuration file is for geocoding>

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


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 156

Geocoding Extenders for Database DevelopersDevelopers 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 Geocoding Extender for Oracle

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

The Oracle Geocoding Extender includes MapMarker USA functionality. This is available on request.

MapInfo Geocoding Extender for SQL Server 2005

The SQL Server 2005 Extender product is for SQL server database programmers. This product is 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

The Geocoding Extender includes MapMarker USA functionality. This is available on request.


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 158

MapMarker Java API ErrorsMapMarker 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

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

Error Code Error # Description

ERROR_PARSER_INPUT_ADDRESS_NULL

2000 Input address is null.

ERROR_PARSER_PARSED_ADDRESS_NULL

2001 Parsed address is null.

ERROR_PARSER_INITIALIZATION 5000 Unable to initialize parser.


Data Access Exceptions

License Exceptions


ERROR_DATA_ACCESS_INVALID_REQUEST

2100 Invalid request made during data access.

ERROR_DATA_ACCESS_DATA_CORRUPTED

2101 Data corruption encountered during data access.

ERROR_DATA_ACCESS_IO 2102 IO error encountered during data access.

ERROR_DATA_ACCESS_NO_DICTIONARY

2103 The data manager failed to find 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_BASE

2105 No street base available for 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_LICENSED

2108 Data not licensed.

ERROR_DATA_ACCESS_MISSING_FILE 5100 Missing file: {0}.


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_NOT_MATCH_MACHINE

5204 License does not match the current machine.


General Geocoding Process Exceptions

ERROR_LICENSE_FILE_NOT_FOUND 5205 License specified does not exist.

ERROR_SOFTWARE_LICENSE_EXPIRED 5206 Software license has expired.



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_FAILED

2306 Error initializing data manager. 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_PROTOCOL

2310 Unsupported XML Protocol request.


Reverse Geocode Exception Codes

Client Exceptions


RG_ERROR_FAILED_TO_CREATE_SUBHANDLER_NOPOOL

5350 Unable to get Geostan pool.

RG_ERROR_FAILED_TO_CREATE_SUBHANDLER_BADPOOL

5351 Invalid Geostan pool present.

RG_ERROR_GEOSTAN_FIND_ERROR 5352 No Spatial Index files

ERROR_GEOSTAN_UNABLE_TO_LOAD_SPATIAL_INDEX

5353 Unable to load the Spatial 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_GEOCODING_NOT_LICENSED

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


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.


Server Exceptions

ERROR_SERVER_JDOM 2600 The server was unable to process the request.

ERROR_SERVER_INVALID_REQUEST_TYPE

2601 An invalid request type was provided.


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

In this Appendix

Match Codes 164Location Codes 171Using Status Codes 183

Match CodesGeoStan 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 ValuesHex Digits Associated with Match CodesCorrected Lastline Match CodesError and No Match Codes

Match Code ValuesThe 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.


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

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.

Match Code Values(Continued)

Code Description

Match Code Hex Digits

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

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.


Corrected Lastline Match CodesLastline 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.

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

Street type, predirectional, and 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 changed.

Street name, street type, and postdirectional changed.

E State, City, and ZIP + 4 changed.

Street name, predirectional, and postdirectional changed.

F State, City, ZIP, and ZIP + 4 changed.

Street name, street type, predirectional, and postdirectional changed.

Match Code Hex Digits (Continued)

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

means:


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.


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.

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

Lastline Correction Codes (Continued)

Code Description


Error and No Match CodesThe 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.


Location CodesGeoStan 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 164 and Result Codes on page 133.

See also:Address Location CodesStreet Centroid Location CodesZIP +4 Code Location CodesGeographic Location CodesLocation Code Not Available

Address Location CodesAddress 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.

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

Error or No Match Codes (Continued)

Code Description

Structure of Address Location Codes

Character Description

1st character

Always an A indicating an address location.

2nd character

May be one of the following

C Interpolated address point 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.

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 characters

Digit indicating other qualities about the location.

See the table of Address Location Codes (A Codes)

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.

Structure of Address Location Codes (Continued)

Character Description


nn = 05 Structure centroid.

Indicates the center of a building footprint polygon, where the building receives mail or has telephone service.

Usually a residential address consists of a single building. For houses with outbuildings (detached garages, shed, barns, etc.), only the residences have a structure point. Condominiums and duplexes have multiple points for each building. Larger buildings, such as apartment complexes, typically receive mail at one address for each building and therefore individual apartments are not represented as discrete structure points.

Shopping malls, industrial complexes, and academic or medical center campuses where one building accepts mail for the entire complex are represented as one point. When addresses are assigned to multiple buildings within one complex, each addressed structure is represented by a point.

If the center of a structure falls outside of its polygon, the center is manually repositioned to fall inside the polygon.

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.

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.


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.


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.


Code Description


Street Centroid Location CodesStreet 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.

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.


Code Description

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.


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.

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.

Street Centroid Location Codes (C Codes)

Character position Code Description

2nd Character

Census ID Accuracy

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.

Structure of ZIP+4 Location Codes


1st character Always Z indicating a location derived from a ZIP centroid.

2nd character Census ID accuracy.


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.

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.

ZIP +4 Centroid Location Codes (Z Codes)


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

Structure of ZIP+4 Location Codes (Continued)



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.

ZIP +4 Centroid Location Codes (Z Codes) (Continued)



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.




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




Geographic Location CodesGeographic 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.

The Geographic Location Codes (G Codes) table provides a detailed description of the geographic centroid location codes. These always begin with the letter G.

Location Code Not AvailableA 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 CodesIn 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 103.

Structure of Geographic Location Codes


1st character Always G indicating a location derived from a geographic centroid.

2nd character Geographic area type.

Geographic Location Codes (G Codes)


2nd Character

M Municipality (city).

C County.

S State.


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 96 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 164 and Location Codes on page 171).

See also:Match Codes on page 164Location Codes on page 171Result Codes on page 133

Evaluating Candidate Match QualityExamine 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 133 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 37 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 502City: MassenaState: NYZIP: 13662-9750

Using Standard Match Mode, this returns the following close match candidate:

MainAddress: PO BOX 502City: MASSENAState: NYZIP:13662ZIP+4: 0502Result Code: S1HPNTSCZAMatch Code: S80Location Code: ZC5X

S1 Result Code: indicates ZIP Code accuracy only.


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 MainKansas City, MO 66109


MainAddress: 9300 MAIN STCity: KANSAS CITYState: KSZIP: 66109Result Code: S5HPN-SCZAMatch Code: TC1Location 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 changed1 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 LakesAlbrightsville, PA 18210


MainAddress: 70 INDIAN MOUNTAIN LKSCity: ALBRIGHTSVILLE


State: PAZIP: 18210-3004Result Code: S1HP-TSCZAMatch Code: A88Location 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 StreetDenver, CO 80236


2762 S KING STDENVER, CO 80236-2514Result Code: S8HPNTSCZAMatch Code: S80Location 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).


Index

A

address cleansing 7address dictionary

available 8definition 31

address matchinggeocoding 5

address point interpolation 68, 135address standardization 91addresses

browsing 82input 24, 25result code information 28

airport geocoding 87airports

finding by code 88finding by state 87

alternate lookup valuesUSA_GeocodeConstraints 64

B

best match from multiple candidatesresult codes 141

browsing addresses 82

C

candidate qualityevaluating 183

candidatesdefinition 31retrieving 72

centerline offsetin properties file 69using 69

centroiddefinition 32

citygeographic candidate returns 49

close matchdefinition 32

closematch key 57CMRA

definition 32common schema 145configuration file

JNI adapter 154constants

match mode 66constraints 61

geocoding 20, 56coordinate systems

JNI adapter configuration file settings 154setting in applications 67

country settings 154

creating web clientsample code 92

creating web geocoding client 54

D

data source informationreturning 79

database development tools 156DataManagerSettings

address dictionary path 36centerline offset entry 69configuring 36, 52multi-threaded environment 52

deployment as servlet 128dictionary result information 29dictionary usage preference

65DPV

availability and status 88

E

Envinsa 20error message reference 158Exact Match Mode 38expanded search results

returning 71

F

fallback preferences 21fallback to geographic 59fallback to postal

GeocodeConstraints 59

G

generic preferences 25geocode requests

contents of 27geocode subtypes

REST API 94geocode types 22, 28

REST API 94GeocodeConstraints 56, 59, 70

fallback to geographic 59fallback to postal 59maximum candidates 59must match 59

geocodingairports 87constraints 20geographic centroids 84, 85highway exits 86model 20, 21


Index

result codes 27, 28geocoding applications

choosing development tool 18, 19XML programming in .NET 94

geocoding constraints 61geocoding request types 150geocoding results

result codes 134, 143geocoding terms 31geographic candidate

return fields 48geographic centroid geocoding 84, 85geographic geocoding 48getDBType method 79getPrecisionCode method 82getsegmentID method 73

H

highway exit geocoding 86

I

input addressesbuilding 24, 25setting 55

integrating multiple country geocoders 129

J

Java APIcreating an application 54

Java Generic API 54Java USA API 54JavaDocs location 54JNI adapter

configuration file settings 154JVM settings 154

K

keyclosematch 57

L

latitudestreet candidate returns 45, 48

location codes 171address location 171evaluating candidates 183, 186geographic location 183returning 90street centroid location 177ZIP centroid location 178

longitudestreet candidate returns 45, 48

M

MapInfo FTP Site 16MapMarker

features 13technical support 15

MapMarker serverdeploying in Web environments 128

MapMarker Streetsusing with MapMarker 14

MapXtreme 19match codes 164

evaluating candidates 183, 186hex digits 165lastline corrections 166returning 90values 164

match mode constants and methods 66matching addresses

with geographic data 5maximum candidates

GeocodeConstraints 59methods

match mode 66MMJCommon.xsd 145MMJRequest.xsd 145MMJResponse.xsd 145multiple country integration 129must match

definition 33GeocodeConstraints 59USA_GeocodeConstraints 62

N

non-match result codes 143

O

optimizing server performance 52Oracle geocoding extender 156

P

performanceoptimizing 29

PMBdefinition 33

positional accuracy of pointsresult code information 28

postal candidatereturn fields 48

postal centroid matchresult codes 142

postal geocoding 23, 47definition 33

post-Directionaldefinition 33


Index

postTypedefinition 33

pre-Directionaldefinition 34

preferencesgeneric and U.S. 25sample application 37usage examples 25, 26

preTypedefinition 34

R

range informationreturning 77

range unit informationreturning 77

Relaxed Match Mode 39request schema 145request types 150response schema 145REST API

character encoding 102constraints 97, 99input parameters 95response 101using 93XML 103

result codesaddress point interpolation 135best match from multiple candidates 141complete M code 138complete S code 138definition 34G category 142geographic candidate returns 49geographic matches 142interpreting 27, 28M category 141N category 143non-match codes 143postal candidate returns 48postal centroid matches 142returning 73S category 135S3 and Z3 comparison 141S5 140S6 140S7 140S8 139single close match 135Z category 142

reverse geocoding 49reverse geocoding candidate

return fields 50reverseGeocode method 82

S

S1 result 137S3 result 137

S5 result 136, 137S6 result 136S8 result 136sample application

MapMarker 30requirements 35testing the server 36using 35–36, 41, 48

sample codecreating web client 92

SC 138schemas

MapMarker 145search level values

USA_GeocodeConstraints 64segment ID 73sending geocode requests 27servlet deployment 128setting

geocoding constraints 61input address 55

short address informationreturning 78

single match result codes 135SQL Server geocoding extender 156Standard Match Mode 38standardizing addresses 91street address

street candidate returns 42street geocoding 41street geocoding candidates 42street level geocoding

definition 34street name

definition 34street-level geocoding 22support

technical support 15

T

technical support 15–16Tomcat

configuring as a Windows service 128tomcat servlet container 128

U

USA_GeocodeConstraints 61must match 62user dictionary 62

user dictionarydefinition 34USA_GeocodeConstraints 62

W

war files 128Web environments 128web geocoding client


Index

creating 54WebLogic 128WebSphere 128wide search 70Windows service

configuring Tomcat as a service 128

X

XMLgeocoding constraint keys 146schemas 145

XML API 94overview 144

Z

Z1 result 138Z2 result 138Z3 result 138Z6 result 138


mapmarker usa v29 developer guide

Documents