Global Geocoding API Version 1.2 REST and Java API Developer Guide
Total Page:16
File Type:pdf, Size:1020Kb
Location Intelligence Global Geocoding API Version 1.2 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 121 Appendix B: Result Codes 626 2 - Using the Global Geocoding Appendix C: API Error Messages 659 Introduction 18 Input Address Guidelines 19 Geocoding Capabilities 20 Configured Geocoding Datasets 21 Matching Options 22 Geocoding Options 28 Reverse Geocoding Options 36 Custom Options 40 Candidate Return Information 42 3 - REST Web Services Introduction to Global Geocoding Services 44 Making Requests using HTTP 44 Geocode Service 47 Reverse Geocode Service 79 Capabilities Service 101 Dictionaries Service 111 4 - Java API Getting Started 117 Javadocs 118 Sample Application 119 1 - Installation In this section Installing the Software 4 Installing the Data 7 Installation Installing the Software This chapter covers the following topics: • System requirements • Using the interactive software installer • Using the silent installer • Publishing the REST web service System Requirements Operating Systems The Global Geocoding API is supported on the following operating systems. Windows Operating Systems • Windows Server 2008 R2 • Windows Server 2012 R1 & R2 UNIX/Linux Operating Systems • AIX 6.1 • AIX 7.1 • Oracle Linux 6 • Red Hat Enterprise Linux 5 • Red Hat Enterprise Linux 6 • Solaris 10 (SPARC only) • Solaris 11 (SPARC only) • SUSE 10 • SUSE 11 Disk Space A complete installation of the Global Geocoding API (without data) requires approximately 350MB. Global Geocoding API 1.2 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.2 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.2 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 • 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.2 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.2 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.2 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,