Location Intelligence Geographic Information Systems MapMarker Plus Version 31 Developer Guide Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of Pitney Bowes, 350 Jordan Road, Troy, New York 12180-8399. ©1994-2019 Pitney Bowes All rights reserved. MapInfo, Group 1 Software, Centrus, and MapMarker are trademarks of Pitney Bowes All other marks and trademarks are property of their respective holders. Contact information for all Pitney Bowes Inc. offices is located at:: pitneybowes.com Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. The following trademarks are owned by the United States Postal Service: LACSLink, SuiteLink, DPV, ZIP + 4, ZIP Code, ZIP, CASS, CASS Certified, Post Office, P.O. Box USPS, U.S. Postal Service and United States Postal Service. Pitney Bowes is a non-exclusive DPV and LACSLink Licensee of the United States Postal Service® AD#1.08 Portions © January 2019 TomTom Inc. © 1987 - 2019 HERE. All rights reserved Shapefile C Library v. 1.2.10 is licensed under the MIT Style License. The license can be downloaded from: . © 1998 Frank Warmerdam. The source code for this library is available from . January 2019 Table of Contents 1 - Introduction 4 5 - Using the REST API 91 What Is Geocoding? 5 REST API Framework and Syntax 92 What Is MapMarker? 5 Usage Guidelines 99 MapMarker Features 6 REST API Examples 101 MapMarker Documentation Set 13 MapMarker Streets 14 6 - Deploying Applications 125 Getting Technical Support 15 Deploying MapMarker as a Servlet 126 2 - Designing Geocoding Applications16 Integration with MapMarker for Other Countries 127 Choosing a Development Tool 17 Defining the Geocoding Model 19 7 - Result Codes 131 Geocoding Application Design Overview 21 Understanding Result Codes 132 3 - Geocoding with MapMarker USA 29 Single Match (S category) 133 Best Match From Multiple Candidates (M Geocoding Terms 30 category) 139 Address Conventions for MapMarker USA 33 Postal Centroid Matches (Z category) 140 Geocoding with MapMarker USA 34 Geographic Matches (G category) 140 Sample Application Requirements and Setup34 Reverse Geocoded Matches (R category) 140 Running the Sample Application 35 Non-match Codes (N category) 141 Using the MapMarker USA Sample Application 35 A - Using the XML API 142 Street Geocoding 40 Postal Geocoding 46 Tips on Using the XSD Schemas 143 Geographic Geocoding 47 Geocoding Constraint Keys 144 Reverse Geocoding 48 Geocoding Request Types 148 Optimizing MapMarker USA – Usability and Performance Tips 50 B - JNI Adapter Configuration File Settings 151 4 - Using the MapMarker Java API 52 JVM Settings 152 Using the MapMarker Java USA API 53 Country Settings 152 Using the MapMarker Generic Java API 53 Using the JavaDocs API Documentation 53 Developing Geocoding Applications in Java 53 C - Using Database Extenders 153 Geocoding and Returning Candidate Information Geocoding Extenders for Database Developers 70 154 Creating a Reverse Geocoding Application in Java 78 Browsing Addresses 80 D - Error Messages 155 Geocoding To Postal Centroids 81 Geocoding to Geographic Centroids 82 MapMarker Java API Errors 156 Geocoding to Highway Exits 84 Geocoding to Airports 85 E - Match Codes and Location Codes161 DPV Related Actions 86 Returning Match Codes and Location Codes88 Match Codes 162 Standardizing Addresses 89 Location Codes 169 Creating a Web Geocoding Client in Java 90 Using Status Codes 181 184 MapMarker USA 31 Developer Guide 3 1 1 – Introduction Welcome to MapMarker USA, one of the premier address matching and geocoding offerings from Pitney Bowes. MapMarker USA enables you to assign geographic coordinates to large tables of American address records in a single session. In this chapter: What Is Geocoding? 5 What Is MapMarker? 5 MapMarker Features 6 MapMarker Documentation Set 13 MapMarker Streets 14 Getting Technical Support 15 Introduction What Is Geocoding? Geocoding is the process of assigning geographic coordinates to data that contain addresses. The coordinates assigned to each address turn each record into a geographic object that can be displayed on a map using MapInfo Professional or MapXtreme. Geocoding turns ordinary data records containing address information into geographic objects that can be displayed on a map. A list of customers, stores, or anything with a street address or postal code may be matched using the comprehensive street and postal code files provided in the Address Dictionary. The result of geocoding is an X/Y coordinate linked to a specific address. When displayed, this enables you to better visualize the relationships in your data. You can display coordinates by creating maps in MapInfo Professional or via MapXtreme and add to other map objects to give your data a geographic reference. You can then perform a wide variety of functions to analyze your data in geographic terms. Data that once was only readable in column and row format can be now viewed with a whole new perspective, thereby disclosing patterns and clusters you never knew existed. Visualizing your records on a map can make the relationships among your data clearer. You can display your geocoded records against a street map, a postal centroid map, a local map, or whatever is most appropriate to your needs. You can then use the wide variety of functions available in MapInfo mapping software to perform querying, create thematic maps, create territories, and perform many other types of geographic analysis. Beyond visualizing data on a map, location data can be leveraged in many ways. See Location Intelligence Products and related parts of the Pitney Bowes web site for details on how your organization can use location information to make better decisions. What Is MapMarker? MapMarker is a powerful geocoding tool produced by Pitney Bowes MapMarker enables you to assign geographic coordinates to large tables of U.S.-based address records in a single session. This is a key step toward mapping and analyzing your business data. MapMarker adds geographic coordinates to every record in your database that it matches against its comprehensive Address Dictionary, a database of USPS® street addresses, street geometry and the latest ZIP + 4® centroids. MapMarker assigns coordinates to an address based on how well it matched in the Address Dictionary. The precision of the match can vary. For each address you geocode, you may get back a single perfect, street-level match or a list of street-level match candidates from which you choose the best match. You may get a less precise match, for example a ZIP Code centroid match if you provided a ZIP Code or a city-level centroid match. To identify the match precision, MapMarker also returns a result code for each address that it geocodes. The precision that you require for your geocoded records depends on how you plan to use your data. MapMarker USA 31 Developer Guide 5 Introduction In addition to being a powerful geocoder, MapMarker is also a suite of tools that allows you to standardize your U.S. addresses, add spatial information and create points for your records, develop standalone or client/server custom geocoding applications, and embed MapMarker functionality in existing applications. The MapMarker Desktop application, MapMarker server, and MapMarker developer tools have geocoding capabilities that allow you to add geocoding functionality to your own desktop or Web application. MapMarker Features MapMarker USA allows a great deal of flexibility in geocoding. This section briefly describes the major features of MapMarker USA. This does not completely summarize all the MapMarker features and capabilities. See the MapMarker USA Release Notes for new features, Address Dictionary updates, and behavioral changes that you may notice with MapMarker. The Release Notes also describe fixes to customer-reported issues and known issues that customers must be aware of. The MapMarker USA Release Notes are located at the Pitney Bowes Product Documentation site. MapMarker Installer The MapMarker USA 31 installer is designed to simplify the installation and provide more feedback during installation. The installer accommodates: • Typical and custom installs • Upgrading software and data or upgrading data only • Silent installation and modification • Selecting and installing the JVM • Installing the sample application (for Server installation) • Selecting default and custom locations for installing software and data • Choosing shortcut locations • Uninstalling MapMarker Note: Note You must have administrator rights to install MapMarker software. This is true for all operating systems. Street Level Geocoding If you select the street level geocoding operation, MapMarker will match your full address record against its Address Dictionary and/or User Dictionary (If you have created and selected a User Dictionary.). This process will correct misspelled street addresses and city/town names. It can also correct postal code information, or add postcodes if your data does not already include them. After MapMarker completes the address cleaning step, it will geocode your records in accordance with the other preferences you have set. MapMarker USA 31 Developer Guide 6 Introduction Addresses that are geocoded to a street level return an S or M result code. See Chapter 7 Result Codes for a description of these and other result codes. Intersection Geocoding MapMarker USA can geocode to street intersections. Using any of several ways to designate a street intersection, MapMarker can find the position of the intersection of two street segments within a given postal code or city. See Intersection Geocoding on page 7. Addresses that are geocoded to an intersection return an SX result code. See Single Match (S category) on page 133 for a description of all result codes. PlaceName Geocoding PlaceNames are included in the data and can be geocoded by MapMarker USA.