Perl CPAN module to turn WGS84 coordinates into three word addresses and vice-versa using what3words.com HTTPS API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib/Geo
t
.gitignore
.travis.yml
CHANGES
README.mkdn
README2.md
dist.ini

README.mkdn

NAME

Geo::What3Words - turn WGS84 coordinates into three word addresses and vice-versa using what3words.com HTTPS API

VERSION

version 2.1.1

SYNOPSIS

my $w3w = Geo::What3Words->new();

$w3w->pos2words('51.484463,-0.195405');
# returns 'three.example.words'

$w3w->pos2words('51.484463,-0.195405', 'ru');
# returns 'три.пример.слова'

$w3w->words2pos('three.example.words');
# returns '51.484463,-0.195405' (latitude,longitude)

DESCRIPTION

what3words (http://what3words.com/) divides the world into 57 trillion squares of 3 metres x 3 metres. Each square has been given a 3 word address comprised of 3 words from the dictionary.

This module calls API version 2 (https://docs.what3words.com/api/v2/) to convert coordinates into those 3 word addresses (forward) and 3 words into coordinates (reverse).

Version 1 is deprecated and will stop working December 2016.

You need to sign up at http://what3words.com/login and then register for an API key at http://what3words.com/api/signup”

METHODS

new

Creates a new instance. The api key is required.

my $w3w = Geo::What3Words->new( key => 'your-api-key' );
my $w3w = Geo::What3Words->new( key => 'your-api-key', language => 'ru' );

For debugging you can either set logging or provide a callback.

my $w3w = Geo::What3Words->new( key => 'your-api-key', logging => 1 );
# will print debugging output to STDOUT

my $callback = sub { my $msg = shift; $my_log4perl_logger->info($msg) };
my $w3w = Geo::What3Words->new( key => 'your-api-key', logging => $callback );
# will log with log4perl.

ping

Check if the remote server is available. This is helpful for debugging or testing, but too slow to run for every conversion.

$w3w->ping();

words2pos

Tiny wrapper around words_to_position.

$w3w->words2pos('three.example.words');
# returns '51.484463,-0.195405' (latitude,longitude)

$w3w->words2pos('does.not.exist');
# returns undef

pos2words

Tiny wrapper around position_to_words.

$w3w->pos2words('51.484463,-0.195405'); # latitude,longitude
# returns 'three.example.words'

$w3w->pos2words('51.484463,-0.195405', 'ru');
# returns 'три.пример.слова'

$w3w->pos2words('invalid,coords');
# returns undef

valid_words_format

Returns 1 if the string looks like three words, 0 otherwise. Does not call the remote API.

$w3w->valid_words_format('one.two.three');
# returns 1

words_to_position

Returns a more verbose response than words2pos.

$w3w->words_to_position('prom.cape.pump');
# {
#   "crs": {
#     "type": "link",
#     "properties": {
#       "href": "http://spatialreference.org/ref/epsg/4326/ogcwkt/",
#       "type": "ogcwkt"
#     }
#   },
#   "words": "prom.cape.pump",
#   "bounds": {
#     "southwest": {
#       "lng": "-0.195426",
#       "lat":"51.484449"
#     },
#     "northeast": {
#       "lng": "-0.195383",
#       "lat": "51.484476"
#     }
#   },
#   "geometry": {
#     "lng": "-0.195405",
#     "lat": "51.484463"
#   },
#   "language": "en",
#   "map": "http://w3w.co/prom.cape.pump",
#   "status": {
#     "status": 200,
#     "reason": "OK"
#   },
#   "thanks": "Thanks from all of us at index.home.raft for using a what3words API"
# }

position_to_words

Returns a more verbose response than pos2words.

$w3w->position_to_words('51.484463,-0.195405')
# {
#   "crs": {
#     "type": "link",
#     "properties": {
#       "href": "http://spatialreference.org/ref/epsg/4326/ogcwkt/",
#       "type": "ogcwkt"
#     }
#   },
#   "words": "prom.cape.pump",
#   "bounds": {
#     "southwest": {
#       "lng": "-0.195426",
#       "lat": "51.484449"
#     },
#     "northeast": {
#       "lng": "-0.195383",
#       "lat": "51.484476"
#     }
#   },
#   "geometry": {
#     "lng": "-0.195405",
#     "lat": "51.484463"
#   },
#   "language": "en",
#   "map": "http://w3w.co/prom.cape.pump",
#   "status": {
#     "status": 200,
#     "reason": "OK"
#   },
#   "thanks": "Thanks from all of us at index.home.raft for using a what3words API"
# }

get_languages

Retuns a list of language codes and names.

$w3w->get_languages();
# {
#     'languages' => [
#                      {
#                        'name' => 'German',
#                        'name_native' => 'Deutsch',
#                        'code' => 'de'
#                      },
#                      {
#                        'name' => 'English',
#                        'name_native' => 'English',
#                        'code' => 'en'
#                      },
#                      {
#                        'name' => "Spanish",
#                        'name_native' => "Español",
#                        'code' => 'es'
#                      },
# ...

INSTALLATION

The test suite will use pre-recorded API responses. If you suspect something changed in the API you can force the test suite to use live requests with your API key

PERLLIB=./lib W3W_RECORD_REQUESTS=1 W3W_API_KEY=<your key> perl t/base.t

AUTHOR

mtmail mtmail-cpan@gmx.net

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by OpenCage Data Limited.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.