Server SDK

The what3words Server SDK gives you programmatic access to what3words technology in your own Java code base. The Server SDK allows the conversion of 3 word addresses to coordinates (forward geocoding), the conversion of coordinates to 3 word addresses (reverse geocoding), to obtain suggestions based on a full or partial 3 word address (AutoSuggest) and to determine the languages that the currently installed Server SDK supports.

SDK Version

This page describes version 2 of the what3words Server SDK; this is the latest version.

Get Started

To get a feel for geocoding with what3words, we recommend that you start with our RESTful API; this has all the main functional elements of our offline capable server SDK and you can be up and running in minutes. When you want to dive deeper into the server SDK, just get in touch with us at support@what3words.com and we'll get the ball rolling for you.

Supported Java Versions

The what3words SDK supports Java 7 and above. To develop applications using the SDK, you will need a Java 7 or higher Java Development Kit (JDK). To run applications developed using the SDK, you will need a Java 7 or higher Java Runtime Environment (JRE).

Both the official Oracle Java distribution and the OpenJDK distribution are supported by the what3words SDK.

Installation

The what3words SDK is distributed as a compressed archive. To install, simply uncompress the archive onto your server's filesystem.

└── var
    └── what3words
        ├── w3w-data
        │   ├── wordlists
        │   ├── reversegeocode
        │   └── att
        ├── sample
        │   ├── src
        │   │   └── main
        │   │       └── java
        │   │           └── com
        │   │               └── what3words
        │   │                   └── sample
        │   │                       └── Main.java
        │   ├── build.gradle
        │   └── README.md
        └── com
            └── what3words
                ├── w3w-core
                │   └── 2.0.0
                │       └── w3w-core-2.0.0.jar
                └── utils-lib
                    └── 2.0.0
                        └── utils-lib-2.0.0.jar
            

For UNIX and Linux installations we recommend that you maintain the directory hierarchy from the installation media, placing the SDK's files into the root directory which will create the /var/what3words directory hierarchy.

For Windows installation we recommend that you place the contents of var/what3words from the installation media into C:\what3words.

The /var/what3words/com/what3words/w3w-core/w3w-core-2.0.0.jar and /var/what3words/com/what3words/utils-lib/utils-lib-2.0.0.jar should be referenced in your project's build files as dependencies.

Documentation

Complete and detailed documentation of the what3words SDK, its public classes and methods are available in Javadoc format .

The remainder of this page provides an introduction to the concepts and useage of each of the SDK's public methods.

SDK Initialisation

To initialise the what3words SDK, instantiate a new instance of ServerAPIInstance, passing the location of the what3words data directory.

                        
import com.what3words.apiinstance.IAPIInstance;
import com.what3words.apiinstance.ServerAPIInstance;

public class Main {
    public static void main(String[] args) {
        String dataPath = "/var/what3words/w3w-data";
        IAPIInstance sdk = new ServerAPIInstance(dataPath);
    }
}
                        
                    

Forward Geocoding

The ServerAPIInstance.forwardGeocode() method converts a 3 word addresses to coordinates.

                        
import com.what3words.apiinstance.IAPIInstance;
import com.what3words.apiinstance.ServerAPIInstance;
import com.what3words.apiinstance.W3wPosition;

public class Main {
    public static void main(String[] args) {
        String dataPath = "/var/what3words/w3w-data";
        IAPIInstance sdk = new ServerAPIInstance(dataPath);

        String addr = "index.home.raft";
        String lang = "en";
        W3wPosition pos = sdk.forwardGeocode(addr, lang);
    }
}
                        
                    

Reverse Geocoding

The ServerAPIInstance.reverseGeocode() method converts coordinates to a 3 word address.

                        
import com.what3words.common.LatLng;
import com.what3words.apiinstance.IAPIInstance;
import com.what3words.apiinstance.ServerAPIInstance;
import com.what3words.apiinstance.W3wPosition;

public class Main {
    public static void main(String[] args) {
        String dataPath = "/var/what3words/w3w-data";
        IAPIInstance sdk = new ServerAPIInstance(dataPath);

        LatLng coords = new LatLng(51.455905, -0.341492);
        String lang = "en";
        W3wPosition pos = sdk.reverseGeocode(coords, lang);
    }
}
                        
                    

AutoSuggest

The ServerAPIInstance.autosuggest() method returns a list of 3 word addresses based on user input and other parameters.

This method provides corrections for the following types of input error:

  • typing errors
  • spelling errors
  • misremembered words (e.g. singular vs. plural)
  • words in the wrong order

