NAME
Geo::WhatThreeWords - Turn WGS84 coordinates into three words or OneWords and vice-versa using w3w.co HTTP API
VERSION
version 0.8
SYNOPSIS
my $w3w = Geo::WhatThreeWords->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)
$w3w->words2pos('*LibertyTech');
# returns '51.512573,-0.144879'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 their API (http://what3words.com/api/reference) to convert coordinates into those 3 word addresses and back.
You need to register to receive an API key.
METHODS
new
Creates a new instance. The api key is required.
my $w3w = Geo::WhatThreeWords->new( key => 'your-api-key' );
my $w3w = Geo::WhatThreeWords->new( key => 'your-api-key', language => 'ru' );For debugging you can either set logging or provide a callback.
my $w3w = Geo::WhatThreeWords->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::WhatThreeWords->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('*libertytech');
# returns '51.512573,-0.144879'pos2words
Tiny wrapper around position_to_words.
$w3w->pos2words('51.484463,-0.195405');
# returns 'three.example.words'
$w3w->pos2words('51.484463,-0.195405', 'ru');
# returns 'три.пример.слова'valid_words
Returns 3 if the string looks like three words, 1 if it looks like a OneWord. Returns 0 otherwise.
$w3w->valid_words('one.two.three');
# returns 3
$w3w->valid_words('*one-two12');
# return 1words_to_position
Returns a more verbose response than words2pos.
$w3w->words_to_position('prom.cape.pump');
# {
# 'language' => 'en',
# 'position' => [
# '51.484463',
# '-0.195405'
# ],
# 'type' => '3 words',
# 'words' => [
# 'prom',
# 'cape',
# 'pump'
# ]
# },position_to_words
Returns a more verbose response than pos2words.
$w3w->position_to_words('51.484463,-0.195405')
# {
# 'language' => 'en',
# 'position' => [
# '51.484463',
# '-0.195405'
# ],
# 'words' => [
# 'prom',
# 'cape',
# 'pump'
# ]
# }get_languages
Retuns a list of language codes and names.
$w3w->get_languages();
# {
# 'languages' => [
# {
# 'name_display' => 'Deutsch',
# 'code' => 'de'
# },
# {
# 'name_display' => 'English',
# 'code' => 'en'
# },
# {
# 'name_display' => "Espa\x{f1}ol",
# 'code' => 'es'
# },
# ...oneword_available
Checks if a OneWord is available
$w3w->oneword_available('helloworld');
# {
# 'message' => 'Your OneWord is available',
# 'available' => 1
# }INSTALLATION
During installation the test suite will skip any API calls if you're not online (Net::Ping). If that fails you can also try to set the environment variable 'W3W_SKIP_ONLINE'.
AUTHOR
mtmail <mtmail-cpan@gmx.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Lokku 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.