MapInfo Geocoding Cartridge. User s Guide

Transcription

1 MapInfo Geocoding Cartridge User s Guide

2 Information in this document is subject to change without notice and does not represent a commitment on the part of MapInfo 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 MapInfo Corporation, One Global View, Troy, New York MapInfo Corporation. All rights reserved. MapInfo Help MapInfo Corporation. All rights reserved. MapInfo, MapInfo Professional, MapBasic, MapMarker, and the MapInfo Rainbow Logo are trademarks of MapInfo Corporation. Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark. MapInfo welcomes your comments and suggestions MapInfo Corporate Headquarters: MapInfo Europe Headquarters: Germany: Voice: (518) Voice: +44 (0) Voice: +49 (0) Fax: (518) Fax: +44 (0) Fax: +49 (0) Sales Info Hotline: (800) uk@mapinfo.com germany@mapinfo.com US Government Sales: (800) Technical Support Hotline: (518) Technical Support Fax: (518) Toll-free telephone support is available in the U.S. and Canada. Contact your MapInfo sales representative for details. For international customers, please use the Technical Support Fax number. Contact MapInfo Corporation on the Internet at: Portions copyright (c) Matchware Technologies, Inc., All rights reserved. ZIP+4 is a registered trademark of the U.S. Postal Service Geographic Data Technology, Inc. This product contains proprietary and confidential property of Geographic Data Technology, Inc. Unauthorized use, including copying for other than testing and standard backup procedures, of this product is expressly prohibited. This documentation reflects the contributions of almost all of the women and men who work for MapInfo Corporation. It was specifically produced by Larry Strianese. Juliette Funiciello-Vunk, Associate Editor. These members of the Documentation Department are indebted to MapInfo s Quality Assurance Department and, of course, to all the members of the Product Development team that engineered this project. MapInfo Geocoding Cartridge 2.0 January 2000

3 Table of Contents Chapter 1: Introduction What s New Software Requirements Documentation for the MapInfo Geocoding Cartridge Installation Upgrading to Uninstalling the MapInfo Geocoding Cartridge Chapter 2: Working with the MapInfo Geocoding Cartridge Preparing to Geocode Using the MapInfo Geocoding Cartridge Geocoding a Single Address Geocoding a Table Oracle8i Object Types The Geoaddress Object Type The Candidate Object Type The addressrange Object Type The mm_inputtableinfo Object The mm_outputtableinfo Object The mm_preferences Object Type Managing Geocoding Preferences Result Codes Defined Geocoding Examples Chapter 3: Troubleshooting Error Codes Appendix A: MapMarker J Server and MapInfo Geocoding Cartridge Preference Comparison Appendix B: Glossary of Address and Geocoding Terms

4 Chapter 1: Introduction Overview MapInfo Geocoding Cartridge is for users of Oracle8i databases who wish to add Oracle8i spatial points or longitude/latitude information to their address records for display and analysis in mapping software. This is accomplished by a process known as geocoding, where a record containing address information is matched to an address with coordinates in a search dictionary. If a match is found, the geographic coordinates of the match record are assigned to the input address to complete the process. MapInfo Geocoding Cartridge is a Java-based tool that allows you to interact with the powerful geocoding engine in MapMarker from an Oracle8i database. The cartridge uses the MapMarker J Server to communicate with MapMarker via Java Native Interface (JNI). You may geocode addresses individually or process an entire table using functions and procedures provided with the cartridge. Records are geocoded to the street level. If a street level match cannot be made, MapMarker will attempt to match it to the nearest postal centroid. Direct postal centroid geocoding, browsing the Address Dictionary, and querying the server, are not supported. Currently, MapMarker contains information for U.S.-based addresses only. The cartridge, however, was written using MapMarker J Server's international protocol so that it may run unchanged as international solutions become available. The current MapMarker engine will simply ignore extra international information such as the language, country, and character set. To learn how to use the MapInfo Geocoding Cartridge, look at the samples that are installed in the \MapInfoGeocodingCartridge2.0\demo directory. A summary of these samples is described in the section, Geocoding Examples.

5 Chapter 1: Introduction What s New The following functions and procedures have been added to the new version of the MapInfo Geocoding Cartridge. For more information on these features, see Chapter 2: Working with the MapInfo Geocoding Cartridge. get_default_preference_name - This will print out the name of the preference that is currently the default preference (procedure). add_new_http_server(httpurl, serversrid) - Creates an entry in the misys.misys_server_properties table for this httpserverurl with this SRID. If the httpserverurl already exists it will print out an error message. This allows us to store the SRID the MapMarker J Server will return coordinates in. Only used in Oracle and above (procedure). add_new_tcp_server(inputtcpserverhostid, InputTcpServerPostId, InputrSRID) - Creates an entry in the misys.misys_server_properties table for the given host, port and SRID. If the host and port combination are already in the table, an error message will be printed out (procedure). print_version - This prints the current version of the MapInfo Geocoding Cartridge (procedure). getoraclespatialobject (candidate index, SRID) - Returns the mdsys.sdo_geometry object containing longitude and latitude information for the candidate at the given index. The input SRID will be used to create the object (function). Integration Considerations for Users of Previous Versions Important changes for users of previous versions of the MapInfo Geocoding Cartridge include the following: The misys.mm_outputtableinfo object has a new parameter, following the latitude: SQL> desc mm_outputtableinfo Name Null? Type OUTTABLENAME VARCHAR2(32) OUTPRIMARYKEYCOLNAME VARCHAR2(32) OUTFIRMCOLNAME VARCHAR2(32) OUTSTREETCOLNAME VARCHAR2(32) OUTSTREET2COLNAME VARCHAR2(32) OUTCITYSUBDIVISIONCOLNAME VARCHAR2(32) OUTCITYCOLNAME VARCHAR2(32) OUTCOUNTRYDIVISIONCOLNAME VARCHAR2(32) OUTCOUNTRYCOLNAME VARCHAR2(32) OUTPOSTALCODECOLNAME VARCHAR2(32) 2

