Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Modules for working with points on Earth

Project description


At this point upoints only exists to assist the users who have been using it for years, I absolutely do not recommend its use to new users.


upoints is a collection of GPL v3 licensed modules for working with points on Earth, or other near spherical objects. It allows you to calculate the distance and bearings between points, mangle xearth/xplanet data files, work with online UK trigpoint databases, NOAA’s weather station database and other such location databases.

Previous versions of upoints were called earth_distance, but the name was changed as it no longer reflected the majority of uses the packages was targeted at.


upoints’s only strict requirements beyond the Python standard library are aaargh and lxml, and as such should run with Python 2.6 or newer [1]. If upoints doesn’t work with the version of Python you have installed, drop me a mail and I’ll endeavour to fix it.

The modules have been tested on many UNIX-like systems, including Linux and OS X, but it should work fine on other systems too. The modules and scripts contain a large collection of tests that can be checked with nose2.

[1]If you still use Python v2.5 only small changes are required, for example to the property definitions.
[2]Some tests may fail due to rounding errors depending on the system the tests are being run on, but such instances should be obvious even to the casual user and some effort has been put in to reduce the likelihood of such failures.


The simplest way to show how upoints works is by example, and here goes:

>>> from upoints import point
>>> Home = point.Point(52.015, -0.221)
>>> Telford = point.Point(52.6333, -2.5000)
>>> print("%d kM, with an initial bearing of %d°"
...       % (Home.distance(Telford), Home.bearing(Telford)))
169 kM, with an initial bearing of 294°

All the class definitions, methods and independent functions contain hopefully useful usage examples in the docstrings. The API documentation is built with Sphinx, and is available in doc/html/api/.

There is some accompanying text and examples for, formerly, available in geolocation and path cross. More examples are available for in xearth and path cross. Some background and more examples for is online in Trigpointing and Usage examples for is available in Cities and And finally, Pythons on a plane contains information on


The following people have submitted patches, testing and feedback:

  • Cédric Dufour -’s CSV import, and flight plan output
  • Thomas Traber - GPX support enhancements, Points filtering, and some cool usage scenarios
  • Kelly Turner - Xearth import idea, and copious testing
  • Simon Woods - Testing

API Stability

API stability isn’t guaranteed across versions, although frivolous changes won’t be made.

When upoints 1.0 is released the API will be frozen, and any changes which aren’t backwards compatible will force a major version bump.


The modules assume the caller will take care of significant digits, and output formatting [2]. All results are returned with whatever precision your Python install or system generates; unintuitive float representation, rounding errors, warts and all.

The reasoning is simple, the caller should always know what is required and any heuristics added to the code would be just that – guesses, which can and will be wrong.

The upoints modules do not take flattening in to account, as in calculations based in most populated areas of the earth the errors introduced by ignoring the earth’s flattening are quite small. Future versions may change if the limitation becomes an issue in real use.

Although not really a limitation one should also be careful to use data sources that are based around the same datum, and even within two data sources that use the same datum you should make sure they use the same representations. It isn’t unusual to find data sources from the USA that specify longitudes west of Greenwich as positive for example.

[3]A future release may include more standard output definitions, but there is no intention to add “magic” data mangling.


If you find a bug don’t hesitate to drop me a mail preferably including a minimal testcase, or even better a patch!

Project details

Download files

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

Files for upoints, version 0.12.2
Filename, size File type Python version Upload date Hashes
Filename, size upoints-0.12.2-py2.py3-none-any.whl (72.2 kB) File type Wheel Python version 2.7 Upload date Hashes View hashes
Filename, size upoints-0.12.2.tar.bz2 (488.2 kB) File type Source Python version None Upload date Hashes View hashes
Filename, size upoints-0.12.2.tar.gz (499.5 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page