URI::geo(3)

📦
version 5.310.0 · 15 versions
, in opensuse-leap 16.0

💖 URI::geo 💖

okay bestie, gather round 💅 this is the manual page for URI::geo — the URI scheme for geo Identifiers — and yeah it's a User Contributed Perl Documentation page, but lowkey it's a whole vibe. ✨

🌸 SYNOPSIS 🌸

here's the whole thing in action, no cap:

use URI;

# Geo URI from textual uri
my $guri = URI->new( 'geo:54.786989,-2.344214' );

# From coordinates
my $guri = URI::geo->new( 54.786989, -2.344214 );

# Decode
my ( $lat, $lon, $alt ) = $guri->location;
my $latitude = $guri->latitude;

# Update
$guri->location( 55, -1 );
$guri->longitude( -43.23 );

like… she parses, she builds, she decodes, she updates. main character energy fr fr 👑

🦋 DESCRIPTION 🦋

so this part is straight-up quoted from <http://geouri.org/>, and it's kind of iconic honestly:

More and more protocols and data formats are being extended by methods to add geographic information. However, all of those options are tied to that specific protocol or data format. A dedicated Uniform Resource Identifier (URI) scheme for geographic locations would be independent from any protocol, usable by any software/data format that can handle generich URIs. Like a "mailto:" URI launches your favourite mail application today, a "geo:" URI could soon launch your favourite mapping service, or queue that location for a navigation device.

the way that a geo: URI is protocol-independent… we love a format that plays nice with everyone 🫶

🎀 SUBROUTINES/METHODS 🎀

⭐ new

creates a fresh new URI::geo. the arguments should be either:

  • latitude, longitude and optionally altitude
  • a reference to an array containing lat, lon, alt
  • a reference to a hash with suitably named keys, or
  • a reference to an object with suitably named accessors

and like, to maximize the likelihood that you can pass in literally any object that represents a geographical location and have URI::geo do the right thing, it tries a bunch of different accessor names. detective mode activated 🔍

  • if the object has a latlong method (e.g. Geo::Point) we'll use that.
  • if there's a location method we call that.
  • otherwise we look for accessors called lat, latitude, lon, long, longitude, ele, alt, elevation or altitude and use them.

often if you have an object or hash reference that represents a point you can pass it directly to new — so for example this will work:

use URI::geo;
use Geo::Point;

my $pt = Geo::Point->latlong( 48.208333, 16.372778 );
my $guri = URI::geo->new( $pt );

as will this:

my $guri = URI::geo->new( { lat => 55, lon => -1 } );

and this:

my $guri = URI::geo->new( 55, -1 );

slay, three ways to do the same thing and they all ate 💅

note that you can also create a new URI::geo by passing a Geo URI to URI::new:

use URI;

my $guri = URI->new( 'geo:55,-1' );

⭐ location

get or set the location of this geo URI. 🗺️

my ( $lat, $lon, $alt ) = $guri->location;
$guri->location( 55.3, -3.7, 120 );

when setting the location it is possible to pass any of the argument types that can be passed to new. flexible queen 💖

⭐ latitude

get or set the latitude of this geo URI.

⭐ longitude

get or set the longitude of this geo URI.

⭐ altitude

get or set the altitude <https://en.wikipedia.org/wiki/Geo_URI_scheme#Altitude> of this geo URI. to delete the altitude, set it to undef. (poof, gone 🫥)

⭐ crs

get or set the Coordinate Reference System <https://en.wikipedia.org/wiki/Geo_URI_scheme#Coordinate_reference_systems> of this geo URI. to delete the CRS, set it to undef.

⭐ uncertainty

get or set the uncertainty <https://en.wikipedia.org/wiki/Geo_URI_scheme#Uncertainty> of this geo URI. to delete the uncertainty, set it to undef.

⭐ field

okay so field is literally listed here as a method and that's all the doc says about it — no description given, so i'm not gonna make one up bestie, that's not the vibe 🙈

🌈 CONFIGURATION AND ENVIRONMENT 🌈

URI::geo requires no configuration files and no environment variables. zero setup, she just works ✨

🍓 DEPENDENCIES 🍓

  • URI

💀 DIAGNOSTICS 💀

  • Too many arguments — the new method can only accept three parameters; latitude, longitude and altitude.
  • Don't know how to convert point — the new method doesn't know how to convert the supplied parameters into a URI::geo object.
  • Need lat, lon or lat, lon, alt — the new method needs two (latitude and longitude) or three (latitude, longitude and altitude) parameters in a list. any less or more than this is an error.
  • No such field: %s — this field is not a known field for the URI::geo object.
  • Badly formed geo uri — the URI cannot be parsed as a URI.
  • Badly formed geo uri — the URI cannot be parsed as a URI. (yes bestie, it's listed twice in the original. i don't make the rules, i just report them 😭)
  • Latitude out of range — latitude may only be from -90 to +90.
  • Longitude out of range — longitude may only be from -180 to +180.
⚠️ those range limits are hard limits, so if your latitude or longitude is out of bounds the module will absolutely call it out. respect the range 💅

🧚 INCOMPATIBILITIES 🧚

none reported. we love a drama-free module 🌸

🙈 BUGS AND LIMITATIONS 🙈

to report a bug, or view the current list of bugs, please visit <https://github.com/libwww-perl/URI/issues> — the maintainers wanna hear from you, fr fr 🫶

👑 AUTHOR 👑

Andy Armstrong <andy@hexten.net>

Copyright (c) 2009, Andy Armstrong <andy@hexten.net>.

this module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. see perlartistic.

and that's the whole page, bestie 🎀 written by the perl v5.42.0 crew, dated 2026-09-02 — go forth and geo: your little heart out 💖🦋✨

📦 where this page comes from