.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "URI::geo 3"
.TH URI::geo 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
URI::geo \- URI scheme for geo Identifiers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use URI;
\&
\&  # Geo URI from textual uri
\&  my $guri = URI\->new( \*(Aqgeo:54.786989,\-2.344214\*(Aq );
\&
\&  # 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 );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
From <http://geouri.org/>:
.PP
.Vb 3
\&  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.
.Ve
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.ie n .SS """new"""
.el .SS "\f(CWnew\fP"
.IX Subsection "new"
Create a new URI::geo. The arguments should be either
.IP "\(bu" 4
latitude, longitude and optionally altitude
.IP "\(bu" 4
a reference to an array containing lat, lon, alt
.IP "\(bu" 4
a reference to a hash with suitably named keys or
.IP "\(bu" 4
a reference to an object with suitably named accessors
.PP
To maximize the likelihood that you can pass in some object that
represents a geographical location and have URI::geo do the right thing
we try a number of different accessor names.
.PP
If the object has a \f(CW\*(C`latlong\*(C'\fR method (e.g. Geo::Point) we'll use that.
If there's a \f(CW\*(C`location\*(C'\fR method we call that. Otherwise we look for
accessors called \f(CW\*(C`lat\*(C'\fR, \f(CW\*(C`latitude\*(C'\fR, \f(CW\*(C`lon\*(C'\fR, \f(CW\*(C`long\*(C'\fR, \f(CW\*(C`longitude\*(C'\fR,
\&\f(CW\*(C`ele\*(C'\fR, \f(CW\*(C`alt\*(C'\fR, \f(CW\*(C`elevation\*(C'\fR or \f(CW\*(C`altitude\*(C'\fR and use them.
.PP
Often if you have an object or hash reference that represents a point
you can pass it directly to \f(CW\*(C`new\*(C'\fR; so for example this will work:
.PP
.Vb 2
\&  use URI::geo;
\&  use Geo::Point;
\&
\&  my $pt = Geo::Point\->latlong( 48.208333, 16.372778 );
\&  my $guri = URI::geo\->new( $pt );
.Ve
.PP
As will this:
.PP
.Vb 1
\&  my $guri = URI::geo\->new( { lat => 55, lon => \-1 } );
.Ve
.PP
and this:
.PP
.Vb 1
\&  my $guri = URI::geo\->new( 55, \-1 );
.Ve
.PP
Note that you can also create a new \f(CW\*(C`URI::geo\*(C'\fR by passing a Geo \s-1URI\s0 to
\&\f(CW\*(C`URI::new\*(C'\fR:
.PP
.Vb 1
\&  use URI;
\&
\&  my $guri = URI\->new( \*(Aqgeo:55,\-1\*(Aq );
.Ve
.ie n .SS """location"""
.el .SS "\f(CWlocation\fP"
.IX Subsection "location"
Get or set the location of this geo \s-1URI.\s0
.PP
.Vb 2
\&  my ( $lat, $lon, $alt ) = $guri\->location;
\&  $guri\->location( 55.3, \-3.7, 120 );
.Ve
.PP
When setting the location it is possible to pass any of the argument
types that can be passed to \f(CW\*(C`new\*(C'\fR.
.ie n .SS """latitude"""
.el .SS "\f(CWlatitude\fP"
.IX Subsection "latitude"
Get or set the latitude of this geo \s-1URI.\s0
.ie n .SS """longitude"""
.el .SS "\f(CWlongitude\fP"
.IX Subsection "longitude"
Get or set the longitude of this geo \s-1URI.\s0
.ie n .SS """altitude"""
.el .SS "\f(CWaltitude\fP"
.IX Subsection "altitude"
Get or set the altitude <https://en.wikipedia.org/wiki/Geo_URI_scheme#Altitude> of this geo \s-1URI.\s0 To delete the altitude set it to \f(CW\*(C`undef\*(C'\fR.
.ie n .SS """crs"""
.el .SS "\f(CWcrs\fP"
.IX Subsection "crs"
Get or set the Coordinate Reference System <https://en.wikipedia.org/wiki/Geo_URI_scheme#Coordinate_reference_systems> of this geo \s-1URI.\s0 To delete the \s-1CRS\s0 set it to \f(CW\*(C`undef\*(C'\fR.
.ie n .SS """uncertainty"""
.el .SS "\f(CWuncertainty\fP"
.IX Subsection "uncertainty"
Get or set the uncertainty <https://en.wikipedia.org/wiki/Geo_URI_scheme#Uncertainty> of this geo \s-1URI.\s0 To delete the uncertainty set it to \f(CW\*(C`undef\*(C'\fR.
.ie n .SS """field"""
.el .SS "\f(CWfield\fP"
.IX Subsection "field"
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
URI::geo requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
\&\s-1URI\s0
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """Too many arguments""" 4
.el .IP "\f(CWToo many arguments\fR" 4
.IX Item "Too many arguments"
The new method can only accept three parameters; latitude, longitude and altitude.
.ie n .IP """Don\*(Aqt know how to convert point""" 4
.el .IP "\f(CWDon\*(Aqt know how to convert point\fR" 4
.IX Item "Dont know how to convert point"
The new method doesn't know how to convert the supplied parameters into a URI::geo object.
.ie n .IP """Need lat, lon or lat, lon, alt""" 4
.el .IP "\f(CWNeed lat, lon or lat, lon, alt\fR" 4
.IX Item "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.
.ie n .IP """No such field: %s""" 4
.el .IP "\f(CWNo such field: %s\fR" 4
.IX Item "No such field: %s"
This field is not a known field for the URI::geo object.
.ie n .IP """Badly formed geo uri""" 4
.el .IP "\f(CWBadly formed geo uri\fR" 4
.IX Item "Badly formed geo uri"
The \s-1URI\s0 cannot be parsed as a \s-1URI\s0
.ie n .IP """Badly formed geo uri""" 4
.el .IP "\f(CWBadly formed geo uri\fR" 4
.IX Item "Badly formed geo uri"
The \s-1URI\s0 cannot be parsed as a \s-1URI\s0
.ie n .IP """Latitude out of range""" 4
.el .IP "\f(CWLatitude out of range\fR" 4
.IX Item "Latitude out of range"
Latitude may only be from \-90 to +90
.ie n .IP """Longitude out of range""" 4
.el .IP "\f(CWLongitude out of range\fR" 4
.IX Item "Longitude out of range"
Longitude may only be from \-180 to +180
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
To report a bug, or view the current list of bugs, please visit <https://github.com/libwww\-perl/URI/issues>
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Armstrong  \f(CW\*(C`<andy@hexten.net>\*(C'\fR
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2009, Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.