NAME

Geo::WebService::Elevation::USGS - Elevation queries against USGS web services.

SYNOPSIS

use Geo::WebService::Elevation::USGS;

my $eq = Geo::WebService::Elevation::USGS->new();
print "The elevation of the White House is ",
  $eq->elevation( 38.898748, -77.037684 )->{Elevation},
  " feet above sea level.\n";

NOTICE

Some time while I was not looking the USGS changed the web address and the API for the point elevation service yet again.

I have dealt with this by resurrecting the compatible attribute and defaulting it to a true value. This attribute affects the hash returned by the elevation() method. See that method's documentation for the gory details.

You are encouraged to set this attribute to a false value as soon as you can, since my long-term plan is to discourage a true value, and then ultimately deprecate and remove it.

DESCRIPTION

This module executes elevation queries against the United States Geological Survey's Elevation Data Point Service. You provide the latitude and longitude in degrees, with south latitude and west longitude being negative. The return is typically a hash containing the data you want. Query errors are exceptions by default, though the object can be configured to signal an error by an undef response, with the error retrievable from the 'error' attribute.

For documentation on the underlying web service, see https://www.usgs.gov/programs/national-geospatial-program/national-map, particularly https://epqs.nationalmap.gov/v1/docs.

For all methods, the input latitude and longitude are documented at the above web site as being WGS84, which for practical purposes I understand to be equivalent to NAD83. The vertical reference is not documented under the above link, but correspondence with the USGS says that it is derived from the National Elevation Dataset (NED; see https://www.usgs.gov/programs/national-geospatial-program/national-map). This is referred to NAD83 (horizontal) and NAVD88 (vertical). NAVD88 is based on geodetic leveling surveys, not the WGS84/NAD83 ellipsoid, and takes as its zero datum sea level at Father Point/Rimouski, in Quebec, Canada. Alaska is an exception, and is based on NAD27 (horizontal) and NAVD29 (vertical).

Anyone interested in the gory details may find the paper Converting GPS Height into NAVD88 Elevation with the GEOID96 Geoid Height Model by Dennis G. Milbert, Ph.D. and Dru A. Smith, Ph.D helpful. This is available at https://www.ngs.noaa.gov/PUBS_LIB/gislis96.html. This paper states that the difference between ellipsoid and geoid heights ranges between -75 and +100 meters globally, and between -53 and -8 meters in "the conterminous United States."

Methods

The following public methods are provided:

$eq = Geo::WebService::Elevation::USGS->new();

This method instantiates a query object. If any arguments are given, they are passed to the set() method. The instantiated object is returned.

%values = $eq->attributes();

This method returns a list of the names and values of all attributes of the object. If called in scalar context it returns a hash reference.

$rslt = $usgs->elevation($lat, $lon, $valid);

This method queries the data base for the elevation at the given latitude and longitude, returning the results as a hash reference.

If the compatible attribute is true, this hash will contain the following keys:

{Data_Source} => A text description of the data source (always 'USGS Elevation Point Query Service');
{Elevation} => The elevation in the given units;
{Units} => The units of the elevation ('Feet' or 'Meters');
{x} => The $lon argument;
{y} => The $lat argument.

If the compatible attribute is false, the hash will contain the values documented at https://epqs.nationalmap.gov/v1/docs. Note that the elevation comes back in key {value}. For my own sanity key {Elevation} is added to this hash; it contains the value of {value}, rounded to places if that attribute is set.

You can also pass a Geo::Point, GPS::Point, or Net::GPSD::Point object in lieu of the $lat and $lon arguments. If you do this, $valid becomes the second argument, rather than the third.

If the optional $valid argument is specified as a true value and the returned data are invalid, nothing is returned. The source does not seem to produce data recognizable as invalid, so you will probably not see this.

$value = $eq->get($attribute);

This method returns the value of the given attribute. It will croak if the attribute does not exist.

$rslt = $eq->getAllElevations($lat, $lon, $valid);

This method was removed in version 0.116_01. Please use the elevation() method instead. See the NOTICE above for details.

$rslt = $eq->getElevation($lat, $lon, $source, $elevation_only);

This method was removed in version 0.116_01. Please use the elevation() method instead. See the NOTICE above for details.

$boolean = $eq->is_valid($elevation);

This method (which can also be called as a static method or as a subroutine) returns true if the given datum represents a valid elevation, and false otherwise. A valid elevation is a number having a value greater than -1e+300. The input can be either an elevation value or a hash whose {Elevation} key supplies the elevation value.

Note that as of June 11 2024 I am unable to find any documentation to support this method. Therefore use of this method is discouraged, and it will deprecated and removed when I drop support for the compatible attribute.

$eq = $eq->set($attribute => $value ...);

This method sets the value of the given attribute. Multiple attribute/value pairs may be specified. The object itself is returned, to allow call chaining. An attempt to set a non-existent attribute will result in an exception being thrown.

Attributes

carp

Boolean

This Boolean attribute determines whether the data acquisition methods carp on encountering an error. If false, they silently return undef. Note, though, that the croak attribute trumps this one.

If retry is set to a number greater than 0, you will get a carp on each failed query, provided croak is false. If croak is true, no retries will be carped.

This attribute was introduced in Geo::WebService::Elevation::USGS version 0.005_01.

The default is 0 (i.e. false).

compatible

This attribute was removed in version 0.116_01. It existed to support interaction with the now-long-defunct GIS web service. See the NOTICE above for details.

croak

Boolean

This Boolean attribute determines whether the data acquisition methods croak on encountering an error. If false, they return undef on an error.

If retry is set to a number greater than 0, the data acquisition method will not croak until all retries are exhausted.

The default is 1 (i.e. true).

default_ns

This attribute was removed in version 0.116_01. It existed to support interaction with the now-long-defunct GIS web service. See the NOTICE above for details.

error

String

This attribute records the error returned by the last query operation, or undef if no error occurred. This attribute can be set by the user, but will be reset by any query operation.

The default (before any queries have occurred) is undef.

places

Integer

If this attribute is set to a non-negative integer, elevation results will be rounded to this number of decimal places by running them through sprintf "%.${places}f".

The default is undef.

proxy

This attribute was removed in version 0.116_01. It existed to support interaction with the now-long-defunct GIS web service. See the NOTICE above for details.

retry

Unsigned integer

This attribute specifies the number of retries to be done by elevation() when an error is encountered. The first try is not considered a retry, so if you set this to 1 you get a maximum of two queries (the try and the retry).

Retries are done only on actual errors, not on bad extents. They are also subject to the "throttle" setting if any.

The default is 0, i.e. no retries.

retry_hook

Code reference

This attribute specifies a piece of code to be called before retrying. The code will be called before a retry takes place, and will be passed the Geo::WebService::Elevation::USGS object, the number of the retry (from 1), the name of the method being retried ('elevation' and the arguments to that method. If the position was passed as an object, the hook gets the latitude and longitude unpacked from the object. The hook will not be called before the first try, nor after the last retry.

Examples:

# To sleep 5 seconds between retries:
$eq->set( retry_hook => sub { sleep 5 } );

# To sleep 1 second before the first retry, 2 seconds
# before the second, and so on:
$eq->set( retry_hook => sub { sleep $_[1] } );

# To do nothing between retries:
$eq->set( retry_hook => sub {} );

The default is the null subroutine, i.e. sub {}.

source

This attribute was removed in version 0.116_01. It existed to support interaction with the now-long-defunct GIS web service. See the NOTICE above for details.

throttle

Non-negative number, or undef

Geo::WebService::Elevation::USGS->set( throttle => 5 );

This attribute, if defined and positive, specifies the minimum interval between queries, in seconds. This attribute may be set statically only, and the limit applies to all queries, not just the ones from a given object. If Time::HiRes can be loaded, then sub-second intervals are supported, otherwise not.

This functionality, and its implementation, are experimental, and may be changed or retracted without notice. Heck, I may even go back to $TARGET, though I don't think so.

timeout

Integer, or undef

This attribute specifies the timeout for the query in seconds.

The default is 30.

trace

Boolean

If true, this Boolean attribute requests that network requests and responses be dumped to standard error. This should only be used for troubleshooting, and the author makes no representation about and has no control over what output you get if you set this true.

The default is undef (i.e. false).

units

String

This attribute specifies the desired units for the resultant elevations. Valid values are 'Feet' and 'Meters'. In practice these are not case-sensitive, and any value other than case-insensitive 'Meters' will be taken as 'Feet'.

The default is 'FEET', but this will become 'Feet' when the compatibility code goes away.

use_all_limit

This attribute was removed in version 0.116_01. It existed to support interaction with the now-long-defunct GIS web service. See the NOTICE above for details.

usgs_url

This attribute specifies the URL to query. Under normal circumstances you will not need to change this, but maybe it can get you going again if the USGS moves the service.

The default is the value of environment variable GEO_WEBSERVICE_ELEVATION_USGS_URL. If that is undefined, the default is https://epqs.nationalmap.gov/v1/json. Note that without query parameters this URL does nothing useful. See https://www.usgs.gov/programs/national-geospatial-program/national-map for details.

ACKNOWLEDGMENTS

The author wishes to acknowledge the following individuals and groups.

The members of the geo-perl mailing list provided valuable suggestions and feedback, and generally helped me thrash through such issues as how the module should work and what it should actually be called.

Michael R. Davis provided prompt and helpful feedback on a testing problem in my first module to rely heavily on Test::More.

BUGS

Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Geo-WebService-Elevation-USGS, https://github.com/trwyant/perl-Geo-WebService-Elevation-USGS/issues, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III; wyant at cpan dot org

COPYRIGHT AND LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

To install Geo::WebService::Elevation::USGS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Geo::WebService::Elevation::USGS

CPAN shell

perl -MCPAN -e shell
install Geo::WebService::Elevation::USGS

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

NOTICE

DESCRIPTION

Methods

$eq = Geo::WebService::Elevation::USGS->new();

%values = $eq->attributes();

$rslt = $usgs->elevation($lat, $lon, $valid);

$value = $eq->get($attribute);

$rslt = $eq->getAllElevations($lat, $lon, $valid);

$rslt = $eq->getElevation($lat, $lon, $source, $elevation_only);

$boolean = $eq->is_valid($elevation);

$eq = $eq->set($attribute => $value ...);

Attributes

carp

compatible

croak

default_ns

error

places

proxy

retry

retry_hook

source

throttle

timeout

trace

units

use_all_limit

usgs_url

ACKNOWLEDGMENTS

BUGS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions