Common Lisp API for http://what3words.com/
Implementation of the api-functions described at https://docs.what3words.com/api/v2/
Load library and run:
(what3words:position-to-three-words 51.484463 -0.195405 :key "your-w3w-key")
Existing functions:
- three-words-to-position
- position-to-three-words
- get-languages
2016-11-19
- Modified existing functions to work with the v2 api of w3w
- The v1 api of w3w will be disabled on end of November according to the w3w website.
- drakma
(ql:quickload :drakma)
- jsown
(ql:quickload :jsown)
- cl-ppcre
(ql:quickload :cl-ppcre)
(should be already loaded with drakma)
Run the following function after loading the library:
(what3words-test:test "your-w3w-key")
Works on:
- SBCL on Debian GNU/Linux
- CCl on Debian GNU/Linux
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")
(defun three-words-to-position (three-words &key (language nil) (corners nil) (key *key*) (raise-error nil))
three-words
List of three words or string of three words with dots.
language
set to NIL (default) for default language or set language-code as provided fromget-languages
; use only if you want to return 3 words in a different language then the language of the 3 words you submitted (can be used for translation of '3 words')corners
set to NIL (default)for the center-coordinates of the w3w square, set to true for the southwest and northeast coordinates of the squarekey
your w3w api-key,key
is set to what3words:key by defaultraise-error
set to true if you want to raise errors based on the error messages from w3w, set to NIL (default) to get w3w error messages as return value of the function
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/v2/forward
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))
(defun position-to-three-words (latitude longitude &key (language nil) (corners nil) (key *key*) (raise-error nil))
latitude
in degreeslongitude
in degreeslanguage
set to NIL for default language or to language-code (seeget-languages
)- `corners: true for the coordinates of the w3w square, false for the southwest and northeast coordinates of the square
key
your w3w api-key,key
is set to what3words:key by defaultraise-error
set to true if you want to raise errors based on the error messages from w3w, set to NIL (default) to get w3w error messages as return value of the function
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/v2/reverse
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
(defun get-languages (&key (codes-only t) (key *key*) (raise-error nil))
codes-only
if true return a list of language codes, if nil return a-list of language-codes and language-nameskey
your w3w api-key,key
is set to what3words:key by defaultraise-error
set to true if you want to raise errors based on the error messages from w3w, set to NIL (default) to get w3w error messages as return value of the function
API-URL: https://api.what3words.com/v2/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)"))
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:
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.
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.
- SBCL on Debian GNU/Linux
Please see the file LICENSE in the distribution.