Envinsa. Version 4.4 USER DICTIONARY GUIDE

Transcription

1 Envinsa Version 4.4 USER DICTIONARY GUIDE

2 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 Pitney Bowes Software Inc. All rights reserved. MapInfo, the MapInfo logo and Envinsa are trademarks of Pitney Bowes Software Inc. and/or its affiliates. Corporate Headquarters: Phone: Fax: Sales: Government Sales: Technical Support: UK and EMEA Headquarters: Phone: Fax: Technical Support: Asia Pacific Headquarters: Phone: Fax: Technical Support: Contact information for all offices is located at: 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. February 5, 2010

3 Table of Contents Chapter 1: Installing the Utility What is a User Dictionary? Downloading and Installing the User Dictionary Utility Chapter 2: Creating and Using Dictionaries Source Data Requirements Generate a User Dictionary Create the User Dictionary Descriptive File Integrate your User Dictionary with the Location Utility Service Configure Default Dictionaries Using User Dictionaries in Envinsa Address Point Interpolation Batch Geocoding Location Utility Service (XML) Specifying Dictionary Usage Disabling User Dictionaries Java SDK Specifying Dictionary Usage Disabling User Dictionaries NET SDK Specifying Dictionary Usage Disabling User Dictionaries Chapter 3: User Dictionary Requirements User Dictionaries Requirements Point of Interest (POI) Geocoding in User Dictionaries Source Table Data For User Dictionaries User Dictionary Fields by Country United States Optional (Recommended) Input Fields Canada Optional Input Fields Germany Australia

4 Optional (Recommended) Input Columns Envinsa 4.4

5 Installing the Utility 1 Pitney Bowes MapInfo provides a 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. In this section: What is a User Dictionary? Downloading and Installing the User Dictionary Utility

6 Downloading and Installing the User Dictionary Utility What is a User Dictionary? A User Dictionary is a custom table of streets and address ranges that you match ungeocoded records against. If you have custom, newer, or more precise data than what is available in the Address Dictionary that ships with Envinsa geocoding services, creating a User Dictionary with this data can help you achieve more accurate geocoding results. For example, if you have address point data you can create a dictionary with it that enables you to take advantage of the address point interpolation capabilities. You can configure Envinsa to choose the dictionaries you want to use. You may choose to geocode with the provided Address Dictionary and one or more User Dictionaries, or you may decide that you want to use your User Dictionaries only. The format of a User Dictionary is similar to that of the Address Dictionary. The only difference appears in the georesult code. A candidate from a User Dictionary has a U at the end of the georesult code. A candidate that comes from the Address Dictionary has an A at the end of the georesult code. A User Dictionary is made up of a stand-alone group of files, which means that it can be used by itself to geocode records against. It is not dependent on the Address Dictionary for use, but you can use it with the Address Dictionary when you geocode. Note: While you can use a User Dictionary independently, you must have an Address Dictionary in order to create a User Dictionary. This is because the Address Dictionary has some internal structures that must be available when you are creating a User Dictionary. Downloading and Installing the User Dictionary Utility The MapInfo User Dictionary Utility is an easy-to-use utility that simplifies the steps for creating, configuring, and deploying User Dictionaries. The tool can be downloaded from Follow the instructions to download the MapInfo User Dictionary Utility to your Envinsa installation. 1. Begin the installation procedure as follows, depending on whether you are installing on Windows or on UNIX/Linux: On Microsoft Windows, run the install.exe program that you downloaded. On Solaris, Linux, or HP-UX, run the command: sh install.bin Note: If the installer does not start or exits unexpectedly, it means that the installer could not find a valid JVM. In that case, run the installer with one of the following commands to manually specify the JVM. install.exe LAX_VM "C:\JavaHome\bin\java.exe" Or: sh install.bin LAX_VM /JavaHome/bin/java where JavaHome is the directory of the JVM to be used to run the installer. This JVM must be version or greater. 6 Envinsa 4.4

7 2. In the Introduction dialog, click Next to display the License Agreement dialog. Chapter 1: Installing the Utility 3. After reading the License Agreement, click I accept the terms of the License Agreement, and then click Next to display the Select Geocoding Directory dialog. 4. In the Select Geocoding Directory dialog, specify your existing Envinsa Data Domain directory. The default data domain for Envinsa 4.1 and later is C:\Program Files\DataDomain and for 4.0 it is C:\Program Files\Envinsa-4.0\DataDomain. Click Next to continue. 5. In the Choose Geocoding Installations dialog, you will see a list of paths pointing to country specific geocode instances. These paths represent the installed Envinsa countries for which you can build User Dictionaries. From the list, select the countries for which you want to create User Dictionaries using this instance of the User Dictionary Utility. After making the path selections, click Next to continue. User Dictionary Guide 7