The autosuggest method determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. This method can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.

Input 3 word address

You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.

Clipping and Focus

We provide various clip policies to allow you to specify a geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend that you use the clip parameter to give a more targeted, shorter set of results to your user. If you know your user’s current location, we also strongly recommend that you use the focus to return results which are likely to be more relevant.

In summary, the clip policy is used to optionally restrict the list of candidate AutoSuggest results, after which, if focus has been supplied, this will be used to rank the results in order of relevancy to the focus.

Language

The lang parameter is mandatory for ServerAPIInstance.autosuggest; we recommend that you set this according to the language of your user interface, or the browser/device language of your user. If your software or app displays 3 word addresses to users (in addition to accepting 3 words as a search/input) then we recommend you set the language parameter for this method to the same language that 3 word addresses are displayed to your users.

Results

A maximum of 10 AutoSuggest results may be returned, but you may choose to display fewer results to your user e.g. the first 3 or 5 (depending on your user interface). By default, 3 results will be returned. It is possible we may increase the number of results returned in the future, so if you choose to limit the list of results returned, we recommend that you choose to include e.g. the top 3/5/7 results rather than choose to exclude the bottom e.g. 8/9/10 results.

Clipping Policies

None default

ClipNone. No clipping takes place; this is the default.

Radius

ClipRadius(LatLng coords, double radius). Clips to a radius of radius kilometers from the point specified as coords.

Bounding Box

ClipBBox(double nelat, double neLng, double swLat, double swlat). Clips to 3 word addresses that are fully contained inside a bounding box, specified by the northeast and southwest corner coordinates.

                        
import com.what3words.LatLng;
import com.what3words.apiinstance.IAPIInstance;
import com.what3words.apiinstance.ServerAPIInstance;
import com.what3words.apiinstance.Suggestion;
import com.what3words.autosuggest.IClip;
import com.what3words.autosuggest.ClipNone;

import java.util.List;

public class Main {
    public static void main(String[] args) {
        String dataPath = "/var/what3words/w3w-data";
        IAPIInstance sdk = new ServerAPIInstance(dataPath);

        String addr = "index.home.ra";
        String lang = "en";
        LatLng focus = new LatLng(51.455905, -0.341492);
        IClip clip = new ClipNone();
        List<Suggestion> = sdk.autosuggest(addr, lang, focus, clip);
    }
}
                        
                    

Get Languages

The ServerAPIInstance.getLoadedLanguages() method allows you to query the what3words SDK for the list of languages that the SDK currently supports.

                        
import com.what3words.apiinstance.IAPIInstance;
import com.what3words.apiinstance.ServerAPIInstance;

import java.util.Set;

public class Main {
    public static void main(String[] args) {
        String dataPath = "/var/what3words/w3w-data";
        IAPIInstance sdk = new ServerAPIInstance(dataPath);

        Set<String> languages = sdk.getLoadedLanguages();
    }
}
                        
                    

Calculate Distance

The what3words SDK provides four helper functions to calculate distances:

  • ServerAPIInstance.distanceToPoint() and ServerAPIInstance.distanceToPointGC() returns the distance between a 3 word address and a given point.
  • ServerAPIInstance.distanceBetweenPoints() and ServerAPIInstance.distanceBetweenPointsGC() returns the distance between two points.

All of these methods return distance in meters. ServerAPIInstance.distanceToPointGC() and ServerAPIInstance.distanceBetweenPointsGC() use the Great Circle algorithm to calculate distance, which gives good accuracy over large distances. ServerAPIInstance.distanceToPoint() and ServerAPIInstance.distanceBetweenPoints() use the Haversine algorithm, which gives accuracy over smaller distances.

                        
import com.what3words.LatLng;
import com.what3words.apiinstance.IAPIInstance;
import com.what3words.apiinstance.ServerAPIInstance;

public class Main {
    public static void main(String[] args) {
        String dataPath = "/var/what3words/w3w-data";
        IAPIInstance sdk = new ServerAPIInstance(dataPath);

        String addr = "index.home.raft";
        LatLng endPoint = new LatLng(64.13577516756123, -21.919784545898438);
        double distance = sdk.distanceToPoint(addr, endPoint);

        LatLng startPoint = new LatLng(51.455905, -0.341492);
        distance = sdk.distanceBetweenPoints(startPoint, endPoint);
    }
}
                        
                    

Sample Application

The what3words SDK provides a sample Java application that initialises the SDK and invokes all the public methods. The sample is located in /var/what3words/sample and can be compiled and run under Gradle using the command $ gradle run.