This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!
Project Description


License / Fork Information

Copyright (c) 2014-2015 Gen Del Raye
Copyright (c) 2015 Ryan Vennell

This is a derivative, forked from the original work by:
Gen Del Raye <> and located at:

Licensed under the GPLv3:

The purpose of this fork is to provide full Python3 (and Python2)
support in light of the fact that the original work has no public
repository which can be contributed to or traditionally forked.


Methods for representing geographic coordinates (latitude and longitude) including the ability to:

  • Convert lat/lon strings from almost any format into a LatLon object (analogous to the datetime library’s stptime method)
  • Automatically store decimal degrees, decimal minutes, and degree, minute, second information in a LatLon object
  • Output lat/lon information into a formatted string (analogous to the datetime library’s strftime method)
  • Project lat/lon coordinates into some other proj projection
  • Calculate distance and heading between lat/lon pairs using either the FAI or WGS84 approximation
  • Create a new LatLon object by offsetting an initial coordinate by a distance and heading
  • Subtracting one LatLon object from another creates a GeoVector object with distance and heading attributes (analogous to the datetime library’s timedelta object)
  • Adding or subtracting a Latlon object and a GeoVector object creates a new LatLon object with the coordinates adjusted by the GeoVector object’s distance and heading
  • GeoVector objects can be added, subtracted, multiplied or divided


LatLon has only been tested in Python 2.7

Installation through pip:

$ pip install LatLon23

Installation through pip:

$ pip3 install LatLon23

Requires the following non-standard libraries:

  • pyproj

Usage Notes

Usage of LatLon is primarily through the class LatLon, which is designed to hold a single pair of Latitude and Longitude objects. Strings can be converted to LatLon objects using the method string2latlon, and to Latitude or Longitude objects using string2geocoord. Alternatively, a LatLon object can be constructed by subtracting two LatLon objects, or adding or subtracting a Latlon object and a GeoVector object.

Latitude or Longitude Construction

Latitude of longitude construction is through the classes Latitude and Longitude, respectively. You can pass a latitude or longitude coordinate in any combination of decimal degrees, degrees and minutes, or degrees minutes and seconds. Alternatively, you can pass a formatted string using the function string2geocoord for a string containing a single latitude or longitude, or string2latlon for a pair of strings representing the latitude and longitude.

String formatting:

string2latlon and string2geocoord both take a formatter string which is loosely modeled on the format keyword used in datetime’s strftime function. Indicator characters (e.g. H or D) are placed between a specific separator character (%) to specify the way in which a coordinate string is formatted. Possible values are as follows:

*H* is a hemisphere identifier (e.g. N, S, E or W)

*D* is a coordinate in decimal degrees notation (e.g. 5.833)

*d* is a coordinate in degrees notation (e.g. 5)

*M* is a coordinate in decimal minutes notation (e.g. 54.35)

*m* is a coordinate in minutes notation (e.g. 54)

*S* is a coordinate in seconds notation (e.g. 28.93)

Any other characters (e.g. ' ' or ', ') will be treated as a separator between the above components.

All components should be separated by the *%* character. For example, if the coord_str is '5, 52,
59.88_N', the format_str would be 'd%, %m%, %S%_%H'


One format that will not currently work is one where the hemisphere identifier and a degree or decimal degree are not separated by any characters. For example ‘5 52 59.88 N’ is valid whereas ‘5 52 59.88N’ is not.

String output:

Both LatLon and Latitude and Longitude objects include a to_string() method for outputting a formatted coordinate.


Use LatLon.project to transform geographical coordinates into a chosen projection. Requires that you pass it a pyproj or basemap projection.

Distance and Heading Calculation:

LatLon objects have a distance() method which accepts a 2nd LatLon object as an argument. distance() will calculate the great-circle distance between the two coordinates using the WGS84 ellipsoid by default. To use the more approximate FAI sphere, set ellipse to ‘sphere’. Initial and reverse headings (in degrees) can be calculated in a similar way using the heading_initial() and heading_reverse() methods. Alternatively, subtracting one LatLon object from another will return a GeoVector object with the attributes heading and distance.

Creating a New LatLon Object by Offset from Another One:

Use the offset() method of LatLon objects, which takes an initial heading (in degrees) and distance (in km) to return a new LatLon object at the offset coordinates. Also, you can perform the same operation by adding or subtracting a LatLon object with a GeoVector object.


Create a LatLon object from coordinates:

>> palmyra = LatLon(Latitude(5.8833), Longitude(-162.0833)) # Location of Palmyra Atoll in decimal degrees
>> palmyra = LatLon(5.8833, -162.0833) # Same thing but simpler!
>> palmyra = LatLon(Latitude(degree = 5, minute = 52, second = 59.88),
>>                  Longitude(degree = -162, minute = -4.998) # or more complicated!
>> print palmyra.to_string('d% %m% %S% %H') # Print coordinates to degree minute second
('5 52 59.88 N', '162 4 59.88 W')

Create a Latlon object from a formatted string:

>> palmyra = string2latlon('5 52 59.88 N', '162 4 59.88 W', 'd% %m% %S% %H')
>> print palmyra.to_string('d%_%M') # Print coordinates as degree minutes separated by underscore
('5_52.998', '-162_4.998')

Perform some calculations:

>> palmyra = LatLon(Latitude(5.8833), Longitude(-162.0833)) # Location of Palmyra Atoll
>> honolulu = LatLon(Latitude(21.3), Longitude(-157.8167)) # Location of Honolulu, HI
>> distance = palmyra.distance(honolulu) # WGS84 distance in km
>> print distance
>> print palmyra.distance(honolulu, ellipse = 'sphere') # FAI distance in km
>> initial_heading = palmyra.heading_initial(honolulu) # Heading from Palmyra to Honolulu on WGS84 ellipsoid
>> print initial_heading
>> hnl = palmyra.offset(initial_heading, distance) # Reconstruct Honolulu based on offset from Palmyra
>> print hnl.to_string('D') # Coordinates of Honolulu
('21.3', '-157.8167')

Manipulate LatLon objects using GeoVectors:

>> vector = (honolulu - palmyra) * 2 # A GeoVector with 2x the magnitude of a vector from palmyra to honolulu
>> print vector # Print heading and magnitude
14.6907922022 3533.38260751
print palmyra + (vector/2.0) # Recreate the coordinates of Honolulu by adding half of vector to palmyra
21.3, -157.8167



1.0.7 (MARCH/29/2015)

  • Forked from original work:
  • Added Python3 support and refactored a bit of the code
  • Updated Readme to correct issues and provide proper attribution
  • Adding
Release History

Release History


This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
LatLon23-1.0.7.tar.gz (25.1 kB) Copy SHA256 Checksum SHA256 Source Mar 29, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting