https://github.com/opencagedata/perl-geo-what3words
Perl module to access the what3words.com HTTPS API
https://github.com/opencagedata/perl-geo-what3words
perl what3words
Last synced: 2 months ago
JSON representation
Perl module to access the what3words.com HTTPS API
- Host: GitHub
- URL: https://github.com/opencagedata/perl-geo-what3words
- Owner: OpenCageData
- Created: 2014-07-24T16:59:33.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2024-06-17T18:54:55.000Z (12 months ago)
- Last Synced: 2024-06-17T20:55:02.128Z (12 months ago)
- Topics: perl, what3words
- Language: Perl
- Homepage: https://metacpan.org/pod/Geo::What3Words
- Size: 111 KB
- Stars: 3
- Watchers: 9
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.mkdn
- Changelog: CHANGES
- Security: SECURITY.md
Awesome Lists containing this project
README
# NAME
Geo::What3Words - turn WGS84 coordinates into three word addresses and vice-versa using what3words.com HTTPS API
[](https://github.com/OpenCageData/perl-Geo-What3Words/actions/workflows/ci.yml)[](https://metacpan.org/pod/Geo::What3Words)
# VERSION
version 3.0.3
# 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 3 (https://docs.what3words.com/public-api/)
to convert coordinates into 3 word addresses (forward) and 3
words into coordinates (reverse).
Versions 1 and 2 are deprecated and are no longer supported.
You need to sign up at http://what3words.com/login and then register for
an API key at https://developer.what3words.com
# 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');
# {
# 'coordinates' => {
# 'lat' => '51.484463',
# 'lng' => '-0.195405'
# },
# 'country' => 'GB',
# 'language' => 'en',
# 'map' => 'https://w3w.co/prom.cape.pump',
# 'nearestPlace' => 'Kensington, London',
# 'square' => {
# 'northeast' => {
# 'lat' => '51.484476',
# 'lng' => '-0.195383'
# },
# 'southwest' => {
# 'lat' => '51.484449',
# 'lng' => '-0.195426'
# }
# },
# 'words' => 'prom.cape.pump'
# };
## position\_to\_words
Returns a more verbose response than pos2words.
$w3w->position_to_words('51.484463,-0.195405')
# {
# 'coordinates' => {
# 'lat' => '51.484463',
# 'lng' => '-0.195405'
# },
# 'country' => 'GB',
# 'language' => 'en',
# 'map' => 'https://w3w.co/prom.cape.pump',
# 'nearestPlace' => 'Kensington, London',
# 'square' => {
# 'northeast' => {
# 'lat' => '51.484476',
# 'lng' => '-0.195383'
# },
# 'southwest' => {
# 'lat' => '51.484449',
# 'lng' => '-0.195426'
# }
# },
# 'words' => 'prom.cape.pump'
# };
## get\_languages
Retuns a list of language codes and names.
$w3w->get_languages();
# {
# 'languages' => [
# {
# 'name' => 'German',
# 'nativeName' => 'Deutsch',
# 'code' => 'de'
# },
# {
# 'name' => 'English',
# 'nativeName' => 'English',
# 'code' => 'en'
# },
# {
# 'name' => "Spanish",
# 'nativeName' => "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= perl t/base.t
# AUTHOR
mtmail
# COPYRIGHT AND LICENSE
This software is copyright (c) 2021 by OpenCage GmbH.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.