NAME

Geo::OLC - API for Google's Open Location Codes

SYNOPSIS

Open Location Codes are a Google-created method of reducing a Latitude/Longitude pair to a short string. This module implements the recommended API from https://github.com/google/open-location-code

    use Geo::OLC qw(encode decode shorten recover_nearest);
    use Geo::OLC qw(:all);

    $code = encode(34.6681375,135.502765625,11);
    # '8Q6QMG93+742'

    $ref = decode('8Q6QMG93+742');
    # @{$ref->{center}} == (34.6681375,135.502765625)

    $short = shorten('8Q6QMG93+742',34.6937048,135.5016142);
    # 'MG93+742' ("...in Osaka")
    $short = shorten('8Q6QMG93+742',34.6788184,135.4987303);
    # '93+742' ("...in Chuo Ward, Osaka")

    $full = recover_nearest('XQP5+',35.0060799,135.6909098);
    # '8Q6QXQP5+' (Kyoto Station, "XQP5+ in Kyoto")

By default, Geo::OLC does not export any functions.

FUNCTIONS

is_valid($code)

Returns 1 if $code is a valid short, full, or zero-padded OLC.

is_short($code)

Returns 1 if $code is a valid shortened code.

is_full($code)

Returns 1 if $code is a valid full-length code, and has lat < 90 and lon < 180.

encode($lat,$lon,[$len])

Encodes a location as OLC. $len can be 2, 4, 6, 8, 10, or 11-16. The default $len is 10, which is approximately 13.9x13.9 meters at the equator; 11 brings that down to 3.5x2.8 meters, and 12 is about 0.9x0.6 meters, so there's not much point in going past that. I only go to 16 because there's a test case for the Ruby API that uses 15.

decode($code)

Decodes a valid OLC into its location, returned as three pairs of lat/lon coordinates, plus the length of the original code. 'lower' and 'upper' are the bounding-box of the OLC grid, and 'center' is the target location.

  $ref = decode('8Q6QMG93+742');

  $ref = {
    lower => [34.668125,135.50275],
    center=> [34.6681375,135.502765625],
    upper => [34.66815,135.50278125],
    length=> 11,
  };

shorten($code,$latref,$lonref)

Shortens a valid full-length code based on the reference location; returns the original code if it can't be shortened.

Note that removing 2 or 8 digits is not necessarily practical, since there may not be useful names for the area covered, but it's necessary for API testing. I recommend using shorten46() instead.

shorten46($code,$latref,$lonref)

Shortens a valid full-length code by 4 or 6 digits, based on the reference location.

recover_nearest($shortcode,$latref,$lonref)

Converts a shortened OLC back into a full-length code, using the reference location to supply the missing digits. Note that the resulting code will not necessarily have the same leading digits as the reference location, if it's not in the same grid.

_code_digits($code)

Returns number of non-padded digits in a code; used internally by shorten() and shorten46(), and useful for testing.

AUTHOR

J Greely, <jgreely at cpan.org>

LOCATIONS

8Q6QMG93+742 is Tenka Gyoza in Osaka, home of the best one-bite gyoza you'll ever devour multiple plates of ("+742 Dotonbori Osaka").

8FW4V75V+ is the Eiffel Tower ("V75V+ Paris").

86HJW8XV+ is Wrigley Field ("W8XV+8Q Chicago").

849VCRVJ+CHV is a pair of ATMs at Stanford Mall, Palo Alto, CA ("CRVJ+CHV Palo Alto").

BUGS

The off-by-one-cell code in recover_nearest() is largely untested, because there are no test cases for it. The "XQP5+ in Kyoto" case in the synopsis is a simple test I came up with, since most of Kyoto is in 8Q7Q0000+, but the station is just across the border in 8Q6Q0000+.

cpanm Geo::OLC

perl -MCPAN -e shell
install Geo::OLC