8 Downloading and Installing the User Dictionary Utility 6. In the Product Instance Name dialog, type an Instance Name. This name will be used to uniquely identify this instance of the MapInfo User Dictionary Utility (on the Start menu or Desktop shortcut). After typing the instance name, click Next to continue. 7. In the Choose Install Folder dialog, select the directory in which the MapInfo User Dictionary Utility will be installed. Typically, the default directory might be C:\Program Files\MapInfo\User Dictionary Utility. Either accept the default directory or click Choose to navigate to an alternative directory. Click Next to continue. 8 Envinsa 4.4

9 Chapter 1: Installing the Utility 8. In the Choose Java Virtual Machine dialog, do one of the following: Select one of the already installed JVMs (version or later) to be used by the MapInfo User Dictionary Utility. Select Choose Another to navigate to an alternative location of a JVM on your computer. Choose a JVM associated with a Envinsa installation that you plan to use with the MapInfo User Dictionary Utility. Select Search for Others to have the installer search your computer for an installed JVM. As the search progresses, the dialog will be populated with a list of the JVMs that were found on your computer. This may take some time. The Choose Java Virtual Machine dialog appears as follows: After selecting a JVM, Click Next to continue. 9. 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 selections, click Next to continue. 10. 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 previous dialogs. When you are satisfied with your installation choices, click Install. A progress dialog reports progress as the software and data are installing. 11. When the installation is finished, the Install Complete message appears. Click Done to exit the installer. Once the Utility is installed, you can create user dictionaries and use them to perform custom geocoding. See Chapter 2: Creating and Using Dictionaries for more information. User Dictionary Guide 9

10 Downloading and Installing the User Dictionary Utility 10 Envinsa 4.4

11 Creating and Using Dictionaries 2 Once you have installed the User Dictionary Utility, you can prepare your source data and use the Utility to automate the User Dictionary creation process. In this section: Source Data Requirements Generate a User Dictionary Create the User Dictionary Descriptive File Integrate your User Dictionary with the Location Utility Service 15 Configure Default Dictionaries Using User Dictionaries in Envinsa

12 Generate a User Dictionary Source Data Requirements To create a User Dictionary, your source data must adhere to the following requirements: The source data must be in the form of a MapInfo table (.tab). Each row in the table is equivalent to a street segment. Segments that make up intersections must have one or more endpoints in the intersection to recognize it as an intersection. The MapInfo table must contain specific fields (other fields are optional), which are used to convert the table into the dictionary format. This table structure varies for each country. For more information about table structures and requirements, see Chapter 3: User Dictionary Requirements. Generate a User Dictionary 1. Start the MapInfo User Dictionary Utility. Select the Instance Name that you created in step 6 of the utility installation procedure. 2. In the MapInfo User Dictionary Utility, select a country from the Country drop-down list. This will be one of the countries you selected in step 5 of the utility installation procedure. 3. Select the input table for the User Dictionary. Choose the country geocode instance that will use the User Dictionary. Select the Address Dictionary File by browsing to the Address Dictionary file for the selected country. The Address Dictionary file will have a *.mmj extension and is located in the country specific data folder. For example, the US geocode Address Dictionary is located in the \<Data_Domain>\US\GeocodeUS\data\ directory. Choose the Table (*.tab) that contains the source data for your User Dictionary. Click Next to continue. 12 Envinsa 4.4

13 Chapter 2: Creating and Using Dictionaries 4. Select the required columns. Note: The specific field labels and details will vary for different countries. See Chapter 3: User Dictionary Requirements for information on the.tab file requirements for custom user data. Click Next to continue. 5. Select the optional columns. Since these are optional fields, you do not have to specify them. Click Next to continue. 6. Specify a unique output directory and file name for the User Dictionary that you are creating. You must specify an empty directory. The default file name for the User Dictionary is cty_custom1.jdr, User Dictionary Guide 13

14 Create the User Dictionary Descriptive File where cty is the three-letter country code. For example, the file name for the Netherlands User Dictionary would be nld_custom1.jdr. Note: Remember the name and location of your User Dictionary. This information will be required for integrating your User Dictionary with Envinsa. Click Finish to create the User Dictionary. 7. The UD Creation Complete dialog displays a log file that summarizes processing and lists all the created files. If any errors occurred, these will be indicated in the Error File area of the dialog. 8. Click Exit to exit the MapInfo User Dictionary Utility. After successfully creating the User Dictionary, the specified directory will contain 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. Note: At any time, you can click System Information for a summary of system-related information on the MapInfo User Dictionary Utility. This identifies the JVM used by the geocoding engine, and other system details. Create the User Dictionary Descriptive File A descriptive name must be given to the new User Dictionary for Envinsa to process requests to the dictionary. To give the dictionary a descriptive name: 1. Create a new file named dictionarydesc.txt in the directory where the new User Dictionary was created. This directory should contain the *.jdr file. Note: The file name dictionarydesc.txt must be all lower case. 2. Open the dictionarydesc.txt file and add a descriptive name for the new User Dictionary. The descriptive name must not contain any spaces. However, underscores are allowed. For example, envinsa_ud_new_2008 is a valid descriptive name. 3. Save the file. You must now integrate the User Dictionary with the Envinsa Location Utility Service. 14 Envinsa 4.4

