Global Geocoding API Version 1.5 REST and Java API Developer Guide
Total Page:16
File Type:pdf, Size:1020Kb
Location Intelligence Global Geocoding API Version 1.5 REST and Java API Developer Guide Table of Contents 1 - Installation Appendices Installing the Software 4 Appendix A: Installing the Data 7 Country-Specific Information 136 Appendix B: Language Coverage by Country 691 2 - Using the Global Geocoding Appendix C: API Result Codes 699 Appendix D: Introduction 21 Error Messages 729 Input Address Guidelines 22 Geocoding Capabilities 22 Configured Geocoding Datasets 23 Matching Options 24 Geocoding Options 29 Reverse Geocoding Options 40 Custom Options 44 Candidate Return Information 45 Setting Country-Level Preference Overrides 48 3 - REST Web Services Introduction to Global Geocoding Services 52 Making Requests using HTTP 52 Geocode Service 56 Reverse Geocode Service 90 Capabilities Service 115 Dictionaries Service 126 4 - Java API Getting Started 132 Javadocs 133 Sample Application 134 1 - Installation In this section Installing the Software 4 Installing the Data 7 Installation Installing the Software This chapter covers the following topics: • Using the interactive software installer • Using the silent installer • Publishing the REST web service For system requirements and supported operating systems, see the Release Notes. Global Geocoding API 1.5 REST and Java API Developer Guide 4 Installation Using the Interactive Software Installer Using the Interactive Installer on Windows Note: You need to have administrator rights to install the software. The file name for the installer is: install.exe 1. Launch the installer. 2. Follow the instructions to complete the install. In case of installation failure, review the log file located in your installation directory. In the default installation directory, the log file is located in: C:\Program Files\Pitney Bowes\geocoding\Logs Using the Interactive Installer on UNIX/Linux Note: You must have sufficient privileges to write to the installation directory. The file name for the installer is: install.bin 1. Execute the following command in the console: chmod +x install.bin 2. Start the installer by executing the following command: ./install.bin 3. Follow the instructions provided by the script to complete the install. Using the Silent Installer The silent install process allows you to pre-configure the installation process so that it runs without user intervention. The following table describes the properties in the installer.properties file that need to be set for silent installation. Property Value Description INSTALLER_UI SILENT This property enables the silent installer mode. Global Geocoding API 1.5 REST and Java API Developer Guide 5 Installation Property Value Description USER_INSTALL_DIR Folder/Directory Indicates where the software is to be installed. • On Windows: Use "\\" between folders. For example, C:\\Program Files\\Pitney Bowes\\geocoding • On UNIX/Linux: Use "/" between folders. For example, /usr/pb/geocoding CHOSEN_INSTALL_SET FULL This property indicates that the entire software is to be installed. 1. Uncomment the properties inside the installer.properties file accompanying the installer. 2. Place the installer.properties file in the same directory as the install.exe (Windows)/install.bin (UNIX/Linux) file. 3. After modifying the installer.properties file, run the install using the appropriate install executable for your platform. Publishing the REST Web Service To start the REST Web Server, follow the instructions below for your platform. • On Windows: Run install_dir\tomcat\bin\startup.bat • On UNIX/Linux: Run install_dir/tomcat/bin/startup.sh After the server starts up, run the data installer, followed by the ConfigureData tool. Global Geocoding API 1.5 REST and Java API Developer Guide 6 Installation Installing the Data This chapter covers the following topics: • Using the interactive data installer • Using the silent data installer • Using the data configuration tool • Manually configuring datasets • Setting the geocoding dataset search order • Configuring a User Dictionary Using the Interactive Data Installer After downloading your geocoding datasets, the interactive data installer will install your data. To run the data installer, the following items are required: • The data installer executable: • On Windows: GAPIData.exe — For the default installation, this executable is located in the media\win64 directory. • On UNIX/Linux: GAPIData.bin — For the default installation, this executable is located in the media/platform directory. Where platform may have the following values. Use the one associated with your platform: • linux64—Can be used for all UNIX/Linux systems, except for Solaris and AIX. • solaris64 • aix64 • The installer.properties file — This file contains installer properties that can be modified for your installation. The file is located: • On Windows: For the default installation, the installer.properties file is located in the media\conf directory. • On UNIX/Linux: For the default installation, the installer.properties is located in the media/conf directory. After running the Interactive Data Installer, your geocoding datasets will be installed by default in: • On Windows: media\data directory • On UNIX/Linux: media/data directory Global Geocoding API 1.5 REST and Java API Developer Guide 7 Installation The following table describes the properties that can be modified in the installer.properties file. Property Value Description SGI_MEDIA_PROFILE ALL This property enables the installation of all the countries that are included with the installer. If there are geocoding datasets that are missing when the installer is run, the installation will still continue but will issue a warning. APAC This property enables the installation of the “Asia-Pacific” geocoding dataset. AMER This property enables the installation of the "Americas" geocoding dataset. XWGXWG This property enables the installation of the "World Centroids" geocoding dataset. EMEA This property enables the installation of the "Europe, Middle East and Africa" geocoding dataset. ALLNT This property enables the installation of the NAVTEQ dataset. Using the Interactive Data Installer on Windows Note: When installing multiple geocoding datasets for a country, it is necessary to select and install all of them concurrently to ensure the software will recognize all the datasets for the country. 1. After setting up the installer.properties file, launch the data installer executable: GAPIData.exe. 2. Follow the prompts provided by the installer. In case of installation failure, review the log file located in your installation directory. If the defaults were used for the installation, the log file is located in: C:\Program Files\Pitney Bowes\pbgdata\Logs After the data installation successfully completes, you need to configure the geocoding dataset(s). For details, see Using the Data Configuration Tool on page 11. Global Geocoding API 1.5 REST and Java API Developer Guide 8 Installation Using the Interactive Data Installer on UNIX/Linux Note: When installing multiple geocoding datasets for a country, it is necessary to select and install all of them concurrently to ensure the software will recognize all the datasets for the country. 1. After setting up the installer.properties file, execute the following command in the console: chmod +x GAPIData.bin 2. Start the installer by executing the following command: ./GAPIData.bin 3. Follow the script instructions to complete the install. When entering the geocoding datasets you would like to install, by default all are selected. To exclude geocoding datasets, provide a comma-separated list of the ones you do not want to install. After the data installation successfully completes, you need to configure your geocoding dataset(s). For details, see Using the Data Configuration Tool on page 11. Global Geocoding API 1.5 REST and Java API Developer Guide 9 Installation Using the Silent Data Installer The silent data install process allow you to pre-configure the data installation process so that it runs without user intervention. Note: When installing multiple geocoding datasets for a country, it is necessary to select and install all of them concurrently to ensure the software will recognize all the datasets for the country. The following table describes the properties in the installer.properties file that can be set for silent installation. Property Value Description SGI_MEDIA_PROFILE ALL This property enables the installation of all the countries that are included with the installer. If there are geocoding datasets that are missing when the installer is run, the installation will still continue but will issue a warning. APAC This property enables the installation of the “Asia-Pacific” geocoding dataset. AMER This property enables the installation of the "Americas" geocoding dataset. XWGXWG This property enables the installation of the "World Centroids" geocoding dataset. EMEA This property enables the installation of the "Europe, Middle East and Africa" geocoding dataset. ALLNT This property enables the installation of the NAVTEQ dataset. INSTALLER_UI SILENT This property enables silent installer mode. USER_INSTALL_DIR Folder/Directory Indicates where the geocoding dataset(s) is to be installed. • On Windows: Use "\\" between folders. For example, C:\\Program Files\\Pitney Bowes\\pbgdata Global Geocoding API 1.5 REST and Java API Developer Guide 10 Installation Property Value Description • On UNIX/Linux: Use "/" between folders. For example, /usr/pb/pbgdata CHOSEN_INSTALL_SET Custom This tells the installer to install the entire software. CHOSEN_FEATURE_LIST