Getting Started with the Java API
Requirements
- Java 8
- GGS distribution (ggs-dist-{version}.zip)
- Dataset(s) in the Spectrum data format (*.spd)
Placeholders
The following conventions are used as placeholders for some common items:- {directory} Any directory where you would like to install the resources for the SDK.
- {version} The version of the GGS SDK such as 3.0.0.
- {spd} Dataset in the Spectrum data format. For example, KGD082019.spd.
Open the Sample Code in IDE
- Extract the zipped Global Geocoding SDK (GGS) distribution to an empty directory. For
example: {directory}/ggs-dist-{version}. The following directories will be
created:
- cli – contains the Geocoding command-line interface (CLI) Utility used to configure GGS. [About the Geocoding CLI Utility.]
- resources – contains runtime resources for the GGS API.
- sdk – contains resources for the JAVA API development.
- webapp – contains the REST API distribution war file ‘Geocode-{version}.war’ [About deploying a war file.]
- Open the sample project in
{directory}/ggs-dist-{version}/sdk/samples/ggs-javaapi-sample.
- Review the README.md for getting started with the sample project code.
- For additional detail, see the JAVA docs in {directory}/ggs-dist-{version}/sdk/javadoc.
Install and Configure Datasets
Before geocoding, install and configure the data for the SDK. There are two options:
- Configure using the GGS CLI if you want your configuration to persist for future calls to the API.
- Configure programmatically if you want your configuration to apply only to that runtime.
Configure using the GGS CLI
- Create a location where datasets will be installed.
- Windows:
mkdir {directory}/data
- Linux:
mkdir
-p {directory}/data
- Windows:
- Run the GGS CLI. The command below starts the CLI in interactive mode. Note: The GGS CLI can be run in interactive or batch mode. [About the CLI Batch Process.]
- Windows:
cd
{directory}/ggs
-dist
-{version}/
cli
cli
.cmd
- Linux:
cd {directory}/ggs-dist-{version}/cli cli.sh
- Windows:
- Locate .spd file(s) and extract the dataset(s). [About the Extract
command.]
extract --s "{spd}" --d "{directory}/data"
- Configure data for the SDK, based on the dataset location, by running this command from
within the interactive CLI. [About the Configure
command.]
configure --s "{directory}/data" --d "{directory}/ggs-dist-{version}/resources/config"
The "–d" parameter indicates the location of the configuration. It must be in the directory as specified in the above command. Copy this path to use in the next step.
- Use the configuration to build a geocoder.
public SimpleGeocodeWrapper() throws GeocodingException { GeocodingAPI geocoder = new GeocoderBuilder() // ggs.home - "{directory}/ggs-dist-{version}" // resources - directory containsing GGS runtime resource "{directory}/ggs-dist-{version}/resources" // location where ggs configuration can be found {ggs.home}/resources .withConfiguration(new ConfigurationBuilder() .withResourcesPath(Paths.get("{directory}/ggs-dist-{version}/resources")) .build()) // default preferences, if none defined it will // use the defaults defined in {ggs.home}/resources/config/geocodePreferences.xml location .withPreferences(new GeocoderPreferences()) .build(); }
Configure programmatically
There are two options:
Note: If you have more than one data path, use this syntax:
withDataPath(Paths.get("{directory}/data"), Paths.get("{directory}/someOtherData"), ...) // this will only be used if resources location already does not contain any data info
Configuring previously extracted data
public GeocodeWrapperWithConfiguration() throws GeocodingException {
GeocodingAPI geocoder = new GeocoderBuilder()
// ggs.home - "{directory}/ggs-dist-{version}"
// ggs.resources.location - directory containsing GGS runtime resource "{directory}/ggs-dist-{version}/resources"
// ggs.data.location - location where extracted data can be found i.e. "{directory}/data" from above extract command
.withConfiguration(new ConfigurationBuilder()
.withResourcesPath(Paths.get("{directory}/ggs-dist-{version}/resources"))
.withDataPath(Paths.get("{directory}/data")) // this will only be used if resources location already does not conatin any data info
.build())
// default preferences, if none defined it will
// use the defaults defined in {ggs.home}/resources/config/geocodePreferences.xml location
.withPreferences(new GeocoderPreferences())
.build();
}
Extracting and configuring data programmatically
public GeocodeWrapperWithDynamicConfiguration() throws GeocodingException {
GeocodingAPI geocoder = new GeocoderBuilder()
.withConfiguration(new ConfigurationBuilder()
//path to ggs runtime resources, this will be located under ggs distribution
.withResourcesPath(Paths.get("{directory}/ggs-dist-{version}/resources"))
//path to ggs data directory, this can be extracted data or directory containg spd files
.withDataPath(Paths.get("{directory}/data"))
.withExtractorBuilder(new ExtractorConfiguration.Builder()
//number of extractors that will be used for extracting data
.withExtractorCount(4)
//path to where data can be extracted, it will skip any data that has been previously extracted
.withExtractPath(Paths.get("{directory}/data"))
.build())
.build())
// default preferences, if none defined it will
// use the defaults defined in {directory}/ggs-dist-{version}/resources/config/geocodePreferences.xml location
.withPreferences(new GeocoderPreferences())
.build();
}