6 Chapter 1: Introduction OUTPOSTALADDONCODECOLNAME VARCHAR2(32) OUTRESULTCODECOLNAME VARCHAR2(32) OUTCENSUSBLOCKCOLNAME VARCHAR2(32) OUTDELIVERYPOINTCOLNAME VARCHAR2(32) OUTCHECKDIGITCOLNAME VARCHAR2(32) OUTLACSCOLNAME VARCHAR2(32) OUTCARRIERROUTECOLNAME VARCHAR2(32) OUTLANGUAGECOLNAME VARCHAR2(32) OUTCHARSETCOLNAME VARCHAR2(32) OUTLONGITUDECOLNAME VARCHAR2(32) OUTLATITUDECOLNAME VARCHAR2(32) OUTSPATIALOBJECTCOLNAME VARCHAR2(32) //**** NEW! **** OUTPRECISIONCOLNAME VARCHAR2(32) OUTSCORECOLNAME VARCHAR2(32) OUTBCLOSECOLNAME VARCHAR2(32) Before geocoding on Oracle or higher, you will need to add an entry to the MISYS_SERVER_PROPERTIES table using the add_new_http_server or add_new_tcp_server. Software Requirements Geocoding Oracle8i records requires the following software: MapInfo Geocoding Cartridge - Product for geocoding for Oracle8i records. Oracle8i (Oracle 8.1.5, Oracle 8.1.6, or Oracle 8.1.7) with the Spatial option - Spatial database with Java options. MapMarker 6.x or MapMarker 6.x Plus - Geocoding engine and Address Dictionary. MapMarker J Server 2.1 or higher - Java-based component that communicates with the cartridge and MapMarker. Install the MapInfo Geocoding Cartridge, as well as MapMarker J Server and MapMarker on the same machine as Oracle8i or place the MapMarker J Server and engine on a separate machine. MapMarker J Server is written in Java and will run on any platform. MapMarker and MapMarker Plus are supported on Windows NT/98/2000, Sun Solaris, and HP systems. The MapInfo Geocoding Cartridge will run on any Oracle platform. Consult your Oracle8i documentation for Oracle system requirements. Important: We assume you are familiar with Oracle8i databases, including how to update tables, add columns, create objects, etc. 3

7 Chapter 1: Introduction Documentation for the MapInfo Geocoding Cartridge Several sources of documentation are provided to assist you with using the MapInfo Geocoding Cartridge effectively: Installation The MapInfo Geocoding Cartridge User s Guide provides installation instructions and an overview of how to use the cartridge. For assistance with MapMarker J Server installation and usage, see the HTML document Getting Started with MapMarker J Server, provided with that product. For Java API documentation for the MapMarker J Server, look in \javadoc under the directory where you installed the client, server or both. See Index.html for an alphabetical index of all classes with their methods and properties. For more information on geocoding, refer to the MapMarker Product Guide and Online Help. For information related to Oracle8i operations, see the Oracle8i documentation set. The following is the recommended order in which to install Oracle8i, MapMarker, the MapMarker J Server, and the MapInfo Geocoding Cartridge. 1. Install Oracle8i, the Spatial option, and the JDBC drivers. Rerun the Oracle8i installer to add these options if necessary. Refer to your Oracle8i documentation for installation instructions. 2. Install MapMarker 6.x or MapMarker Plus 6.x. Test that MapMarker is installed correctly and will run. Refer to the MapMarker Supplemental Guide or Getting Started for installation instructions. You will be required to call MapInfo Corporation for a data access code during the installation. 3. Install and test the MapMarker J Server on the same machine as MapMarker 6.x or MapMarker Plus 6.x by following the instructions in the Getting Started with MapMarker J Server found on the MapMarker J Server CD. 4. To install the MapInfo Geocoding Cartridge on the Oracle8i server, insert the MapInfo Geocoding Cartridge CD and double-click on install.htm. Follow the screen prompts. This intermediate install process will place the SQL files needed to complete the installation for the MapInfo Geocoding Cartridge on your system. Alternatively, run the installer manually from: Windows NT/98/2000: At the CD root, go to InstData\Windows\Vm and run install.exe. 4

