Unofficial Java wrapper for what3words.com API to convert 3 word addresses into coordinates and vice versa

I was fascinated by the idea of three-word addresses, which is the basis of the site what3words.com. But I want to realise the library to another way than official package provides.

Acquire

Please add dependency to your project:

<dependency>
  <groupId>uk.bot-by.3wa</groupId>
  <artifactId>what3words-api</artifactId>
  <version><!-- check releases page --></version>
</dependency>

Usage

Instantiate an instance of What3Words with Feign

api = Feign.builder()
           .client(new Http2Client())
           .decoder(new What3WordsDecoder())
           .errorDecoder(new What3WordsErrorDecoder())
           .requestInterceptor(new KeyInterceptor("qwerty-api-key"))
           .target(What3Words.class, What3Words.W3W_API);

This is a minimal configuration and KeyInterceptor is optional: you can put an API key in request data.

Convert coordinates to 3 word address

WordsRequest wordsRequest = WordsRequest.builder()
                                        .coordinates(51.381051d, -2.359591d)
                                        .language(Language.builder()
                                                          .code("uk")
                                                          .build())
                                        .build();

Words words = api.convertToAddress(wordsRequest).getWords();

It converts coordinates of Roman Baths to Ukrainian words ///зрання.поїздка.зрізаний.

The language is optional: if you do not add it then what3words returns English words ///spring.tops.issued.

Convert 3 word address into coordinates

CoordinatesRequest coordinatesRequest = CoordinatesRequest.builder()
                                                          .words("filled.count.soap")
                                                          .build();

Coordinates coordinates = api.convertToCoordinates(coordinatesRequest).getCoordinates();

It returns well known coordinates of the what3words's office.

Get available languages

Collection<Language> languages = api.availableLanguages();

or with explicit API key

Collection<Language> languages = api.availableLanguages("xyz-api-key");

Contributing

Please read Contributing.

History

See Changelog

License

Copyright 2021,2022 Witalij Berdinskich

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Apache License v2.0