what3words

https://github.com/MartinEnders/what3words.git

git clone 'https://github.com/MartinEnders/what3words.git'

(ql:quickload :what3words)
1

Common Lisp API for http://what3words.com/

Implementation of the api-functions described at http://developer.what3words.com/api/

Hello World example

Load library and run: lisp (what3words:position-to-three-words 51.484463 -0.195405 :key "your-w3w-key")

Status

Existing functions:

Dependencies

Test

Run the following function after loading the library: lisp (what3words-test:test "your-w3w-key")

Works on: * SBCL on Debian GNU/Linux * CCl on Debian GNU/Linux

Remarks

To try the examples you have to ‘sign up for API’ on http://developer.what3words.com/ to get your API-key

You can pass the key to the functions through the :key parameter or set the key variable:

(setf what3words:*key* "your-w3w-key")

Convert 3 words to position

(defun three-words-to-position (three-words &key (language nil) (corners nil) (key *key*) (raise-error nil))

returns (multiple return values): * position (list) * type (string) * three words (list) * language (language-code, string) * corners (positions of southwest and northeast corners or nil)

API-URL: https://api.what3words.com/w3w

Examples:

three-words-to-position returns multiple values (coordinates, type, 3-words, corners)

WHAT3WORDS> (three-words-to-position (list "prom" "cape" "pump"))
(51484463/1000000 -39081/200000)
"3 words"
("prom" "cape" "pump")
"en"
NIL
WHAT3WORDS> (three-words-to-position (list "prom" "cape" "pump") :language "de")
(51484463/1000000 -39081/200000)
"3 words"
("scholle" "lohn" "gleichheit") ;; Translation of prom cape pump
"de"
NIL
WHAT3WORDS> (three-words-to-position (list "prom" "cape" "pump") :corners t)
(51484463/1000000 -39081/200000)
"3 words"
("prom" "cape" "pump")
"en"
((51484449/1000000 -97713/500000) (12871119/250000 -195383/1000000))

Convert position to 3 words

(defun position-to-three-words (latitude longitude &key (language nil) (corners nil) (key *key*) (raise-error nil))

returns (multiple return values): * three words (list) * position (list) * language (language-code, string) * corners (positions of southwest and northeast corners or nil)

API-URL: https://api.what3words.com/position

Examples:

position-to-three-words returns multiple values

WHAT3WORDS> (position-to-three-words 51.484463 -0.195405)
("prom" "cape" "pump")
(51484463/1000000 -39081/200000)
"en"
NIL

WHAT3WORDS> (position-to-three-words 51.484463 -0.195405 :language "de")
("scholle" "lohn" "gleichheit")
(51484463/1000000 -39081/200000)
"de"
NIL

WHAT3WORDS> (position-to-three-words 51.484463 -0.195405 :corners t)
("prom" "cape" "pump")
(51484463/1000000 -39081/200000)
"en"
((51484449/1000000 -97713/500000) (12871119/250000 -195383/1000000))

WHAT3WORDS> (format t "~{~A~%~}" (position-to-three-words 51.484463 -0.195405))
prom
cape
pump

WHAT3WORDS> (format t "https://map.what3words.com/~{~A~^+~}" (position-to-three-words 51.484463 -0.195405))
https://map.what3words.com/prom+cape+pump

Get list of available 3 word languages

(defun get-languages (&key (codes-only t) (key *key*) (raise-error nil))

API-URL: https://api.what3words.com/get-languages

WHAT3WORDS> (get-languages)
("de" "en" "es" "fr" "it" "pt" "ru" "sv" "sw" "tr")

WHAT3WORDS> (get-languages :codes-only nil)
(("de" . "Deutsch (beta)") ("en" . "English") ("es" . "Español (beta)")
 ("fr" . "Français (beta)") ("it" . "Italiano (beta)")
 ("pt" . "Português (beta)") ("ru" . "Русский (beta)")
 ("sv" . "Svenska (beta)") ("sw" . "Kiswahili (beta)") ("tr" . "Türkçe (beta)"))
 ```

Exception handling
----------------------

Every API-Function has an optional `raise-error` attribute.
Errors which are controlled by the `raise-error` attribute are the errors listed in the w3w 'Error code list' (http://developer.what3words.com/additional-reference-docs/#apierrorcodes)
If `raise-error` is true then a w3w-api-error is thrown:

```lisp
WHAT3WORDS> (handler-case (let ((*key* "testtest"))
                (get-languages :raise-error t))
          (w3w-api-error (e) 
        (print 'error-handling)
        (print e)
        (print (text e))
        (print (data e))))
          

ERROR-HANDLING 
#<W3W-API-ERROR {1006A60963}> 
"w3w error [X1]: Missing or invalid key" 
("X1" "Missing or invalid key") 
("X1" "Missing or invalid key")
; compiling (DEFPACKAGE #:WHAT3WORDS ...)

If raise-error parameter is NIL (default value) then the error-message from the w3w API is returned as mulitple values (nil, id and description). So if raise-error is NIL then the functions return NIL if an error message is submitted from what3words. lisp WHAT3WORDS> (let ((*key* "testtest")) (get-languages :raise-error nil)) NIL "X1" "Missing or invalid key" WHAT3WORDS>

I use drakma for the https requests and jsown for JSON-parsing so if one of this libraries runs into an exception they will be not handeled by the what3words library.

Development environment

License

Please see the file LICENSE in the distribution.