NAME

Geo::What3Words - Turn WGS84 coordinates into three words or OneWords and vice-versa using w3w.co HTTP API

VERSION

version 1.0.2

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)

  $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 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('*libertytech');
  # returns '51.512573,-0.144879'

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 'три.пример.слова'

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 1

words_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ñ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.

cpanm Geo::What3Words

perl -MCPAN -e shell
install Geo::What3Words