MapMarker Australia v15.5 Developer Guide

MapMarker
Australia
®
v15.5
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 Software Inc., One Global View, Troy, New York 12180-8399.
©2010 Pitney Bowes Software Inc. All rights reserved. MapInfo, Group 1 Software, and MapMarker are trademarks of Pitney Bowes Software Inc. All other
marks and trademarks are property of their respective holders.
Asia Pacific/Australia:
Phone: +61.2.9437.6255
Fax: +61.2.9439.1773
Technical Support: 1.800.648.899
pbinsight.com.au
United States:
Phone: 518.285.6000
Fax: 518.285.6070
Sales: 800.327.8627
Government Sales: 800.619.2333
Technical Support: 518.285.7283
Technical Support Fax: 518.285.6080
pbinsight.com
Canada:
Phone: 416.594.5200
Fax: 416.594.5201
Sales: 800.268.3282
Technical Support:.518.285.7283
Technical Support Fax: 518.285.6080
pbinsight.ca
Europe/United Kingdom:
Phone: +44.1753.848.200
Fax: +44.1753.621.140
Technical Support: +44.1753.848.229
pbinsight.co.uk
Contact information for all Pitney Bowes Software Inc. offices is located at: http://www.pbinsight.com/about/contact-us.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
G-NAF is a registered trademark of PSMA Australia, Ltd.
Adobe Acrobat® is a registered trademark of Adobe Systems Incorporated in the United States
June 17, 2011
Table of Contents
Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
What Is MapMarker Australia? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
MapMarker Server and Developer Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
MapMarker Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
MapMarker Documentation Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
MapMarker Developer Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
MapMarker Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Publications on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Getting Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Before You Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
The Support Tracking System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Expected Response Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Exchanging Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Accessing the Pitney Bowes Business Insight FTP site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Software Defects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Data Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Chapter 2: Installing MapMarker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Installation Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
About the Address Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Operating Requirements and Performance Recommendations. . . . . . . . . . . . . . . . . .14
Operating Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Hardware and Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
JVM Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Database Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Supported Web Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Optimising Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Installing MapMarker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Install Using the Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Installing Silently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
MapMarker Australia v15.5
1
Developer Guide
Modifying the MapMarker Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Modify Using the Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Modify Silently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
Upgrading the MapMarker Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Upgrade Using the Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Upgrade Silently. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Uninstalling MapMarker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Uninstall Using the Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Uninstall Silently. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Starting the MapMarker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Chapter 3: Understanding Australian Geography and Addresses . . . . . . . . . . . 27
Australian States and Territories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Australian Postal System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Postcode Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Australian Census Geography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Meshblock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Local Government Area (LGA). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Format of Australian Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Australian Street Address Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Refining Your Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Input Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Street Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Town, Suburb, and State Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Postcode Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Intersection Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Ambiguous Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Chapter 4: Geocoding with MapMarker Australia. . . . . . . . . . . . . . . . . . . . . . . . . 35
Address Conventions for MapMarker Australia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Address Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Geocoding with MapMarker AUS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Sample Application Requirements and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Running the Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Testing the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Understanding the MapMarker AUS Sample Application . . . . . . . . . . . . . . . . . . . . . . .38
Preferences and Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Street Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Street Candidate Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Geocoding Street Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Typical Street Addresses with Must Match on Street and House Number . . . . . . . . . . . . . . . 43
Intersection Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
PO Box Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
MapMarker Australia v15.5
2
Developer Guide
Addresses and Candidates with Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Centerline Offset Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Fallback to Postal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Fallback to Geo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Postal Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Postal Candidate Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Geographic Geocoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Geographic Candidate Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Reverse Geocoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Reverse Geocoding Candidate Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Reverse Geocoding Preferences and Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Optimising MapMarker AUS – Usability and Performance Tips . . . . . . . . . . . . . . . . . .50
General Guidelines for Optimising Geocoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Batch Geocoding Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Interactive Geocoding Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Chapter 5: Using the MapMarker Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Using the MapMarker Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Developing Geocoding Applications in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
MapMarker AUS Java API Input Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
MapMarker AUS Java API Output Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Creating a Street Geocoding Application in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Setting the Input Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Setting Geocoding Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Geocode Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Australian Geocode Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Candidate Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Australian Candidate Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Candidate Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Using Match Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Setting the Coordinate System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
G-NAF PID Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Choosing G-NAF Standard or Street Frontage Points . . . . . . . . . . . . . . . . . . . . . . . . . .64
Returning Original G-NAF Coordinates as String Values . . . . . . . . . . . . . . . . . . . . . . .66
Returning Original Coordinates for Point User Dictionary Candidates. . . . . . . . . . . . . .67
Centerline Offset for User Dictionary Point Candidates . . . . . . . . . . . . . . . . . . . . . . . . .67
Postal Code Override. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Getting the Total Number of Candidates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Getting the Result Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Getting the Segment ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Creating a Web Geocoding Client in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Street Geocoding Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
MapMarker Australia v15.5
3
Developer Guide
Web client created using the MapMarker Australia API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Web client created using the MapMarker Generic API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Creating a Reverse Geocoding Application in Java . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Setting Import Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Setting the Input Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Setting Reverse Geocoding Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Reverse Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Reverse Geocoding Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Browsing Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Geocoding to Postal Centroids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Using the MapMarker Australia API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Using the MapMarker Generic API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Geocoding to Geographic Centroids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Address Interpolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Chapter 6: Using the XML API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Understanding the XSD Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
MapMarker XML Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Examples of XML Requests and Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Street Geocoding Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Street Geocoding Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Street G-NAF Geocoding Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Street G-NAF Geocoding Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Reverse Geocoding Request and Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Reverse Geocoding Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Postal Geocoding Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Postal Geocoding Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Candidate Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Geocoding Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Geocode Request Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
AUS Geocoding Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Candidate Additional Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Deploying MapMarker as a Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Using the Default Tomcat Servlet Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Deploying MapMarker Server in Other Web Environments . . . . . . . . . . . . . . . . . . . . . .98
Chapter 8: Custom User Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
What Is a Custom User Dictionary? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
User Dictionary Capabilities and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Source Data Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Required Input Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
MapMarker Australia v15.5
4
Developer Guide
Optional (Recommended) Input Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
User Dictionary File Names and Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Additional User Dictionary Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Data Access License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Address Range Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Street Intersections and Customised User Dictionaries. . . . . . . . . . . . . . . . . . . . . . . .104
Using the User Dictionary Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Guidelines for Creating a Point-Based User Dictionary . . . . . . . . . . . . . . . . . . . . . . . .109
Required Address Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Optional Address Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Configuring the User and Address Dictionary Ranking . . . . . . . . . . . . . . . . . . . . . . .110
Configuring the DataManagerSettings.properties File . . . . . . . . . . . . . . . . . . . . . . . . .111
Setting Dictionary Preferences Using MapMarker Java API . . . . . . . . . . . . . . . . . . . .112
Chapter 9: Result Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Understanding Result Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Single Close Matches (S category) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Interpreting Complete S Result Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Interpreting S5 Result Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Postal Code Centroid Matches (Z category). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Geographic Centroid Matches (G category) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Reverse Geocoded Matches (R category) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Non-match Codes (N category) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Appendix A: Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
MapMarker Java API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Engine Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Parser Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Data Access Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
License Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
General Geocoding Process Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Client Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Localisation (Geocoder Construction Time) Exceptions . . . . . . . . . . . . . . . . . . . . . . .123
Server Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Geocoding Engine Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Adapter Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
MapMarker Australia v15.5
5
Developer Guide
Introduction
Welcome to MapMarker Australia, the premier address matching product from
Pitney Bowes Business Insight. MapMarker Australia enables you to assign
geographic coordinates to large tables of Australian addresses in a single
session.
In addition to being a powerful geocoder, MapMarker allows you to standardise
your Australian addresses, add spatial information, and create points for your
records. The Desktop Application is ready to use as soon as you install it. The
Server product allows you to develop standalone or client/server custom
geocoding applications and embed MapMarker functionality in existing
applications.
In this chapter:
Š
Š
Š
Š
Š
Š
What Is MapMarker Australia? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
MapMarker Server and Developer Tools . . . . . . . . . . . . . . . . . . . . .7
MapMarker Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
MapMarker Documentation Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Getting Technical Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Data Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
1
Chapter 1: Introduction
What Is MapMarker Australia?
What Is MapMarker Australia?
MapMarker can geocode large tables of Australian street addresses in a single pass. This is a key
step toward mapping and analysing your business data.
MapMarker adds geographic coordinates to every record in your database that it matches against its
comprehensive Address Dictionary. The MapMarker Street Range Address Dictionary is included
with MapMarker Australia, and it contains Australian street addresses, street geometry, town/suburb
(city) centroids, and postcode centroids. Optionally, you can purchase the G-NAF National Address
File point dictionary to provide parcel precision geocodes for all addresses.
The standard street Address Dictionary is updated twice a year based on StreetPro data, which
contains address ranges built using the Geocoded National Address File (G-NAF) for Australia – the
comprehensive and current address reference in Australia.
MapMarker Australia can be purchased as:
•
•
MapMarker Australia Desktop Application. This is ready to use as soon as it is installed.
MapMarker Australia Server.
The MapMarker Australia 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. For example, you can geocode a portion of your table using the Quick Geocode
feature, or geocode a large database of addresses in batch mode. See the MapMarker Australia
User Guide for detailed information on using the Desktop Application.
This book, (MapMarker Australia Developer Guide) describes how to use MapMarker Server.
MapMarker Server and Developer Tools
MapMarker Sever includes developer tools that allow you to build and deploy geocoding
applications and add geocoding functionality to your Desktop or Web Application. - install and play
experience.
MapMarker Server enables multiple simultaneous geocoding requests to be served from a single
MapMarker engine. Using the Java API or XML API, developers can write client/server or
standalone geocoding applications.
MapMarker Australia v15.5
7
Developer Guide
Chapter 1: Introduction
MapMarker Features
MapMarker Features
See the MapMarker Australia v15.5 Release Notes for a summary of product features, address
dictionary updates, and behavioural 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 Australia v15.5 Release Notes are located on the Pitney Bowes Business
Insight Product Documentation site.
L
See the Introduction chapter of the MapMarker Australia User Guide for a detailed summary
of all MapMarker Australia features. The User Guide is provided on your installation media
and on the Pitney Bowes Business Insight Product Documentation site.
MapMarker Documentation Set
The documentation set for MapMarker Australia includes PDF and online resources to help you
make the most of the product. The set includes:
•
•
•
•
MapMarker Australia User Guide in PDF format.
Online Help for the MapMarker Desktop Application.
MapMarker Australia Developer Guide in PDF format. The Developer Guide covers the
MapMarker Server product and accompanying developer tools.
Release Notes that provide updated information on new features, behavioural changes in the
software, fixes for customer-reported issues, and known issues. MapMarker Release Notes are
posted to http://reference.mapinfo.com/.
MapMarker Developer Guide
This MapMarker Australia v15.5 Developer Guide (this document) describes how to install and use
the MapMarker Australia v15.5 Server product. Specific topics include
•
•
•
•
•
•
Using the Java API, with code examples
Using the XML API, with code examples
Using the provided sample application (Java client)
Deploying applications
Configuring user dictionaries using the API
Error messages
MapMarker Release Notes
The MapMarker Release Notes are posted to http://reference.mapinfo.com/ and contain a
summary of the following:
•
•
•
Data vintage
New features
Behavioural changes
MapMarker Australia v15.5
8
Developer Guide
Chapter 1: Introduction
Getting Technical Support
•
•
Bug fixes
Known issues
Publications on the Web
The MapMarker documentation and detailed version-specific Release Notes are available for
download on the Pitney Bowes Business Insight web site (http://www.mapinfo.com). To access
them, click the Support and Training tab on the home page, click the Documentation link; and then
click Publications.
Documentation on the web site may be updated if corrections are necessary or if new information
becomes available.
Getting Technical Support
Pitney Bowes Business Insight 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:
Asia-Pacific Headquarters
Support: 1800 648 899
Fax: 61.2.9439.1773
Main Office Phone (Sydney): 61. 2.9437.6255
Hours: Monday–Friday from 8:00am and 6:00pm (EST) Australian Eastern Standard Time,
excluding company holidays.
E-mail: pbbi.support@pb.com
The Americas
Support: 800 552 2511
Fax: 518.285.6080
Hours: Monday - Friday from 8:00am - 7:00pm EST, excluding company holidays.
E-mail: pbbi.support@pb.com
Europe/Middle East/Africa:
Support: +44 1634.880.141 (option 1)
Fax: +44 1634.880.383
Hours: Monday - Friday from 9am to 5pm GMT, excluding company holidays.
E-mail: pbbi.support@pb.com
Before You Call
Have the following information ready when contacting us for assistance on MapMarker Australia.
1. Serial Number (or Customer Agreement Number).
MapMarker Australia v15.5
9
Developer Guide
Chapter 1: Introduction
Getting Technical Support
2. Your name and organisation. 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?
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 quickly and effectively.
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, 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 addresses:
•
Globally – pbbi.support@pb.com
Accessing the Pitney Bowes Business Insight FTP site
For information regarding our FTP site, contact Technical Support. If information cannot be provided
electronically, Pitney Bowes Business Insight also accepts information in the following media
formats:
•
CD
•
DVD
MapMarker Australia v15.5
10
Developer Guide
Chapter 1: Introduction
Data Acknowledgments
Software Defects
If the issue is recognised as a defect in the software, the Technical Support representative will log
the issue in our incident database and assign an incident number that can be used for tracking
purposes.
Data Acknowledgments
You must ensure, pursuant to the End User License Agreement, that you include the appropriate
copyright/disclaimer information and associated logo, on any data output generated from
MapMarker Australia.
PSMA Australia Limited
Copyright© Based on data provided under license from PSMA Australia Ltd. PSMA Australia and
the elliptical compass rose are registered trademarks of PSMA Australia Limited.
G-NAF®
Pitney Bowes Business Insight
Copyright© Pitney Bowes Software Inc. All rights reserved.
While every care is taken to ensure the accuracy of the data within this product, the owners of the
data (including the State, Territory and Commonwealth Governments of Australia) do not make any
representations or warranties about its accuracy, reliability, completeness or suitability for any
particular purpose and, to the extent permitted by law, the owners of the data disclaim all
responsibility and all liability (including without limitation, liability in negligence) for all expenses,
losses, damages (including indirect or consequential damages) and costs which might be incurred
as a result for the data being inaccurate or incomplete in any way and for any reason.
MapMarker Australia v15.5
11
Developer Guide
Installing MapMarker
This chapter contains instructions for installing MapMarker. Refer to this chapter
for step-by-step instructions and other issues related to installation.
In this chapter:
Š
Š
Š
Š
Š
Š
Š
Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Operating Requirements and Performance Recommendations .14
Installing MapMarker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Modifying the MapMarker Installation . . . . . . . . . . . . . . . . . . . . . .22
Upgrading the MapMarker Installation . . . . . . . . . . . . . . . . . . . . . .24
Uninstalling MapMarker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Starting the MapMarker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
2
Chapter 2: Installing MapMarker
Installation Overview
Installation Overview
MapMarker is available as a Desktop product and as a Server product. This chapter describes the.
Server installation. If you purchased the Desktop product (which is sold and licensed separately),
see the Installing MapMarker chapter of the MapMarker Australia User Guide.
MapMarker Desktop The Desktop Application includes the graphical user interface for geocoding
addresses and the MapMarker Street Range Address Dictionary. You can purchase data for all
Australian states and territories or for individual states or collections of states. You can also
purchase the MapMarker G-NAF Point Address Dictionary. The MapMarker Desktop product (and
installation) is described in the MapMarker Australia User Guide.
The Desktop Application runs on Microsoft Windows only.
MapMarker Server The MapMarker Server product enables multiple simultaneous geocoding
requests to be served from a single MapMarker engine. It also includes the tools necessary for
developing MapMarker solutions using the Java API or XML API. The MapMarker Server product
(and installation) is described in the MapMarker Australia v15.5 Developer Guide.
L
The MapMarker Australia Desktop product and MapMarker Australia Server product are sold
and licensed separately. The Server product does not include a Desktop license.
MapMarker is delivered on one DVD, which includes the software, data, and installer.
The MapMarker Australia installer program can be used for the following purposes:
•
•
•
•
New installation. See Installing MapMarker on page 16.
Modifying existing installation to add or remove features. For example you could add new data or
add a feature to an existing installation. See Modifying the MapMarker Installation on
page 22.
Upgrading existing installation. For example, if a point release version of MapMarker is available,
you could upgrade to the point release with the same set of features that are already installed.
See Upgrading the MapMarker Installation on page 24
Uninstalling. See Uninstalling MapMarker on page 25.
Installation Components
All the components you need for installing MapMarker Australia are on the provided media. The data
is included as the MapMarker Street Range Address Dictionary and allows you to geocode your
records. You can also purchase and install the MapMarker G-NAF Point Address Dictionary. Both
the Street Range and G-NAF Point Address Dictionaries can be licensed any subset of states or
territories.
L
Your serial number and data unlocking code are attached to your media.
MapMarker Australia v15.5
13
Developer Guide
Chapter 2: Installing MapMarker
Operating Requirements and Performance Recommendations
About the Address Dictionaries
The MapMarker Address Dictionaries are installed during the installation of the MapMarker software.
MapMarker Australia comes with the following Address Dictionaries.
•
MapMarker Street Range Address Dictionary. This is always available.
<Install Folder>\MapMarker_AUS_v15.5_Data
•
Two Geocoded National Address File (G-NAF®) Point Address Dictionaries.
<Install Folder>\MapMarker_AUS_v15.5_Data\GNAF123
<Install Folder>\MapMarker_AUS_v15.5_Data\GNAF456
The two G-NAF123 Dictionary contains G-NAF address records with the highest precision of
geocoding (characterised by Reliability Level 1, 2, or 3).
L
For more information on the G-NAF Address Dictionaries, see the chapter Understanding
G-NAF Data in the MapMarker Australia User Guide. The User Guide is provided on your
media whether you purchased the Server product or the Desktop product.
The G-NAF456 Dictionary contains the remainder of address information in G-NAF that does not
meet high precision geocoding criteria (characterised by Reliability Level 4, 5, or 6.) In this table
good address references can continue to be used but the geocodes are less reliable. That is, they
may be a centre of road segment or centre of suburb rather than at a parcel point.
You can install all or only a portion of the data set that you purchased. To install only a portion of the
purchased data set, uncheck states that you do not want to install when you reach the Choose Install
Set dialog. You can install other licensed states at a later time.
MapMarker Australia data is updated up to four times per year. See your version-specific Release
Notes to verify the vintage dates of your data.
Operating Requirements and Performance Recommendations
Note the following recommendations in order to maximise the performance of your MapMarker
installation.
Operating Requirements, p. 14
Optimising Performance, p. 16
Operating Requirements
This section describes the basic software and hardware requirements for MapMarker Australia. See
your version-specific Release Notes for more detailed descriptions and updated information on
supported software and hardware.
MapMarker Australia v15.5
14
Developer Guide
Chapter 2: Installing MapMarker
Operating Requirements and Performance Recommendations
Hardware and Memory Requirements
The minimum system requirements for MapMarker on a full installation of the MapMarker Australia
Server product are:
•
•
1 GB RAM
5 GB available disk space (including 1 GB for address dictionary)
For optimal performance of a full installation of both the Desktop Application and MapMarker SDK
we recommend:
•
•
•
Dual core processor or better
2GB RAM
10 GB available disk space
Supported Operating Systems
MapMarker Australia Server runs on the following operating systems:
•
•
•
•
•
•
•
•
•
Microsoft Windows XP Professional (32 and 64-bit)
Microsoft Windows 2003 Enterprise Edition
Microsoft Windows Vista Ultimate Edition (32 and 64-bit)
Microsoft Windows 2008 Server
Microsoft Windows 7
Solaris 2.9 and 2.10
HP-UX 11
Red Hat Linux 4.0 and 5.0
SUSE Linux 9, 10 and 11
See the product Release Notes for detailed information on supported operating systems for your
specific version of MapMarker.
JVM Requirements
MapMarker Australia requires a Java Virtual Machine (JVM). The following JVMs are supported:
•
JVM 1.5 and 1.6
MapMarker Australia ships with:
•
•
•
Sun JRE v. 1.5.0_09 (for Microsoft Windows and Sun Solaris)
HP JRE 1.5.0._04 (for HP-UX)
Sun JRE 1.5.0_11 (for Linux)
See the product Release Notes for detailed JVM support information for your specific version of
MapMarker.
Database Support
MapMarker Australia supports the following ODBC databases and drivers.
•
•
SQL Server 2008
SQL Server 2005
MapMarker Australia v15.5
15
Developer Guide
Chapter 2: Installing MapMarker
Installing MapMarker
•
•
•
•
SQL Server 2000
Microsoft Access 2007 (Link to download: driver for Microsoft Access 2007)
Microsoft Access 2003
Microsoft Access 2000
MapMarker also supports the following Oracle drivers:
•
•
Oracle 11
Oracle 10G Release 2
You must install the Oracle driver separately. To use the driver, you must have the Oracle client
installed.
Supported Web Servers
The MapMarker server allows you to develop geocoding applications on any Java Platform,
Enterprise Edition (Java EE) application server that supports JDK 1.5 or JDK 1.6.
MapMarker Australia ships with:
•
Apache Tomcat 5.5 (installed if the Web Application feature is selected during installation)
See the product Release Notes for detailed web server support information for your specific version
of MapMarker.
Optimising Performance
To get the greatest benefit from the MapMarker geocoding capabilities, consider these guidelines for
optimising performance.
•
•
•
•
•
•
•
•
Use the fastest processor available to you. We recommend 2.5 Ghz dual processor or better
Have enough memory so that the operating system can allocate some memory to your disk
cache. We recommend 1 GB RAM or better
Have at least 10 GB available disk space
Sort your table by postcode before geocoding.
Choose exact match criteria for all (house number, street name, suburb name, postcode).
Do not create points automatically.
Remove indexes on any table output columns before geocoding.
Store the Address Dictionary on a local hard drive.
Installing MapMarker
This section describes the typical MapMarker installation procedures for Microsoft Windows users
and for UNIX/Linux users. The graphical installer interface guides you through the procedure. You
can also install silently, without user interaction.
Install Using the Graphical Interface, p. 17
Installing Silently, p. 21
MapMarker Australia v15.5
16
Developer Guide
Chapter 2: Installing MapMarker
Installing MapMarker
Install Using the Graphical Interface
Follow these steps for typical installation using the graphical installer program:
1. Begin the installation procedure as follows, depending on whether you are installing on Windows
or on UNIX/Linux:
•
On Microsoft Windows, place the MapMarker DVD into your drive. The installation should
start automatically. Click Install Product in the list of options. In the Install Product dialog
box, click Install MapMarker. Proceed to step 2.
If the installation does not automatically run, from the Windows 2000/2003/XP Start menu,
choose Run. From the Run dialog, type D:\SETUP.EXE in the Open command box (where
D is the drive letter of your DVD drive). On Microsoft VISTA, from the Windows VISTA Start
menu, type D:\SETUP.EXE in the search box provided, where D is the drive letter of your
drive.
•
On Solaris, Linux, or HP-UX, run the shell script from the root of the DVD using the
command:
sh startinstall.sh
Proceed to step 2.
To bypass the startinstall.sh script, go to the /instdata folder of the DVD, and run executable
appropriate for your operating system. For example, on a Linux operating system:
sh linux/install.bin
2. In the Introduction dialog, click Next to display the What’s New dialog box. This provides a brief
summary of new features for MapMarker Australia and provides data vintage information.
3. Click Next to display the License Agreement dialog.
4. After reading the License Agreement, click the I accept the terms of the License Agreement
button, and then click Next to display the Licensing dialog.
5. In the Licensing dialog box, type your MapMarker serial number and unlocking code. These
codes are attached to your media.
After entering the serial number and unlocking code, click Next.
If you entered valid serial number and unlocking codes, you will see the Choose Install Set dialog
box. If you did not enter the correct codes, you will receive an error message and have the
opportunity to re-enter the serial number and unlocking code.
MapMarker Australia v15.5
17
Developer Guide
Chapter 2: Installing MapMarker
Installing MapMarker
6. In the Choose Install Set dialog box, the default Typical Install Set shows all the software and all
the data you purchased. To see a description of each feature, click on the feature to highlight it. A
description of the selected feature appears in the Description box.
Check the boxes for the features that you want to install and clear the check boxes of the
features that you do not want to install. Product documentation is always installed.
L
The MapMarker SDK selections are available only for the Server product (Developer
Edition installation).
After choosing the features to install, click Next to display the Choose Install Folders dialog box
7. In the Choose Install Folder dialog box, select the locations to install MapMarker software and
data.
MapMarker Australia v15.5
18
Developer Guide
Chapter 2: Installing MapMarker
Installing MapMarker
You can use the default locations or click Choose to display the Browse for Folder dialog, where
you can navigate to the desired location. Click OK in the Browse for Folder dialog when you are
finished.
If you decide after selecting an alternative location that you would prefer the default location,
click Restore Default Folder in the Choose Install Folder dialog box.
When you have selected the software and data install folders, click Next.
8. MapMarkerMapMarkerMapMarkerMapMarkerMapMarkerMapMarkerMapMarkerIf you are
installing the MapMarker SDK and you chose to install the Web Application feature (from the
Choose Install Set dialog box, step 6), the Web Application Settings dialog box appears. If you
did not select this feature, proceed to step 9.
This dialog box gives you the opportunity to confirm or change host name, startup port, and
shutdown port. Port number 8095 is the default Startup Port number. Port 8007 is the default
Shutdown Port number.
Click Next to display the Choose Java Virtual Machine dialog box.
9. In the Choose Java Virtual machine dialog box, do one of the following:
•
Select the Install a Java VM specifically for this application button to install the Java
virtual machine that comes with MapMarker.
•
Select the Choose a Java VM already installed on this system button to select a Java
virtual machine that you already have installed on the computer. Then select the Search for
Others button to have the installer search your computer for an installed JVM. After the
search is completed, the dialog box will be populated with a list of the JVMs that were found
on your workstation. This may take some time.
MapMarker Australia v15.5
19
Developer Guide
Chapter 2: Installing MapMarker
Installing MapMarker
The Choose Java Virtual Machine dialog box appears as follows.
L
See your MapMarker version-specific Release Notes for complete information on
operating requirements and recommendations, including information on the supported
and recommended JVMs.
After selecting the JVM, Click Next to display the Choose Shortcut Folder dialog box. If you
select a JVM that is already installed on your system, and that JVM is invalid or cannot be found,
you will receive an error message.
10. In the Choose Shortcut Folder dialog, choose where you want to create the product icons. You
can create a new Program Group, place the icons in an existing Program Group, or make other
choices. After making your selection, click Next to continue.
11. In the Pre-Installation Summary dialog, review the disk space requirements and your install
selections. To edit any selections, click the Previous button to go back to the earlier dialogs.
MapMarker Australia v15.5
20
Developer Guide
Chapter 2: Installing MapMarker
Installing MapMarker
12. When you are satisfied with your installation choices, click Install. A progress dialog reports
progress as the software and data is installing.
An installation of MapMarker and the entire Address Dictionary may be time-consuming. The
amount of time required to install depends on how much data you are installing and machine
processing power. Do not cancel the install process the hard drive or DVD drive is active. To
verify that the installation is progressing, check the directory where the data is targeted to reside.
You should see new files being added as the process continues.
13. When the installation is finished, the Install Complete message appears. Click Done to exit the
installer.
Installing Silently
You can install MapMarker Australia without using a graphical interface and without user interaction.
This allows you to install MapMarker in environments that do not provide a graphical user interface.
To perform a silent install, use the properties file located in the root folder on the DVD. This file
defines the values for the installer to use when installing in silent mode. The file is named:
silentinstall.properties
You must edit the file to suit your particular needs. This file includes extensive comments to assist
you in this process. The serial number and unlocking code variables must be populated with valid
values. By default, the file is initially configured to install the engine, web application, samples,
additional tools, and licensed data. After editing this file, you can then launch the silent install and
pass this properties file to the installer program.
To edit the silentinstall.properties file:
1. Copy the silentinstall.properties template file to a a location on the target machine and open the
file in a text editor.
MapMarker Australia v15.5
21
Developer Guide
Chapter 2: Installing MapMarker
Modifying the MapMarker Installation
2. In the properties file, specify information for the install properties and set the software and data
features that you want to install. The file contains instructions for changing each of the values.
You must specify the following:
•
Serial Number and unlocking Code
•
Install location of the application files and data
•
Java Virtual Machine
•
Shortcuts/links location
•
Features to install
•
Web Application configuration
•
Desktop Application configuration
3. To launch the silent install, use the following command line arguments:
On Unix/Linux (where media/DVD represents the location of the installation media and /tmp
represents the location of the silentinstall.properties file).
/media/DVD/startinstall.sh -f /tmp/silentinsall.properties
On Windows operating systems (where D: represents the drive location of the installation media
and C:\tmp represents the location of the silentinstall.properties file).
start /w D:\instdata\install.exe -f C:\tmp\silentinstall.properties
Note You must use an absolute path for the properties file.
Modifying the MapMarker Installation
After you have installed MapMarker, you can run the Install program to modify the MapMarker
installation. For example, you may want to add data for states that you originally purchased but did
not previously install. Or you may want to remove features that you had previously installed.
L
Some things cannot be modified, such as the paths for software and data.
If MapMarker is already installed on your system, the install program will open to the Introduction
dialog. This bypasses the Licensing dialog box, since your you have already accepted the License
Agreement. You can then proceed to modify your installation
Modify Using the Graphical Interface, p. 22
Modify Silently, p. 23
Modify Using the Graphical Interface
To modify your MapMarker Australia installation, do the following:
1. Start the installer as described in step 1 of Install Using the Graphical Interface on page 17.
2. At the Introduction dialog box, click Next.
MapMarker Australia v15.5
22
Developer Guide
Chapter 2: Installing MapMarker
Modifying the MapMarker Installation
3. Enter or confirm your serial number and unlocking code. This information will already be
populated in the dialog box. If you purchased new features (such as additional data), you will
have a new unlocking code and must enter this in the Licensing dialog box.
4. The Install Set dialog box will appear and show a checked box for every MapMarker feature that
is installed. This is where you can install licensed features that you previously chose not to
install, or uninstall selected features. Do the following:
a. Uncheck any feature that you want to remove. For example you can uncheck and remove
data for states that you previously installed. Click Next.
b. Check features that you want to install. You will see only features that are licensed to you,
based on your unlocking code. Click Next.
5. You will see the Web Applications Settings dialog boxes if you chose to install the Web
Application. See step 8 (Web Application) from the procedure for Install Using the Graphical
Interface.
6. The Pre-installation Summary dialog box will show a list of product features that will be installed.
If you chose to install new features, they will be listed. If you chose to uninstall any features,
those features will be absent from the list of product features.
7. After verifying the product features, click Install.
8. The Install Complete dialog box will confirm your actions. Click Done.
Modify Silently
You can modify MapMarker Australia without using a graphical interface and without user
interaction. To perform a silent modify, edit the silentinstall.properties file to suit your needs. See
Installing Silently on page 21 for information on the location and use of the properties file.
The FEATURE_LIST variable of the silentinstall.properties file must include all the MapMarker
features that you want to install. For example, if you already had installed data for NSW and QLD
and wanted to add data for ACT and VIC, make sure that the FEATURE_LIST indicates all of those
choices – not just the states that you are adding.
You cannot use the silent modify procedure to change any of the following.
•
•
•
Program paths
JVM
Shortcuts and links
To make these changes, you must uninstall then reinstall MapMarker.
Also, you cannot use the silent modify procedure to change the configuration of a previously
installed Web Application. To change the configuration, you must you must uninstall then reinstall
the Web Application feature.
MapMarker Australia v15.5
23
Developer Guide
Chapter 2: Installing MapMarker
Upgrading the MapMarker Installation
Upgrading the MapMarker Installation
Major releases (such as 8.0) can be upgraded when point releases (such as 8.1) become available.
Similarly, one point release can be upgraded to the next point release. When performing an
upgrade, the installer updates all of the currently installed MapMarker features to the new version.
All settings and configuration will remain unchanged.
If you want to add or remove features or change settings, you must first upgrade and then run the
installer again to modify your installation (see Modifying the MapMarker Installation). Alternatively,
you may uninstall and then re-install MapMarker if you have changes that cannot be performed
using the Modify option.
L
You cannot upgrade from one major release to another. For example, you cannot upgrade
from MapMarker v14 to v15. You must perform a new installation of v15. You will be able to
upgrade to a point release if an upgrade is released.
You can have different versions of major releases on the same workstation (such as MapMarker
Australia v14 and v15.5), but you cannot have different point releases installed on the same
workstation. We recommend that you contact Technical Support if you want to use more than one
version of MapMarker.
Upgrade Using the Graphical Interface, p. 24
Upgrade Silently, p. 24
Upgrade Using the Graphical Interface
To upgrade MapMarker Australia to a point release (such as to from 8.0 to 8.1 when the upgrade is
available), do the following:
1. Start the installer as described in step 1 of Install Using the Graphical Interface on page 17.
2. Continue with step 2 through step 4 as described in Install Using the Graphical Interface. In
the Pre-Installation Summary dialog box, click Install to begin the upgrade.
3. When the Upgrade Complete dialog box appears, click Done.
Upgrade Silently
You can upgrade MapMarker Australia to a point release without using a graphical interface and
without user interaction. Start the silent installer as described in Installing Silently on page 21.
Because this is an upgrade, If there are any changes to the installation reflected in the properties file
they will be ignored.
MapMarker Australia v15.5
24
Developer Guide
Chapter 2: Installing MapMarker
Uninstalling MapMarker
Uninstalling MapMarker
When uninstalling MapMarker, you have two options, a complete uninstallation or removal of certain
features only. A complete uninstall will remove the MapMarker program directories, groups, and
icons. Files and folders created after the installation will not be removed or affected in any way.
You can uninstall specific features (rather than a complete uninstall) if you use the graphical
interface uninstall. The silent uninstall always does a complete uninstall.
Uninstall must be done using the same mode (graphical interface or silent) as the previous
installation, modify, or upgrade. So if your previous install, modify, or upgrade was performed using
the graphical interface, then the uninstall will be run using the graphical interface.
Uninstall Using the Graphical Interface, p. 25
Uninstall Silently, p. 25
Uninstall Using the Graphical Interface
Use Add/Remove Programs on their own workstation to remove MapMarker Server product.
1. Begin the uninstall procedure as follows, depending on whether you are uninstalling on Windows
or on UNIX/Linux:
•
On Microsoft Windows, from the Control Panel Add or Remove Programs utility. Select
MapMarker AUS v15.5 and click the Change/Remove button. Proceed to step 2.
•
On Solaris, Linux, or HP-UX Run the shell script from the root of the DVD using the
command:
sh
/opt/MMv15.5/Uninstall_MapMarker_AUS_v15.5/Uninstall_MapMarker_AUS_v1
5.5
where /opt/MMv15.5 is the directory into which MapMarker Australia was installed.
2. In the Uninstall MapMarker AUS dialog box, click Next.
3. Select Complete Uninstall or Uninstall Specific Features, then click Next.
4. If you selected Complete Uninstall in step 3, the uninstall program will run immediately and
MapMarker Australia will be completely uninstalled.
If you selected Uninstall Selected Features in step 3, uncheck the product features that you
want to uninstall, then click Uninstall to uninstall those features only.
5. When the uninstall completes, click Done.
Uninstall Silently
If your previous installation, modify, or upgrade of MapMarker was performed silently, the uninstall
will run silently as well. Launch the uninstall by running the command appropriate for your operating
system shown in step 1 of Uninstall Using the Graphical Interface. Remember, a silent uninstall
will always perform a complete uninstall of MapMarker.
MapMarker Australia v15.5
25
Developer Guide
Chapter 2: Installing MapMarker
Starting the MapMarker Server
Starting the MapMarker Server
After successfully installlang the MapMarker Australia v15.5 Server product, start the MapMarker
server as follows, depending on whether you are running on Windows or on UNIX/Linux:
•
On Microsoft Windows, from the Start Menu or the program group where you installed the
MapMarker icons, click the icon named Start MapMarker AUS v15.5 Server. The
MapMarker Server will now start.
If you chose not to install icons, open the directory where you installed MapMarker, and in the
subdirectory named sdk\tomcat\bin double-click on the file startup.bat. The
MapMarker Server will now start.
•
On Solaris, Linux, or HP-UX, from the directory where you installed the MapMarker icons, run:
sh Start_MapMarker_AUS_v15.5_Server
If you chose not to install icons, run the following command from the installation directory:
sh sdk/tomcat/bin/startup.sh
L
On all operating systems, Administrator privilege is required to start the MapMarker Server.
MapMarker Australia v15.5
26
Developer Guide
Understanding
Australian Geography
and Addresses
This chapter provides important information on Australian geography,
postcodes, the format and organisation of Australian addresses, and special
considerations for working with Australian data. This information will help you
understand and refine your input data so that you can more effectively geocode
Australian addresses and get the most from MapMarker Australia.
In this chapter:
Š
Š
Š
Š
Australian States and Territories . . . . . . . . . . . . . . . . . . . . . . . . . .28
Australian Postal System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Format of Australian Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . .30
Refining Your Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
3
Chapter 3: Understanding Australian Geography and Addresses
Australian States and Territories
Australian States and Territories
Australia is divided into six states and two territories, as follows:
Australian States and Territories
State or Territory
Abbreviation
New South Wales
NSW
Queensland
QLD
South Australia
SA
Tasmania
TAS
Victoria
VIC
Western Australia
WA
Australian Capital Territory
ACT
Northern Territory
NT
Australian Postal System
Australia’s postal system is organised using four-digit postcodes. Australia is divided into six states
and 2 mainland territories. There are also several external (island or research station) territories.
Postcodes may be an area (polygon) or point.
Postcode Formats
All postcodes consist of four digits. While there are exceptions, the general format of postcodes is as
follows:
Digit 1 – represents the state or territory, within the following general conventions:
Digit 1 of Postcodes
2
NSW
2600 and 2900
ACT
3
VIC
4
QLD
5
SA
MapMarker Australia v15.5
28
Developer Guide
Chapter 3: Understanding Australian Geography and Addresses
Australian Census Geography
Digit 1 of Postcodes
6
WA
7
TAS
0
NT
Digit 2 – represents a region within the state. State or territorial capitals usually have a 0 or 1 as the
second digit.
Digits 3 and 4 – Major towns usually have a 0 as the last digit (or sometimes as the last two digits).
Other Conventions – Other digit ranges are typically used for P.O. Box addresses and LVRs (Large
Volume Recipients).
These are general guidelines, and there are exceptions to these postcode number ranges.
Australian Census Geography
The Australian Bureau of Statistics (ABS) defines the Australian census divisions using the
Australian Standard Geographical Classification (ASGC). A Collection District (CD) is the basic
building block of the census. Other census divisions defined by the ASGC are:
•
•
•
•
•
•
•
•
•
•
•
•
Meshblock
Collection District (CD)
Statistical Local Area (SLA)
Local Government Area (LGA)
Statistical Subdivision (SSD)
Statistical Division (SD)
Statistical District (S Dist)
Statistical Region (SR)
Major Statistical Region (MSR)
Urban Centre/Locality (UC/L)
Section of State (SOS)
State/Territory (S/T)
The meshblock and LGA are relevant to MapMarker Australia geocoding. These terms and other
Australian census-related terms are described in the glossary of the Australian Bureau of
Statistics web site.
Meshblock
A Meshblock is the smallest geographic unit for which statistical data is collected by the ABS.
Meshblocks usually contain a minimum of 20 to 50 households. This is about one fifth the size of a
Collection District (CD).
MapMarker Australia v15.5
29
Developer Guide
Chapter 3: Understanding Australian Geography and Addresses
Format of Australian Addresses
When geocoding with the G-NAF Dictionary, each street candidate returns meshblock information (if
available) in an additional field named MESH_BLOCK_ID. You can use this information to do
additional attributions against your own data.
Local Government Area (LGA)
Local Government Area (LGAs) do not encompass all of Australia. For example, LGAs do not cover
extensive northern parts of South Australia, a large part of the Northern Territory, and the Australian
Capital Territory.
An LGA can include a number of official suburbs. It is best to use the suburb name for geocoding
purposes, but it is possible to get a match on the LGA (or to return LGA information) in geocoded
results from the MapMarker Street Range Address Dictionary.
An LGA can be returned by MapMarker Australia under these conditions only:
•
•
using the server version (not the desktop version)
geocoding with the MapMarker Street Range Address Dictionary (not the G-NAF Point
Dictionary.)
See Town, Suburb, and State Input Data on page 33 for suburb address guidelines and
information on LGA geocoding data
Format of Australian Addresses
This section illustrates Australia Post guidelines for formatting an Australian address. MapMarker
Australia bases its geocoding rules around this system, so understanding this format helps you
structure your input data for successful geocoding.
Australian address components are described below. These guidelines are adapted from the
Australia Post Addressing Guidelines. See:
http://www.auspost.com.au/BCP/0,1467,CH2092~MO19,00.html
Australian Street Address Components
Many address components are optional. This discussion focusses on the required address
components for Australian addresses.
Line 1
Addressee: Recipient name. This component is not used by MapMarker Australia for geocoding.
For example:
PITNEY BOWES BUSINESS INSIGHT
MR. JOHN SMITH
MapMarker Australia v15.5
30
Developer Guide
Chapter 3: Understanding Australian Geography and Addresses
Format of Australian Addresses
Line 2
Street Number and Type: The street address can include alphanumeric characters or address
ranges. Optionally, unit type (building name, apartment, suite) and building name information can be
included. Level information is geocoded if you are using the G-NAF Point Address Dictionary.
Some examples of street number and addresses are:
Apt. 19, 123 JONES ST.
11B WATERMAN AVE.
101-105 WENTWORTH RD.
Line 3
Placename, Suburb, State, Postcode: This line includes the placename, suburb/locality,
state/territory, and the postcode. Some examples are:
NORTH SYDNEY NSW 2060
SOUTH BRISBANE QLD 4101
Sample Addresses
These examples illustrate typical, properly formatted Australian addresses.
Addressed to organisation.
PSMA AUSTRALIA LIMITED
115 CANBERRA AVE
GRIFFITH ACT 2603
Addressed to Post Office Box recipient.
SILKHORSE TRAVEL
(ATTN: Mr. A BROWN)
PO BOX 37
SPRINGVALE VIC 3171
Addressed to Large Volume Recipient (LVR)
MS H. WILLIAMS
FINANCE AND ACCOUNTING
AUSTRALIA POST
219-241 CLEVELAND ST
STRAWBERRY HILLS NSW 1427
MapMarker Australia v15.5
31
Developer Guide
Chapter 3: Understanding Australian Geography and Addresses
Refining Your Input Data
Refining Your Input Data
To get the best match rates, make sure your address is in the best format possible before it is
geocoded. This section provides information and examples to ensure that your data is in the best
format possible before you start to geocode.
•
•
Input Data
Ambiguous Input Data
Input Data
Having your data in optimal condition maximises the performance, speed, and accuracy of the
geocoding. Building on the structure of an address shown in Format of Australian Addresses on
page 30, the following table describes the ideal structure for your input data.
Input Field
Description
Example
G-NAF PID
G-NAF Persistent Identifier. See the chapter
Understanding G-NAF Data in the MapMarker Australia
User Guide for information on PIDs and other G-NAF
features.
GAVIC411711441
Place Name
Business or organisation name. Place name information
is included in the G-NAF Point Address Dictionary and is
supported in User Dictionaries. The Street Range
Address Dictionary does not include place name
information.
Pitney Bowes
Software Inc.
Address
Full street address
170 Pacific Highway
Town/Suburb
Town, suburb, or locality name
Sydney
State
State or territory name
NSW
Postcode
4-digit postcode
2065
Refining your input data increases the efficiency and accuracy at which the geocoder operates. This
section helps you make sure your data is in the best form it can be before you geocode. The
following topics provide suggestions for formatting your data.
•
•
•
•
Street Input Data
Town, Suburb, and State Input Data
Postcode Input Data
Intersection Input Data
MapMarker Australia v15.5
32
Developer Guide
Chapter 3: Understanding Australian Geography and Addresses
Refining Your Input Data
Street Input Data
Follow these suggestions to ensure that your street input data is in the best format possible for
optimum geocoding:
1. House numbers and apartments – Remove spaces between house number and apartment
letter. 123 A Main Street does not geocode correctly because the geocoder assumes that the
name of the street is A. Two workaround options are available:
•
Do not include the apartment letter.
•
Delete the space between house number and apartment letter: 123A Main Street geocodes
because the geocoder ignores the A.
2. House numbers and unit information – The house number pinpoints the location of the
address. Apartment, suite, or unit numbers can also be used for geocoding process. Unit input
can be in several formats, as shown in the following examples:
•
Flat 2, 17 Jones St.
•
2/17 Jones St. (Use the forward slash to separate an apartment, flat, or unit number from the
thoroughfare number.)
•
Apt 19, 123 Main St., where Apt is the unit type and 99 is the unit number. In this format, you
must specify a valid unit type, otherwise the address will not be geocoded correctly.
•
99-123 Main St. For an address derived from the G-NAF Dictionary, this address is a unique
house number and is geocoded as a single delivery point, not as a range.
3. Directionals – Use directionals in the input address wherever possible. This is especially true
towns and cities, such as For example: 134 Centre Dandenong Road (include Centre), or 48-62
Pound Road West (include West).
4. Street types – These distinguish different streets of the same name. For example, Main Avenue
and Main Street are two entirely different entities. Using types is not essential, but it adds
precision to your data.
Town, Suburb, and State Input Data
Follow these notes to ensure that your town/suburb input data is in the best format possible for
optimum geocoding:
1. Town / Suburb – Your input address should use the official town or suburb name. This will
produce the best geocoding results. If MapMarker Australia identifies multiple candidates on the
street in the specified suburb, it can use the Local Government Area (LGA) to make the close
match. See Local Government Area (LGA) on page 30 for information on LGAs.
2. State / Territory– Use the standard abbreviation. In some cases the State field may be left blank,
but this may affect geocoding accuracy.
Postcode Input Data
Use the Australia Post four-digit standard postcodes. This should be the last item in a domestic
address.
MapMarker Australia v15.5
33
Developer Guide
Chapter 3: Understanding Australian Geography and Addresses
Refining Your Input Data
Intersection Input Data
You can use any of several formats to specify a street intersection address. One format is to use a
double ampersand (&&) between the intersecting streets to designate an intersection address. For
example "Hunter St && Elizabeth St" specifies an intersection. For more information on the G-NAF
Address Dictionaries, see the MapMarker Australia User Guide for a description of other intersection
searching formats.
Ambiguous Input Data
If MapMarker Australia encounters an incomplete address, it will still try to interpret and geocode the
address. But because these are ambiguous matches, the address may be geocoded to the wrong
street, town/suburb, state, or postcode. For example, 330 Main could be in any town or in any state
with a 330 Main Street. And while 330 Main St, NSW specifies the state, this address potentially
could be located on a Main Street in any number of cities.
Remember that a street number and name alone is not likely to give a good geocode match without
other pieces of information. Similarly, an intersection without town and state does not contain
enough information for an accurate geocode. The more complete input data you provide the
geocoder, the better your match rates will be.
MapMarker Australia v15.5
34
Developer Guide
Geocoding with
MapMarker Australia
This chapter describes the major MapMarker Australia v15.5 geocoding
features. All country-specific MapMarker products have similar capabilities, but
details depend on the addressing and postal conventions of the specific country.
MapMarker Australia v15.5 comes with a Java client sample application that
illustrates how to geocode Australian addresses.
In this chapter:
Š
Š
Š
Š
Š
Š
Š
Š
Š
Š
Address Conventions for MapMarker Australia . . . . . . . . . . . . . .36
Geocoding with MapMarker AUS . . . . . . . . . . . . . . . . . . . . . . . . . .37
Sample Application Requirements and Setup. . . . . . . . . . . . . . . .37
Running the Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . .38
Understanding the MapMarker AUS Sample Application. . . . . . .38
Street Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Postal Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Geographic Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Reverse Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Optimising MapMarker AUS – Usability and Performance Tips .50
4
Chapter 4: Geocoding with MapMarker Australia
Address Conventions for MapMarker Australia
Address Conventions for MapMarker Australia
This section describes some address conventions for Australian addresses and MapMarker
Australia v15.5.
For complete information on addressing practices and conventions and postcodes, see the
Australia Post web site.
Address Elements
Australian addresses may contain some or all of the following address elements.
Address Elements
Address Element
Description
Example
Place Name
Pitney Bowes Business Insight
A place name is typically a company,
organisation, business name, or building
name. Place Name is supported by User
Dictionaries and also supported by the
G-NAF Address Dictionary.
Street Name/Single
Line
Must include street name and may
include street type, house number, and
unit information. Also used for
unformatted (single-line) address input.
1 Elizabeth Plaza
Suburb
This is equivalent to AreaName3. The
sample application uses the label of
Suburb. Either Suburb or a PostCode
must be included in an input address.
North Sydney
State
This is equivalent to AreaName1. The
NSW
sample application uses the label of State
PostCode
PostCode should always be used for
proper addressing, but MapMarker
Australia v15.5 will add the postcode if it
is not provided on input.
2060
X (Longitude)
X coordinate (used as input for reverse
geocoding)
150.991012
Y (Latitude)
Y coordinate (used as input for reverse
geocoding)
-33.836827
MapMarker Australia v15.5
36
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Geocoding with MapMarker AUS
Geocoding with MapMarker AUS
The following sections describe some examples of geocoding.
Features are illustrated using the sample application that is installed with MapMarker. However, note
that the sample application does not expose every feature and is not a supported interface. It is for
demonstration and learning purposes only.
Sample Application Requirements and Setup
Before you try to geocode an address using the application, make sure that you have access to a
MapMarker Australia server. Your classpath must include path(s) to the following jar files.
mmjclient.jar
<Install_Folder> \sdk\engine\lib\client
mmjclient_aus.jar
<Install_Folder> \sdk\engine\lib\client
clibwrapper_jiio.jar
<Install_Folder>\sdk\engine\lib\common
commons-logging.jar
<Install_Folder>\sdk\engine\lib\common
jai_codec.jar
<Install_Folder>\sdk\engine\lib\common
jai_core.jar
<Install_Folder>\sdk\engine\lib\common
jai_imageio.jar
<Install_Folder>\sdk\engine\lib\common
jdom.jar
<Install_Folder>\sdk\engine\lib\common
log4j.jar
micsys.jar
<Install_Folder>\sdk\engine\lib\common
midev-common.jar
<Install_Folder>\sdk\engine\lib\common
midev-coordsys-core.jar
<Install_Folder>\sdk\engine\lib\common
midev-dataaccesscomponents-rtree.jar
<Install_Folder>\sdk\engine\lib\common
midev-geometry.jar
<Install_Folder>\sdk\engine\lib\common
mijts.jar
<Install_Folder>\sdk\engine\lib\common
miutil.jar
<Install_Folder>\sdk\engine\lib\common
mxjgeom.jar
<Install_Folder>\sdk\engine\lib\common
sjsxp.jar
<Install_Folder>\sdk\engine\lib\common
stax-api.jar
<Install_Folder>\sdk\engine\lib\common
MapMarker Australia v15.5
37
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Running the Sample Application
xercesImpl.jar
<Install_Folder>\sdk\engine\lib\common
xmlParserAPIs.jar
<Install_Folder>\sdk\engine\lib\common
mmjsample_aus.jar
<Install_Folder>\sdk\examples
Running the Sample Application
The MapMarker sample application is a Java client that illustrates how to geocode Australia
addresses using the MapMarker Australia v15.5 server.
You must first start the server then start the Sample Application, as follows.
Windows users From the Start menu, navigate to the program shortcuts for the MapMarker AUS.
Select Start MapMarker Australia v15 Server. After the server starts, select the program shortcut
for MapMarker Australia v15 Sample Application.
Unix users Unix users must first start the MapMarker Server (see Starting the MapMarker Server
on page 26) After the server starts, from the links directory run:
sh MapMarker_Australia_v15_Sample_Application
If links were not installed the MMJE_AUS_Sample.class can be run from the /sdk/examples
directory in the path where you installed MapMarker.
Testing the Server
The server must be running properly before you can perform any successful geocoding.
To test the server:
1. Examine the sample application's URL server test area. The URL to the MapMarker Australia
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 Australia server, the text under the URL
displays Server: VALID. If the connection is not successful, then the text under the URL displays
Server: INVALID.
Understanding the MapMarker AUS Sample Application
The MapMarker sample application is a Java client that illustrates how to geocode AUS addresses
using the MapMarker Australia v15.5 server.
MapMarker Australia v15.5
38
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Understanding the MapMarker AUS Sample Application
The sample application is provided for example and demonstration purposes and to help you
become familiar with MapMarker Australia v15.5. 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 (AUS_DataManagerSettings.properties)
will be configured to use the installed dictionary files. The data dictionary properties file is located in:
<Install_Folder>\sdk\tomcat\webapps\mapmarker40\WEB-INF\classes
By default, the properties file has the following paths to the G-NAF and Standard Address
Dictionaries:
DICTIONARY_PATH1=/C:/Program Files/MapInfo/MapMarker_AUS_v15/
MapMarker_AUS_v15_Data/GNAF123
DICTIONARY_PATH2=/C:/Program Files/MapInfo/MapMarker_AUS_v15/
MapMarker_AUS_v15_Data/
DICTIONARY_PATH3=/C:/Program Files/MapInfo/MapMarker_AUS_v15/
MapMarker_AUS_v15_Data/GNAF456
For more information on these dictionaries, see About the Address Dictionaries on page 14.
Preferences and Constraints
You can select constraints that determine the Must Match criteria. A candidate is returned only if it
meets these criteria. You can also select fallback options, dictionary preference, and control how
many candidates are returned.
Sample Application Constraints and Preferences
Must Match Constraints and
Preference
Description
Must Match House Num
If checked, a candidate must match the building/house
number in order for it to be considered a close match.
This constraint is used by default for MapMarker AUS.
Must Match Street
If checked, a candidate must match the street name in
order for it to be considered a close match. This
constraint is used by default for MapMarker AUS.
Must Match State
If checked, a candidate must match the State in order for
it to be considered a close match.
Must Match Post Code
If checked, a candidate must match the postal code in
order for it to be considered a close match.
Must Match Suburb
If checked, a candidate must match the Suburb in order
for it to be considered a close match.
Must Match Input
If checked, a candidate must match all the input elements
in order for it to be considered a close match.
MapMarker Australia v15.5
39
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Street Geocoding
Sample Application Constraints and Preferences(continued)
Must Match Constraints and
Preference
Description
Close Match Only
Specifies the geocoder return only those candidates that
have been flagged as close matches to the input address.
Fallback to Geographic
If no candidates are returned from an street geocoding
operation, MapMarker can fallback to the geographic
centroid.
Fallback to PostCodel
If no candidates are returned from an street geocoding
operation, MapMarker can fallback to the postal centroid
(if a postal code is supplied).
Max. Candidates
Specifies the maximum number of candidates to be
displayed in the Candidates panel. From the drop-down
selection, choose from All or from 1 through 50.
Dictionary Options (drop-down
list)
Select one of the following:
Geocode Type (drop-down list)
NO PREF. (no preference)
PREFER AD (prefer address dictionary)
PREFER UD (prefer user dictionary)
AD ONLY (address dictionary only)
UD ONLY (user dictionary only)
Select one of the following from the drop-down list:
Street
Postal
Geography
Reverse
Street Geocoding
If you provide a street address, and either a suburb or a postcode, you can perform an address
geocode. MapMarker Australia v15.5 will match your full address record against the available
dictionaries (Address, G-NAF, and any User Dictionaries). Minor misspellings in street addresses
and or suburb names can be corrected in the returned candidates (depending on the Must Match
constraints). MapMarker Australia v15.5 can also correct postcode information or add postcodes if
your input does not already include them.
MapMarker will geocode your records in accordance with the preferences you have set. See
Preferences and Constraints on page 39 for information how the sample application allows you to
control constraints.
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.
MapMarker Australia v15.5
40
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Street Geocoding
Street Candidate Returns
The following table shows the Street Candidate Return Fields in the MapMarker Australia v15.5
sample application.
Street Candidate Return Fields
Column Name
Contents and Description
Example
Close Match
T for close match or F for
non-close match.
Place Name
Pitney Bowes Business Insight
A place name is typically a
company, organisation, business
name, or building name. Place
name information is included in the
G-NAF Address Dictionary and is
also supported in User
Dictionaries. The Street Segment
Address Dictionary does not
include place name information.
Street
Street address can include unit
information, house number, and
street name.
1 Elizabeth Plaza
Suburb
Town
North Sydney
LGA
Local Government Area
North Sydney
State
State
NSW
Post Code
Full Postcode
2060
Meshblock
This is the smallest geographic unit 80020440000
for which statistical data is
collected by the Australian Bureau
of Statistics (ABS). Meshblock can
be returned from the G-NAF123
Dictionary.
Segment ID
Segment IDs are numeric codes
that uniquely identify each
interpolated point (S5 result) or
street centroid (S4 result)
candidate.
MapMarker Australia v15.5
41
T
900741752
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Street Geocoding
Street Candidate Return Fields (continued)
Column Name
ResultCode
Contents and Description
Result code for returned
candidates.
Example
S8HPNTSCZG. An S8 results indicates
point/parcel level precision. The G
indicates the result came from the
G-NAF Address Dictionary.
S5–PNTSCZA (S5 result code indicates
an interpolated street candidate.) An S4
result code is also possible, and this
indicates a street centroid candidate.
Z1 returned for Postal geocoding.
G3 result codes indicate a geography
match on an Suburb centroid
Longitude (X)
Returned for street, postal, or
geographic geocoded candidates.
150.991012
Latitude (Y)
Returned for street, postal, or
geographic geocoded candidates.
-33.836827
Geocoding Street Addresses
You can enter address information using separate fields. Each address element entered in an
appropriate field. See the table of Sample Application Constraints and Preferences for a
description of the input fields.
The Street Address input field can contain some or all these elements:
•
•
street name (this is required)
house number
Your input must also include either:
•
•
Suburb
Post Code (complete)
Descriptions and examples of street geocoding are covered in the following topics.
Typical Street Addresses with Must Match on Street and House Number
Addresses and Candidates with Ranges
Fallback to Postal
Fallback to Geo
MapMarker Australia v15.5
42
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Street Geocoding
Typical Street Addresses with Must Match on Street and House Number
Consider a typical input street address of:
Street Address: 1 Elizabeth Plaza
Suburb: North Sydney
State: NSW
Post Code: 2060
Using Must Match on Street and House Number, this returns one close match candidate.
Street Address
Suburb
1 Elizabeth Plaza North
Sydney
LGA
North
Sydney
State
NSW
Post Code
2060
Segment ID
900741752
ResultCode
S5HPNTSCZA
This close match candidate returned from the Address Dictionary has an S5 result code. Other result
codes are possible depending on how accurate the input address is and whether the match came
from the standard Address Dictionary, G-NAF Address Dictionary, or a User Dictionary.
The MapMarker Australia Server (Developer) Edition geocoder returns the Segment ID with every
S5 (interpolated point) or S4 (street centroid) candidate. Segment IDs are also returned for reverse
geocoded candidates. The segment ID is not with supported by the Desktop Application.
The following input does not return a close match candidate when you use Must Match on House
Number option, because there is no house number 11 on Elizabeth Plaza.
Street Address: 11 Elizabeth Plaza
Post Code: 2060
Suburb: North Sydney
However, there will be non-close match candidates.
Intersection Geocoding
MapMarker allows you to geocode to street intersections. There are several ways to designate
street intersections. See the Street Intersection Geocoding topic in the MapMarker Australia User
Guide.
For the following input address:
Street Address: CNR Hunter St AND Elizabeth St
Suburb: Sydney
State: NSW
This returns one close match candidate at 96 Hunter St. and 2 Elizabeth St. with an SX result code.
PO Box Geocoding
MapMarker Australia v15.5 geocodes PO Boxes to the centroid of the post office in which the PO
Box is located. PO Box geocoding is available for the standard Street Range Address Dictionary (not
the G-NAF dictionary). variations of acceptable PO Box formats.
MapMarker Australia v15.5
43
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Street Geocoding
For the following input address:
Street Address: PO Box 7770
Suburb: Perth
State: WA
This returns close match candidates with an SPHPNTSCZA result code.
Addresses and Candidates with Ranges
Each house number within a street segment is returned as a range.
For the following input address:
Street Address: 24-36 Meagher St.
Suburb: Chippendale
State: NSW
Post Code: 2008
MapMarker Australia v15.5 returns one close match candidate from the standard Address Dictionary
with an S5HPNTSCZA result code. A number of non-close candidates with Meagher Street
addresses are also returned.
Centerline Offset Feature
If you are geocoding with a user-generated Point User Dictionary, you can use the centerline offset
feature to relocate points at a specified distance from the associated street segment. The centerline
offset feature requires:
•
•
point information from a User Dictionary (not from the G-NAF dictionaries)
segment information from either the Address Dictionary or a User Dictionary
L
Centerline offset does not affect points returned from the G-NAF Address Dictionaries
because of potential inconsistencies with G-NAF metadata information. Instead, the G-NAF
Address Dictionary can return points that have been relocated to the street frontage of the
parcel. See Choosing G-NAF Standard or Street Frontage Points on page 64.
If you use this feature, returned point candidates will be offset a specified distance from the
associated street segment (rather than at the original parcel point). Where possible, the coordinates
are offset perpendicularly from the segment. If no segment geometry candidate is present, the
original point candidate is returned.
The centerline offset capability is disabled by default, but you can enable and control the offset
distance using several GeocodeConstraints methods. See Centerline Offset for User Dictionary
Point Candidates on page 67 for information on these methods.
Centerline offset candidates are returned with an SC result code. The U in the last character of the
result code indicates that the result came from a User Dictionary. For example:
SCHPNTSCZU
The centerlne offset feature is available with the Server (Developer) edition only and is supported in
the Sample Application; this feature is not available in the Desktop application.
MapMarker Australia v15.5
44
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Postal Geocoding
Fallback to Postal
If MapMarker Australia v15.5 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 Australia v15.5 attempts to geocode to the postal centroid.
The following input does not return a close street match candidate when you use Must Match on
Suburb because the Suburb is misspelled (Amoroo instead of Amaroo).
Street Address: u 1 39 Mornington St
Post Code: 2914
Suburb: Amoroo
However, if you select the Fallback to Postal option, you will get a close postcode match with a Z1
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 45.
Fallback to Geo
If MapMarker Australia v15.5 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 Geo
option. If street address geocoding did not return a close match candidate (and Suburb is supplied
on input), MapMarker Australia v15.5 attempts to geocode to the geographic centroid.
The following input does not return a close match candidate when you use street geocode with or
Must Match House No. because there is no house number 399.
Street Address: u 1 399 Mornington St
Post Code: 2914
Suburb: Amaroo
However, if you select the Fallback to Geo option, you will get a close postcode match with a G3
result code (suburb centroid match).
You can also directly geocode to a geographic centroid (rather than using the Fallback to Geo
option). See Geographic Geocoding on page 46.
Postal Geocoding
MapMarker Australia v15.5 can perform Postal geocoding to postcode centroids. You must enter a
complete postcode for Postal geocoding.
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:
Post Code: 2060
This returns one close match candidate with a Z1 result code (postal centroid match).
MapMarker Australia v15.5
45
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Geographic Geocoding
You can also use Postal geocoding as a fallback option if a Street geocoding operation fails to return
close match candidates.See Fallback to PostCodel on page 40.
Postal Candidate Returns
Postal geocoding requests returns a single matching postcode.
The following table shows the Postal Candidate Return Fields in the MapMarker Australia v15.5
sample application. The other fields are not relevant to postal geocoding, and will be empty for
postal 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
Post Code
Full Postcode
2060
Result Code
Result code for returned candidate. Z1
Longitude (X)
X coordinate
151/20578
Latitude (Y)
Y coordinate
-33.83934
Geographic Geocoding
MapMarker Australia v15.5 can perform Geographic geocoding to geographic centroids.
To perform a geographic geocode, enter an Suburb. Select Geography from the Geocode Type
drop-down list. Then click Geocode Address.
The following input can be geocoded to geographic centroid:
Suburb: Camroo
This returns one close match candidate with a G3 result code (geographic centroid match).
You can also use Geographic geocoding as a fallback option if a Street geocoding operation fails to
return close match candidates. See Fallback to Geographic on page 40.
Geographic Candidate Returns
Geographic geocoding requests returns a single matching postcode.
The following table shows the Geographic Candidate Return Fields in the MapMarker Australia
v15.5 sample application. The other fields are not relevant to geographic geocoding, and will be
empty for postal geocoding candidates.
MapMarker Australia v15.5
46
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Reverse Geocoding
Geographic Candidate Return Fields
Column Name
Contents and Description
Example
Close Match
T for close match or F for
non-close match.
T
Suburb
Result code for returned
candidates. (AreaName3)
North Sydney
LGA
Local Government Area
Blackall Tambo Regional
State
State (AreaName1)
QLD
Post Code
Full Postcode
4478
Result Code
Result code for returned candidate G3
Longitude (X)
X coordinate
146.12818
Latitude (Y)
Y coordinate
-25.56318
Reverse Geocoding
MapMarker Australia Server Edition supports reverse geocoding. If you provide X/Y
(Longitude/Latitude) coordinates, the geocoder returns the closest address for the given X/Y
location based on the available address dictionaries. Any available unit information is returned, but
unit information is not expanded into the candidate formattedAddress.
You can perform reverse geocoding using the standard segment address dictionary or using the
G-NAF address dictionary.
L
Reverse geocoding is available with the Server (Developer) edition only and is supported in
the Sample Application. Reverse geocoding is not available in the Desktop application and is
not available with User Dictionaries.
Candidates return a R result codes, indicating that records was matched by reverse geocoding. 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.
To perform a reverse geocode, select the Coordinates button in the Address Input group. This
activates the Coordinates X and Y input fields. Enter the X and Y coordinates and select Reverse
from the Geocode Type drop-down list. Then click Geocode Address.
For example, you can reverse geocode the following input:
X: 150.991012
Y: -33.836827
MapMarker Australia v15.5
47
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Reverse Geocoding
MapMarker Australia v15.5 returns one close match candidate from the an Address Dictionary (this
can be either the Standard address dictionary or G-NAF address dictionary.
See Creating a Reverse Geocoding Application in Java on page 74 for examples of reverse
geocoding using the Java API.
Reverse Geocoding Candidate Returns
A reverse geocoding operation returns the same type of address candidates as a traditional street
address geocoding operation. However, reverse geocoding does not return Longitude/Latitude
(those are used for input) and the result codes are different than for traditional address geocoding.
See Reverse Geocoding Candidate Returns on page 48.
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 multiple
candidates are returned, they are sorted by mainAddress and house number.
If a candidate includes ranges, then the range associated with the candidate’s house number is
returned.
Additionally, for each reverse geocoding candidate:
•
•
•
•
A returned field indicates its distance from the input location. See distance in the table of
Reverse Geocoding Candidate Return Fields on page 48.
Each candidate returns a result code that indicates the precision. See Reverse Geocoded
Matches (R category) on page 119.
Candidates include a house number, if one is available.
Candidates from a street segment dictionary include range information for the segment.
Reverse Geocoding Candidate Return Fields
Column Name
Contents and Description
Example
Match
Match flags are not set for Reverse
Geocoding.
Place Name
This is a Point of Interest (POI) and Pitney Bowes Business Insight
is used when geocoding with User
Dictionaries only This field is not
used with the Street Segment
Address Dictionary. See
Chapter 8: Custom User
Dictionaries.
Street Address
Street address can include house
number and street name.
1 Elizabeth Plaza
Suburb
Town
North Sydney
LGA
Local Government Ares
North Sydney
MapMarker Australia v15.5
48
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Reverse Geocoding
Reverse Geocoding Candidate Return Fields (continued)
Column Name
Contents and Description
Example
State
State
NSW
Post Code
Full Postcode
2060
Meshblock
This is the smallest geographic unit 80020440000
for which statistical data is
collected by the Australian Bureau
of Statistics (ABS). Meshblock can
be returned from the G-NAF123
Dictionary.
Segment ID
Segment IDs are numeric codes
that uniquely identify each
interpolated point (S5 result) or
street centroid (S4 result)
candidate.
900741752
Result Code
Result code for returned
candidates.
RS8G (Point/parcel level precision.
Candidate returned from G-NAF
dictionary with G-NAF Reliability level of
1 or 2.)
RS5A (RS5 result code indicates an
interpolated street candidate for reverse
geocoding.)
RS4A (RS4 indicates a street centroid
candidate for reverse geocoding.)
See Reverse Geocoded Matches (R
category) on page 119 for a complete
list of R result codes.
distance
Distance from input location in
meters.
0 if the input coordinates are reverse
geocoded to an exact location of a
candidate. Otherwise, the distance is in
meters. This value is not displayed in
the Sample Application but is displayed
in the XML output.
Reverse Geocoding Preferences and Constraints
You can specify the radius to search from the input coordinates. Street segments or points within
that radius are considered. The closest candidate within that radius is returned as a close match. If
more than one address or point is the same distance from the input location, then multiple close
match candidates can be returned. The default search radius is 150 meters and the maximum
search radius that can be specified is 1600 meters.
MapMarker Australia v15.5
49
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Optimising MapMarker AUS – Usability and Performance Tips
You can also specify the coordinate system for the input X/Y point. In the Java API use the
setCoordsys method of the ReverseGeocodeLocation class. See Setting the Coordinate System
on page 63. If you do not specify a coordinate system, the country default is used. For MapMarker
Australia this is GDA94.
Optimising MapMarker AUS – Usability and Performance Tips
You can use a number of strategies to improve the accuracy and speed of geocoding with
MapMarker Australia v15.5.
General Guidelines for Optimising Geocoding
MapMarker Australia v15.5 has been optimised for high performance. Follow these guidelines to
achieve even faster performance.
In general, you will achieve faster and more accurate geocoding if you standardise and format your
data. By reducing the ambiguity in the input data, MapMarker Australia v15.5 will be able to find
appropriate candidates faster. For complete information on addressing practices and conventions
and postcodes, see the Australia Post web site.
•
•
•
•
•
Use the fastest processor available to you. We recommend 2.5 Ghz dual processor or better.
Have enough memory so that the operating system can allocate some memory to your disk
cache. We recommend 2GB RAM or better.
Have at least 10 GB available disk space.
Use approved address formats in your input data.
Use Must Match criteria carefully.
For example, if you specify Must Match criteria, you may fail to identify a good candidate
because of a slight misspelling of the input address.
Batch Geocoding Guidelines
In addition to General Guidelines for Optimising Geocoding on page 50, the following guidelines
will help you achieve the best results when you are geocoding in batch mode (using the server).
•
•
•
Use postcodes in your input data. This can improve performance significantly depending on
other factors.
The proper combination of postcode with Suburb, will produce better performance. That is, make
sure that the postcode is consistent with the named Suburb.
Sort your input table by postcode before geocoding.
MapMarker Australia v15.5
50
Developer Guide
Chapter 4: Geocoding with MapMarker Australia
Optimising MapMarker AUS – Usability and Performance Tips
•
Use Must Match criteria wisely. 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 restrictive Must Match criteria
first. Then run the non-geocoded addresses using less restrictive Must Match criteria or with
Postal or Geo fallback enabled.
For best performance (speed), geocode your input file using less restrictive Must Match
criteria in the first geocoding pass.
Use the option to return "Close Matches Only". Also consider setting "Max Candidates" to 1
and "Max Ranges" to 0. These steps will reduce the data transfer between client and server.
To achieve this, in JavaAPI, use the following methods:
setCloseMatch
setMaxCandidates(int)
setMaxRanges(int)
In the XML API, specify the following in the BaseConstraints:
closeMatchOnly="true"
<maxCandidates>1</maxCandidates>
<maxRanges>0</maxRanges>
Interactive Geocoding Guidelines
In addition to General Guidelines for Optimising Geocoding on page 50, the following guidelines
may help you achieve the best results when you are geocoding in interactive mode.
•
•
Use less restrictive Must Match criteria to get a higher number of matches (with the possibility of
getting some false positive results).
Do not set "Close Matches Only". Also set "Max Candidates" to All (this is -1 in the
MaxCandidates Geocoding Constraint). This combination allows you to see all the available
candidates and make your choice as to which one is the best.
MapMarker Australia v15.5
51
Developer Guide
Using the MapMarker
Java API
This chapter shows how to build a geocoding application using the MapMarker
Australia Java API. It also discusses how to deploy your application, as well as
some of the geocoding features available in the API, such as geographic
centroid geocoding, and street or place name browsing.
For detailed information on all classes, refer to the API documentation for
MapMarker Australia. The API documentation is located in the \docs\aus\ folder
under the directory where you installed the product. For example: C:\Program
Files\MapInfo\MapMarker_AUS_v15.5\docs\aus\.
In this section:
Š
Š
Š
Š
Š
Š
Š
Using the MapMarker Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Developing Geocoding Applications in Java . . . . . . . . . . . . . . . .53
Creating a Street Geocoding Application in Java . . . . . . . . . . . . .55
Creating a Reverse Geocoding Application in Java . . . . . . . . . . .74
Browsing Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Geocoding to Geographic Centroids . . . . . . . . . . . . . . . . . . . . . . .78
Address Interpolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
5
Chapter 5: Using the MapMarker Java API
Using the MapMarker Java API
Using the MapMarker Java API
The MapMarker Java API is used to create custom geocoding applications with MapMarker
Australia or with any MapMarker country geocoder.
For detailed information on all classes, refer to the API documentation (Javadocs) for MapMarker
Australia. This is located in <install_dir >\docs\aus folder, where <install_dir> represents your
MapMarker installation directory. From that location, run index.html to see the MapMarker Javadocs.
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 MapMarkerJava API.
Developing Geocoding Applications in Java
Within the Java API, there are objects and calls that are specialised for handling Australian
addresses. For example, some geocode constraints are designed to handle address content from
the Australian G-NAF Dictionary. You can use the Australian-specific statements if you want to
optimise your application for Australian address geocoding and are not concerned with geocoding
other national addresses.
If you expect the application to handle more than one MapMarker country, use the generic Java
strategy and statements. This strategy produces the most portable application, which can be used to
geocode addresses from Australia or any other country that is supported by the same version of
MapMarker.
This chapter shows both the generic Java API approach and the comparable Australian-specific API
calls and examples.
MapMarker AUS Java API Input Fields
The Java Input Fields and Descriptions table shows and describes the input fields for the Java
API.
Java Input Fields and Descriptions
Java Input Field
Address Item
State
State (not required). Can be part of postAddress instead.
LGA
LGA (not required).
Suburb
Suburb (not required if postcode present). Can be part of
postAddress instead.
PostCode
Post Code (not required if suburb is present). Can be part of
postAddress instead.
PostAddress
Can be a combination of suburb/locality, state and postcode.
MapMarker Australia v15.5
53
Developer Guide
Chapter 5: Using the MapMarker Java API
Developing Geocoding Applications in Java
Java Input Fields and Descriptions (continued)
Java Input Field
Address Item
AddressNumber
(can be separate or part of StreetName instead House Number
StreetName
Street Address Can be Unit plus full street name with house
number.
PlaceName
Place/Building Name
MapMarker AUS Java API Output Fields
The Java Output Fields and Description table shows and describes the output fields for the Java
API.
Java Output Fields and Description
Java Output Field
Address Item
State
State
LGA
LGA
Suburb
Suburb
postCode1
PostCode
AddressNumber
House Number
preAddress
Pre street name information, such as "THE", "SAINT",
"MOUNT", "ST", "ST.", "MT.", "MT"
preDirectional
the pre-Directional
preThoroughfareType
Pre ThoroughfareType
MainAddress
Street Name
postThoroughfareType
Post Thoroughfare Type
postDirectional
the post-Directional
placeName
the place\Building Name
formattedStreetAddress
[Unit] house number] [Full street name]
formattedLocationAddress
[suburb] [state] [postcode]
GNAF Additional Field Information There are direct methods for these items
MeshBlock
MapMarker Australia v15.5
MeshBlock Id
54
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
Java Output Fields and Description (continued)
Java Output Field
Address Item
GNAF Confidence Level
GNAF Confidence Level
GNAF Reliability code
GNAF Reliability
GNAF Geocoding Level
GNAF Geocode Level
GNAF PID
GNAF PID
Creating a Street Geocoding Application in Java
Make sure that your application contains these import statements:
Using the AUS-specific Java API approach:
/* MapMarker Australia Java API */
import com.mapinfo.mapmarker.user.MapMarkerJavaAPI
import com.mapinfo.mapmarker.user.MMJEngine;
import com.mapinfo.mapmarker.user.ClientGeocodeResponse;
import com.mapinfo.mapmarker.AUS.AUS_GeocodeConstraints;
import com.mapinfo.mapmarker.IGeocodeConstraints;
import com.mapinfo.mapmarker.AUS.AUS_UserCandidateAddress;
import com.mapinfo.mapmarker.AUS.AUS_UserInputAddress;
Using the generic Java API approach:
/* MapMarker Generic Java API */
import com.mapinfo.mapmarker.user.MMJEngine;
import com.mapinfo.mapmarker.client.ClientGeocodeResponse;
import com.mapinfo.mapmarker.IGeocodeConstraints;
import com.mapinfo.mapmarker.common.AddressImpl;
import com.mapinfo.mapmarker.common.Address;
Note that a copy of the AUS_DataManagerSettings.properties file must be in your classpath with the
correct location of the MapMarker data.
Setting the Input Address
You geocoding application must set the input address. Following is an example of how to set the
input address if you were using the AUS-specific Java API approach:
/* Input address example */
String addr = "1 Elizabeth Plaza";
String postcode = "2060";
String suburb = "North Sydney";
String state= "NSW";
String LGA = "North Sydney"
AUS_UserInputAddress inpAddr = new AUS_UserInputAddress();
MapMarker Australia v15.5
55
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
/* Set the input Address */
inpAddr.setStreet_Name(addr);
inpAddr.setSuburb(suburb);
inpAddr.setState(state); \
inpAddr.setLGA
inpAddr.setPostCode(postcode);
If you are using the generic Java API approach, use the Address class implemented with
AddressImpl.
AddressImpl = new AddressImpl();
/* Set the input Address */
inpAddr.setCountry(“AUS”);
inpAddr.setMainAddress(addr); /* street */
inpAddr.setAreaName3(suburb); /* suburb */
inpAddr.setAreaName1(state); /* state */
inpAddr.setPostCode(postcode); /* postcode */
Setting Geocoding Constraints
You can also set the geocoding constraints (or preferences). If no constraints are explicitly provided,
MapMarker Australia v15.5 uses default settings. Following is an example of how to set constraints
using the AUS-specific Java API approach:
AUS_GeocodeConstraints geoCon = new AUS_GeocodeConstraints();
/* Geocode Constraints:
* Review Java docs for a complete constraint list and
* default values
*/
geoCon.setMustMatchAddressNumber(true);
geoCon.setMaxCandidates(1);
geoCon.setReturnCloseCandidatesOnly(true);
geoCon.setMustMatchSuburb(true);
geoCon.setFallbackToPostal(false);
If you are using the generic Java API approach, use the GeocodeConstraints class:
GeocodeConstraints=new GeocodeConstraints();
constraints.setMustMatchAddressNumber(true);
constraints.setMaxCandidates(1);
constraints.setMustMatchAreaName3(true);
constraints.setReturnCloseCandidatesOnly(true);
constraints.setFallbackToPostal(true);
Geocoding constraints affect the conditions under which MapMarker Australia attempts to match a
record. Changing settings can affect the time in which MapMarker takes to geocode a record.
Choose matching conditions to fit your needs. Generic (GeocodeConstraints) and Australia
(AUS_GeoodeConstraints) constraints are described as follows.
MapMarker Australia v15.5
56
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
Geocode Constraints
com.mapinfo.mapmarker.user.GeocodeConstraints
The GeocodeConstraints class provides a generic implementation for setting geocoding engine
properties. It defines constants that are used by local country geocoders for standard geocoding
settings. The Geocode Constraints table describes the available constraints.
Geocode Constraints
Key
Description
Default
KEY_CLIENT_CRS
“epsg:4283”
String describing the client coordinate
system. Accepted values include EPSG
Names as well as MAPINFO
MAPBASIC Projection String SRS
(Spatial Reference System) Names.
See com.mapinfo.coordsys.CoordSys.
Default uses GDA94.
KEY_CLOSEMATCHESONLY
Only close matches are returned.
false
KEY_CORNEROFFSET
Defines the position of the geocoded
point with respect to the corner.
12.0
KEY_CORNEROFFSETUNITS
The units used in
KEY_CORNEROFFSET.
“m” (metres)
KEY_DICTIONARY_SEARCH_ORDER Defines the order in which dictionaries
are searched.
null
KEY_DICTIONARY_USAGE
Specifies AD (Address Dictionary) or
UD (User Dictionary). When using AD
and UD together, prefer a UD close
match over an AD close match
AD_AND_UD
KEY_FALLBACK_TO_GEOGRAPHIC
If no close street level candidates found false
return geographic centroid for the input
address.
KEY_FALLBACK_TO_POSTAL
If no close street level candidates found false
return postal centroid for the input
address.
KEY_MATCH_MODE
This key contains the match mode
value. This must be one of the defined
match modes. The possible key values
are described in
MapMarker Australia v15.5
57
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
Geocode Constraints (continued)
Key
Description
Default
KEY_MAXCANDIDATES
Maximum number candidates to be
returned. (use "-1" to return all
candidates)
3
KEY_MAXRANGES
Maximum ranges per candidate to be
returned (use "-1" to return all ranges)
0
KEY_MAXRANGEUNITS
Maximum number of range units that is 0
returned for each range.
KEY_MUST_MATCH_ADDRNUM
Only candidates matching address
number are considered close.
false
KEY_MUST_MATCH_AREA1
Only candidates matching AreaName1
can be considered close.
false
KEY_MUST_MATCH_AREA2
Only candidates matching AreaName1
can be considered close.
KEY_MUST_MATCH_AREA3
Only candidates matching AreaName3
can be considered close.
KEY_MUST_MATCH_AREA4
Only candidates matching AreaName1
can be considered close.
KEY_MUST_MATCH_COUNTRY
Requires Australia country match.
true
KEY_MUST_MATCH_INPUT
Only candidates matching all input
areas (where MUST_MATCH is
defined) are considered close.
false
KEY_MUST_MATCH_MAINADDR
Only candidates matching the main
address are considered close.
false
KEY_MUST_MATCH_POSTAL
Requires postcode match for a close
match.
false
KEY_STREETOFFSET
Defines the position of the geocoded
point with respect to the centreline of
the street.
10.0
KEY_STREETOFFSETUNITS
The units used in
KEY_STREETOFFSET.
“m” (metres)
MapMarker Australia v15.5
58
false
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
Australian Geocode Constraints
com.mapinfo.mapmarker.AUS.AUS_GeocodeConstraints
The AUS_GeocodeConstraints class provides local implementation of GeocodeConstraints. The
AUS_GeocodeConstraints table describes the available constraints.
AUS_GeocodeConstraints
Key
Description
Default
GDA94
Constant for Geodetic
Datum of Australia.
GEOCODE_TYPE_PID
Custom geocode type
constant
no default. See G-NAF PID
Lookup on page 64
KEY_GNAF_ORIGINAL
Constant to request
G-NAF original
coordinates. If true,
original G-NAF
coordinates are
returned.
false – G-NAF truncated and
rounded points are returned).
See Returning Original G-NAF
Coordinates as String Values
on page 66.
KEY_STREET_FRONTAGE_POINTS Constant to request
G-NAF street frontage
points. See Choosing
G-NAF Standard or
Street Frontage
Points on page 64.
Use the system default
behaviour as specified by the
AUS_DataManagerSettings.pro
perties file. See the description
in the table of G-NAF Frontage
Point Methods on page 65
KEY_POSTAL_CODE_OVERRIDE
false – a missing or incorrect
input city name will eliminate the
candidate as a close match. See
Postal Code Override on
page 68.
Constant to return a
close match candidate
based on a postcode
and street address
match, even if the input
city is missing or
incorrect.
Candidate Addresses
com.mapinfo.mapmarker.CandidateAddress
The CandidateAddress class represents the CandidateAddress that is returned from call to a
geocodable address. The CandidateAddress contains CandidateRanges if range data was found for
the address. The values in the CandidateAddress Class table are codes that represent the
precision of the returned candidate. .
MapMarker Australia v15.5
59
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
CandidateAddress Class
Constant
Value
Description
ADDRESS_POINT_PROJECTED
18
Precision code indicating that the original point
was offset from the nearest segment. See the
Centerline Offset Feature on page 44.
ADDRESS_POINT_INTERPOLATED
17
Precision code indicating that the result was
generated by using address point data to modify
the candidates segment data.
ADDRESS_POINT_PRECISION
16
Precision code indicating the result is an
Address Point.
GEOGRAPHIC_AREANAME1
8
Match level indicating that the candidate point
represents an area name 1 centroid for this
candidate address.
GEOGRAPHIC_AREANAME2
9
Match level indicating that the candidate point
represents an area name 2 centroid for this
candidate address.
GEOGRAPHIC_AREANAME3
10
Match level indicating that the candidate point
represents an area name 3 centroid for this
candidate address.
GEOGRAPHIC_AREANAME4
11
Match level indicating that the candidate point
represents an area name 4 centroid for this
candidate address.
LOCAL_CUSTOM_POINT_
PRECISION_1
12
Additional point precision for unspecified custom
item.
LOCAL_CUSTOM_POINT_
PRECISION_2
13
Additional point precision for unspecified custom
item.
LOCAL_CUSTOM_POINT_
PRECISION_3
14
Additional point precision for unspecified custom
item
LOCAL_CUSTOM_POINT_
PRECISION_4
15
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.
MapMarker Australia v15.5
60
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
CandidateAddress Class (continued)
Constant
Value
Description
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_ 4
PARTIAL
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 value 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
Australian Candidate Addresses
com.mapinfo.mapmarker.AUS.AUS_UserCandidateAddress
The AUS_UserCandidateAddress Class extends and provides a local implementation for the
CandidateAddress Class. This returns candidate information on G-NAF, meshblock, and other
Australian-specific features.
L
If you are using the XML API, this information is returned in Additional Fields.
AUS_UserCandidateAddress Class
Key
Description
KEY_GNAF_CONFIDENCE
G-NAF Confidence Level
KEY_GNAF_RELIABILITY
G-NAF Reliability
KEY_GNAF_GEOCODE_LEVEL
G-NAF Geocode Level
KEY_GNAF_PID
G-NAF PID
MapMarker Australia v15.5
61
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
AUS_UserCandidateAddress Class(continued)
Key
Description
KEY_MESH_BLOCK
G-NAF Meshblock ID
KEY_LEVEL_TYPE
Level Type, returned when a level type is associated with a
unit.
KEY_LEVEL_NUMBER
Level Number, returned when a level number is associated
with a unit.
KEY_ORIGINAL_LONGITUDE
Original G-NAF Longitude coordinates returned as a string
accurate to 8 digits after the decimal. See Returning
Original G-NAF Coordinates as String Values on
page 66.
KEY_ORIGINAL_LATITUDE
Original G-NAF Latitude coordinates returned as a string
accurate to 8 digits after the decimal.
KEY_UD_ORIGINAL_LONGITUDE
Original longitude returned from a point-based user
dictionary candidate. Accurate to any number of digits,
depending on the accuracy of the source data. See
Returning Original Coordinates for Point User
Dictionary Candidates on page 67.
KEY_UD_ORIGINAL_LATITUDE
Original latitude returned from a point-based user dictionary
candidate. Accurate to any number of digits, depending on
the accuracy of the source data.
Candidate Ranges
com.mapinfo.mapmarker.CandidateRange
The CandidateRange class contains information about a candidate's ranges and street range parity.
The Odd/Even Range Indicator constants indicate whether an address range contains odd or even
house numbers. The Street Side Range Indicator constants indicate whether the range is on the
left or right side of the street.
This range information is obtained using the getLeftRightIndicator and getOddEvenIndicator
methods of the CandidateRange class (com.mapinfo.mapmarker.CandidateRange).
Odd/Even Range Indicator
Constant
Value
Description
ODD_EVEN_BOTH
0
Range contains both odd and even house
numbers.
ODD_EVEN_EVEN
2
Range contains even house numbers.
MapMarker Australia v15.5
62
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
Odd/Even Range Indicator
Constant
Value
Description
ODD_EVEN_ODD
1
Range contains odd house numbers.
ODD_EVEN_UNKNOWN
-1
Unknown house number odd/even status for this
range.
Street Side Range Indicator
Constant
Value
Description
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.
Using Match Modes
The following constants and methods are related to match modes. These are included in the
GeocodeConstraints class.
Modes override Must Match criteria, except for MATCH_MODE_NONE, which means that custom
settings (Must Match constraints) are used.
Match Mode Constants
Constant
Description
RELAXED_MODE
Sets Relaxed match mode.
EXACT_MODE
Sets Exact match mode.
DEFAULT_MODE
Sets Default match mode.
MATCH_MODE_NONE
Indicates that match mode is not used. This means that
custom individual settings (MustMatch constraints) are
used instead. See Geocode Constraints on page 57.
KEY_MATCH_MODE
Indicates which match mode is being used.
Setting the Coordinate System
A coordinate system is a recognised 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 Australia v15.5
63
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
MapMarker Australia uses all of the coordinate systems supported by MapXtreme, including
systems recognised by the European Petroleum Survey Group (EPSG).
Coordinate systems can be set through the setClientCoordinateSystem method of the
AUS_GeocodeConstraints class. This class extends the GeocodeConstraints class, which
implements IGeocodeConstraints.
If you use the core GeocodeConstraints, the default coordinate system is GDA94 (Geocentric
Datum of Australia).
The following example uses the CoordSys object to set the coordinate system to WGS84. This
overrides the default value GDA94.
AUS_GeocodeConstraints constraints = new AUS_GeocodeConstraints();
constraints.setClientCoordinateSystem(CoordSys.longLatWGS84);
Alternatively, you can use the equivalent epsg string value:
constraints.setClientCoordinateSystem("epsg:4326");
G-NAF PID Lookup
You can geocode a unique G-NAF PID. Following is an example of how to input a G-NAF PID.
// PID lookup example
AUS_GeocodeConstraints constraints = new AUS_GeocodeConstraints();
AUS_UserInputAddress inpAddr = new AUS_UserInputAddress();
inpAddr.setGNAFPID("GAACT715293357");
MMJEngine engine = new MMJEngine();
ClientGeocodeResponse response =
engine.geocode(AUS_GeocodeConstraints.GEOCODE_TYPE_PID,
inpAddr, constraints);
//... candidate is returned ...
Choosing G-NAF Standard or Street Frontage Points
Coordinates returned from the G-NAF123 address dictionary can be returned as the standard points
or as street frontage points. The standard points are the most precise (rooftop) points available. The
street frontage points are relocated to the frontage of the candidate location, and these are generally
preferable for routeing applications.
Both sets of points (original and frontage) are stored in the G-NAF123 address dictionary. You can
choose which set of points that you want MapMarker Australia v15.5 to return. By default, the
standard points are returned.
MapMarker Australia v15.5
64
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
The AUS_GeocodeConstraints class includes the following methods to control whether standard
points or street frontage points are returned from the G-NAF123 dictionary.
G-NAF Frontage Point Methods
Method
Usage
setReturnStreetFrontagePoints(bFlag)
Set bflag to true to return street frontage points from the G-NAF
dictionary. Set to false to return standard points.
getReturnStreetFrontagePoints()
Returns true if street frontage points are returned from the
G-NAF dictionary.
getUsingDefaultStreetFrontagePoints()
If setReturnStreetFrontagePoints has not been called with either
true or false, then getUsingDefaultStreetFrontagePoints always
returns true. This means that the default behaviour is controlled
by the AUS_DataManagerSettings.properties file on the engine
or server.
If no default behaviour is specified in the
AUS_DataManagerSettings.properties file, standard points are
returned. To change the default behaviour to return frontage
points, add DEFAULT_STREET_FRONTAGE=true to the
AUS_DataManagerSettings.properties file.
The following piece of sample code demonstrates how street frontage points are returned.
// choice of points ( use street frontage ) example
AUS_UserInputAddress inpAddr = new AUS_UserInputAddress();
inpAddr.setStreet_Name("13 Bimini Drive");
inpAddr.setSuburb("Yaroomba");
inpAddr.setState("QLD");
inpAddr.setPostCode("4573");
AUS_GeocodeConstraints constraints = new AUS_GeocodeConstraints();
// set to return the street frontage points for G-NAF street candidates
constraints.setReturnStreetFrontagePoints(true);
MMJEngine engine = new MMJEngine();
ClientGeocodeResponse response =
engine.geocode(MapMarkerJavaAI.GEOCODE_TYPE_ADDRESS, inpAddr,
constraints);
//... candidates are returned
If you geocode with a user-generated Point User Dictionary, there is a different way to return offset
points. You can use the centerline offset feature to relocate points at a specified distance from the
associated street segment. See Centerline Offset for User Dictionary Point Candidates on
page 67
MapMarker Australia v15.5
65
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
Returning Original G-NAF Coordinates as String Values
Candidates matched in the G-NAF dictionary include the Longitude/Latitude coordinates from the
original G-NAF data. By default, rounded Longitude/Latitude coordinates are returned (accurate to 6
digits after the decimal). But you can return the original G-NAF Long/Lat coordinates, which are
accurate to 8 digits after the decimal.
The following methods are used.
G-NAF Original Coordinates Method
Method
Usage
setReturnGNAFOriginal(bFlag)
(in AUS_GeocodeConstraints
class)
If set to true, the original (unmodified) G-NAF coordinates
are returned. If false (default), the truncated (rounded)
points are returned.
returnGNAFOriginal
(in AUS_GeocodeConstraints
class)
Returns true if the original G-NAF coordinates are
requested (by setReturnGNAFOriginal(bFlag).
Returns the original longitude for G-NAF candidates. Only
getGNAFOriginalLongitude()
(in AUS_UserCandidateAddress available if setReturnGNAFOriginal is true.
class)
Returns the original latitude for G-NAF candidates. Only
getGNAFOriginalLatitude()
(in AUS_UserCandidateAddress available if setReturnGNAFOriginal is true.
class)
The following piece of sample code demonstrates how to return original G-NAF points as string
values. This example uses PID lookup as the geocode type. Values are returned in the Additional
Field keys of the AUS_UserCandidateAddress class. See Australian Candidate Addresses on
page 61 for information on these and other Additional Fields.
// get original coordinates example ( using PID lookup )
AUS_GeocodeConstraints constraints = new AUS_GeocodeConstraints();
AUS_UserInputAddress inpAddr = new AUS_UserInputAddress();
inpAddr.setGNAFPID("GAQLD160709533");
constraints.setReturnGNAFOriginal(true);
MMJEngine engine = new MMJEngine();
ClientGeocodeResponse response =
engine.geocode(AUS_GeocodeConstraints.GEOCODE_TYPE_PID,
inpAddr, constraints);
... candidates are returned ...
String origLong = candAddr.getAdditionalFieldForKey
(AUS_UserCandidateAddress.KEY_ORIGINAL_LONGITUDE);
MapMarker Australia v15.5
66
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
String origLat = candAddr.getAdditionalFieldForKey
(AUS_UserCandidateAddress.KEY_ORIGINAL_LATITUDE);
Returning Original Coordinates for Point User Dictionary Candidates
If your point-based user dictionary is created with the MapMarker Australia v15.5 User Dictionary
Utility, candidate longitude and latitude is accurate to six significant digits after the decimal point.
This level of accuracy is supported by both the Desktop application and the Server.
With the Server product, you can also return original longitude/ latitude coordinates accurate to any
number of digits, depending on the accuracy of the source data. Only the Server product (not the
Desktop application) can return original coordinates from a point user dictionary.
The following keys in the AUS_UserCandidateAddress class are used to access the original
longitude/ latitude fields from a point-based user dictionary candidate:
AUS_UserCandidateAddress.UD_ORIGINAL_LATITUDE ("UD_ORIGINAL_LATITUDE")
AUS_UserCandidateAddresss.UD_ORIGINAL_LONGITUDE ("UD_ORIGINAL_LONGITUDE")
To take advantage of the either six digit accuracy or the original longitude/ latitude coordinates
feature, you must build the point-based user dictionary with the MapMarker Australia v15.5 User
Dictionary Utility. See the following topics:
Using the User Dictionary Utility on page 105
Guidelines for Creating a Point-Based User Dictionary on page 109.
Centerline Offset for User Dictionary Point Candidates
If you are geocoding with a user-generated point User Dictionary, you can use the centerline offset
feature to relocate points at a specified distance from the associated street segment (rather than at
the original parcel point). Where possible, the coordinates will be offset perpendicularly from the
segment. If no segment geometry candidate is present, the original point candidate is returned.
For a more detailed description of this feature, see Centerline Offset Feature on page 44.
The following methods are used.
Centerline Offset Methods
Method
Usage
Set to true to specify that point candidates
should be offset from the nearest segment
(default is false).
setUseCenterlineOffset()
(in AUS_GeocodeConstraints class)
MapMarker Australia v15.5
67
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
Centerline Offset Methods (continued)
setCenterlineOffset(double offset)
(in AUS_GeocodeConstraints class)
Specifies the offset distance from the
segment toward the original point.
setCenterlineOffsetUnit(String unit) Specifies the offset distance units. The
(in AUS_GeocodeConstraints class)
allowable units are: f., mi, m, km.
The following portion of sample code demonstrates how to return centerline offset points
AUS_GeocodeConstraints ausgeo = new AUS_GeocodeConstraints();
ausgeo.setUseCenterlineOffset(true);
ausgeo.setCenterlineOffsetUnit("m");
ausgeo.setCenterlineOffset(50.0);
Centerline offset candidates are returned with an SC result code. This indicates that the original
point was offset from the nearest segment. See Single Close Matches (S category) on page 116.
The precision for this type of interpolation is 18 (ADDRESS_POINT_PROJECTED). See Address
Interpolation on page 79.
L
Centerline offset does not affect points returned from the G-NAF Address Dictionaries
because of potential inconsistencies with G-NAF metadata information. Instead, the G-NAF
Address Dictionary can return points that have been relocated to the street frontage of the
parcel. See Choosing G-NAF Standard or Street Frontage Points on page 64.
Postal Code Override
The MapMarker Australia Server can return a close match candidate if the input postcode and street
address match, even if the city is missing or incorrect. This preference is supported in the Server
product only, not in the Desktop application.
The following AUS_GeocodeConstraints methods are used.
setPostalCodeOverride(true/false)
usePostalCodeOverride()
// returns true or false
By default, this setting is false.
Getting the Total Number of Candidates
Your application can check to see how many candidates were found. To do this, use the
totalPossibleCandidates property of the ClientGeocodeResponse object.
if (geoRes.totalPossibleCandidates() >0) {
/* [. . . ] */
}
MapMarker Australia v15.5
68
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Street Geocoding Application in Java
From all the candidates found, you can also see how many were close matches. You can do this by
examining the totalPossibleCloseMatchCandidates property and the of the ClientGeocodeResponse
object.
if (geoRes.totalPossibleCloseMatchCandidates() >0) {
/* [. . . ] */
}
MapMarker Australia returns a subset of the total possible candidates that it has found. As a default
MapMarker returns the first three candidates that are found. If you would like 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 the AUS_UserCandidateAddress method 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 */
AUS_UserCandidateAddress ausCand =
new AUS_UserCandidateAddress (geoRes.candidateAt(i));
System.out.println(auscand.toString();
System.out.println(auscand.getLocation().toString());
}
Getting the Result Code
MapMarker returns a result code for every record it attempts to match. The code indicates the
success or failure of the geocoding operation as well as 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 getPrecisonCode method of the CandidateAddress class.
Following is an example of how to get the result code:
String resultCode=cancand.getPrecisonCode()
For more information on interpreting the geocoding results, see Result Codes in Chapter 9 on
page 115.
MapMarker Australia v15.5
69
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Web Geocoding Client in Java
Getting the Segment ID
The standard (street segment) Address Dictionary returns the Segment ID with every S5
(interpolated point) or S4 (street centroid) candidate. The Segment ID is obtained using the
getSegmentID method of the CandidateAddress class. For example:
String segmentID=auscand.getSegmentID()
Creating a Web Geocoding Client in Java
If you have deployed MapMarker Australia as a servlet, you need to develop a web client application
to send geocoding requests to the server. Follow all of the steps under Creating a Street
Geocoding Application in Java on page 55, except use the MMJClient class instead of the
MMJEngine class. The MMJClient geocode method requires the URL of the servlet.
L
The default Tomcat server port number for MapMarker Australia is 8095.
/* Geocode Address */
String url = new
String("http://localhost:8095/mapmarker40/servlet/mapmarker");
MMJClient m_client;
ClientGeocodeResponse geoRes = MMJClient.geocode
(MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS,inpAddr, geoCon, url);
Your application must contain these import statements:
/* MapMarker Australia Java API */
import com.mapinfo.mapmarker.user.MapMarkerJavaAPI
import com.mapinfo.mapmarker.user.MMJClient;
import com.mapinfo.mapmarker.user.ClientGeocodeResponse;
import com.mapinfo.mapmarker.AUS.AUS_GeocodeConstraints;
import com.mapinfo.mapmarker.IGeocodeConstraints;
import com.mapinfo.mapmarker.AUS.AUS_UserCandidateAddress;
import com.mapinfo.mapmarker.AUS.AUS_UserInputAddress;
/* MapMarker Generic Java API */
import com.mapinfo.mapmarker.client.MMJClient;
import com.mapinfo.mapmarker.client.ClientGeocodeResponse;
import com.mapinfo.mapmarker.GeocodeConstraints;
import com.mapinfo.mapmarker.IGeocodeConstraints;
import com.mapinfo.mapmarker.common.AddressImpl;
import com.mapinfo.mapmarker.common.Address;
These jar files must be in your classpath. You can find these files in the \sdk\engine\lib\client and
sdk\engine\lib\common folders under the directory where you installed the product.
•
•
•
•
•
miutil.jar
micsys.jar
jdom.jar
commons-logging.jar
xercesImpl.jar
MapMarker Australia v15.5
70
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Web Geocoding Client in Java
•
xmlParserAPIs.jar
You can find the following files in the SDK\engine\lib\client and SDK\engine\lib\client folder under the
directory where you installed the product:
•
•
mmjclient.jar
mmjclient_aus.jar
Also make sure that the path to encoding-map.xml is in your classpath. You can find this file in the
\sdk\engine\lib\client folder under the directory where you installed the product.
Street Geocoding Example
The following usage example shows how to create a web client using the AUS-specific Java API
approach.
Web client created using the MapMarker Australia API
/* MapInfo Imports */
import com.mapinfo.mapmarker.AUS.AUS_GeocodeConstraints;
import com.mapinfo.mapmarker.user.ClientGeocodeResponse;
import com.mapinfo.mapmarker.user.MMJClient;
import com.mapinfo.mapmarker.AUS.AUS_GeocodeConstraints;
import com.mapinfo.mapmarker.AUS.AUS_UserCandidateAddress;
import com.mapinfo.mapmarker.AUS.AUS_UserInputAddress;
public class MMJ_AUS_Example {
private void geocode() {
/* Set server url*/
String url = "http://localhost:8095/mapmarker40/servlet/mapmarker";
/* Input address example */
v;
String addr = "1 Elizabeth Plaza";
String state= "NSW";
String postcode = "2060";
AUS_GeocodeConstraints geoCon = new AUS_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);
AUS_UserCandidateAddress ausAddr = null;
AUS_UserInputAddress inpAddr = new AUS_UserInputAddress();
/* Set the input Address */
inpAddr.setStreet_Name (addr); /*street*/
inpAddr.setSuburb (suburb); /*suburb*/
inpAddr.setState (state); /*state*/
inpAddr.setPostCode (postcode); /*postcode*/
/*Geocode Address */
MMJClient client = new MMJClient(url);
MapMarker Australia v15.5
71
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Web Geocoding Client in Java
ClientGeocodeResponse geoRes = client.geocode(
MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS, inpAddr, geoCon);
/*Get candidate count*/
int candCount = geoRes.candidateCount();
/*
*Get returned candidates
*/
if(candCount > 0)
{
for (int i=0; i< candCount; i++)
{
/* Get candidate information */
CandidateAddress candAddr = geoRes.candidateAt(i);
AUS_UserCandidateAddress ausCand = new
AUS_UserCandidateAddress(candAddr);
System.out.println(canCand);
System.out.println(canCand.getLocation());
}
} /* End */
public static void main(String[] args)
{
MMJ_AUS_Example geocodeTest = new MMJ_AUS_Example();
geocodeTest.geocode();
}
}
Web client created using the MapMarker Generic API
The following usage example is a web client created using the generic Java API approach:
/* MapInfo Imports */
import com.mapinfo.mapmarker.CandidateAddress;
import com.mapinfo.mapmarker.user.ClientGeocodeResponse;
import com.mapinfo.mapmarker.user.MMJClient;
import com.mapinfo.mapmarker.GeocodeConstraints;
import com.mapinfo.mapmarker.IGeocodeConstraints;
import com.mapinfo.mapmarker.common.AddressImpl;
import com.mapinfo.mapmarker.common.Address;
public class MMJ_Generic_Example
{
private void geocodeGenericAddress() {
/* Set server url*/
String url =
"http://localhost:8095/mapmarker40/servlet/mapmarker";
/* Input Address Example*/
String addr = "1 Elizabeth Plaza";
String areaname3 = “North Sydney”;
String areaname1 = “NSW”;
String postcode = "2060";
GeocodeConstraints geoCon = new GeocodeConstraints();
/* Geocode Constraints:
* Review Java docs for a complete constraint list
* and default values
MapMarker Australia v15.5
72
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Web Geocoding Client in Java
*/
geoCon.setMustMatchAddressNumber(true);
geoCon.setMaxCandidates(3);
geoCon.setMaxRanges(5);
geoCon.setReturnCloseCandidatesOnly(true);
geoCon.setFallbackToPostal(false);
Address inpAddr = new AddressImpl();
/* Set the input Address */
inpAddr.setCountry(“AUS”);
inpAddr.setMainAddress(addr); /*street*/
inpAddr.setAreaName3(areaname3); /*suburb*/
inpAddr.setAreaName1(areaname1); /*state*/
inpAddr.setPostCode(postcode); /*postcode*/
/* Geocode Address */
MMJClient client = new MMJClient(url);
ClientGeocodeResponse geoRes =
client.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS, inpAddr,
geoCon;
/* Get candidate count */
int candCount = geoRes.candidateCount();
/*
* Get returned candidates
*/
if(candCount > 0)
{
for (int i=0; i < candCount; i++) {
/** Get candidate information
* Review Java docs for a complete list of
* candidate information
*/
CandidateAddress ausAddr = geoRes.candidate(i);
System.out.println(candAddr);
System.out.println(candAddr.getLocation());
System.out.println(
“Precision Code:” + candAddr.getPrecisionCode());
System.out.println();
/** Get candidate range information
* Review Java docs for a complete list of candidate range
* information
*/
for ( int k=0;
k<candAddr.getNumberOfCandidateRangesFound();k++)
{
CandidateRange range = cand.getRangeAt (k);
System.out.println("Range Number:" + (k+1));
System.out.println(Street Side:” +
range.getLeftRightIndicator ());
System.out.println("Low Number:" +
range.getLowAddress());
System.out.println("High Number:" +
range.getHighAddress());
System.out.println();
MapMarker Australia v15.5
73
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Reverse Geocoding Application in Java
}
}
}
}/* End */
public static void main(String[] args)
{
MMJ_Generic_Example geocodeTest =
new MMJ_Generic_Example();
geocodeTest.geocodeGenericAddress();
}
}
Creating a Reverse Geocoding Application in Java
Reverse geocoding accepts Longitude/Latitude input and returns address candidates.segment or
point candidates (depending on whether a segment or point dictionary is used). After you have set
the input coordinates and the optional geocoding constraints, you are ready to reverse geocode.
Setting Import Statements
Make sure that your application contains these import statements. The classes specific to Reverse
Geocoding are highlighted in bold.
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
com.mapinfo.mapmarker.user.ReverseGeocodeLocation;
com.mapinfo.mapmarker.user.MMJEngine;
com.mapinfo.mapmarker.user.MapMarkerJavaAPI;
com.mapinfo.mapmarker.user.ReverseGeocodeAPI;
com.mapinfo.mapmarker.user.ReverseGeocodeConstraints;
com.mapinfo.mapmarker.user.MapMarkerException;
com.mapinfo.mapmarker.user.MapMarkerFatalException;
com.mapinfo.mapmarker.user.ReverseGeocodeResponse;
com.mapinfo.mapmarker.user.ReverseGeocodeCandidateAddress;
com.mapinfo.mapmarker.user.MMJClient;
com.mapinfo.mapmarker.ICandidateRangeIterator;
com.mapinfo.mapmarker.CandidateRange;
com.mapinfo.util.DoublePoint;
com.mapinfo.coordsys.CoordSys;
com.mapinfo.unit.Distance;
com.mapinfo.unit.LinearUnit;
import java.net.MalformedURLException;
Setting the Input Location
For a reverse geocoding application, you must set the input location. You can also set the coordinate
system and the distance to search from the input coordinates.
The Distance specifies the distance (radius) to search from the input coordinates. The default
distance is 150 meters and the maximum cannot exceed 1600 meters.
MapMarker Australia v15.5
74
Developer Guide
Chapter 5: Using the MapMarker Java API
Creating a Reverse Geocoding Application in Java
DoublePoint inputLoc = new DoublePoint(150.991012, -33.836827);
Distance searchDistance = new Distance(150.0, LinearUnit.meter);
ReverseGeocodeLocation rgLoc = new ReverseGeocodeLocation(inputLoc,
CoordSys.longLatGDA94, searchDistance);
Setting Reverse Geocoding Constraints
Set the geocoding constraints (or preferences). If no constraints are explicitly provided, MapMarker
uses default settings.
ReverseGeocodeConstraints constraints = new ReverseGeocodeConstraints();
constraints.setCornerOffset(new Distance(8.0, LinearUnit.meter));
constraints.setStreetOffset(new Distance(8.0, LinearUnit.meter));
Reverse Geocoding
After you have set the input address and have set the geocoding constraints, you are ready to
reverse geocode. Use the geocode method of the MMJEngine class as shown in this example.This
class is used for making geocoding requests to the MapMarker Java-based geocoding engine. To
make geocoding requests to a MapMarker Server, use the MMJClient class.
DoublePoint inputLoc = new DoublePoint(150.991012, -33.836827);
Distance searchDistance = new Distance(150.0, LinearUnit.meter);
ReverseGeocodeLocation rgLoc = new ReverseGeocodeLocation(inputLoc,
CoordSys.longLatGDFA94, searchDistance);
ReverseGeocodeConstraints constraints = new ReverseGeocodeConstraints();
ReverseGeocodeAPI rgAPI = new MMJEngine();
ReverseGeocodeResponse response = rgAPI.reverseGeocode("AUS", rgLoc,
constraints);
Reverse Geocoding Response
After geocoding, get the reverse 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("Post address: " +
candidate.getFormattedLocationAddress());
System.out.println("Distance: " + candidate.getDistance());
System.out.println("Dictionary: " +
candidate.getConfiguredDictionaryNumber());
ICandidateRangeIterator rangeItr = candidate.rangeIterator();
while (rangeItr.hasNext()) {
CandidateRange range = rangeItr.next();
MapMarker Australia v15.5
75
Developer Guide
Chapter 5: Using the MapMarker Java API
Browsing Addresses
System.out.println("Range:" + range.getLowAddress() + " -- " +
range.getHighAddress());
}
}
For more information on interpreting the geocoding results, see Reverse Geocoded Matches (R
category) on page 119.
Browsing Addresses
Browsing enables you to retrieve a list of possible address candidates from an address dictionary
using a partial street or firm name with a suburb/state and/or postcode as input. No geocoding
occurs when you browse, but you are able to view the list of possible candidates.
To browse an address, use the MapMarker JavaAPI interface with the GEOCODE_TYPE_BROWSE
constant.
The following example shows a browse address input using the AUS-specific Java API
/* Input address example */
AUS_UserInputAddress inpAddr = new AUS_UserInputAddress ();
inpAddr.setStreet_Name("G");
inpAddr.setPostCode("2060");
If you are using the generic Java API approach, use the AddressImpl class.
AddressImpl inpAddr = new AddressImpl();
inpAddr.setMainAddress("G");
inpAddr.setPostCode("2060");
inpAddr.setCountry("AUS");
To browse, use the method of the MMJEngine class as shown in this example. This class is used for
browsing with either the MapMarker Australia Java API approach or the MapMarker generic Java
API approach. To browse using the MMJClient class see Creating a Web Geocoding Client in
Java on page 70. The candidates returned will be in the form of a UserCandidateAddress object,
which will hold the street name information.
/* 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 "G" in the postcode 2060 will be returned. Now you can use the
AUS_UserCandidateRange to obtain detailed candidate information.
/* Get candidate count */
int candCount = geoRes.candidateCount();
/*
* Get returned candidates
*/
if (candCount > 0)
{
MapMarker Australia v15.5
76
Developer Guide
Chapter 5: Using the MapMarker Java API
Geocoding to Postal Centroids
for (int i=0; i < candCount; i++)
{
/*Get candidate information */
AUS_UserCandidateAddress candAddr =
new AUS_UserCandidateAddress(geoRes.candidateAt(i));
if (candAddr.getNumberOfCandidateRanges() > 0)
{
AUS_UserCandidateRange candRange =
new AUS_UserCandidateRange(candAddr.getRangeAt(0));
System.out.println("Candidate Range :" + candRange);
}
}
}
Geocoding to Postal Centroids
The MapMarker Australia Java API enables you to geocode records to postal centroids.
To geocode your records to a postal centroid, use the MapMarker JavaAPI interface with the
GEOCODE_TYPE_POSTAL_CENTROID constant.
For detailed information on all classes, refer to the API documentation for MapMarker Australia. It is
located in the <install>\docs\AUS folder, where <install> represents your MapMarker installation
directory. From that location, run index.html to see the MapMarker Javadocs.
Using the MapMarker Australia API
The following example shows postal code input using the AUS-specific Java API.
AUS_UserInputAddress inpAddrv = new AUS_UserInputAddress ();
inpAddr.setPostcode("2060");
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 Generic Java API or the MapMarker Australia Java
API. To geocode using the MMJClient class see Creating a Creating a Web Geocoding Client in
Java on page 70.
MMJEngine engine = new MMJEngine();
ClientGeocodeResponse
geoRes = engine.geocode(
MapMarkerJavaAPI.GEOCODE_TYPE_POSTAL_CENTROID, inpAddr,
geoCon;
You can also specify a preference to “fall back to geographic centroid” from a street-level geocode.
/*Set Fallback to Postal*/
AUS_GeocodeConstraints geoCon = new AUS_GeocodeConstraints();
geoCon.setFallbackToPostal
geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS,
inpAddr, geoCon);
MapMarker Australia v15.5
77
Developer Guide
Chapter 5: Using the MapMarker Java API
Geocoding to Geographic Centroids
After the geocoding call you can use the AUS_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 */
AUS_UserCandidateAddress candAddr = new
AUS_UserCandidateAddress(geoRes.candidateAt(i));
}
}
Using the MapMarker Generic API
The following example shows postal code input using the Generic API.
/* Input address example */
AddressImpl inpAddr = new
AddressImpl();inpAddr.setPostCode1("2060");
inpAddr.setCountry("AUS");
Geocoding to Geographic Centroids
The MapMarker Australia Java API enables you to geocode records to geographic centroids.
To geocode your records to a geographic centroid, use the MapMarker JavaAPI interface with the
GEOCODE_TYPE_GEOGRAPHIC_CENTROID constant.
Using the MapMarker Australia API
The following example shows how to use the AUS-specific Java API approach to geocode records
to geographic centroids.
/* Input address example */
AUS_UserInputAddress inpAddr = new AUS_UserInputAddress ();
inpAddr.setSuburb("North Sydney");
inpAddr.setState("NSW");
Using the MapMarker Generic API
If you are using the MapMarker generic Java API approach, use the AddressImpl class.
AddressImpl inpAddr = new AddressImpl();
inpAddr.setAreaName3("North Sydney");
inpAddr.setAreaName1("NSW");
inpAddr.setCountry("AUS");
MapMarker Australia v15.5
78
Developer Guide
Chapter 5: Using the MapMarker Java API
Address Interpolation
To geocode, use the geocode method of the MMJEngine class as shown in this example. This class
is used for geocoding with either the AUS-specific Java API approach or the MapMarker generic
Java API approach. To geocode using the MMJClient class see Creating a Creating a Web
Geocoding Client in Java on page 70.
/* 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 */
AUS_GeocodeConstraints geoCon = new AUS_GeocodeConstraints();
geoCon.setFallbackToGeographic
geoRes = engine.geocode(MapMarkerJavaAPI.GEOCODE_TYPE_ADDRESS,
inpAddr, geoCon);
After the geocoding call you can use the AUS_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 */
AUS_UserCandidateAddress candAddr =
new AUS_UserCandidateAddress(geoRes.candidateAt(i));
}
}
Geographic centroid candidates may return values for the following:
•
•
•
areaName1 (state)
areaName3 (suburb)
location
G3 is the only possible return code for a geographic centroid in MapMarker Australia.
For deciding close matches, preference is given to the candidate where the spelling of the suburb is
closer to the input address.
Address Interpolation
Address interpolation is a mathematical means of estimating an address location based on a street
segment and the address point ranges associated with that segment.
MapMarker Australia v15.5
79
Developer Guide
Chapter 5: Using the MapMarker Java API
Address Interpolation
This method of interpolation assigns coordinates to address records in relation to the position of
address point candidates in the data, providing greater positional accuracy to the geocoded points.
The geocoding engine can incorporate address point data in the position assignment and
interpolation process.
MapMarker Australia uses address point data that may be present in the Address Dictionary, or
supplied by the user in a customised User Dictionary.
To use address point interpolation, you must set the setAddressPointInterpolation 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).
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 as it would be without using
address point interpolation.
MapMarker Australia v15.5
80
Developer Guide
Using the XML API
MapMarker Australia 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 chapter:
Š
Š
Š
Understanding the XSD Schemas. . . . . . . . . . . . . . . . . . . . . . . . . .82
Examples of XML Requests and Responses . . . . . . . . . . . . . . . . .85
MapMarker XML Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
6
Chapter 6: Using the XML API
Understanding the XSD Schemas
Understanding the XSD Schemas
MapMarker Australia Server operates using a standard XML request/response methodology. A
client application is responsible for constructing a geocoding request, which must conform to the
MapMarker Australia request schema. That request is sent to an active MapMarker Australia server
via an HTTP Post. If the request message is valid, MapMarker attempts to carry out the requested
operation, and if successful, sends an XML response message, which conforms to the MapMarker
Australia response schema.
The MapMarker schemas are installed by MapMarker in:
<Install>\MapMarker_AUS_v15\sdk\engine\schema. The schemas are:
•
•
•
MMJRequest.xsd
MMJResponse.xsd
MMJCommon.xsd
Although MapMarker Australia does not have a native .NET API, developers can still add geocoding
functionality to their .NET applications via this XML API. The sections that follow provide a general
outline of a number of different methods for interacting with MapMarker in this way and provide a set
of detailed instructions for using some of the tools included with the .NET framework.
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
"AUS"
If you are using XML to send batch requests, the request ID and address ID must be unique within
the batch request.
L
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
AUS_DataManagerSettings.properties file.
MapMarker Australia v15.5
82
Developer Guide
Chapter 6: Using the XML API
MapMarker XML Objects
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 Ranges on page 62 for range and parity 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
AUS_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 Address Interpolation
on page 79.
MapMarker XML Objects
Geocoded candidates are returned as XML candidate objects. A candidate object in turn contains
other objects (such as Address, Point, and Range objects).
Following is a simplified illustration of the objects comprising a response from a street geocoding
operation. Some objects may not be present for all candidates. For example, Range and the
contained RangeUnit objects will not be present if range information was not requested.
<Candidate... constraints>
<Address>
<AdditionalFields>
<KeyValuePair>
<Key>RESULT_CODE</Key>
<VALUE> Resultcode </Value>
</KeyValuePair>
MapMarker Australia v15.5
83
Developer Guide
Chapter 6: Using the XML API
MapMarker XML Objects
<KeyValuePair>
<Key>SEGMENT_ID</Key>
<VALUE> SegmentID </Value>
</KeyValuePair>
<KeyValuePair>
<Key> ...additional country-specific keys </Key>
<Value>value</Value>
</KeyValuePair>
.
.
... a number of KeyValuePairs may be returned
.
.
</AdditionalFields>
<AddressNumber>number</AddressNumber>
<AreaName1>state</AreaName1>
.
.
...other standard address elements
.
.
</Address>
<Point>
<Coord>
<X>Longitude</X>
<Y>Latitude</Y>
</Point>
<Range>
<low/high/parity objects>
<Address>
<PlaceName>Place Name</PlaceName>
</Address>
.
.
...A number of Ranges may be returned
.
.
<TotalRangeUnitsFound>
<RangeUnit>
<lowUnit>
<highUnit>
<Address>
<unitType>
<AdditionalFields
<KeyValuePair>
<Key=string>
</AdditionalFields>
MapMarker Australia v15.5
84
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
</RangeUnit>
.
.
... a number of RangeUnits may be returned
.
.
</Range>
</Candidate>
A request object has a similar structure. For geocoding requests, the Additional Constraints are
contained in AdditionalField KeyValuePair elements. The Examples of XML Requests and
Responses illustrate several geocoding requests and responses.
For a more complete and formal description of the XML objects, see the MMJCommon.xsd,
MMJRequest.xsd, and MMJResponse.xsd schemas installed in:
<Install>\MapMarker_AUS_v15\sdk\engine\schema.
Examples of XML Requests and Responses
This section includes some short snippets of sample code that illustrate requests and responses
using the MapMarker XML API.
Street Geocoding Request
The following example submits a street level geocoding request.
<RequestEnvelope clientLocale="en_US" encoding="UTF-8">
<GeocodeRequest requestID="20080409131116196">
<InputAddress addressID="12345">
<Address>
<AreaName1>NSW</AreaName1>
<AreaName3>North Sydney</AreaName3>
<Country>AUS</Country>
<MainAddress>1 Elizabeth Plaza</MainAddress>
<postCode1>2060</postCode1>
</Address>
<GeocodeConstraints>
<BaseConstraints clientLocale="en_US" closeMatchesOnly="false"
fallbackToPostalCentroid="false" fallbackToGeographicCentroid="false"
dictionaryUsage="PREFER_AD" requestType="0">
<maxCandidates>1</maxCandidates>
<maxRanges>0</maxRanges>
<offsetFromCorner unitsOfMeasure="m">10</offsetFromCorner>
<offsetFromStreet unitsOfMeasure="m">10</offsetFromStreet>
</BaseConstraints>
<AdditionalConstraints>
<KeyValuePair>
<Key>MustMatchAddrNum</Key>
<Value>true</Value>
</KeyValuePair>
MapMarker Australia v15.5
85
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
<KeyValuePair>
<Key>MustMatchMainAddr</Key>
<Value>false</Value>
</KeyValuePair>
<KeyValuePair>
<Key>MustMatchArea3</Key>
<Value>false</Value>
</KeyValuePair>
<KeyValuePair>
<Key>MustMatchPostalCode</Key>
<Value>false</Value>
</KeyValuePair>
</AdditionalConstraints>
</GeocodeConstraints>
</InputAddress>
</GeocodeRequest>
</RequestEnvelope>
Street Geocoding Response
The following example shows the response from the preceding street level geocoding request:
<?xml version="1.0" encoding="UTF-8"?>
<ResponseEnvelope>
<GeocodeResponse requestID="20080409131116196">
<ResponseCode>0</ResponseCode>
<RequestResult addressID="12345">
<ResponseCode>0</ResponseCode>
<GeocodeSummary>
<TotalLocationsFound>19</TotalLocationsFound>
<TotalLocationsReturned>1</TotalLocationsReturned>
<TotalCloseMatchesFound>1</TotalCloseMatchesFound>
<UniqueCloseMatchFound>true</UniqueCloseMatchFound>
<dataLicensed>true</dataLicensed>
</GeocodeSummary>
<Candidate genericField4Matched="false" areaName3Matched="true"
streetNameMatched="true" postCode2Matched="true"
genericField2Matched="false" closeMatch="true" fmtdAddr="1 ELIZABETH
PLAZA" srcStID="892516" intersection="false" addressNumberMatched="true"
postCode1Matched="true" preDirectionalMatched="true" CfgOrder="2"
fromUserDictionary="false" areaName1Matched="true"
placeNameMatched="true" streetPrefixSuffixMatched="true"
areaName2Matched="true" postDirectionalMatched="true"
genericField3Matched="false" streetNameFieldsMatched="true"
areaName4Matched="true" thoroughfareTypeMatched="true" matchPrecision="1"
countryMatched="true" genericField1Matched="false" fmtdLoc="North Sydney
NSW 2060">
<Address>
<AdditionalFields>
<KeyValuePair>
<Key>RESULT_CODE</Key>
<Value>S5HPNTSCZA</Value>
MapMarker Australia v15.5
86
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
</KeyValuePair>
</AdditionalFields>
<AddressNumber>1</AddressNumber>
<AreaName1>NSW</AreaName1>
<AreaName2>North Sydney</AreaName2>
<AreaName3>North Sydney</AreaName3>
<Country>AUS</Country>
<MainAddress>ELIZABETH</MainAddress>
<postCode1>AUS</postCode1>
<postThoroughfareType>PLZA</postThoroughfareType>
</Address>
<Point srsName="epsg:4283">
<coord>
<X>151.207857</X>
<Y>-33.839284</Y>
</coord>
</Point>
<TotalRangesFound>0</TotalRangesFound>
</Candidate>
</RequestResult>
</GeocodeResponse>
</ResponseEnvelope>
Street G-NAF Geocoding Request
The following example submits a G-NAF street level geocoding request.
<?xml version="1.0" encoding="UTF-8"?>
<RequestEnvelope clientLocale="en_US" encoding="UTF-8">
<GeocodeRequest requestID="20080409131945901">
<InputAddress addressID="12345">
<Address>
<AreaName1>ACT</AreaName1>
<AreaName3>HALL</AreaName3>
<Country>AUS</Country>
<MainAddress>19 HALL ST</MainAddress>
<postCode1>2618</postCode1>
</Address>
<GeocodeConstraints>
<BaseConstraints clientLocale="en_US" closeMatchesOnly="true"
fallbackToPostalCentroid="false" fallbackToGeographicCentroid="false"
dictionaryUsage="PREFER_AD" requestType="0">
<maxCandidates>1</maxCandidates>
<maxRanges>0</maxRanges>
<offsetFromCorner unitsOfMeasure="m">10</offsetFromCorner>
<offsetFromStreet unitsOfMeasure="m">10</offsetFromStreet>
</BaseConstraints>
<AdditionalConstraints>
<KeyValuePair>
<Key>MustMatchAddrNum</Key>
<Value>false</Value>
</KeyValuePair>
MapMarker Australia v15.5
87
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
<KeyValuePair>
<Key>MustMatchMainAddr</Key>
<Value>false</Value>
</KeyValuePair>
<KeyValuePair>
<Key>MustMatchArea3</Key>
<Value>false</Value>
</KeyValuePair>
<KeyValuePair>
<Key>MustMatchPostalCode</Key>
<Value>false</Value>
</KeyValuePair>
</AdditionalConstraints>
</GeocodeConstraints>
</InputAddress>
</GeocodeRequest>
</RequestEnvelope>
Street G-NAF Geocoding Response
The following example shows the response from the preceding G-NAF street level geocoding
request.
<?xml version="1.0" encoding="UTF-8"?>
<ResponseEnvelope>
<GeocodeResponse requestID="20080409131945901">
<ResponseCode>0</ResponseCode>
<RequestResult addressID="12345">
<ResponseCode>0</ResponseCode>
<GeocodeSummary>
<TotalLocationsFound>55</TotalLocationsFound>
<TotalLocationsReturned>1</TotalLocationsReturned>
<TotalCloseMatchesFound>1</TotalCloseMatchesFound>
<UniqueCloseMatchFound>true</UniqueCloseMatchFound>
<dataLicensed>true</dataLicensed>
</GeocodeSummary>
<Candidate genericField4Matched="false" areaName3Matched="true"
streetNameMatched="true" postCode2Matched="true"
genericField2Matched="false" closeMatch="true" fmtdAddr="19 HALL STREET"
srcStID="3590618" intersection="false" addressNumberMatched="true"
postCode1Matched="true" preDirectionalMatched="true" CfgOrder="1"
fromUserDictionary="false" areaName1Matched="true"
placeNameMatched="true" streetPrefixSuffixMatched="true"
areaName2Matched="true" postDirectionalMatched="true"
genericField3Matched="false" streetNameFieldsMatched="true"
areaName4Matched="true" thoroughfareTypeMatched="true"
matchPrecision="16" countryMatched="true" genericField1Matched="false"
fmtdLoc="HALL ACT 2618">
<Address>
<AdditionalFields>
<KeyValuePair>
<Key>RESULT_CODE</Key>
MapMarker Australia v15.5
88
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
<Value>S8HPNTSCZG</Value>
</KeyValuePair>
<KeyValuePair>
<Key>MESH_BLOCK_ID</Key>
<Value>80020440000</Value>
</KeyValuePair>
<KeyValuePair>
<Key>GNAF_CONFIDENCE</Key>
<Value>2</Value>
</KeyValuePair>
<KeyValuePair>
<Key>GNAF_GEOCODE_LEVEL</Key>
<Value>7</Value>
</KeyValuePair>
<KeyValuePair>
<Key>GNAF_RELIABILITY</Key>
<Value>2</Value>
</KeyValuePair>
<KeyValuePair>
<Key>GNAF_PID</Key>
<Value>GAACT715329020</Value>
</KeyValuePair>
</AdditionalFields>
<AddressNumber>19</AddressNumber>
<AreaName1>ACT</AreaName1>
<AreaName3>HALL</AreaName3>
<Country>AUS</Country>
<MainAddress>HALL</MainAddress>
<postCode1>2618</postCode1>
<postThoroughfareType>ST</postThoroughfareType>
</Address>
<Point srsName="epsg:4283">
<coord>
<X>149.07129</X>
<Y>-35.16761</Y>
</coord>
</Point>
<TotalRangesFound>0</TotalRangesFound>
</Candidate>
</RequestResult>
</GeocodeResponse>
</ResponseEnvelope>
Reverse Geocoding Request and Constraints
This example submits a reverse geocoding request with the specified constraints.
/* Geocoding Request
<ReverseGeocodeInput country="AUS">
<location>
<coord>
MapMarker Australia v15.5
89
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
<X>150.991012</X>
<Y>-33.836827</Y>
</coord>
<CoordinateReferenceSystem>
<Identifier>
<code>4283</code>
<codeSpace> epsg</codeSpace>
</Identifier>
</CoordinateReferenceSystem>
</location>
</ReverseGeocodeInput>
/* Setting Constraints
<constraints locale="US-en">
<offsetFromCorner unitsOfMeasure="m">15.0</offsetFromCorner>
<offsetFromStreet unitsOfMeasure="m">15.0</offsetFromStreet>
</constraints>
Reverse Geocoding Response
This example shows the response from the preceding reverse geocoding request.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseEnvelope>
<ReverseGeocodeResponse>
<ReverseGeocodeResult dataLicensed="true">
<Candidate CfgOrder="1" fmtdAddr="150 Merrylands Road"
fromUserDictionary="false" fmtdLoc="2160 Merrylands">
<Address>
<AdditionalFields>
<KeyValuePair>
<Key>RESULT_CODE</Key>
<Value>RS8G</Value>
</KeyValuePair>
</AdditionalFields>
<AddressNumber>150</AddressNumber>
<AreaName1>NSW</AreaName1>
<AreaName3>Merrylands</AreaName3>
<Country>AUS</Country>
<MainAddress>Merrylands</MainAddress>
<postCode1>2160</postCode1>
<postThoroughfareType>Road</postThoroughfareType>
</Address>
<distance unitsOfMeasure="m">0.0</distance>
<TotalRangesFound>0</TotalRangesFound>
</Candidate>
</ReverseGeocodeResult>
</ReverseGeocodeResponse>
</ResponseEnvelope>
MapMarker Australia v15.5
90
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
Postal Geocoding Request
The following example shows a postal geocoding request:
<?xml version="1.0" encoding="UTF-8"?>
<RequestEnvelope clientLocale="en_US" encoding="UTF-8">
<GeocodeRequest requestID="20080409131456237">
<InputAddress addressID="12345">
<Address>
<AreaName1>AUS</AreaName1>
<AreaName3>North Sydney</AreaName3>
<Country>AUS</Country>
<postCode1>2060</postCode1>
</Address>
<GeocodeConstraints>
<BaseConstraints clientLocale="en_US" closeMatchesOnly="false"
fallbackToPostalCentroid="false" fallbackToGeographicCentroid="false"
dictionaryUsage="PREFER_AD" requestType="1">
<maxCandidates>1</maxCandidates>
<maxRanges>0</maxRanges>
<offsetFromCorner unitsOfMeasure="m">10</offsetFromCorner>
<offsetFromStreet unitsOfMeasure="m">10</offsetFromStreet>
</BaseConstraints>
<AdditionalConstraints>
<KeyValuePair>
<Key>MustMatchAddrNum</Key>
<Value>false</Value>
</KeyValuePair>
<KeyValuePair>
<Key>MustMatchMainAddr</Key>
<Value>false</Value>
</KeyValuePair>
<KeyValuePair>
<Key>MustMatchArea3</Key>
<Value>false</Value>
</KeyValuePair>
<KeyValuePair>
<Key>MustMatchPostalCode</Key>
<Value>false</Value>
</KeyValuePair>
</AdditionalConstraints>
</GeocodeConstraints>
</InputAddress>
</GeocodeRequest>
</RequestEnvelope>
Postal Geocoding Response
The following example shows the response from the above postal geocoding request:
<?xml version="1.0" encoding="UTF-8"?>
<ResponseEnvelope>
MapMarker Australia v15.5
91
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
<GeocodeResponse requestID="20080409131456237">
<ResponseCode>0</ResponseCode>
<RequestResult addressID="12345">
<ResponseCode>0</ResponseCode>
<GeocodeSummary>
<TotalLocationsFound>3</TotalLocationsFound>
<TotalLocationsReturned>1</TotalLocationsReturned>
<TotalCloseMatchesFound>3</TotalCloseMatchesFound>
<UniqueCloseMatchFound>false</UniqueCloseMatchFound>
<dataLicensed>true</dataLicensed>
</GeocodeSummary>
<Candidate genericField4Matched="false" areaName3Matched="false"
streetNameMatched="false" postCode2Matched="true"
genericField2Matched="false" closeMatch="true" fmtdAddr="" srcStID="0"
intersection="false" addressNumberMatched="false" postCode1Matched="true"
preDirectionalMatched="false" CfgOrder="1" fromUserDictionary="false"
areaName1Matched="false" placeNameMatched="false"
streetPrefixSuffixMatched="false" areaName2Matched="false"
postDirectionalMatched="false" genericField3Matched="false"
streetNameFieldsMatched="false" areaName4Matched="false"
thoroughfareTypeMatched="false" matchPrecision="3" countryMatched="true"
genericField1Matched="false" fmtdLoc="">
<Address>
<AdditionalFields>
<KeyValuePair>
<Key>RESULT_CODE</Key>
<Value>Z1</Value>
</KeyValuePair>
</AdditionalFields>
<AreaName3>HMAS WATERHEN</AreaName3>
<Country>AUS</Country>
<postCode1>2060</postCode1>
</Address>
<Point srsName="epsg:4283">
<coord>
<X>151.20578</X>
<Y>-33.83934</Y>
</coord>
</Point>
<TotalRangesFound>0</TotalRangesFound>
</Candidate>
</RequestResult>
</GeocodeResponse>
</ResponseEnvelope>
Candidate Address
The Candidate Address constants contain match level and precision information about the returned
candidates.
See Candidate Addresses on page 59 for a description of these constants and associated values
MapMarker Australia v15.5
92
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
Range
The Candidate Range constants contain information about a candidate's ranges.
See Candidate Ranges on page 62.
Geocoding Constraints
The Geocode Constraint constants describe the base geocoding constraints and the additional
constraints.
See Geocode Constraints on page 57 for descriptions of the base constraints.
The following table describes the base constraints, additional constraints, and country-specific
constraints that you can use in your application. The Base constraints are covered in the schemas.
See Understanding the XSD Schemas on page 82. The Additional constraints are contained in
AdditionalField KeyValuePair elements.
Geocoding Constraints
Constraint Name
(Base, Additional)
AddrPntInterp
Value
Description
true\false
Address Point Interpolation
locale string
Used to set different locales.
true\false
Returns the key for the Close
Matches Only flag.
CoordinateReference
SystemType
String describing the client
coordinate system. Accepted
values include EPSG SRS
Names as well as MAPINFO
MAPBASIC Projection String
SRS Names. Default uses
GDA94
CoordinateReference
SystemTypeIdentifier
Holds the
CoordinateReferenceSystem
TypeIdentifier
Code (string)
example: "4283"
CodeSpace (string)
example: "epsg"
Base
ClientLocale
Base
CloseMatchesOnly
Base
CoordinateReferenceSystem
Base
CoordinateReferenceSystemType
Base
CoordinateReferenceSystemType
Identifier
Base
MapMarker Australia v15.5
93
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
Geocoding Constraints (continued)
Constraint Name
(Base, Additional)
DictionarySearchOrderListType
Value
CfgOrder = number
Base
Description
AllowSearch = true\false
Description = string
UserPriority = number
IsUserDictionary = true\false
DictionarySearchOrderResponse
Base
DictionarySearch
OrderResponseType
DictionarySearch
OrderListCount = number
DictionarySearch
OrderList
DictionaryUsage
DictionaryUsageType
Base
Returns the key for dictionary
usage preference.
Enumerator {AD_ONLY,
UD_ONLY, AD_AND_UD,
PREFER_AD, PRFER_UD}
FallbackToGeographicCentroid
true\false
Returns the key for Fall back to
Geographic centroid.
true\false
Returns the value of fallback to
postal centroid
0 – 99, -1 returns all
Returns the key for the maximum
number of returned candidates.
0 – 99, -1 returns all
Returns the key for the Maximum
number of ranges that is returned
for each candidate
0 – 99, -1 returns all
Maximum units per range to
return.
true\false
Only candidates that match the
main address number are
considered a close match.
true\false
Only candidates that match
AreaName1 are considered a
close match.
Base
FallbackToPostalCentroid
Base
MaxCandidates
Base
MaxRanges
Base
MaxRangeUnits
Base
MustMatchAddrNum
Additional
MustMatchArea1
Additional
MapMarker Australia v15.5
94
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
Geocoding Constraints (continued)
Constraint Name
(Base, Additional)
MustMatchArea2
Value
true\false
Only candidates that match
AreaName2 are considered a
close match.
true\false
Only candidates that match
AreaName3 are considered a
close match.
true\false
Only candidates that match
AreaName4 are considered a
close match.
true\false
Only candidates that match the
country are considered a close
match.
true\false
Only candidates that match all
user input are considered a close
match.
true\false
Only candidates that match the
main address are considered a
close match
true\false
Only candidates that match the
postal code are considered a
close match.
OffsetType
Returns the key for the offset
distance from the corner option.
OffsetType
Returns the position of the
geocoded point with respect to
the centreline of the street.
Unit of measure =
{ft,m,mi,km}
Returns the key for the units on
the corner offset option.
Additional
MustMatchArea3
Additional
MustMatchArea4
Additional
MustMatchCountry
Additional
MustMatchInput
Additional
MustMatchMainAddr
Additional
MustMatchPostalCode
Additional
OffsetFromCorner
Base
OffsetFromStreet
Base
OffsetType
Base
Description
Value = 0 - 100
requestType
MapMarker Australia v15.5
0-500
95
Type of geocoding request. See
the table of Geocoding Request
Types.
Developer Guide
Chapter 6: Using the XML API
Examples of XML Requests and Responses
Geocode Request Types
These are used as values for requestType constraints in the XML API.
In the Java API, the corresponding methods are getGeocodeType and setGeocodeType.
Geocoding Request Types
Request
Types Value
Geocoding Request Type
Description
TYPE_GEOCODE_MATCH_ADDRESS
0
Standard street level geocode.
TYPE_GEOCODE_MATCH_POSTOCODE
1
Geocode postal centroid.
TYPE_GEOCODE_MATCH_GEOGRAPHIC
4
Geocode geographic centroid.
TYPE_GEOCODE_MATCH_BROWSE
6
Browse for address but do not
geocode.
GEOCODE_T YPE_PID
206
Geocode G-NAF PID.
(from AUS_GeocodeConstraints)
AUS Geocoding Constraints
The AUS geocode constraint constants describe the Australia-specific geocoding settings.This
provides local implementation of GeocodeConstraints.
See the table of AUS_GeocodeConstraints on page 59 for descriptions of the Australia
constraints.
t
Candidate Additional Field Values
The AUS_UserCandidateAddress class provides local implementation of UserCandidateAddress.
In the XML API, additional fields are returned as <Key> values within <KeyValuePairType>.
<KeyValuePair>
<Key>MESH_BLOCK_ID</Key>
<Value>80020440000</Value>
</KeyValuePair>
See the Australian Candidate Addresses on page 61 for a description of these Australian-specific
address returns.
MapMarker Australia v15.5
96
Developer Guide
Deploying Applications
This chapter discusses how to deploy your application as a Web servlet and
how you can integrate MapMarker Australia with other MapMarker country
geocoders.
In this chapter:
Š
Deploying MapMarker as a Servlet . . . . . . . . . . . . . . . . . . . . . . . . .98
7
Chapter 7:
Deploying MapMarker as a Servlet
Deploying MapMarker as a Servlet
A servlet is a Java program that runs as part of a network service, typically an HTTP server. The
most common use for a servlet is to extend a web server by generating web content dynamically.
MapMarker Australia 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 Tomcat Servlet Container
MapMarker Australia is installed in the Tomcat Servlet Container 5.5.9. The installer provides this
example environment so that you can run the servlet and sample application immediately after
finishing the installation. Simply use the default shortcut to start the server.
On Windows platforms the default shortcut is located under the Windows Start menu, Programs >
MapMarker > Start Server.
On UNIX platforms the default shortcut is installed in your home directory and is called Start_Server.
Deploying MapMarker Server in Other Web Environments
MapMarker Australia is verified and supported on WebLogic 9.0, and WebSphere 5.1 and 6.0.
For information about deploying servlet applications and for information on servlet container specific
requirements, see the documentation that was delivered with your servlet container.
For information about servlet technology and creating a war file, read the documentation on the Sun
Web site, http://java.sun.com/products/servlet/product.html
Sun also provides a list of servlet containers on the following Web site, including links to those
products, http://java.sun.com/products/servlet/industry.html
More information about the Tomcat Servlet Container can be found online at
http://jakarta.apache.org/tomcat/index.html
MapMarker Australia v15.5
98
Developer Guide
Custom User
Dictionaries
MapMarker supports the creation and use of custom User Dictionaries based on
your own source data. A User Dictionary can be used independently or as a
supplement to an Address Dictionary.
This chapter includes information on creating User Dictionaries, source data
requirements and required columns, and other information specific to working
with User Dictionaries.
As part of the Desktop Application, MapMarker provides a User Dictionary
wizard to simplify user dictionary creation in the desktop application.
MapMarker provides the User Dictionary Utility to guide you through the User
Dictionary creation process. This graphical creation tool simplifies the steps for
creating, configuring, and deploying User Dictionaries on the MapMarker server.
Table of Contents
Š
Š
Š
Š
Š
Š
What Is a Custom User Dictionary? . . . . . . . . . . . . . . . . . . . . . . .100
User Dictionary Capabilities and Requirements . . . . . . . . . . . . .100
User Dictionary File Names and Formats . . . . . . . . . . . . . . . . . .103
Additional User Dictionary Considerations . . . . . . . . . . . . . . . . .103
Using the User Dictionary Utility . . . . . . . . . . . . . . . . . . . . . . . . .105
Configuring the User and Address Dictionary Ranking . . . . . . .110
8
Chapter 8: Custom User Dictionaries
What Is a Custom User Dictionary?
What Is a Custom User Dictionary?
A User Dictionary is a customised table of addresses and coordinates that you can use for
geocoding. If you have newer or more precise data than what is available in the MapMarker Address
Dictionaries, creating a dictionary with this data can help you get more accurate geocoding results.
For example, if you have address point data for your customer sites, you can create a User
Dictionary that enables you to take advantage of the MapMarker address point interpolation
capabilities.
A User Dictionary can be used by itself to geocode records, or can be used in combination with the
MapMarker Address Street Range Dictionary or G-NAF Address Dictionaries.
User Dictionary Capabilities and Requirements
The capabilities of User Dictionaries and the basic requirements for creating them are as follows.
•
•
•
•
•
•
•
All columns supported by normal street geocoding can be included in User Dictionaries.
Place Name geocoding is supported in User Dictionaries. Place Name address verification and
geocoding can have important business applications that make User Dictionaries very useful.
User Dictionaries support address browsing using partial street names.
Postal or geographic centroid geocoding are not supported in User Dictionaries.
User Dictionaries do not support reverse geocoding.
A MapMarker Street Range Address Dictionary is required to create the User Dictionary. This is
because the MapMarker Address Dictionary has some internal structure that must be available
when you are creating a User Dictionary.
If you want your User Dictionary to include geocodable Place Name/Business Name information,
the installed G-NAF dictionary must be available in the Dictionary path when you create your
User Dictionary.
The results from a User Dictionary are similar to that from the MapMarker Address Dictionary.
However, a candidate from a User Dictionary has a ‘U’ at the end of the georesult code. A candidate
that comes from the MapMarker Address Dictionary has an ‘A’ at the end of the georesult code. For
example: S5HPNTSCZA is a result code that comes from an Address Dictionary, while
S5HPNTSCZU comes from a User Dictionary. See Chapter 7: Result Codes for a complete
description of result codes.
If you geocode with a point-based User Dictionary, you can return candidates at a specified offset
from the associated street segment (rather than at the original parcel point).
This center line offset feature is described in Centerline Offset Feature on page 44. This feature is
not enabled by default, but you can enable and control it using several GeocodeConstraints
methods. For more information, see the topic Centerline Offset for User Dictionary Point
Candidates on page 67.
Source Data Requirements
The source data for User Dictionaries includes street data but can also include place names and
intersections.
MapMarker Australia v15.5
100
Developer Guide
Chapter 8: Custom User Dictionaries
User Dictionary Capabilities and Requirements
To create a User Dictionary, your source data must conform to the following requirements:
•
•
•
•
•
Source records must include required columns, and these columns are mapped during the User
Dictionary creation process. If a value of a required column is empty for a particular record, then
that record will not be imported into the User Dictionary. Required columns may vary for different
countries. The MapInfo table must contain specific columns, which MapMarker then uses to
convert the table into the dictionary format. These input columns are described in Required
Input Columns on page 101.
Source records must be in a MapInfo table (TAB file). The TAB file requirements will vary for
different countries.
Segments that make up intersections must have one or more endpoints in the intersection for
MapMarker to recognise it as an intersection.
Source records can be either point objects or segments.
Each row in the table is equivalent to a street segment.
Required Input Columns
You must specify the column names in the MapInfo table (TAB file) in order for the table to be
translated into a User Dictionary. Certain columns are required and must be present in the MapInfo
table. Other columns are optional, but are recommended because there may be negative
consequences if they are omitted. This is described in Optional (Recommended) Input Columns.
If any of the required columns are missing, a missing column error code is returned.
The following table describes the required input columns for a street range user dictionary.
Required Input Fields for Mapping
Field
Description
Street Name
Name of street
Postcode
Four-digit postcode
State
State or territory
Town / Suburb
Municipality or locality
Point-based user dictionaries have different column and mapping requirements. See Guidelines for
Creating a Point-Based User Dictionary on page 109 more information.
Optional (Recommended) Input Columns
The Left and Right Odd/Even Indicator columns are used to specify whether the sides of the street
segment contain odd or even address ranges. Although these indicators are not required for
creating a User Dictionary, it is important to use the Odd/Even Indicators when your data contains
odd/even address numbers.
When the Odd/Even Indicator is specified, but is inconsistent with address numbers, the indicator is
set to Both.
MapMarker Australia v15.5
101
Developer Guide
Chapter 8: Custom User Dictionaries
User Dictionary Capabilities and Requirements
When the Odd/Even Indicator is not specified and both Start Address and End Address have values,
the indicator is set to Both, unless the start and end address numbers are the same number. In that
case, the indicator is set to Odd if the address numbers are odd, and set to Even if the address
numbers are even.
L
If your table contains odd/even indicator information, we strongly recommend that you use
the Odd/Even indicator columns. These columns ensure that your geocoded addresses are
located on the correct side of the street. Omitting the columns when your data contains
odd/even information may produce incorrect results.
The following table describes the optional input columns for a street range user dictionary.
Optional Input Fields for Mapping
Field
Description
Place Name
A place name is typically a company, organisation,
business name, or building name. Place Name is
supported by User Dictionaries and also supported by the
G-NAF Address Dictionary.
Local Government Area
See Local Government Area (LGA) on page 30 for a
description of LGA.
Unit Number
Unit Numbers are associated with Unit Types.
Unit Type
Unit Types include Apartment, Building, Flat, Suite, and
others.
Left Starting Address
Number
Start of address range on left side of street
Right Starting Address
Number
Start of address range on right side of street
Left Ending Address
Number
End of address range on left side of street
Right Ending Address
Number
End of address range on right side of street
Left Odd/Even indicator*
Left side of the street contains only odd or even address
ranges (O=odd, E=even, B=both)
Right Odd/Even indicator*
Right side of the street contains only odd or even address
ranges (O=odd, E=even, B=both)
*
These columns are highly recommended.
MapMarker Australia v15.5
102
Developer Guide
Chapter 8: Custom User Dictionaries
User Dictionary File Names and Formats
Point-based user dictionaries have different column and mapping requirements. See Guidelines for
Creating a Point-Based User Dictionary on page 109 more information.
User Dictionary File Names and Formats
MapMarker has some requirements for User Dictionary files that you must be aware of before you
create a User Dictionary:
•
•
•
•
Each User Dictionary has a base name of eight characters or fewer.
Each User Dictionary resides in its own directory.
The maximum length of a path to a User Dictionary is 1024 characters.
The maximum length of the paths to multiple User dictionaries is 1024 characters.
Because each User Dictionary resides in its own directory, User dictionaries may share the same
name. However, it is generally good practice to use a unique name for each User Dictionary.
Some of the output files are tied to the base name. The other output files have constant names. For
example, the output files for a dictionary called ud1 are the following:
postinfo.jdr
postinfo.jdx
lastline.jdr
post2sac.mmj
geo2sac.mmj
sac2fn_ud.mmj
ud1.jdr
ud1.jdx
ud1.bdx
alt.mmj (if based on the G-NAF Dictionary)
If your data includes place names, the dictionary contains the following files:
ud1.pdx
ud1.pbx
The dictionary also contains these log files:
ud1.log
ud1.err
Additional User Dictionary Considerations
Consider the following when working with custom User dictionaries.
Data Access License
Address Range Order
Street Intersections and Customised User Dictionaries
MapMarker Australia v15.5
103
Developer Guide
Chapter 8: Custom User Dictionaries
Additional User Dictionary Considerations
Data Access License
You must still have a valid access license to the data contained in the MapMarker Street Range
Address Dictionary when you are geocoding against your custom User Dictionary. For example, if
you create a dictionary of Adelaide streets and addresses, you must purchase the South Australia or
entire Australian MapMarker Address Dictionary.
Address Range Order
MapMarker determines the order of the address range based on a comparison of the start and end
addresses. The comparison produces the following results:
•
•
•
If the end is greater than the start, the range is ascending
If the start is greater than the end, the range is descending
If the start is equal to the end, the range is ascending
Street Intersections and Customised User Dictionaries
When geocoding to street intersections with a custom User Dictionary, MapMarker cannot recognise
the intersections if one or more of the segments that make up the intersection does not have an
endpoint at the intersection. This can happen when you create the User Dictionary from a
customised street table in which some segments that terminate at intersections do not have
endpoints (Example 1).
Example 1: Intersection in custom User Dictionary does not have endpoints for all segments.
MapMarker does not recognise this as an intersection.
Example 2: Intersection in Address Dictionary includes endpoints for all segments. MapMarker
geocodes to this intersection.
MapMarker Australia v15.5
104
Developer Guide
Chapter 8: Custom User Dictionaries
Using the User Dictionary Utility
Using the User Dictionary Utility
The User Dictionary Utility can be installed as one of the available SDK features with your
MapMarker Developer (Server) product. This is an easy-to-use utility that simplifies the steps for
creating User Dictionaries.
Once you have installed the User Dictionary Utility and prepared your source data to meet the
requirements for a user dictionary (see User Dictionary Capabilities and Requirements on
page 100), you can use the Utility to automate the user dictionary creation process.
In order to create a User Dictionary with the User Dictionary Utility, a MapMarker Address Dictionary
must already be present. If you have installed any current version of MapMarker, the associated
Address Dictionary is also installed.
1. Start the MapMarker User Dictionary Utility. If you installed this utility, it will be listed in the
MapMarker Australia v15.5 program group.
2. From the first dialog, browse to an empty directory in which the user dictionary will be saved and
specify a file name (the .jdr file extension will be added). For example, you could browse to an
empty directory named UD_AUS_Streets, and in that folder save the file
NSW_Streets_UserDict.jdr. You can also add a description of the user dictionary. When you
complete this action, the dialog resembles this:
Click Next to continue.
3. In the User Dictionary Utility dialog, select AUS from the Country drop-down list
MapMarker Australia v15.5
105
Developer Guide
Chapter 8: Custom User Dictionaries
Using the User Dictionary Utility
Click Next to continue.
4. Enter the location of the valid address dictionary. Because the address dictionary has some
internal structure that is required for creating a user dictionary, you must provide the address
dictionary path. Browse to and select the sac2fn.mmj file in the Data directory.
Click Next to continue.
5. Select the User Dictionary Type (Address Range or Point Based). In this example, you are
creating an address range user dictionary.
MapMarker Australia v15.5
106
Developer Guide
Chapter 8: Custom User Dictionaries
Using the User Dictionary Utility
If you want to create a user dictionary with point-based addresses, the User Dictionary Utility
steps are the same, but the column mapping requirements are different. See Guidelines for
Creating a Point-Based User Dictionary on page 109.
Click Next to continue.
6. Browse to the TAB file that contains the source data for your User Dictionary.
Click Next to continue.
7. Select the required columns and map them appropriately as shown below. The required
mappings are Street Name, Postcode, Town/Suburb, and State. For a point-based user
dictionary, the required address mappings are described in Guidelines for Creating a PointBased User Dictionary on page 109.
MapMarker Australia v15.5
107
Developer Guide
Chapter 8: Custom User Dictionaries
Using the User Dictionary Utility
Click Next to continue.
8. Select the optional columns. Since these are optional fields, you do not have to specify them. For
a point-based user dictionary, the optional address mappings are described in Guidelines for
Creating a Point-Based User Dictionary on page 109.
9. Click Finish to create the User Dictionary. Depending on the size of your input file, this may take
some time. The UD Creation Complete dialog displays a log file that summarises processing and
lists all the created files. Any errors will be indicated in the Error File area of the dialog.
MapMarker Australia v15.5
108
Developer Guide
Chapter 8: Custom User Dictionaries
Using the User Dictionary Utility
10. Click Exit to exit the User Dictionary Utility.
After successfully creating the User Dictionary, the output directory (named in step 2) contains
the files that comprise the User Dictionary (with .mmj, .jdr, .jdx, .sdx, and .bdx file extensions).
The log file and error file are also stored in the same directory.
11. Edit the appropriate AUS_DataManagerSettings.properties file and restart the MapMarker server
before you can use the User Dictionary. See Configuring the User and Address Dictionary
Ranking on page 110.
At any time, you can click System Information for a summary of system-related information on the
User Dictionary Utility. This identifies the JVM, MapMarker core engine, and other system details.
Guidelines for Creating a Point-Based User Dictionary
Follow these requirements and column mapping guidelines when creating a point-based user
dictionary with the User Dictionary Utility.
Required Address Mappings
The required column mappings are the same as described in Required Input Columns on
page 101, except a point-based user dictionary has an additional requirement for mapping the
Address Number column.
Required Column
Description
Street Name
Name of street
Postcode
Four-digit postcode
State
State or territory
Town / Suburb
Municipality or locality
Address Number
House number. For point-based user dictionaries each record has
a single house number with no left/right range indicator.
Optional Address Mappings
The optional address mappings for a point-based user dictionary are summarised in the following
table. This differs from the Required Input Columns for street range user dictionaries in several
ways. Point-based user dictionaries have one required Address Number column mapping instead
of optional Left and Right Starting/Ending columns. Also there is a single Odd/Even column.
MapMarker Australia v15.5
109
Developer Guide
Chapter 8: Custom User Dictionaries
Configuring the User and Address Dictionary Ranking
Optional Column
Description
Local Government Area
See Local Government Area (LGA) on page 30 for a
description of LGA.
Odd/Even
odd or even (O=odd, E=even, B=both) For point-based user
dictionaries each record can have an optional odd or even
indicator with no left/right odd/even indicator, as there can be
for street range user dictionaries.
Place Name
A place name is typically a company, organisation, business
name, or building name. Place Name is supported by User
Dictionaries and also supported by the G-NAF Address
Dictionary.
Unit Number
Unit Numbers are associated with Unit Types,
Unit Type
Unit Types include Apartment, Building, Flat, Suite, and others.
See Acceptable Unit Types on page 205 for more
information.
Original Longitude (X)
Original longitude coordinates returned as a string accurate to
any number of digits after the decimal
Original Latitude (Y)
Original latitude coordinates returned as a string accurate to
any number of digits after the decimal.
Configuring the User and Address Dictionary Ranking
You can geocode using:
•
•
•
•
User Dictionary (or multiple User Dictionaries) alone
MapMarker Street Range Address Dictionary
MapMarker G-NAF Point Address Dictionary
A combination of User and Address Dictionaries
You must configure the AUS_DataManagerSettings.properties file so that MapMarker can find the
User Dictionary. The DataManagerSettings.properties file also controls the priority (ranking) of
deployed User Dictionaries and the Address Dictionary. The dictionary ranking determines which
dictionary is used first when geocoding.
You can also use the MapMarker Java API to control dictionary preferences and ranking. See
Setting Dictionary Preferences Using MapMarker Java API on page 112.
There can be several instances of the properties file, depending on your installation choices. Default
locations and use of the AUS_DataManagerSettings.properties file are:
MapMarker Australia v15.5
110
Developer Guide
Chapter 8: Custom User Dictionaries
Configuring the User and Address Dictionary Ranking
AUS_DataManager Properties File
Properties File Location
<install>\desktop\
Use and Configuration
This instance of the
AUS_DataManagerSettings.properties file is present
if you installed the desktop application. If you have
written your own application using the C Developer
API, you must configure this file so that MapMarker
can determine the location and ranking of the User
Dictionary.
<install>\sdk\engine\lib\client\ This instance of the
AUS_DataManagerSettings.properties file is present
if you installed the Developer Kit (SDK). If you
developed you own Java Sample Application, you
must configure this file so that MapMarker can
determine the location and ranking of the User
Dictionary.
<install>\sdk\tomcat\webapps\
mapmarker40\WEB-INF\classes\
This instance of the
AUS_DataManagerSettings.properties file is used by
the tomcat web server. This is used for running the
provided Java Sample Application. Also, if you have
written your own application using the Java API, you
must configure this file so that MapMarker can
determine the location and ranking of the User
Dictionary.
See the following topics:
•
•
Configuring the DataManagerSettings.properties File
Setting Dictionary Preferences Using MapMarker Java API
Configuring the DataManagerSettings.properties File
By default the AUS_DataManagerSettings.properties file appears as follows:
# Optional - The number of dictionaries to be loaded.
DICTIONARY_COUNT=1
DEFAULT=1
# Required - The path to the highest ranking dictionary.
# Note that DICTIONARY_PATH is required from 1 to DICTIONARY_COUNT.
DICTIONARY_PATH1=/C:/Program
Files/MapInfo/MapMarker_AUS_v15.5/MapMarker_AUS_v15.5_Data
MAP_MARKER_HOME=/C:/Program
Files/MapInfo/MapMarker_AUS_v15.5/MapMarker_AUS_v15.5_Data
MapMarker Australia v15.5
111
Developer Guide
Chapter 8: Custom User Dictionaries
Configuring the User and Address Dictionary Ranking
The following example shows a AUS_Datamanager.properties file that has been edited to allow for
two dictionaries (DICTIONARY_COUNT=2) and to add a path to the User Dictionary
(DICTIONARY_PATH2=). The User Dictionary has a higher ranking, since it is designated as
PATH1. In this example, the standard Address Dictionary has been configured as PATH2.
# Optional - The number of dictionaries to be loaded. DEFAULT=1 */
DICTIONARY_COUNT=2
#**********
# Required - The path to the highest ranking dictionary.
# Note that DICTIONARY_PATH is required from 1 to DICTIONARY_COUNT.
#**********
DICTIONARY_PATH1=/C:/Program Files/MapInfo/MapMarker_AUS_v15.5/
MapMarker_AUS_v15.5_Data/Custom1
DICTIONARY_PATH2=/C:/Program Files/MapInfo/MapMarker_AUS_v15.5/
MapMarker_AUS_v15.5_Data
MAP_MARKER_HOME=C:\Program Files\MapInfo\MapMarker_AUS_v15.5\
MapMarker_AUS_v15.5_Data
To indicate which dictionaries to use, edit the configured dictionaries in the
AUS_DataManagerSettings.properties file. Add PATH keys for the dictionaries that you want to use,
and remove PATH keys to dictionaries that you do not want to use. Make sure that you update the
DICTIONARY_COUNT to reflect the correct number of dictionaries.
To specify the ranking of the configured dictionaries, change the rank (DICTIONARY_PATH#) as
necessary. The integer in PATH# represents the order in which the dictionary is searched, where #
can be an integer from 1 to N. Dictionary number 1 (PATH1) has the highest ranking. The number of
DICTIONARY_PATH entries in the properties file must match the value of DICTIONARY_COUNT.
Close matches from lower ranked dictionaries are demoted to non-close matches. When there are
close match candidates from different dictionaries, the close matches that are returned from the
higher ranking dictionary are given precedence.
L
Remember to shut down and restart the MapMarker server after editing the
DataManagerSettings.properties file. You must do this to make the new User Dictionary
available.
Setting Dictionary Preferences Using MapMarker Java API
The developer can also use the MapMarker Java API to specify the order of dictionaries and which
dictionaries to use in a geocode request. The API settings overrides preferences set through the
Desktop Application or the DataManagerSettings.properties file.
Dictionary preferences are set using the IDictionarySearchOrder object. To retrieve the object, use
the getDictionarySearchOrder method.
MapMarker Australia v15.5
112
Developer Guide
Chapter 8: Custom User Dictionaries
Configuring the User and Address Dictionary Ranking
The IDictonarySearchOrder object retrieves a list of the configured dictionaries and contains specific
information about each one. It returns the count of the number of configured dictionaries, plus the
following information for each dictionary:
•
Configured index
•
Description string
•
If dictionary is a User Dictionary
•
User Dictionary search order
•
Whether this dictionary is searched by default
Once you have the IDictionarySearchOrder object, you can modify it using a number of methods to
set the dictionary preferences for the geocode operation and then add the object to the
GeocodeConstraints to be passed in with the geocode request.
For example, clients may call GetDictionarySearchOrder, then in the constraints make changes to
the search order and set the resulting object in the constraints using the setDictionarySearchOrder
method. So if the server has three configured dictionaries, the client can specify that they want
candidates from a particular dictionary number.
Some of the methods that are used with GetDictionarySearchOrder are described briefly in the
following table:
Method
Description
getDictionaryCount
Returns the number of configured dictionaries
available to the engine.
getDictionaryDescription
Returns the description of the indicated dictionary. If
no description is found, a string indicating whether
the dictionary is a user dictionary will be returned.
To create a dictionary description, type the
description text into a text file and name it
dictionarydes.txt. Then place the file in the
dictionary path.
getSearchOrderForDictionary
Returns the dictionary search order.
isDictionaryAvailableForSearch
Returns true if dictionary will be searched.
isUserDictionary
Returns true if the dictionary is a user-created
dictionary.
setDictionaryAvailableForSearch
Setting to false indicates that the dictionary will not
be searched.
setSearchOrderForDictionary
Sets the order in which the dictionaries will be
searched.
MapMarker Australia v15.5
113
Developer Guide
Chapter 8: Custom User Dictionaries
Configuring the User and Address Dictionary Ranking
Dictionaries may be removed from the list of dictionaries to search by using a
setDictionaryAvailableforSearch method on the IDictionarySearchOrder object, and then adding it to
the constraints for the geocode request.
To find out which dictionary a candidate came from, you can use the getDictionaryNumber method in
the CandidateAddress class. You can use this number to get a description of the configured
dictionary in the dictionarydesc.txt file for the dictionary. If this file is missing, the description of the
dictionary will be limited to Address Dictionary or User Dictionary.
To pass in the IDictionarySearchOrder object with the geocode constraints, use the
setDictionarySearchOrder method in the IGeocodeConstraints interface. It sets a custom order for
searching configured user dictionaries.
For detailed information about all classes, refer to the API documentation (Javadocs) for
MapMarker. This is located in <install_dir >\docs\aus folder, where <install_dir> represents your
MapMarker installation directory. From that location, run index.html to see the MapMarker Javadocs.
MapMarker Australia v15.5
114
Developer Guide
Result Codes
As an output option, MapMarker Australia returns a result code for every record
it attempts to match. The code represents the success or failure of the
geocoding operation as well as conveying information about the quality of the
match. Each character of the code tells how precisely MapMarker Australia
matched each address component.
In this chapter:
Š
Š
Š
Š
Š
Š
Š
Understanding Result Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Single Close Matches (S category). . . . . . . . . . . . . . . . . . . . . . . .116
Postal Code Centroid Matches (Z category) . . . . . . . . . . . . . . . .118
Postal Code Centroid Matches (Z category) . . . . . . . . . . . . . . . .118
Geographic Centroid Matches (G category) . . . . . . . . . . . . . . . .118
Reverse Geocoded Matches (R category) . . . . . . . . . . . . . . . . . .119
Non-match Codes (N category). . . . . . . . . . . . . . . . . . . . . . . . . . .119
9
Chapter 9: Result Codes
Understanding Result Codes
Understanding Result Codes
The result code is an alphanumeric code of 1-10 characters. The codes fall into four major
categories:
•
•
•
•
•
•
Single Close Matches (S category)
Postal Code Centroid Matches (Z category)
Postal Code Centroid Matches (Z category)
Geographic Centroid Matches (G category)
Reverse Geocoded Matches (R category)
Non-match Codes (N category)
The codes reflect the settings you choose for your geocoding session. They also reflect the quality
of your data as it compares to the address data in the Address Dictionary.
Examples of result codes are S5HP-TSC-A, and S5H--T-CZA.
The following sections describe each category that is returned in this version of MapMarker
Australia.
Single Close Matches (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 Australia found a street address that matches your
record.
The second position in the code reflects the positional accuracy of the resulting point for the
geocoded record, as indicated below. If the last character is a G, the candidate was returned from
the G-NAF dictionary. The intervening dots represent characters that indicate which elements of the
address were matched. See Interpreting Complete S Result Codes on page 117.
•
S4 – Single close match, point located at the center of a shape point path (shape points define
the shape of the street polyline).
S4.......G – The S4.......G result code is used for single matches with a G-NAF Reliability level
of 4 (associated with a unique road feature.) G-NAF confidence level and reliability levels are
described more fully in the G-NAF chapter of the MapMarker Australia User Guide.
•
•
S5 – Single close match, point located at a street address position.
S7 – single match, located at an interpolated point along the candidate’s street segment. When
the potential candidate is not an address point candidate and there are no exact house number
matches among other address point candidates, the S7 result is returned using address point
interpolation.
S7.......G – The S7.......G result code is used for single matches with G-NAF Reliability level of
3. G-NAF confidence level and reliability levels are described more fully in the G-NAF chapter of
the MapMarker Australia User Guide.
MapMarker Australia v15.5
116
Developer Guide
Chapter 9: Result Codes
Single Close Matches (S category)
•
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.
S8.......G – The S8.......G result code is used for single matches with G-NAF Reliability levels
of 1or 2 (the highest level of G-NAF Reliability. G-NAF confidence level and reliability levels are
described more fully in the G-NAF chapter of the MapMarker Australia User Guide.
•
•
•
SX – Single close match, point located at street intersection.
S0 – Single close match, no coordinates available.
SG – Single close match with point at the centre of a locality/or Locality level geocode derived
from topographic feature. An SG result code is associated with G-NAF Reliability Level 5 (locality
or neighbourhood) or with Level 6 (unique region.) See G-NAF Reliability Level on page 88 for
more information on G-NAF Reliability levels.
SP – Single close match to a post office location. This can be generated from the standard Street
Range Address Dictionary only (not the G-NAF dictionary).
SC – Single close match where the original point has been moved a specified distance along a
perpendicular line toward or away from the associated street segment. This is associated with
the centerline offset feature. See Centerline Offset for User Dictionary Point Candidates on
page 67 for more information on this feature.
•
•
Interpreting Complete S Result Codes
For S category result codes, eight additional characters describe the accuracy of the match and from
which dictionary the candidate was returned. The characters appear in the order listed in the
following table. Any non-matched components are represented by a dash.
Result Code Component
Description
Example
H
House Number
330
P
Street Prefix Direction
NE
N
Street Name
Front
T
Street Type
St
S
Street Suffix
W
C
City Name
Toronto
Z
Postal Code
M5V 3B7
A, U, or G
Address Dictionary, User Dictionary, or G-NAF
Dictionary.
A
For example, the result code S5- -N-SCZA represents a single close match that matched the street
name, street suffix direction, city, and postcode exactly. The dashes indicate that there was no
match on house number, street prefix direction, or street type. The match came from the MapMarker
Address Dictionary. This record would be geocoded at the street address position of the match
candidate.
MapMarker Australia v15.5
117
Developer Guide
Chapter 9: Result Codes
Postal Code Centroid Matches (Z category)
See Interpreting S5 Result Codes for a more detailed analysis of analyzing S5 result codes.
Interpreting S5 Result Codes
If you receive an S5 match for a record that did not locate where you thought it should, you need to
analyze the result code closely to determine why. This situation occurs during a geocoding pass for
which the Match Strategy is relaxed (when House Number and Street Name matching are not
required). When MapMarker Australia attempts to geocode the record with those settings, it
searches larger areas than it would if the conditions were stricter. It may match the record to a
distant address that has a similar name.
To understand how the match was made, look at the full result code. A typical result in this situation
looks like this: S5-P--S--A. Even though MapMarker Australia returned an S5 (it found a single close
match to a street address), it did not match the house number (H), street name (N), street type (T),
city (C) or postcode (Z). Those components in the result code are missing and represented by
dashes. A perfect street level match would return a result code with every component of the address
matched and would look like S5HPNTSCZA.
In order to minimize the match inaccuracy, geocode your table using stricter matching conditions.
For the strictest match settings and greatest matching accuracy, try geocoding using the match on
exact house number mode. Geocoding modes are explained further in Geocoding Preferences
and Options in Chapter 6 on page 115.
Postal Code Centroid Matches (Z category)
Matches in the Z category indicate that no street match was made for one of the following reasons:
•
•
There is no close match and you allowed MapMarker Australia to fall back to Postal Code
Centroid.
You set MapMarker Australia to match to postcode centroids.
The resulting point is located at the postcode centroid.
•
•
•
Z3 – full postcode centroid match (FSADLU - full postcode; 6 characters).
Z1 – partial postcode centroid match (FSA - first 3 characters).
Z0 – no coordinates available (very rare).
Geographic Centroid Matches (G category)
Matches in the G category indicate that no street match was made for one of two reasons:
•
•
There is no close match and you allowed MapMarker Australia to fall back to geographic
centroid.
You set MapMarker Australia to match to geographic centroids.
The resulting point is located at the geographic centroid:
•
G3 – Geographic centroid match to a city or municipality centroid.
MapMarker Australia v15.5
118
Developer Guide
Chapter 9: Result Codes
Reverse Geocoded Matches (R category)
•
G1 – Geographic centroid match to a province centroid.
Reverse Geocoded Matches (R category)
Candidates return a R result codes, indicating that records was matched by reverse geocoding. 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 address dictionaries only (not
user dictionaries).
Reverse geocoding result codes are as follows:
•
•
•
•
•
•
RS8G – Point/parcel level precision. Candidate returned from G-NAF dictionary with G-NAF
Reliability level of 1 or 2.
RS7G – Candidate returned from G-NAF dictionary with G-NAF Reliability level of 3.
RS5A – Street address match. Candidate returned from address dictionary.
RS4A – Street address match. Candidate returned from address dictionary.
RS4G – Candidate returned from G-NAF dictionary with a G-NAF Reliability level of 4
(associated with a unique road feature)
RSGG – Candidate returned from G-NAF dictionary with G-NAF Reliability Level 5 (locality or
neighbourhood) or with Level 6 (unique region.)
For the following input coordinates, a close match candidate is returned with a result code of RS5A.
X: 150.991012
Y: -33.836827
Note that reverse geocoding against the G-NAF address dictionary is based on street frontage
points, not the points that represent the exact location of the parcel. Street frontage points are more
suitable for routing applications.
L
Reverse geocoding is available in the Developer (Server) edition. It is not available in the
Desktop application.
Non-match Codes (N category)
The following result codes indicate no match was made:
N – No close match.
•
•
•
NX – No close match for street intersections.
ND – MapMarker Australia could not find the Address Dictionary for the given postcode or
city/province. These records can be re-geocoded once the Address Dictionary is available.
NG – The user marks these records as non-geocodable. MapMarker Australia does not attempt
to match these records again until the code is removed.
MapMarker Australia v15.5
119
Developer Guide
Error Messages
This appendix provides a reference to error messages you may receive in the
course of using MapMarker Australia.
In this appendix:
Š
Š
Š
MapMarker Java API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Geocoding Engine Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Adapter Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
A
Chapter A: Error Messages
MapMarker Java API Errors
MapMarker Java API Errors
Engine Errors
Error Code
Description
ERR_CANT_CREATE_GEOCODABLE_ADDRESS
Engine unable to create an address
object for the given country.
ERR_EXCEPTION_IN_ENGINE
Engine encountered an exception.
ERR_UNKNOWN_GEOCODE_TYPE
Engine was given an unknown geocode
type.
ERR_ENGINE_RESET_NULL
Engine returned null instead of a
response object.
Parser Errors
Error Code
Error #
Description
ERROR_PARSER_INPUT_ADDRESS_NULL
2000
Input address is null.
ERROR_PARSER_PARSED_ADDRESS_NULL
2001
Parsed address is null.
ERROR_PARSER_INITIALIZATION
5000
Unable to initialise parser.
Data Access Exceptions
Error Code
Error #
Description
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.
MapMarker Australia v15.5
121
Developer Guide
Chapter A: Error Messages
MapMarker Java API Errors
Error Code
Error #
Description
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 optimised. 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}.
License Exceptions
Error Code
Error #
Description
ERROR_LICENSE_INIT
2200
Unable to initialise license manager.
ERROR_LICENSE_MISSING_BASIC_LICENSE
5200
Missing required initialisation license.
ERROR_LICENSE_ILLEGAL_GEOCODE_MODE
5201
Illegal geocode mode encountered
during license evaluation.
General Geocoding Process Exceptions
Error Code
Error #
Description
ERROR_GAC_RESOURCE
2300
Unable to find resource bundle for error
messages.
ERROR_GAC_FACTORY_INSTANTIATION
2301
Unable to instantiate geocodable
address factory for country code {0}.
ERROR_NULL_RESULT
2302
The geocoding engine was unable to
return a result.
ERROR_GEO_TYPE_UNSUPPORTED
2303
Unsupported geocode type: {0}
ERROR_NO_PARSE_RESULT
2304
No result received from parser.
ERROR_GAC_PARSER_INIT_FAILED
2305
Error initialising parser.
MapMarker Australia v15.5
122
Developer Guide
Chapter A: Error Messages
MapMarker Java API Errors
Error Code
Error #
Description
ERROR_GAC_DATA_MANAGER_INIT_FAILED
2306
Error initialising data manager. Check
MMAUSLicenseProvider.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.
Client Exceptions
Error Code
Error #
Description
ERROR_CLIENT_BAD_URL
2400
Malformed URL.
ERROR_CLIENT_HTTP_ERROR
2401
HTTP Error: {0}.
ERROR_CLIENT_JDOM
2402
JDom Exception encountered.
ERROR_CLIENT_XML_TRANSFORM
2403
Error during XML transformation.
ERROR_CLIENT_IO
2404
IO Error.
ERROR_CLIENT_MISSING_URL
2405
The URL to the servlet has not been
set. Please try again with a Servlet
URL.
ERROR_CLIENT_MISSING_RESPONSE
2406
No response was returned from
server.
Localisation (Geocoder Construction Time) Exceptions
Error Code
Error #
Description
ERROR_HANDLER_INVALID
2500
The provided IHandler
implementation is not valid.
ERROR_HANDLER_INCOMPLETE_NO_DATA_MANAGER
2501
The provided IHandler
implementation is not
complete. No local data
manager was provided.
MapMarker Australia v15.5
123
Developer Guide
Chapter A: Error Messages
MapMarker Java API Errors
Error Code
Error #
Description
ERROR_HANDLER_INCOMPLETE_NO_PARSER_RULES
2502
The provided IHandler
implementation is not
complete. No local address
parsing rules were provided.
ERROR_HANDLER_INVALID_ADDRESS_GEOCODER
2503
The IAddressGeocoder
provided in the IHandler
implementation is required but
not valid.
ERROR_HANDLER_INVALID_POSTAL_GEOCODER
2504
The IPostalGeocoder
provided in the IHandler
implementation is required but
not valid.
ERROR_HANDLER_INVALID_GEOGRAPHIC_GEOCODER
2505
The IGeographicGeocoder
provided in the IHandler
implementation is required but
not valid.
ERROR_HANDLER_INVALID_BROWSE_GEOCODER
2506
The IBrowseGeocoder
provided in the IHandler
implementation is required but
not valid.
ERROR_HANDLER_INVALID_STANDARDIZE_GEOCODER
2507
The IStandardizeGeocoder
provided in the IHandler
implementation is required but
not valid.
ERROR_HANDLER_INVALID_CUSTOM_GEOCODER
2508
The ICustomGeocoder
provided in the IHandler
implementation is required but
not valid.
ERROR_HANDLER_INVALID_POSTAL_FILTER
2509
The IPostalCentroidFilter
provided in the IHandler
implementation is not valid.
ERROR_HANDLER_INVALID_GEOGRAPHIC_FILTER
2510
The
IGeographicCentroidFilter
provided in the IHandler
implementation is not valid.
ERROR_HANDLER_INVALID_PARSER
2511
The parser provided in the
IHandler implementation is
not valid.
MapMarker Australia v15.5
124
Developer Guide
Chapter A: Error Messages
Geocoding Engine Errors
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.
Geocoding Engine Errors
Error Code
Error#
Description
GEO_ENG_MALLOC_ERR
1
The engine was unable to allocate
memory.
GEO_ENG_BAD_PARAM_ERR
3
The engine encountered a
parameter that was not specified
correctly.
GEO_ENG_END_OF_DATA
11
The engine reached the end of the
data.
GEO_ENG_BAD_INPUT_ADDRESS
14
The engine encountered a bad
input address.
GEO_ENG_NO_DATA_AVAILABLE
15
No data is available or engine
cannot find the data.
GEO_ENG_COORDS_NOT_AVAILABLE
51
No coordinates are available.
GEO_ENG_BAD_CAND_INDEX
52
Candidate index is incorrect.
GEO_ENG_BAD_RANGE_INDEX
53
Range index is incorrect.
MapMarker Australia v15.5
125
Developer Guide
Chapter A: Error Messages
Adapter Errors
Adapter Errors
Error Code
Error #
Description
ADAPTER_NO_CONFIG
1793
Could not find or open the config
file.
ADAPTER_EXCEEDED_OPTIONS
1794
Number of options exceeds
number of options specified in
config file.
ADAPTER_NO_ENGINE_CLASS
1797
Unable to find mmjni.jar in
classpath.
ADAPTER_NO_HELPER_CLASS
1801
Unable to find mmjni.jar in
classpath.
ADAPTER_GEOCODE_RESULT_NO_CLASS
1804
Unable to find mmjni.jar in
classpath.
ADAPTER_CANDIDATE_NO_CLASS
1806
Unable to find mmjni.jar in
classpath.
ADAPTER_RANGE_NO_CLASS
1808
Unable to find mmjni.jar in
classpath.
ADAPTER_JNI_CFG_PARMS_NO_CLASS
1810
Unable to find mmjni.jar in
classpath.
ADAPTER_DOUBLE_POINT_NO_CLASS
1814
Unable to find miutil.jar in
classpath.
ADAPTER_MAPMARKER_EXCEPTION_NO_CLASS
1820
Unable to find mmj.jar in
classpath.
ADAPTER_MAPMARKER_FATAL_EXCEPTION_NO_CL
ASS
1822
Unable to find mmj.jar in
classpath.
ADAPTER_NO_CONSTRAINTS_NO_CLASS
1824
Unable to find mmj.jar in
classpath.
ADAPTER_NO_MM_EXCEPTION_CODES_CLASS
1826
Unable to find mmj.jar in
classpath.
ADAPTER_RUNTIME_ERR
1841
Runtime error occurred.
ADAPTER_OUT_OF_MEMORY
1842
Memory exceeded. Check
memory specified in config file.
MapMarker Australia v15.5
126
Developer Guide
Chapter A: Error Messages
Adapter Errors
Error Code
Error #
Description
ADAPTER_RUNTIME
1843
Runtime exception occurred.
Check data path.
ADAPTER_MAPMARKER_FATAL_UNKNOWN
1844
Unknown fatal exception occurred.
ADAPTER_UNKNOWN_EXCEPTION
1845
Unknown exception occurred.
ADAPTER_NO_JVM_DLL
1871
Unable to find jvm.
ADAPTER_NO_JVM_CREATE
1872
Unable to create jvm. Check jvm
installation, or config file options.
MapMarker Australia v15.5
127
Developer Guide
Index
A
D
address browsing 76
address dictionary
installing 14
storing on hard drive 14
address interpolation 79
AUS_GeocodeConstraints 59
Australian address format 30
Australian geography 29–34
Australian postcodes 28
data
ambiguous input 34
input 32
installing 14
intersections 34
postcode input 33
storing 14
street input 33
town and state input 33
deployment as servlet 98
dictionary ordering 112
dictionary preference 40
B
batch requests
xml API 82
browsing addresses
Java API 76
E
error message reference 121, 127
exact match street
street geocoding example 43
C
candidates
retrieving 68
candidates with ranges 44
centerline offset 44
centerline offset for point user dictionary 67
close matches only
constraints 40
common schema 83
constants
match mode 63
constraints
close matches only 40
fallback to geo 40
fallback to postal 40
using 39
coordinate systems
setting in applications 63
creating
user dictionary 100
creating Web client 70–74
MapMarker Australia v15.5
F
fallback to geo 45
constraints 40
fallback to postal 45
constraints 40
ftp site 10
G
geocode request types 96
geocode type
selecting 40
GeocodeConstraints 57
geocoding
address format 30
geocoding constraints 56, 59
geocoding results
geographic centroid match 118
non-match codes 119
postal centroid match 118
128
Developer Guide
L
S4G code 116
S5 codes 118
S7G code 116
S8 codes 117
SG codes 117
single close match 116
SP codes 117
geographic candidate
return fields 46
geographic centroid geocoding 79
Java API 78
geographic centroids
result codes 118
geographic geocoding 46
geography
Australian 29–34
getGeoResult 69
getGNAFOriginalLatitude 66
getGNAFOriginalLongitude 66
getSegmentID 70
segment ID 70
getUsingDefaultStreetFrontagePoints 64
G-NAF
meshblock information 29
G-NAF frontage points 64
G-NAF PID lookup
setGNAFPID 64
G-NAF standard points 64
latitude
address element 36
street candidate returns 42
LGA
definition 30
locality
reverse geocode returns 48
longitude
address element 36
street candidate returns 42
M
MapMarker
technical support 11
MapMarker Plus Canada
new features 8
product overview 7
MapMarker server
deploying in Web environments 98
match mode constants and methods 63
meshblock
definition 29
reverse geocode returns 49
street candidate returns 41
methods
match mode 63
MMJCommon.xsd 83
MMJRequest.xsd 82
MMJResponse.xsd 82
modify
silent 23
I
input address setup for applications 55
input data 32
input fields
Java 53
installation
multiple versions of MapMarker 24
new installation 16
removing MapMarker 25
silent install 21–22
UNIX/Linux 16
upgrading 24
Windows procedure 16
installation components 13
intersection geocoding 43
intersections
customised user dictionary 104
input format 34
N
new in this release 8
non match codes
result codes 119
O
original G-NAF points 66
original user dictionary points 67
output fields
Java 54
P
performance
optimising 16
place name
address element 36
reverse geocode returns 48
J
Java input fields 53
Java output fields 54
MapMarker Australia v15.5
129
Developer Guide
street candidate returns 41
user dictionary support 100
postal candidate
return fields 46
postal code centroids
result codes 118
postal code override 68
postal geocoding 45
Java API 77
postal system 28
postcode
address element 36
geography 28
input format 33
postal candidate returns 46–47
reverse geocode returns 49
street candidate returns 41
preferences
user dictionary 112
provinces
installation 13
preferences and constraints 49
return fields 48
S
sample application
MapMarker 35
requirements 37
testing the server 38
using 37–40, 46
schemas
MapMarker 82
xsd 82
segment ID 70
reverse geocode returns 49
street candidate returns 41
servlet deployment 98
setCenterlineOffset 67
setCenterlineOffsetUnit 67
setClientCoordinateSystem 63
setPostalCodeOverride 68
setReturnGNAFOriginal 66
setReturnStreetFrontagePoints 64
setting
geocoding constraints 56, 59
input address 55
setUseCenterlineOffset 67
silent install 21–22
silent modify 23
silent uninstall 25
silent upgrade 24
single close match result codes 116
state
address element 36
geographic candidate returns 47
reverse geocode returns 49
street candidate returns 41
street address
reverse geocode returns 48
street candidate returns 41
street data
input format 33
street geocoding 40, 42
candidates with ranges 44
example 43
fallback to geo 45
fallback to postal 45
street geocoding candidates 41
street intersections
customised user dictionary 104
street name
address element 36
suburb
R
ranges 44
region
geographic candidate returns 47
removing MapMarker from your system 25
request schema 82
response schema 82
result code retrieval 69
result codes
geographic candidate returns 47
geographic centroid match 118
non match codes 119
postal candidate returns 46
postal centroid match 118
reverse geocode returns 49
S4G results 116
S5 results 118
S7G results 116
S8 results 117
SG results 117
single close match 116
SP results 117
street candidate returns 42
return values
geographic centroid candidates 79
reverse geocoding 47
constraints 75
getting response 75
Java API 75
Java implementation 74
MapMarker Australia v15.5
130
Developer Guide
address element 36
support
technical support 11
T
technical support 9, 11
Tomcat servlet container 98
town
geographic candidate returns 47
reverse geocode returns 48
street candidate returns 41
town/suburb and state data 33
U
uninstall 25
silently 25
upgrade
silently 24
upgrading your installation 24
usePostalCodeOverride 68
user dictionaries
preferences 112
user dictionary
considerations and restrictions 103
data requirements 100
description 100
format requirements 103
intersections 104
W
war files 98
Web environments 98
Web geocoding client 70–74
WebLogic 98
WebSphere 98
X
XML
geocoding constraint keys 96
MapMarker Australia v15.5
131
Developer Guide