8 Chapter 1: Introduction Sun Solaris: Change the current working directory to the CD root. At the command line type: sh InstData/Unix/Solaris/install.bin. This step requires that the installer finds the Java VM on your Solaris machine. It will generate the appropriate error message if it cannot find the VM, so make sure your PATH environment variable contains a VM. HP: Change the current working directory to the CD root. Use the command line sh InstData/Unix/Others/install.bin. 5. Proceed through the prompts entering the necessary information. At the Choose Install Set screen, select Install. The MISYS Account Information screen displays. 6. At the MISYS Account Information screen, enter the MISYS password. Enter the necessary information and click Next. The MapMarker J Server screen displays. 7. Enter the necessary information in the following MapMarker J Server screens. After all of the information is entered, the Install Complete screen displays. If you have installed from an Oracle8i server, skip to step 9 to complete the installation. If you are installing from an Oracle8i client, continue to the next step for special directions. 8. Important: If installing from an Oracle8i client, modify the misys.sql file. In the MapInfoGeocodingCartridge2.0\install\misys.sql file under your Oracle home, modify the lines: host loadjava -u misys/misys -o -v -r -f mapmarker.jar host loadjava -u misys/misys -o -v -r -f mapmarkerjserver.jar to read: host loadjava -u misys/misys@<your_database> -o -v -r -f mapmarker.jar host loadjava -u misys/misys@<your_database> -o -v -r -f mapmarkerjserver.jar If you forget <your database> name, consult the tnsnames.ora under your Oracle home. Note: In the above lines, MISYS is the default password for the misys account. If you chose a different password, substitute that password for MISYS. 5

9 Chapter 1: Introduction 9. All users: To complete the installation, you will need to connect via SQL*Plus as system, then manually run the system.sql file. To do this, from a command prompt go to the MapInfoGeocodingCartridge2.0\install directory. Start SQL*Plus by typing "sqlplus" at the command prompt, or for Windows users, select Start>Programs, navigate through the Oracle program group and select SQL Plus. Log in to SQL*Plus as system. If you are installing from an Oracle8i client, you will need to give the host string with the password, i.e. manager@<your_database>. 10. Connect via SQL*Plus as misys, once you are logged in, type misys.sql You should see the install script tables and packages created. Note: The command loadjava embedded in misys.sql may have a problem with the contents of your global CLASSPATH. It can stop the smooth execution of misys.sql. If you think this is happening to you, try setting the CLASSPATH to the empty string before invoking SQL*Plus and running misys.sql. This conflict depends entirely on the Java-oriented applications you have installed on your system. 11. To see how to set up a demo table that uses the MapInfo Geocoding Cartridge, look for single_geoaddr.sql in the MapInfoGeocodingCartridge2.0\demo directory. 6

10 Chapter 1: Introduction Upgrading to 2.0 To upgrade your existing version of the MapInfo Geocoding Cartridge: 1. Place the MapInfo Geocoding Cartridge CD in your CD-ROM drive. 2. Proceed through the prompts entering the necessary information. At the Choose Install Set screen, select Upgrade Install. The MISYS Account Information screen displays. 3. At the MISYS Account Information screen, enter the MISYS password. The Install Complete screen displays. 4. At the Install Complete screen, click Done and continue with the following instructions. 5. Use SQL*Plus to execute the misys.sql file located in the install directory. If you are connecting from Oracle 8I Client Install, modify the misys.sql file accordingly: -misys.sql --created by MapInfo Geocoding Cartridge host loadjava -u _database> -o -v -r -f MapMarkerJServer.jar host loadjava -u _database> -o -v -r -f mapmarker.jar --end of misys.sql Note: In the above lines, MISYS is the default password for the misys account. If you chose a different password, substitute that password for MISYS. 7

11 Chapter 1: Introduction Uninstalling the MapInfo Geocoding Cartridge To uninstall the MapInfo Geocoding Cartridge: Connect to Oracle as system, then enter the following: drop role mm_admin cascade; drop role mm_user cascade; drop user misys cascade; Alternatively, you can execute the uninstall.sql file in the MapInfoGeocodingCartridge2.0\install directory. Running the uninstall.sql script will drop the misys schema and any tables within this schema. 8

12 Chapter 2: Working with the MapInfo Geocoding Cartridge Preparing to Geocode Before you can geocode your records, there are a few things to consider. First you need to define your requirements. Do you need all possible address candidates for your input address? Do you need street number range information? Or do you simply want the latitude/ longitude of what MapMarker thinks is the "best" match? If you want multiple candidates or address range information added to an existing table, you will need to add a column of type misys.geoaddress and copy input address information into the appropriate fields of the geoaddress. For geocoding a table when you do not need to save multiple candidates, you will need to add columns to hold the output information you want returned. This may include candidate street, city, state, postal code, latitude, longitude, postal carrier route, census, etc. When the appropriate columns have been added and the geoaddress column populated (if used), you are ready to geocode. Note: When matching to intersections, if an ampersand character appears in a string literal argument when constructing a geoaddress object, the character must be double quoted (i.e. four single quotes with an ampersand character in the middle) in the string literal. For example, when specifying an intersection in the street attribute, the string literal would be specified as follows: 'jordan rd ' chr(38) 'global view' where chr(38) is equivalent to the ASCII &. Using the MapInfo Geocoding Cartridge Geocoding in the database using the MapInfo Geocoding Cartridge can be done in two ways: geocode a single address or a table of addresses. To geocode single addresses, use the findlocation call of the misys.geoaddress object. Although this call requires a geoaddress object, we include an example of how to call this without adding a geoaddress object to your table. See Geocoding Examples. To geocode an entire table (or a portion selected by a where clause), use the misys.mm_user.geocode_table command. Some versions of geocode_table require a geoaddress object column, others do not.

