Global Geocoding SDK V2.1.0 Developer Guide
Total Page:16
File Type:pdf, Size:1020Kb
Location Intelligence Global Geocoding SDK Version 2.1 REST and Java API Developer Guide Table of Contents Appendix C: Result Codes 147 1 - Installation Appendix D: Error Messages 181 Deploying the Global Geocoding SDK Distribution 4 2 - Using the Global Geocoding SDK Introduction to the Global Geocoding APIs 11 3 - REST Web Services Geocode Service 13 Reverse Geocode Service 35 Interactive Geocode Service 45 Key Lookup Service 53 Capabilities Service 58 Dictionaries Service 66 PBLocator REST API 70 4 - Java API Getting Started 78 Configuring 78 Javadocs 80 Chapter : Appendices Appendix A: ISO 3166-1 Country Codes 82 Appendix B: Country-Specific Custom Fields 91 1 - Installation In this section Deploying the Global Geocoding SDK Distribution 4 Installation Deploying the Global Geocoding SDK Distribution Global Geocoding SDK resources must be deployed and configured before they can be used by a geocoding engine. This section explains the necessary commands. The following topics are covered: • Geocoding CLI Utility on page 5 • deploy Command on page 6 • extract Command on page 6 • configure Command on page 7 • setting Command on page 7 Syntax Conventions The following syntax conventions apply when using these CLI commands: Values containing a space must be enclosed with quotes, for example, "Some Value" Path slash marks must be escaped with quotes around it. For example: • A Windows path "C:\path", must be written as "C:\\path" or "C:/path" • A Linux /path must be written as "/path" Global Geocoding SDK 2.1 REST and Java API Developer Guide 4 Installation Geocoding CLI Utility Geocoding CLI utility is bundled with the Global Geocoding SDK (GGS) distribution. Starting CLI The cli folder contains the files as below. • lib: Contains java library for available utility commands. • resources: Contains GGS resources including GGS Javadocs • cli.cmd: Windows batch script to start Geocoding CLI shell. • cli.sh: Linux shell script to start Geocoding CLI shell. • Logging.properties Contains properties required for logging strategy. Note: cli.cmd is for Windows users. cli.sh is for UNIX/Linus users. Ensure that the cli.sh file has execute permission. chmod 755 cli.sh Now cli.sh shell script file is executable. cli.sh Execute this shell script to start geocoding CLI shell. $ ./cli.sh CLI Batch Process How to run the cli commands as a batch process: Linux platform ./cli.sh --cmdfile ./commands.cli Windows platform ./cli.cmd --cmdfile commands.cli Global Geocoding SDK 2.1 REST and Java API Developer Guide 5 Installation deploy Command The Global Geocoding SDK distribution is deployed by using CLI's deploy command. Use the deploy command to deploy the application to a Tomcat webapps directory, creating an application ROOT directory if necessary. This example uses "Geocode" as the directory. Format of this command: deploy --c "/ggs-dist-{version}/resources" --m "WAR_EXTRACTED" --d "/tomcat/webapps/Geocode" --l "/tomcat/logs" where the deploy parameters are: --c or --config Configuration resources directory.is included at root level of as a resources directory when extracted --m or --mode Deployment mode default: WAR WAR - will configure and copy .war to destination directory WAR_EXTRACTED - will configure and extract .war file to destination directory. Destination directory must be empty JAVA_API -will configure and copy the Java API to the destination directory (must be empty). The logDirectory path param (–l or --logDirectory) is not required. --d or --destination Destination directory where application will be configured, for example tomcat/webapps/Geocode --l or --logDirectory Logging directory is required for WAR and WAR_EXTRACTED file deployments where the application will create log files. Optional for JAVA_API. extract Command Reference data for geocoding, such as streets and points, and Interactive is bundled as .spd files, which must extracted and configured before it is available for use. Format of the extract command: extract --s "/location/to/spd/files" --d "/data" where --s is the location of the source .spd file and --d is the destination folder for the extracted data. Global Geocoding SDK 2.1 REST and Java API Developer Guide 6 Installation configure Command Once the geocoding reference data has been extracted, it must be configured for use. The configuration parameters go into a JsonDataConfig.json. This file is created when you run the configure command. Format of this command: configure --s "/data" --d "/ggs-dist-{version}/resources/config" where --s is the location of the extracted .spd file and --d is the destination folder for the generated JsonDataConfig.json. Note: If a REST Service is running, the web server must be restarted whenever JsonDataConfig.json is updated. To configure the data located on multiple paths, the format is: configure --s "/data,/data2" --d "/ggs-dist-{version}/resources/config" where "/data,/data2" are two folders of data. setting Command The setting command is used to change a setting in the GGS API. To modify settings using the CLI, follow this format: setting --n [Name of setting] --v [Value for setting] --d [Path to configuration dir] --t [Type of setting] To remove a particular setting, set --v to an empty string, e.g., --v "". To define a country setting, use the country ISO 3 code with --t [Type of setting]. Examples: # Global Settings setting --n MAXIMUM_BATCH_SIZE --v 100 --d "/path/to/config/dir" # or with type specified setting --n MAXIMUM_BATCH_SIZE --v 100 --d "/path/to/config/dir" --t GLOBAL # Country level settings (use iso3 country code for country level settings) Global Geocoding SDK 2.1 REST and Java API Developer Guide 7 Installation setting --n RETURN_EXTENDED_DATA --v no --d "/path/to/config/dir" --t USA # Core settings setting --n COUNTRY_FALLBACK_MODE --v BASIC --d "/path/to/config/dir" --t CORE_SETTINGS Manually Configuring Datasets If you have data that was not installed and configured using Geocoding CLI Utility on page 5, you can manually edit a .json file to include the path, properties and other information about your data. You can include as many countries and datasets as you want in the file. JsonDataConfig.json is located in the Global Geocoding SDK (GGS) installation directory under the /resources/config directory. There are two main sections to the file: roots and countries. • roots - may contain one or more key:value pairs that define locations where several countries are installed. "root1" key can be any name you wish. • countries - a list of configurations by country where each configuration is identified by its ISO-3 country code. Each country configuration can contain properties and a list of datasets. The keys in this section are not arbitrary. { "roots" : { "root1" : "C:\\mydata" }, "countries" : [ { "country" : "USA", "properties" : null, "dataSets" : [ ] }] } The example below has been edited to include several countries, one with multiple datasets for USA (CTP, TTS). In the case of CTP, notice useRoot is true. The path to the data then is root1 plus path (c:\\myserver\\mydata\\DVDCPoints). When useRoot is false, as in the case for TTS, the path to the dataset must be defined in the path element. The rootId would be ignored. { "roots": { "root1": "c:\\myserver\\mydata" }, "countries": [ { Global Geocoding SDK 2.1 REST and Java API Developer Guide 8 Installation "country": "USA", "properties": { "RETURN_EXTENDED_DATA": "yes", "DEBUG": "no", "GEOSTAN_INSTANCE_COUNT": "5", "APN_CODE": "true", "ELV_CODE": "true", "FILE_MEMORY_LIMIT": "2000" }, "dataSets": [ { "name": "CTP", "path": "/DVDCPoints", "rootId": "root1", "useRoot": true }, { "name": "TTS", "path": "c:\\myserver2\\mydata\\TTS", "rootId": "THIS_WILL_BE_IGNORED_SINCE_useRoot_IS_FALSE", "useRoot": false } ] }, { "country": "ABW", "properties": null, "dataSets": [ { "name": "NTS", "path": "/ABW/NTS", "rootId": "root1", "useRoot": true } ] }, { "country": "ARG", "properties": null, "dataSets": [ { "name": "NTS", "path": "/ARG/NTS", "rootId": "root1", "useRoot": true } ] }, ] } Global Geocoding SDK 2.1 REST and Java API Developer Guide 9 2 - Using the Global Geocoding SDK In this section Introduction to the Global Geocoding APIs 11 Using the Global Geocoding SDK Introduction to the Global Geocoding APIs The Global Geocoding SDK allows you to develop and deploy geocoding desktop, mobile or Web applications that are capable of delivering location information for over 120 countries. This guide contains information about using the REST and Java APIs which provide: • Geocode Service - The Geocode Service service performs forward geocoding using input addresses and returning location data and other information. Reverse Geocode Service - The Reverse Geocode Service service performs reverse geocoding using input coordinates and returns address information that is the best match for that point. Interactive Geocode Service - The Interactive Geocode Service service suggests addresses and place names as you type. Key Lookup Service - The Key Lookup Service service returns geocoded candidates when given a unique key. It is a more efficient method than matching with an address, as the key is unique to that address. Global Geocoding Module supports the pbKey™ unique identifier for US data and the G-NAF key for AUS data. Each service has options that allow you to control matching and geocoding criteria, dataset resource configuration and more. Global Geocoding SDK 2.1 REST and Java API Developer Guide 11 3 - REST Web Services In this section Geocode Service 13 Reverse Geocode Service 35 Interactive Geocode Service