NAME

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

VERSION

version 2.0.0

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) 2016 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.

cpanm Geo::What3Words

perl -MCPAN -e shell
install Geo::What3Words