13 Chapter 2: Working with the MapInfo Geocoding Cartridge Geocoding a Single Address Single addresses are geocoded by using the findlocation call of the misys.geoaddress object. Use of the geoaddress object can be transparent to the user. See the single_fields.sql file under the MapInfoGeocodingCartridge2.0\demo directory for an example of a routine that asks for the information necessary to geocode. Another instance of single address geocoding can be invoked automatically via a trigger when an address is updated or added to a table. Triggers can be set to work with geoaddress columns or the address values in individual columns. Examples of how to perform single geocodes can be found in the MapInfoGeocodingCartridge2.0\demo directory. The following example files geocode single addresses: single_fields.sql, single_geoaddr.sql, trigger_fields.trg and trigger_geoaddr.trg. Geocoding a Table Use the function geocode_table to geocode a table of addresses. Some versions of this function require a geoaddress object column, others do not. The geocode_table functions are defined in the mm_user package. The system administrator or misys account must grant execute permission on the mm_user package to other accounts that will use the geocode_table command. You may return one or more candidates for each record in your table. To return multiple candidates or address range information, your table must contain a column of geoaddress objects. The geoaddress objects should be populated with the input address information. When you invoke the geocode_table command, it will geocode the table and put returned candidates and ranges into the geoaddress objects. When you are interested in returning a single candidate, there are geocode_table calls that do not require a geoaddress object to be added to your table. The results for a single candidate can be placed in the source table or a second table. To make calling easier, we have defined the mm_inputtableinfo and mm_outputtableinfo objects, which you can place in a table to store information for the tables you want to geocode. These calls take the 0-based index of the candidate you wish to return. Most of the time, the returncandidateindex will be 0. 10

14 Chapter 2: Working with the MapInfo Geocoding Cartridge All of the geocode_table forms below take an augmented where clause to be appended to the select statement. To select only a certain state to be geocoded, specify a where clause which includes a table alias, like the following: where geoaddr.countrydivision = NY where: geoaddr = object name of type geoaddress. CountryDivision = attribute of geoaddr object. You may use geocode_table with default preferences, use a preferences name from the MISYS_PREFERENCES table, or create an mm_preferences object to be used for geocoding. The geocode_table functions are described below for each situation. The returncandidateindex parameter in the function signatures shown below is typically set to zero to return the highest ranked candidate. You may set it to a higher number if you desire a lower ranked candidate to be returned. It may not be a number higher than the maxnumcandidates in the misys_preferences table for the preference being used. Using Default Preferences The following call examples use the default geocoding preferences specified in the MISYS_DEFAULT_PREFERENCES table. When using a preference name the name must match exactly one entry in the MISYS_PREFERENCES table. To create and set default preferences, see Managing Geocoding Preferences: function geocode_table(tablename in varchar2, geoaddresscolname in varchar2, whereclause in varchar2) return number; function geocode_table(intableinfo in misys.mm_inputtableinfo, outtableinfo in misys.mm_outputtableinfo, returncandidateindex in number, whereclause in varchar2) return number; Using Preferences from MISYS_PREFERENCES Table The following call examples use the preferences with the given name from the MISYS_PREFERENCES table: function geocode_table(tablename in varchar2, geoaddresscolname in varchar2, PreferenceName in varchar2, whereclause in varchar2) return number; function geocode_table(intableinfo in misys.mm_inputtableinfo, outtableinfo in misys.mm_outputtableinfo, PreferenceName in varchar2, returncandidateindex in number, whereclause in varchar2) return number; 11

15 Chapter 2: Working with the MapInfo Geocoding Cartridge Using the Preferences Object The following calls geocode using the preferences object passed in the third parameter: function geocode_table(tablename in varchar2, geoaddresscolname in varchar2, preferences in misys.mm_preferences, whereclause in varchar2) return number; function geocode_table(intableinfo in misys.mm_inputtableinfo, outtableinfo in misys.mm_outputtableinfo, preferences in misys.mm_preferences, returncandidateindex in number, whereclause in varchar2) return number; Oracle8i Object Types The MapInfo Geocoding Cartridge defines several new Oracle8i object types. These types are used to communicate with the MapMarker J Server, a Java-based implementation for communicating with the MapMarker geocoding engine. Single-record or table geocoding is performed by the geoaddress object, which is also used for storing multiple return candidates or address ranges. The geoaddress object also uses some other defined object types. The candidate type lists a single possible resulting address (including latitude/longitude information) for a geocode request, and the addressrange type gives address range information for a candidate. Two additional types are used. A candidate_set, found in a geoaddress object, is a varray of candidate objects. An addressrange_set, found in a geoaddress object, is a varray of addressrange objects. Information on columns for table geocoding is stored in mm_inputtableinfo and mm_outputtableinfo objects. The mm_preferences type holds geocoding preference information for the geocoding engine. 12

16 Chapter 2: Working with the MapInfo Geocoding Cartridge The Geoaddress Object Type The geoaddress object type defines the attributes and functions required to geocode single addresses. It is also used for table geocoding where you wish to look at address range information or store results for more than one candidate. The address information to be geocoded is placed in the appropriate fields of the geoaddress object, and the findlocation function geocodes the address and populates the candidate_set with the returned candidates. The parts of the geoaddress object are described below. Field Type Description firm varchar2(40) Input: The firm name. street varchar2(40) Input: The street portion of the address. street2 varchar2(40) Input: A second line for street information. This is appended to the first street line by the MapMarker geocoding engine. citysubdivision varchar2(40) Input: The city subdivision. The MapMarker geocoding engine uses this field only for Puerto Rico addresses. city varchar2(40) Input: The city portion of the address. countrydivision varchar2(40) Input: The state, province, or other country division portion of the address. country 1 varchar2(40) Input: The country portion of the address. postalcode varchar2(10) Input: The postal code information for the address. postaladdoncode varchar2(10) Input: The additional postal code information, such as the ZIP+4 Code extension in the U.S. lastline varchar2(80) Input: String containing the unparsed city, countrydivision and postalcode information for the address. language 1 varchar2(40) Input: The language information for the address if an international geocoding engine is used. charset 1 varchar2(40) Input: The charset information for the address if an international geocoding engine is used. numtotalcand number Output: The maximum number of candidates found by the geocoding engine. numreturnedcand number Output: The number of candidates actually returned by the geocoding engine in the candidates array. 13

17 Chapter 2: Working with the MapInfo Geocoding Cartridge Field Type Description numclosecand number Output: The number of close candidates found by the geocoding engine. candidates candidate_set Output: An array of the candidates generated by a findlocation call. ranges addressrange_set Output: An array of all the ranges for the returned candidates. Use the range's candidateindex field to determine which range goes with which candidate. 1 Field is not used by the MapMarker geocoding engine, but may be used by a localized engine. Geoaddress Object Functions and Procedures There are several functions and procedures defined for the geoaddress object: findlocation reads address information from the geoaddress object and populates the candidates with the resulting information. It is available both as a function returning a number representing a return code and a procedure. ScrubAddress is also a function and a procedure returning a misys.geoaddress object. The syntax of the calls is described below. Function findlocation() findlocation(preferencename) findlocation(preference) findlocation() (procedure) Description Returns a new geoaddress object. Geocodes using the default preferences returns an error if there is no default preference or if there are too many rows in the default preference table. Results returned in the calling object. Returns a new geoaddress object. Geocodes using the preference specified returns an error if that preference does not exist or if more than one row in the preference table has that name. Results returned in the calling object. Returns a new geoaddress object. Geocodes using the preference object passed in. Results returned in the calling object. Geocodes using the default preferences returns an error if there is no default preference or if there are too many rows in the default preference table. Results returned in the calling object. 14

18 Chapter 2: Working with the MapInfo Geocoding Cartridge Function findlocation(preferencename) (procedure) findlocation(preference) (procedure) isgeocoded() getlatitude(candidateindex in number default 1) getlongitude(candidateindex in number default 1) getoraclespatialobject (candidateindex in number default 1) 1 getoraclespatialobject (candidate index, SRID) getnumcandidates() getnumrangesforcandidate (candidateindex in number default 1) scrubaddress(candidateindex in number default 1) scrubaddress(candidateindex in number default 1) Description Geocodes using the preference specified returns an error if that preference does not exist or if more than one row in the preference table has that name. Results returned in the calling object. Geocodes using the preference object passed in. Results returned in the calling object. Returns 1 if the geoaddress candidates array contains any candidates, otherwise returns 0. Returns the latitude of the candidate at the given index. Returns the longitude of the candidate at the given index. Returns the mdsys.sdo_geometry object containing longitude and latitude information for the candidate at the given index. This will not update the SDO_GEOMETRY with SRID value when user is using the findlocation on a user created SDO_GEOMETRY column (SRID will be null). The same as above, but the input SRID will be used to create the object. Returns the number of candidates in the geoaddress object. Returns the number of address ranges for the candidate at the given index. Replaces the input geoaddress information with the address information from the candidate at the given index. Extreme care should be used when calling this function because it modifies the original address information. Allows you to replace the input information with the information of candidate x. If the candidate index is out of bounds or the geoaddress object has not been geocoded an error will be raised. 1 When you create a table that contains a MDSYS.SDO_GEOMETRY object, you should insert a row into the USER_SDO_GEOM_METADATA or SDO_GEOM_METADATA (depending on which version you are using) describing the table, column, SRID, and DIM_INFO for those objects. 15

19 Chapter 2: Working with the MapInfo Geocoding Cartridge The Candidate Object Type The candidate object type is used to return a geocoded address. A geocode request may result in a number of possible candidates, ordered from best to worst match. The parts of a candidate object are as follows. Field Type Description firm varchar2(40) The firm name. street varchar2(40) The street portion of the address. street2 1 varchar2(40) Not used by the MapMarker geocoding engine. However, this may be used by a different geocoding engine to return international street address information. citysubdivision varchar2(40) The city subdivision. The MapMarker geocoding engine uses this field only for Puerto Rico addresses. city varchar2(40) The city portion of the address. countrydivision varchar2(40) The state, province, or other country division portion of the address. country 1 varchar2(40) The country portion of the address. postalcode varchar2(10) The postal code information for the address. postaladdoncode varchar2(10) The additional postal code information, such as the ZIP+4 Code extension in the US. resultcode varchar2(12) The geocoding result code that describes this candidate's match status. censusblock varchar2(40) The Census block tabulation number. deliverypoint varchar2(40) The delivery point number. checkdigit varchar2(10) The check digit. lacs varchar2(5) The USPS LACS code. carrierroute varchar2(10) The carrier route number. language 1 varchar2(40) The language information for the address if an international geocoding engine is used. charset 1 varchar2(40) The charset information for the address, if an international geocoding engine is used. longitude number The longitude of the candidate address. latitude number The latitude of the candidate address. precision number The precision of the candidate address. score number The score of the candidate address. rangecount number Number of address ranges for the candidate address. 1 Field is not used by the MapMarker geocoding engine, but may be used by a localized engine. 16