15 Chapter 2: Creating and Using Dictionaries Integrate your User Dictionary with the Location Utility Service Each UD that gets created is associated with a single country. The user will have to locate the appropriate country specific DataManagerSettings.properties file. Following standard Envinsa directory structure, the file should be found in <path to DataDomain>/CC/GeocodeCC where CC represents the country code (i.e. US). For example, E:\Envinsa-4.3\DataDomain\US\GeocodeUS. Configure the geocode component to use the new User Dictionary by doing the following: 1. Open <DataDomain>/US/GeocodeUS/USA_DataManagerSettings.properties in a text editor. If the file does not exist, then look for it in the directory where you installed the GeocodeUS component. 2. Add an DICTIONARY_PATHx additional line for each User Dictionary you want to use. Each DICTIONARY_PATHx name-value pair must have a unique name, and point to the directory where you created your User Dictionary (*.jdr) in step 6. To ensure this, increase the number at the end of DICTIONARY_PATHx by one every time you add a new line. The order of these dictionaries determine the order of precedence for the geocoders. For example, to add two user dictionaries, then you would add the following lines to the file: DICTIONARY_PATH2=D:/DataDomain/US/CustomUD/firstdictionary DICTIONARY_PATH3=D:/DataDomain/US/CustomUD/seconddictionary 3. Increase the DICTIONARY_COUNT value to match the number of DICTIONARY_PATHx lines in the file. For example, if file currently has DICTIONARY_COUNT=1 and you added two paths, then change the line to: DICTIONARY_COUNT=3 4. Save your changes to the configuration file and close the text editor. 5. Start the application server instance where the Location Utility service runs. Your geocoding requests can now use the User Dictionary. Configure Default Dictionaries After creating and integrating a User Dictionary, the Envinsa geocoder will use both the Address Dictionary and the User Dictionaries for geocode requests. To change this default: 1. Start Enterprise Manager. By default, Enterprise Manager is installed at /<Envinsa_Home>/ Tools/EnterpriseManager. For more information, see the Envinsa Administration Guide. 2. Select the LocationUtility service from the main grid. 3. Right-click on the LocationUtility service in the main grid and then select Services > Registration > Parameter Settings. User Dictionary Guide 15

16 Using User Dictionaries in Envinsa 4. In the parameter Settings list, expand LocationUtilityService > Geocode > Global > Preferences > Geocode. 5. On the right side of the window, double-click on dictionaryusage. This opens the Modify Property dialog for the dictionaryusage property. 6. In the dialog, select the default dictionary use you want to use. The choices are: AD_AND_UD: Uses the Address Dictionary and User Dictionaries. AD_ONLY: Uses only the Address Dictionary. This option guarantees that you will not use any User Dictionaries for your geocoding request. PREFER_AD: Uses all available dictionaries, but gives precedence to the Address Dictionary, regardless of how the dictionary precedence was configured when the User Dictionaries were installed. PREFER_UD: Uses all available dictionaries, but gives precedence to User Dictionaries, regardless of how the dictionary precedence was configured. UD_ONLY: Uses only User Dictionaries. 7. Click OK to save you choice and then the Home button to return to the main Enterprise Manager screen. 8. Stop and then start your application server instance where the Location Utility Service runs. All geocode requests using the Location Utility Service will now use the dictionary usage you selected. Application developers can still override this value, if necessary. Using User Dictionaries in Envinsa User Dictionaries can be used with the following Envinsa geocoding methods: Address Point Interpolation Batch Geocoding Location Utility Service (XML) Java SDK.NET SDK 16 Envinsa 4.4

17 Chapter 2: Creating and Using Dictionaries Address Point Interpolation If your User Dictionary contains address point data, you can enable Address Point Interpolation. For more information on this feature, see the Envinsa Location Utility Service Reference or Batch Geocoding Guide at Batch Geocoding To ensure the geocode requests use installed User Dictionaries select one of the following options from the Dictionary Usage list under the Dictionary tab: AD_AND_UD: Uses the Address Dictionary and User Dictionaries. AD_ONLY: Uses only the Address Dictionary. This option guarantees that you will not use any User Dictionaries for your geocoding request. PREFER_AD: Uses all available dictionaries, but gives precedence to the Address Dictionary, regardless of how the dictionary precedence was configured when the User Dictionaries were installed. PREFER_UD: Uses all available dictionaries, but gives precedence to User Dictionaries, regardless of how the dictionary precedence was configured. UD_ONLY: Uses only User Dictionaries. For more information on batch geocoding and the steps you must perform, see the Envinsa Batch Geocoding Guide. Location Utility Service (XML) The following sections describe Location Utility Service User Dictionary requests. For more information on these features and the service in general, see the Envinsa Location Utility Service Reference at reference.mapinfo.com/envinsa. Specifying Dictionary Usage To send a geocode request using XML, the GeocodeRequestTypeEx type must be used. You can specify the DictionaryUsage element as one of the following values: AD_AND_UD: Uses the Address Dictionary and User Dictionaries. AD_ONLY: Uses only the Address Dictionary. This option guarantees that you will not use any User Dictionaries for your geocoding request. User Dictionary Guide 17

