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.
1. Review the README.md for getting started with the sample project code.
2. 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.
1. Windows:
```
mkdir {directory}/data
```
2. Linux:
```
mkdir -p {directory}/data
```
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.]
1. Windows:
```
cd {directory}/ggs-dist-{version}/cli
cli.cmd
```
2. Linux:
```
cd {directory}/ggs-dist-{version}/cli
cli.sh
```
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:

Configure previously extracted data programmatically.
Extract and configure data programmatically.

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();
}