20 Chapter 2: Working with the MapInfo Geocoding Cartridge The addressrange Object Type The addressrange lists the street house ranges for a match candidate. The parts of an addressrange object are described below: Field Type Description candidateindex number The index of the candidate associated with this range. houseparity number The house number parity for the range. 0 = odd, 1 = even, 2 = any. fromhouse varchar2(40) The beginning house number for the range. tohouse varchar2(40) The final house number for the range. unittype varchar2(40) A description of the unit (e.g., "Apt"). fromunit varchar2(40) The beginning unit for the range. tounit varchar2(40) The final unit for the range. postalcode varchar2(40) The postal code information for the range. postaladdoncode varchar2(40) The additional postal code information for the range. placename varchar2(40) Certain ranges may specify a place or firm name. lacs varchar2(40) Location Address Conversion System indicator. "L" indicates that records can be converted to the LACS system, using a product available from the U.S. Postal Service. carrroute varchar2(40) The postal carrier route for the range. 17

21 Chapter 2: Working with the MapInfo Geocoding Cartridge The mm_inputtableinfo Object The mm_inputtableinfo object serves as a pointer to address information stored in a given address. For each of the fields, specify the name of the column used to hold that value for the table or null if there is no column for that value. All the named columns should contain character data. Field Type Description intablename varchar2(32) Unique identifier naming the table that is described. intooutprimarykeycolname varchar2(32) Name of the column that contains values mapping to the correct row in the output table, such as an index or id number column. If the output is written to the same table, you may use "rowid". infirmcolname varchar2(32) Name of the column containing the input firm name. instreetcolname varchar2(32) Name of the column containing the first row of street address information. instreet2colname varchar2(32) Name of the column containing the second row of street address information. incitysubdivisioncolname varchar2(32) Name of the column containing city subdivision information. In the U.S., city subdivision is only used for Puerto Rican addresses (urbanization areas). incitycolname varchar2(32) Name of the column containing the city name. incountrydivisioncolname varchar2(32) Name of the column containing the state or province name. incountrycolname 1 varchar2(32) Name of the column containing the country name. inpostalcodecolname varchar2(32) Name of the column containing the postal code. inpostaladdoncodecolname varchar2(32) Name of the column containing additional postal code information, such as the ZIP+4 Code extension used in the U.S. inlastlinecolname varchar2(32) Name of the column containing unparsed city, state/province, and postal information. inlanguagecolname 1 varchar2(32) Name of the column containing the language for the address. incharsetcolname 1 varchar2(32) Name of the column containing the character set used for the address. 1 Field is not used by the MapMarker geocoding engine, but may be used by a localized engine. 18

22 Chapter 2: Working with the MapInfo Geocoding Cartridge The mm_outputtableinfo Object The mm_outputtableinfo object stores information that defines where the output from the geocoding request should be placed. The attributes of the mm_outputtableinfo object are defined below, along with the suggested column type and minimum size for the output table, where appropriate. All attributes of the mm_outputtableinfo object are String types. Field Type Description outtablename varchar2(32) Unique identifier for the table. outprimarykeycolname varchar2(32) Name of the column that contains values mapping to the correct row in the output table, such as an index or id number column. If the output is written to the same table, you may use "rowid". outfirmcolname varchar2(32) Name of the column to write the output firm name. outstreetcolname varchar2(32) Name of the column to write the first line of the output street address. outstreet2colname 1 varchar2(32) Name of the column to write the second line of the output street address. outcitysubdivisioncolname varchar2(32) Name of the column to write the output city subdivision information. In the U.S., city subdivision is only used for Puerto Rican addresses. outcitycolname varchar2(32) Name of the column to write the output city name. outcountrydivisioncolname varchar2(32) Name of the column to write the output state or province name. outcountrycolname 1 varchar2(32) Name of the column to write the output country name. outpostalcodecolname varchar2(32) Name of the column to write the output postal code. outpostaladdoncodecolname varchar2(32) Name of the column to write the additional output postal code information, such as the ZIP+4 Code extension used in the U.S. outresultcodecolname varchar2(32) Name of the column to write the geocoding result code. 19

23 Chapter 2: Working with the MapInfo Geocoding Cartridge Field Type Description outcensusblockcolname varchar2(32) Name of the column to write the census block of the geocoded address. outdeliverypointcolname varchar2(32) Name of the column to write the delivery point of the geocoded address. outcheckdigitcolname varchar2(32) Name of the column to write the check digit of the geocoded address. outlacscolname varchar2(32) Name of the column to write USPS LACS information for the geocoded address. outcarrierroutecolname varchar2(32) Name of the column to write carrier route for the geocoded address. outlanguagecolname 1 varchar2(32) Name of the column to write the language of the geocoded address. outcharsetcolname 1 varchar2(32) Name of the column to write the character set of the geocoded address. outlongitudecolname varchar2(32) Name of the column to write the longitude of the geocoded address. outlatitudecolname varchar2(32) Name of the column to write the latitude of the geocoded address. outspatialobjectcolname varchar2(32) Name of the spatial column to write the latitude and longitude of the geocoded address. outprecisioncolname varchar2(32) Name of the column to write the precision of the geocoded address. outscorecolname varchar2(32) Name of the column to write the score of the geocoded address. outbclosecolname varchar2(32) Name of the column to write whether the geocoded address was considered a close match or not. 1 Field is not used by the MapMarker geocoding engine, but may be used by a localized engine. 20

24 Chapter 2: Working with the MapInfo Geocoding Cartridge The mm_preferences Object Type The mm_preferences object type is used to define how a geocode request is handled. Different preferences can be created to match different geocoding needs. To modify the default settings in the MapInfo Geocoding Cartridge, create or modify a preferences object in the misys_preferences table, and then use mm_admin.set_default_preference to make that preference the single entry in the misys_default_preferences table. Other preferences may be stored in the misys_preferences table and passed to the geocoding engine when the row is being geocoded. The parts of an mm_preferences object are as follows. Field Type Description preferencename varchar2(30) A unique identifier for the preferences. serialnumber varchar2(20) The serial number for the MapMarker J Server if it has been started in restricted mode. clientid varchar2(20) The clientid for the MapInfo Geocoding Cartridge. httpserverurl varchar2(80) If the MapMarker J Server is running as a servlet, the http address of the servlet, otherwise null. If it is not null, it is assumed to be the correct server. tcpserverhostid varchar2(30) If the MapMarker J Server is running via a TCP/IP connection, the host name or IP address of the machine where the MapMarker J Server is located. tcpserverportid varchar2(8) For a TCP/IP connection, the port ID where the MapMarker J Server is running. exactmatchhousenumber char(1) T to require exact match on house number. T=True, F=False. exactmatchstreetname char(1) T to require exact match on street name. T=True, F=False. exactmatchpostalcode char(1) T to require exact match on postal code. T=True, F=False. matchintersections char(1) T to attempt street intersection matching on input addresses. T=True, F=False. usecassmode char(1) T to use the USPS CASS standards when geocoding. Overrides other preference settings. T=True, F=False. expandsearch char(1) T to expand the search area for finding candidates. T=True, F=False. limitexpandedsearch char(1) T to restrict the candidates returned by the expanded search to the current countrydivision. T=True, F=False. expandradius number(4) The radius of the expanded search in miles. (0-99) 21

25 Chapter 2: Working with the MapInfo Geocoding Cartridge Field Type Description distunit number(4) The distance unit used for the linearoffset andperpendicularsetback: 0 = foot; 1=degree; 2=inch; 3=link; 4=survey foot; 5=yard; 6=rod; 7=chain; 8=mile; 9=nautical mile; 10=millimeter; 11=centimeter; 12=meter; 13=kilometer. linearoffset number(12) The position of the geocoded point with respect to the corner. Default is 25. perpendicularsetback number(12) The position of the geocoded point with respect to the center line of the street. Default is 20. miscprefstring 1 varchar2(80) Provides additional preference information when a non-u.s. geocoding engine is used for international addresses. maxnumcandidates number(8) The maximum number of candidates to return for a geocode request. Warning: No candidates will be returned if this attribute is set to null when constructing a mm_preferences object. maxnumrangespercandidate number(8) The maximum number of address ranges to return for each candidate. returnclosecandidatesonly char(1) T indicates that only close match candidates will be returned, F means return all candidates. T=True, F=False. returnfirm 2 char(1) T indicates that the candidate firm name will be returned. T=True, F=False. returnstreets 2 char(1) T indicates that the candidate street address (and street2 if localized) information will be returned. T=True, F=False. returnlastlineinfo 2 char(1) T indicates that the candidate city subdivision, city, state and postal code (and postal code add-on if localized) will be returned. T=True, F=False. returnpostalinfo 2 char(1) T indicates that the candidate carrier route, check digit, LACS status and delivery point will be returned. T=True, F=False. returncensus 2 char(1) T indicates that the candidate census block information will be returned. T=True, F=False. batchcount number(4) The number of geocode requests to group together when geocoding a table. Since returned information can be lengthy, it is recommended that your batch size be below 30. Also used as the number of addresses to geocode per transaction. 1 Field is not used by the MapMarker geocoding engine, but may be used by a localized engine. 2 When these preferences are turned off (set to False), the candidates will only show latitude, longitude, result code, precision, score and number of ranges, and language and charset if localized. 22

26 Chapter 2: Working with the MapInfo Geocoding Cartridge Managing Geocoding Preferences The MapInfo Geocoding Cartridge is set to use the same defaults as MapMarker, including a required exact match to house number, relaxed match to street name, and postal code. However, these settings may be modified for your needs. To change these settings, use the functions in the mm_admin package. The system administrator or misys account may grant execute permission on this package to other accounts as needed. Preferences are stored in the misys_preferences table. The misys_default_preferences table contains one entry, a pointer to the mm_preferences object in misys_preferences which is to be used for default geocoding preferences. Whenever the Cartridge is invoked without a preference name or a preference object, the default preference is used. The other use of the misys_default_preferences table is for using misys.mm_admin.create_preference. All fields that are passed or null to this procedure will get their value from the preference identified as the default preference. To determine which preference is the default the user can run misys.mm_admin.get_default_preference_name. This prints the preference name of the default preference. The syntax for setting up preferences is as follows. The preference name is used as the index in the misys_preference table. The serialnumber, clientid, HTTP, and TCP/IP connection information describes the connection to the MapMarker J Server. The BatchCount is used as the commit interval when using the geocode_table functions as well as how many addresses to send in a batch to the MapMarker J Server. The remaining parameters are settings of the geocoding engine. See the mm_preferences object for a description of these settings. 23

27 Chapter 2: Working with the MapInfo Geocoding Cartridge procedure create_preferences(preferencename varchar2, serialnumber varchar2 default null, clientid varchar2 default null, httpserverurl varchar2 default null, tcpserverhostid varchar2 default null, tcpserverportid varchar2 default null, exactmatchhousenumber char default null, exactmatchstreetname char default null, exactmatchpostalcode char default null, matchintersections char default null, usecassmode char default null, expandsearch char default null, limitexpandedsearch char default null, expandradius number default null, distunit number default null, linearoffset number default null, perpendicularsetback number default null, miscprefstring varchar2 default null, maxnumcandidates number default null, maxnumrangespercandidate number default null, returnclosecandidatesonly char default null, returnfirm char default null, returnstreets char default null, returnlastlineinfo char default null, returnpostalinfo char default null, returncensus char default null, batchcount number default null); To create the default preferences, an mm_admin procedure sets an object in the misys_preferences table to be the sole entry in the misys_default_preferences table. You invoke this procedure giving it the preference name of the preferences to be set as default. procedure set_default_preferences(preferencename in varchar2); Use the following procedure to print out the name of the preference that is currently the default preference. get_default_preference_name Create an entry in the misys.misys.server_properties table for the httpserverurl with this SRID. If the httpserverurl already exists it will print out an error message. This is only used in Oracle and above. add_new_http_server(httpurl, serversrid) Create an entry in the misys.misys_server_properties table for the given host, port, and SRID. If the host and port combination are already in the table, an error message will be printed out. add_new_tcp_server(inputtcpserverhostid, InputTcpServerPostId, InputrSRID) To print the the current version, use the following procedure: print_version 24

28 Chapter 2: Working with the MapInfo Geocoding Cartridge Result Codes Defined MapMarker returns a result code for every address it attempts to match. The code represents whether a match was made, the type of match it is, and conveys information about the quality of the match. The result code for geocoded addresses may be found in candidate object attribute of the geoaddress object, or columns specified in the mm_outtableinfo object. The result code is an alphanumeric code of 1-10 characters. They fall into three categories: Single close match to street level (S category) Postal Code centroid match (Z category) Non-matches (N category) For S and Z categories, the first two characters represent the positional accuracy of the match, i.e., where the point for the record would spot on a street map. For the S category matches there are an additional 8 characters that define the precision with which MapMarker matched to the individual components in the input address. If MapMarker did not match on a particular address component, the code would contain a dash. For example, a single close match to a street address that matched to all address components except house number would look like: S5-PNTSCZA. S Category: Single Close Match to Street Level S5 S4 S3 S2 S1 SX S0 matched to a street address matched to an interpolated point on the street segment matched to a ZIP+4 centroid (centerpoint of the ZIP+4 boundary) matched to a ZIP+2 centroid (centerpoint of the ZIP+2 boundary) matched to a ZIP Code centroid (centerpoint of the ZIP Code boundary) matched to a street intersection single close match, no coordinates available Eight Additional Precision Characters: H P matched to house number matched to street prefix 25

29 Chapter 2: Working with the MapInfo Geocoding Cartridge N T S C Z A or U matched to street name matched to street type matched to street suffix matched to city name matched to ZIP Code match came from MapMarker Address Dictionary (A) or customized user dictionary (U) N Category: Non-matches N No close match Geocoding Examples To learn how to geocode to MapMarker using the MapInfo Geocoding Cartridge, look at the demos in the MapInfoGeocodingCartridge2.0\demo directory for example SQL scripts. To run them, log in as MISYS. They include: set_preferences.sql: demonstrates how to create geocoding preferences and set them as defaults. single_fields.sql: demonstrates how to geocode a single address when you do not have a geoaddress object. single_geoaddr.sql: demonstrates how to geocode a single address in a geoaddress object. table_fields.sql/table_fields815.sql: demonstrates how to geocode a table when address information is not contained in geoaddress objects. For Oracle 8.1.5, use table_fields815.sql. table_geoaddr.sql: demonstrates how to geocode a table when address information is contained in a geoaddress object. It also shows how to create a new preferences object to use during the geocode. trigger_fields.trg: demonstrates how to geocode a new or updated record when you do not have a geoaddress column. trigger_geoaddr.trg: demonstrates how to add a trigger to a table that invokes a geocoding request when the information geoaddress column changes. 26