18 Using User Dictionaries in Envinsa PREFER_AD: Uses all available dictionaries, but gives precedence to the Address Dictionary, regardless of how the dictionary precedence was configured when the User Dictionaries were installed. PREFER_UD: Uses all available dictionaries, but gives precedence to User Dictionaries, regardless of how the dictionary precedence was configured. UD_ONLY: Uses only User Dictionaries. By default, Envinsa uses AD_AND_UD for geocoding requests. However, your Envinsa administrator may disable this behavior. To guarantee your geocode requests use the installed user dictionaries you should specify a DictionaryUsage element. The following example shows how you can specify that you want to use both the Address Dictionary and User Dictionaries to geocode an address: <_RequestParameters xsi:type="ns3:geocoderequesttypeex" xmlns:ns3=" <Address countrycode="usa"> <StreetAddress> <Street>609 Myrtle Ave</Street> </StreetAddress> <Place type="countrysubdivision">ny</place> <Place type="municipality">albany</place> </Address> <ns3:geocodepreference type="closematchesonly">false</ns3:geocodepreference> <ns3:geocodepreference type="useaddresspointinterpolation"> true</ns3:geocodepreference> <ns3:dictionaryusage>ad_and_ud</ns3:dictionaryusage> </_RequestParameters> Disabling User Dictionaries If you have multiple user dictionaries and want to disable one or more for a geocode request, then change the isdictionaryavailableforsearch attribute to false for that request. You can retrieve a full list of available dictionaries with a GetCapabilities request. See the Envinsa Location Utility Service Reference for more information on this feature. The following example shows how you can disable the default address dictionary and parcel center location (CL) user dictionaries from a request. This geocodes the address using the parcel street location (SL) user dictionaries. <_RequestParameters xsi:type="ns3:geocoderequesttypeex" xmlns:ns3=" <Address countrycode="usa"> <StreetAddress> <_StreetLocation xsi:type="ns2:buildinglocatortype" number="1"/> <Street>Global View</Street> </StreetAddress> <Place type="countrysubdivision">ny</place> <Place type="municipality">troy</place> <PostalCode> </PostalCode> </Address> <ns3:dictionary index="1" isdictionaryavailableforsearch="false" isuserdictionary="false" searchorder="1">address dictionary: MAPMARKER_US_ENTIRE_2007_7</ns3:Dictionary> <ns3:dictionary index="2" isdictionaryavailableforsearch="false" isuserdictionary="true" 18 Envinsa 4.4

19 Chapter 2: Creating and Using Dictionaries searchorder="2">user dictionary: ParcelPrecision_US_CENTR_CL_2007_4</ ns3:dictionary> <ns3:dictionary index="3" isdictionaryavailableforsearch="false" isuserdictionary="true" searchorder="3">user dictionary: ParcelPrecision_US_MWEST_CL_2007_4</ ns3:dictionary> <ns3:dictionary index="4" isdictionaryavailableforsearch="false" isuserdictionary="true" searchorder="4">user dictionary: ParcelPrecision_US_NEAST_CL_2007_4</ ns3:dictionary> <ns3:dictionary index="5" isdictionaryavailableforsearch="false" isuserdictionary="true" searchorder="5">user dictionary: ParcelPrecision_US_PACIF_CL_2007_4</ ns3:dictionary> <ns3:dictionary index="6" isdictionaryavailableforsearch="false" isuserdictionary="true" searchorder="6">user dictionary: ParcelPrecision_US_SEAST_CL_2007_4</ ns3:dictionary> <ns3:dictionary index="7" isdictionaryavailableforsearch="false" isuserdictionary="true" searchorder="7">user dictionary: ParcelPrecision_US_SOUTH_CL_2007_4</ ns3:dictionary> <ns3:dictionary index="8" isdictionaryavailableforsearch="true" isuserdictionary="true" searchorder="8">user dictionary: ParcelPrecision_US_CENTR_SL_2007_4</ ns3:dictionary> <ns3:dictionary index="9" isdictionaryavailableforsearch="true" isuserdictionary="true" searchorder="9">user dictionary: ParcelPrecision_US_MWEST_SL_2007_4</ ns3:dictionary> <ns3:dictionary index="10" isdictionaryavailableforsearch="true" isuserdictionary="true" searchorder="10">user dictionary: ParcelPrecision_US_NEAST_SL_2007_4</ ns3:dictionary> <ns3:dictionary index="11" isdictionaryavailableforsearch="true" isuserdictionary="true" searchorder="11">user dictionary: ParcelPrecision_US_PACIF_SL_2007_4</ ns3:dictionary> <ns3:dictionary index="12" isdictionaryavailableforsearch="true" isuserdictionary="true" searchorder="12">user dictionary: ParcelPrecision_US_SEAST_SL_2007_4</ ns3:dictionary> <ns3:dictionary index="13" isdictionaryavailableforsearch="true" isuserdictionary="true" searchorder="13">user dictionary: ParcelPrecision_US_SOUTH_SL_2007_4</ ns3:dictionary> <ns3:geocodepreference type="closematchesonly">true</ns3:geocodepreference> <ns3:geocodepreference type="maxranges">10</ns3:geocodepreference> </_RequestParameters> Java SDK The following sections describe Location Utility SDK User Dictionary requests. For more information on these features and the service in general, see the Java API Reference (Javadoc) at reference.mapinfo.com/envinsa. User Dictionary Guide 19

