python-altimeter Documentation - Read the Docs

python-altimeter DocumentationRelease 0.1.1Bruno Miguel CustódioNovember 06, 2012

CONTENTSi

python-altimeter Documentation, Release 0.1.1The python-altimeter package acts as a wrapper around the Google Elevation API. From the API’s official documentation:The Elevation API provides elevation data for all locations on the surface of the earth, including depthlocations on the ocean floor (which return negative values). In those cases where Google does not possessexact elevation measurements at the precise location you request, the service will interpolate and returnan averaged value using the four nearest locations.With the Elevation API, you can develop hiking and biking applications, mobile positioning applications,or low resolution surveying applications.CONTENTS 1

python-altimeter Documentation, Release 0.1.12 CONTENTS

CHAPTERONECONTENTS1.1 QuickstartThe python-altimeter package requires one of the following versions of Python:• Python 2.6• Python 2.7• Python 3.1• Python 3.2• Python 3.3Furthermore, it depends on the external requests package, which gets automatically installed when following any ofthe below methods. However, if you’re installing python-altimeter by different means make sure you install requestsproperly:pip install requests==0.14.11.1.1 InstallingYou can use pip to install python-altimeter:pip install altimeterAlternatively, you can checkout the code or download a tarball from the repository and install it using setup.py:python setup.py install1.1.2 Testingpython-altimeter comes with a full test suite. To run this test suite against your installation you can use setup.py:python setup.py test1.2 Featurespython-altimeter let’s you query the Google Elevation API in two different ways:3

python-altimeter Documentation, Release 0.1.1• Request elevation data for one or more points on the surface of the Earth (a positional request);• Request elevation data for a set of equidistant points sampled along the length of a path (a path request).1.2.1 Positional requestsTo make a positional request to the Google Elevation API you need to instantiate a GoogleElevationClientand call its positional method with a list of tuples representing valid coordinates:from altimeter.core import GoogleElevationClientclient=GoogleElevationClient()points=[(39.7391536, -104.9847034), (36.455556, -116.866667)]results=client.positional(points)The above commands will assign to results a list of GoogleElevationResult objects containing the resultsof your query:[, ]1.2.2 Path requestsMaking a path request to the Google Elevation API is pretty similar to making a positional request, with two subtledifferences: you must use the path method instead of positional, and you must supply as the first parameter aninteger representing the number of samples you want to obtain elevation data for:from altimeter.core import GoogleElevationClientclient=GoogleElevationClient()samples=3points=[(36.578581, -118.291994), (36.23998, -116.83171)]results=client.path(samples, points)Just as with the above example, these commands will assign to results a list of GoogleElevationResultobjects containing the results of your query:[, ,

python-altimeter Documentation, Release 0.1.11.2.4 Request timeoutsBoth positional and path take an optional float argument, timeout, which can be used to define the amountof time (in seconds) python-altimeter should wait before giving up on establishing a connection with the GoogleElevation API. The default value for timeout is 60 seconds.from altimeter.core import GoogleElevationClientclient=GoogleElevationClient()points=[(39.7391536, -104.9847034), (36.455556, -116.866667)]results=client.positional(points, timeout=5)Please note that the value of the timeout parameter only affects the connection process itself, not the download ofthe results themselves.1.3 API Reference1.3.1 GoogleElevationClientThe GoogleElevationClient object used to query the API exposes the following methods:altimeter.core.GoogleElevationClient.positional(coordinates, sensor=False, timeout=60)Requests elevation data for all the points in coordinates. coordinates must be a list containing tuples of coordinatesexpressed in decimal degrees. The sensor parameter, a boolean defaulting to False, indicates whetherthe application making the request is using a sensor (e.g., a GPS device) to determine the user’s location. Thetimeout parameter, an integer defaulting to 60, can be used to define the amount of time (in seconds) the methodshould wait before giving up on establishing a connection with the API.Returns a list of GoogleElevationResult objects containing the requested elevation data.altimeter.core.GoogleElevationClient.path(samples, coordinates, sensor=False, timeout=60)Requests elevation data for a set of samples equidistant points sampled along the length of a path defined bycoordinates. samples must be an integer greater than or equal to 2, while coordinates must be a list containingtuples of coordinates expressed in decimal degrees. The sensor parameter, a boolean defaulting to False,indicates whether the application making the request is using a sensor (e.g., a GPS device) to determine theuser’s location. The timeout parameter, an integer defaulting to 60, can be used to define the amount of time (inseconds) the method should wait before giving up on establishing a connection with the API.Returns a list of GoogleElevationResult objects containing the requested elevation data.1.3.2 GoogleElevationResultA GoogleElevationResult object has three main attributes:altimeter.core.GoogleElevationResult.elevationA float representing the elevation (in meters) of the associated coordinates.altimeter.core.GoogleElevationResult.locationA GoogleElevationLocation object containing the location associated with the query.altimeter.core.GoogleElevationResult.resolutionA float representing the maximum distance (in meters) between data points from which the elevation was interpolated(being None if this value is not known).1.3. API Reference 5

python-altimeter Documentation, Release 0.1.11.3.3 GoogleElevationLocationA GoogleElevationLocation object has two main attributes:altimeter.core.GoogleElevationLocation.latitudeA float representing the latitude of the location associated with the query.altimeter.core.GoogleElevationLocation.longitudeA float representing the longitude of the location associated with the query.1.3.4 ExceptionsAll exceptions explicitly raised by python-altimeter derive from either ValueError (used for signaling argumentvalidation errors) or altimeter.exceptions.AltimeterError (used for signaling errors in the request process).class altimeter.exceptions.AltimeterErrorActs as a base class for all errors thrown by the library. Never is it raised explicitly.class altimeter.exceptions.BadRequestErrorIndicates that a bad request has been made to the Google Elevation API. Derives fromaltimeter.exceptions.AltimeterError.class altimeter.exceptions.CommunicationErrorIndicates that there has been an error while processing the request to the Google Elevation API. Derives fromaltimeter.exceptions.AltimeterError.class altimeter.exceptions.GoogleElevationApiErrorActs as a base class for all errors thrown by the Google Elevation API. Derives fromaltimeter.exceptions.AltimeterErrorclass altimeter.exceptions.InvalidRequestErrorIndicates that the request to the Google Elevation API was malformed. Derives fromaltimeter.exceptions.GoogleElevationApiError.class altimeter.exceptions.OverQueryLimitErrorIndicates that the requestor has exceeded quota. Derives from altimeter.exceptions.GoogleElevationApiError.class altimeter.exceptions.RequestDeniedErrorIndicates that the Google Elevation API did not complete the request. Derives fromaltimeter.exceptions.GoogleElevationApiError.class altimeter.exceptions.UnknownErrorIndicates an unknown error. Derives from altimeter.exceptions.GoogleElevationApiError.1.4 Changelog1.4.1 0.1.1 - 2012/11/06• Changed the package’s versioning utilities.• Corrected a few errors in the documentation.• Added integration with tox.6 Chapter 1. Contents

python-altimeter Documentation, Release 0.1.11.4.2 0.1 - 2012/11/02• Initial release.1.4. Changelog 7

python-altimeter Documentation, Release 0.1.18 Chapter 1. Contents

CHAPTERTWOCONTRIBUTINGWe’d love you to contribute to the development of python-altimeter. If you’d like to help us here are some of thethings you can do:• Fork the project and submit a pull request;• Report any errors or problems on the project’s issue tracker.9