Tooling Tuesday: What 3 Words?

What 3 words make you excited?

For me it could be...

Greggs and Poundland

But there is another use of the phrase, and it relates to finding places to eat, visit etc.

So what is it?

What3words is

"what3words provides a precise and incredibly simple way to talk about location. We have divided the world into a grid of 3m x 3m squares and assigned each one a unique 3 word address."

eh?

Ok so say you wanted to go to Blackpool Tower, I could give you the latitude and longitude, a post code (zip code for American readers) but you might forget it! So I can give you three words, that can be used to go directly to that location on a map.

So here are the three words for Blackpool Tower ///gasp.social.kicks

This Python library is a wrapper, and it can be found on their Github page.

So why is this interesting?

Well dear reader, what3words have a Python library that we can use. All we need to do is sign up for a developer account and install the library.

So how do I install it?

Using the pip package manager!

On Linux

sudo pip3 install what3words

On Windows

pip3.exe install what3words

Get a developer account!

Head over to https://accounts.what3words.com/register and sign up. It's free!

Then create a new app and when done the API key will be ready for use!

So can you show me how to use it?

Sure!

Forward Geocode

This means that we feed the library the three words for our chosen location, for example gasp.social.kicks and it will spit out the longitude and latitude for that location.

In your favourite Python editor, import the library.

import what3words

Give it your secret API key, remember no sharing!

api_key = 'super secret thing'

Create an object with which we can use the what3words library via our API key.

w3w = what3words.Geocoder(api_key)

location = w3w.forward(addr='gasp.social.kicks')
print(location)

Running that code spits the following out...

{'language': 'en', 'words': 'gasp.social.kicks', 'thanks': 'Thanks from all of us at index.home.raft for using a what3words API', 'status': {'reason': 'OK', 'status': 200}, 'bounds': {'southwest': {'lat': 53.815869, 'lng': -3.055327}, 'northeast': {'lat': 53.815896, 'lng': -3.055281}}, 'crs': {'type': 'link', 'properties': {'href': 'http://spatialreference.org/ref/epsg/4326/ogcwkt/', 'type': 'ogcwkt'}}, 'map': 'http://w3w.co/gasp.social.kicks', 'geometry': {'lat': 53.815882, 'lng': -3.055304}}

This is a Python dictionary, a way of storing data using a key. In fact this is a dictionary of dictionaries. So lets get the latitude and longitude from this.

print(location['geometry']['lat'])

Returns 53.815882
and...

print(location['geometry']['lng'])

Returns -3.055304

And a quick check with Google Maps shows that we have found Blackpool Tower

Reverse Geocode

So we have some longitude and latitude co-ordinates that we would like to translate into what3words.

Where would this be useful? Well we could use a GPS device to record our position and then automatically translate that into what3words. You could even create a tracker that records the what3words position every x minutes and it is saved into a dictionary of dictionaries that can be used to follow the places that a device (or person if you are evil) visits. But I'd rather use it for what3word geocaching!

The code to perform a reverse geocode is the same as forward. We just change the function to use reverse, and supply the latitude and longitude.

import what3words
api_key = 'Super Secret API Key'
w3w = what3words.Geocoder(api_key)
location = w3w.reverse(lat=53.815882, lng=-3.055304)
print(location)

Again the location object is a dictionary that stores all the data.

{'status': {'status': 200, 'reason': 'OK'}, 'thanks': 'Thanks from all of us at index.home.raft for using a what3words API', 'bounds': {'northeast': {'lat': 53.815896, 'lng': -3.055281}, 'southwest': {'lat': 53.815869, 'lng': -3.055327}}, 'language': 'en', 'map': 'http://w3w.co/gasp.social.kicks', 'geometry': {'lat': 53.815882, 'lng': -3.055304}, 'words': 'gasp.social.kicks', 'crs': {'properties': {'href': 'http://spatialreference.org/ref/epsg/4326/ogcwkt/', 'type': 'ogcwkt'}, 'type': 'link'}}

So using the dictionary key map we can return the URL for the what3words webpage that relates to that location, and using the webbrowser Python library we can open our favourite browser to the what3words site.

Never heard of the Python webbrowser library? That's ok, I wrote another Tuesday tooling post about it, so you can catch up here.

import what3words
import webbrowser
api_key = 'RINCKDOB'
w3w = what3words.Geocoder(api_key)
location = w3w.reverse(lat=53.815882, lng=-3.055304)
print(location['map'])
webbrowser.open_new_tab(location['map'])

So there we have it!

What3words is a little niche, but it can be an interesting way to create geocache / hiking routes. Record where people have been (obviously do this legally with their consent) for replay. This library used with a GPS device would make an awesomely simple project for class!

Happy Hacking!