20 Using User Dictionaries in Envinsa Specifying Dictionary Usage To send a geocode request using the Java SDK, you must use the GeocodeRequest object. You can specify the DictionaryUsage element as one of the following DictionaryUsagePreference values: DICTIONARY_AD_AND_UD: Uses the Address Dictionary and User Dictionaries. DICTIONARY_AD_ONLY: Uses only the Address Dictionary. This option guarantees that you will not use any User Dictionaries for your geocoding request. DICTIONARY_PREFER_AD: Uses all available dictionaries, but gives precedence to the Address Dictionary, regardless of how the dictionary precedence was configured when the User Dictionaries were installed. DICTIONARY_PREFER_UD: Uses all available dictionaries, but gives precedence to User Dictionaries, regardless of how the dictionary precedence was configured. DICTIONARY_UD_ONLY: Uses only User Dictionaries. By default, Envinsa uses DICTIONARY_AD_AND_UD for geocoding requests. However, your Envinsa administrator may disable this behavior. To guarantee your geocode requests use the installed User Dictionaries you should specify a DictionaryUsage element. The following example shows how you can specify that you want to use both the Address Dictionary and User Dictionaries to geocode an address: public Request createrequestex() { //Create a street address Address address = new Address("USA"); StreetAddress streetaddress = new StreetAddress("607 Myrtle Ave"); address.setstreetaddress(streetaddress); address.setcountrysubdivision("ny"); address.setmunicipality("albany"); address.setpostalcode(" "); // Create a Geocoding Street Address request GeocodeRequestEx requestex = new GeocodeRequestEx(address); Properties prefs = new Properties(); prefs.setproperty(geocoderequestex.close_matches_only, "true"); prefs.setproperty(geocoderequestex.mustmatch_addr_num, "true"); prefs.setproperty(geocoderequestex.mustmatch_main_addr, "true"); prefs.setproperty(geocoderequestex.mustmatch_country_subdivision, "true"); prefs.setproperty(geocoderequestex.mustmatch_municipality, "true"); prefs.setproperty(geocoderequestex.mustmatch_postal_code, "true"); prefs.setproperty(geocoderequestex.use_addresspoint_interpolation, "true"); // By default, Envinsa uses user dictionaries for geocoding requests. // However, your Envinsa administrator may disable this behavior. To // guarantee your geocode requests use the installed user dictionaries, // such as ParcelPrecision, you must specify this line. requestex.setdictionaryusagepreference(geocoderequestex.dictionary_ad_and_ud); } requestex.setgeocodepreference(prefs); return requestex; 20 Envinsa 4.4

21 Chapter 2: Creating and Using Dictionaries Disabling User Dictionaries If you have multiple user dictionaries and want to disable one or more for a geocode request, then set the isenabled parameter to false when specifying the GeocodeDictionary constructor. You can retrieve a full list of available dictionaries with a GetCapabilities request. See the Envinsa Location Utility Service Reference for more information on this feature. The following example disables the first seven dictionaries for a request. public Request createrequest() throws Exception { // Create a street address Address addressstreet = new Address("USA"); StreetAddress streetaddress = new StreetAddress("43 West 83rd. Street"); addressstreet.setstreetaddress(streetaddress); addressstreet.setcountrysubdivision("ny"); addressstreet.setmunicipality("new York"); } // Create a Geocoding Street Address request GeocodeRequestEx request = new GeocodeRequestEx(addressStreet); // Specify the dictionaries for the request, disabling the first one. GeocodeDictionary[] gds = new GeocodeDictionary[13]; // GeocodeDictionary(int index, boolean isuserdictionary, // boolean isenabled, int searchorder) // Disable address dictionary gds[0] = new GeocodeDictionary( 1, false, false, 1); // Disable parcel center location user dictionaries gds[1] = new GeocodeDictionary( 2, true, false, 2); gds[2] = new GeocodeDictionary( 3, true, false, 3); gds[3] = new GeocodeDictionary( 4, true, false, 4); gds[4] = new GeocodeDictionary( 5, true, false, 5); gds[5] = new GeocodeDictionary( 6, true, false, 6); gds[6] = new GeocodeDictionary( 7, true, false, 7); // Enable parcel street location user dictionaries gds[7] = new GeocodeDictionary( 8, true, true, 8); gds[8] = new GeocodeDictionary( 9, true, true, 9); gds[9] = new GeocodeDictionary(10, true, true, 10); gds[10] = new GeocodeDictionary(11, true, true, 11); gds[11] = new GeocodeDictionary(12, true, true, 12); gds[12] = new GeocodeDictionary(13, true, true, 13); request.setdictionarysearchorder(gds); return request; User Dictionary Guide 21

22 Using User Dictionaries in Envinsa.NET SDK The following sections describe Location Utility SDK User Dictionary requests. For more information on these features and the service in general, see the.net API Reference (NDoc) at reference.mapinfo.com/envinsa. Specifying Dictionary Usage To send a geocode request using the.net API, you must use the GeocodeRequest object. You can specify the DictionaryUsage element as one of the following DictionaryUsagePreference values: AD_AND_UD: Uses the Address Dictionary and User Dictionaries. AD_ONLY: Uses only the Address Dictionary. This option guarantees that you will not use any User Dictionaries for your geocoding request. PREFER_AD: Uses all available dictionaries, but gives precedence to the Address Dictionary, regardless of how the dictionary precedence was configured when the User Dictionaries were installed. PREFER_UD: Uses all available dictionaries, but gives precedence to User Dictionaries, regardless of how the dictionary precedence was configured. UD_ONLY: Uses only User Dictionaries. By default, Envinsa uses AD_AND_UD for geocoding requests. However, your Envinsa administrator may disable this behavior. To guarantee your geocode requests use the installed User Dictionaries you should specify a DictionaryUsage element. The following example shows how you can specify that you want to use both the Address Dictionary and User Dictionaries to geocode an address: private static Request newaddressinterpolationrequest() { GeocodeRequest gr = new GeocodeRequest(); gr.requestid = "R1"; gr.maximumresponses = "10"; //set geocoding preferences to use address point interpolation GeocodePreference gp = new GeocodePreference(); gp.setproperty(geocodepreference.key_closematchesonly, "false"); gp.setproperty(geocodepreference.key_useaddresspointinterpolation, "true"); // By default, Envinsa uses user dictionaries for geocoding requests. // However, your Envinsa administrator may disable this behavior. To // guarantee your geocode requests use the installed user dictionaries, // such as ParcelPrecision, you must specify this line. gr.dictionaryusage = DictionaryUsagePreference.AD_AND_UD; gr.geocodepreference = gp; //set the address in the request Address addr = new Address(); addr.countrycode ="US"; addr.addressee = "US Address"; StreetAddress streetaddress = new StreetAddress(); streetaddress.value = "607 Myrtle Ave"; addr.streetaddress = streetaddress; addr.countrysubdivision = "NY"; 22 Envinsa 4.4

23 Chapter 2: Creating and Using Dictionaries } addr.municipality = "Albany"; addr.postalcode = " "; Address[] addrs = {addr} ; gr.address = addrs; return gr; Disabling User Dictionaries If you have multiple user dictionaries and want to disable one or more for a geocode request, then set the isenabled parameter to false when specifying the GeocodeDictionary constructor. You can retrieve a full list of available dictionaries with a GetCapabilities request. See the Envinsa Location Utility Service Reference for more information on this feature. The following example disables the first seven dictionaries for a request. public static Request createrequest() { // Create a street address Address addressstreet = new Address("USA"); StreetAddress streetaddress = new StreetAddress("43 West 83rd. Street"); addressstreet.streetaddress = streetaddress; addressstreet.countrysubdivision = "NY"; addressstreet.municipality = "New York"; // Create a Geocoding Street Address request GeocodeRequest request = new GeocodeRequest(); Address[] addrs = new Address[1]; addrs[0] = addressstreet; request.address = addrs; // Specify the dictionaries for the request, disabling the first one. GeocodeDictionary[] gds = new GeocodeDictionary[13]; // GeocodeDictionary(int idx, bool isuserdict, bool isenabled, int order) // Disable address dictionary gds[0] = new GeocodeDictionary(1, false, false, 1); // Disable parcel center location user dictionaries gds[1] = new GeocodeDictionary(2, true, false, 2); gds[2] = new GeocodeDictionary(3, true, false, 3); gds[3] = new GeocodeDictionary(4, true, false, 4); gds[4] = new GeocodeDictionary(5, true, false, 5); gds[5] = new GeocodeDictionary(6, true, false, 6); gds[6] = new GeocodeDictionary(7, true, false, 7); // Enable parcel street location user dictionaries gds[7] = new GeocodeDictionary(8, true, true, 8); gds[8] = new GeocodeDictionary(9, true, true, 9); gds[9] = new GeocodeDictionary(10, true, true, 10); gds[10] = new GeocodeDictionary(11, true, true, 11); gds[11] = new GeocodeDictionary(12, true, true, 12); gds[12] = new GeocodeDictionary(13, true, true, 13); request.dictionary = gds; } return request; User Dictionary Guide 23

24 Using User Dictionaries in Envinsa 24 Envinsa 4.4

25 User Dictionary Requirements 3 This chapter describes requirements and county specific table structures required to create user dictionaries. In this section: User Dictionaries Requirements User Dictionary Fields by Country

26 User Dictionaries Requirements The capabilities of user dictionaries and the basic requirements for creating them are as follows: User Dictionaries support street level geocoding (street address, street centroid, and street intersection) in the same way as the Address Dictionaries. Source records can be either point objects or segments. Your custom data may include any Point of Interest data, including place names, intersections, business or organization names, building names, airports, universities, parks, sports arenas, restaurants, etc. User Dictionaries support address browsing using partial street names or Points of Interest. (Standard Address Dictionaries support browsing but do not support POI geocoding.) Source records must include required fields, and these fields are mapped during the User Dictionary creation process. If a value of a required field is empty for a particular record, then that record is not imported into the User Dictionary. Required fields may vary for different countries. Source records must be in a MapInfo table (.TAB file). The.TAB file requirements vary for different countries. An Address Dictionary is required in order to create the User Dictionary. Note: While you can use a User Dictionary independently, you must have an Address Dictionary in order to create a User Dictionary. This is because the Address Dictionary has some internal structure that must be available when you are creating a User Dictionary. User Dictionaries do not support Postal geocoding or Geographic geocoding. Point of Interest (POI) Geocoding in User Dictionaries Your custom data may include place names, intersections, business or organization names, building names, or any other Point of Interest that you want to use for geocoding purposes. Typical sites might include: airports, train stations, company locations, universities, parks, sports arenas, restaurants, etc. These points are included in the place name field. User Dictionaries support POI geocoding and browsing. Standard Address Dictionaries support browsing, but do not support POI geocoding. Source Table Data For User Dictionaries The source data for a custom User Dictionary must follow the same guidelines, as described below. The source data for custom User Dictionaries includes street data, but the may also include place names and intersections. The source data must be in the form of a MapInfo table. The MapInfo table must contain specific fields, which the MapInfo User Dictionary Utility then uses to convert the table into the dictionary format. These input fields are described in User Dictionary Fields by Country. Each row in the table is equivalent to a street segment. Segments that make up intersections must have one or more endpoints in the intersection for the MapInfo User Dictionary Utility to recognize it as an intersection. 26 Envinsa 4.4

27 Chapter 3: User Dictionary Requirements User Dictionary Fields by Country When creating User Dictionaries, each country requires the structure of the source table to follow specific field requirements. The following countries are described in this document. United States Canada Germany Australia If a countries table structure is not described in this document, refer to the country specific MapMarker documentation at United States You must specify the field names in the table (.TAB file) in order for the table to be translated into a User Dictionary. Certain fields are required and must be present in the table. Other fields are optional, but are strongly recommended because there may be negative consequences if they are omitted. This is described in Optional (Recommended) Input Fields. If any of the required fields are missing, a missing field error code is returned. The following table describes the required input fields. Required Fields Description Maximum Field Length Left Start Address Start of address range on left side of street 10 Right Start Address Start of address range on right side of street 10 Left End Address End of address range on left side of street 10 Right End Address End of address range on right side of street 10 Street Name Name of street 30 State Abbreviation Two-character state abbreviation 2 Left ZIP Code ZIP Code for left side of street 5 Right ZIP Code ZIP Code for right side of the street 5 Optional (Recommended) Input Fields The Left and Right Odd/Even Indicator fields 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. User Dictionary Guide 27

28 User Dictionary Fields by Country 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. When the Odd/Even Indicator is not specified and both Start Address and End Address have values, the indicator is set to Both (odd and even). Note: If your table contains odd/even indicator information, we strongly recommend that you use the Odd/Even indicator fields. These fields ensure that your geocoded addresses are located on the correct side of the street. Omitting the fields when your data contains odd/even information may produce incorrect results. The following table describes the optional input fields. Optional Fields Left Odd/Even indicator * Right Odd/Even indicator * Description Left side of the street contains only odd or even address ranges (O=odd, E=even, B=both) Right side of the street contains only odd or even address ranges (O=odd, E=even, B=both) Maximum Field Length 1 1 City * City name 28 Left ZIP + 4 Code 4-digit ZIP + 4 add-on for left side of street 4 Right ZIP + 4 Code 4-digit ZIP + 4 add-on for right side of street 4 Left Census Block Census Block ID for left side of street 15 Right Census Block Census Block ID for right side of street 15 Place Name Place name 40 * These fields are highly recommended. Canada You must specify the field names in the table (.TAB file) in order for the table to be translated into a User Dictionary. Certain fields are required and must be present in the table. Other fields are optional, but are strongly recommended because there may be negative consequences if they are omitted. This is described in Optional Input Fields. If any of the required fields are missing, a missing field error code is returned. Required Fields Description Maximum Field Length Left Start Address Start of address range on left side of street 10 Right Start Address Start of address range on right side of street Envinsa 4.4

29 Chapter 3: User Dictionary Requirements Required Fields Description Maximum Field Length Left End Address End of address range on left side of street 10 Right End Address End of address range on right side of street 10 Street Name Name of street 30 Province Abbreviation 2-character province abbreviation 2 Left FSA (segment) FSA for left side of street 3 Right FSA (segment FSA for right side of the street 3 You can specify the row or rows in your source data to include in the User Dictionary. If you select only a subset of the rows to include in the User Dictionary, the other rows are ignored during the creation process. Optional Input Fields You can also add a number of optional fields to your User Dictionary. The following table describes the optional input fields. Optional Fields Left Odd/Even indicator Right Odd/Even indicator Description Left side of the street contains only odd or even address ranges (O=odd, E=even, B=blank) Right side of the street contains only odd or even address ranges (O=odd, E=even, B=blank) 1 1 Maximum Field Length City City name 28 Left LDU LDU for left side of street 3 Right LDU LDU for right side of street 3 The Odd/Even indicator fields are not expressly required to create a user dictionary, but may be needed depending on the data in your table. If your table contains odd/even indicator information, use the Odd/Even indicator fields. Use of these fields ensures that your geocoded addresses are located on the correct side of the street. Omitting the fields when your data contains odd/even information may produce incorrect results. If you do not have odd/even indicator information in your data, you can safely omit the fields. User Dictionary Guide 29

30 User Dictionary Fields by Country Germany You must specify the field names in the source table (.TAB file) in order for the table to be translated into a User Dictionary. Certain fields are required and must be present in the table. Other fields are optional. If any of the required fields are missing, a missing field error code is returned. Below are the required and optional fields. These fields represent one object in the table. Field Description Type PlaceName St_nm Province POI index string. Empty for non-poi records. Typically the street name representing an Index string for street geocode operations. All records must have an entry in this field, in cases where this is not known, a dummy value must be entered. AreaName1 (Optional) AreaName1 may contain Province when building the User Dictionary. AreaName2 may also contain province. On Input: If AreaName2 has content, use it for Province and ignore input in AreaName1. If AreaName2 if empty, but AreaName1 has content, then use AreaName1 as if it had been supplied in AreaName2. That is, assume that AreaName1 contains the Province. On Output: Not Used (Bundesland) is returned in AreaName1. Province (Kreis) is returned in AreaName2. Even if the user specified the province in AreaName1, on output the province is returned in AreaName2. Town (Ort) is returned in AreaName3. If Locality (Stadteil) is available, it is returned in AreaName4. Note A user may input the Locality in Areaname3, but Locality will be returned in Areaname4. Areaname4 is never used for input. Character Character Character Town AreaName3 Character Locality AreaName4 Character Postcode 5-digit postcode Character FromLeft Start of address range on left side of street. Integer ToLeft End of address range on left side of street. Integer 30 Envinsa 4.4

31 Chapter 3: User Dictionary Requirements Field Description Type FromRight Start of address range on right side of street. Integer ToRight End of address range on right side of street. Integer L_Struct Structure of house numbers on left side of street Integer R_Struct Structure of house numbers on right side of street Integer * Each record must have an entry in Town (AreaName3), Postcode, or both ** These fields must have a value. If the value is unknown or for a POI, the value must be 0 (zero) Australia You must specify the field names in the table (.TAB file) in order for the table to be translated into a User Dictionary. Certain fields are required and must be present in the table. Other fields are optional, but are strongly recommended because there may be negative consequences if they are omitted. This is described in Optional (Recommended) Input Columns. If any of the required fields are missing, a missing field error code is returned The following table describes the required input columns. Field Description Maximum Column Length Street Name Name of street 50 Town / Suburb Municipality or locality 40 Postcode Four-digit postcode 4 State Abbreviation of state or territory 3 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. 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. User Dictionary Guide 31

32 User Dictionary Fields by Country When the Odd/Even Indicator is not specified and both Start Address and End Address have values, the indicator is set to Both (odd and even). Note: 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. Field Description Maximum Column Length Place Name Place name 40 Local Government Area Unit Number Unit Type An LGA can include a number of official suburbs.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. Therefor it is best to use the suburb name fore geocoding. Unit Numbers are associated with Unit Types, Unit Types include Apartment, Building, Flat, Suite, and others. 50 Left Starting Address Number Right Starting Address Number Left Ending Address Number Right Ending Address Number Start of address range on left side of street 11 Start of address range on right side of street 11 End of address range on left side of street 11 End of address range on right side of street 11 Left Odd/Even indicator * Right Odd/Even indicator * Left side of the street contains only odd or even address ranges (O=odd, E=even, B=both) Right side of the street contains only odd or even address ranges (O=odd, E=even, B=both) 1 1 * These columns are highly recommended. 32 Envinsa 4.4