Author: Dinu Gherman <>
Version: Version 0.1.1
Date: 2014-04-07
Copyright: GNU Public Licence v3 (GPLv3)


Geodist is, right now, a simple wrapper around Google's distance matrix online service and helps you find out quickly the distance between one (or more) origin and destination in space. In fact, it tells you also about the "distance" in time, when travelling either by car, by cycling or simply by walking between these locations.

Version 0.1.1 was tested ok on Python 2.7 and Python 3.4.


  • calculate geographical distances using Google's distance matrix service
  • provide a Python package and a command-line tool
  • provide a Unittest test suite
  • run the same code under Python 2 and Python 3


You can use geodist as a Python module e.g. like in the following interactive sessions:

Python 2/3:

>>> from import distance_matrix
>>> params = {"origins": "Berlin", "destinations": "Milan|Rome",
... "mode": "driving", "sensor": "false", "language": "it"}
>>> distance_matrix(output="json", params=params)
{u'destination_addresses': [u'Milano, Italia', u'Roma, Italia'],
 u'origin_addresses': [u'Berlino, Germania'],
 u'rows': [{u'elements': [{u'distance': {u'text': u'1.034 km',
      u'value': 1034373},
     u'duration': {u'text': u'9 ore 39 min', u'value': 34734},
     u'status': u'OK'},
    {u'distance': {u'text': u'1.507 km', u'value': 1507066},
     u'duration': {u'text': u'13 ore 33 min', u'value': 48770},
     u'status': u'OK'}]}],
 u'status': u'OK'}

In addition there is one command-line tool, geodist which can be used like this:

$ geodist --language it --format rst Berlin\|Paris Milan\|Rome\|Palermo
================= ============== ============ ===============
                \ Milano, Italia Roma, Italia Palermo, Italia
----------------- -------------- ------------ ---------------
Berlino, Germania       1.034 km     1.507 km        2.402 km
  Parigi, Francia         851 km     1.426 km        2.321 km
================= ============== ============ ===============

If you want the table to be transposed you can simply swap origin(s) and destination(s), but keep in mind that the distances might not be exactly the same. (Here, the call uses quotes instead of escaped pipes.):

$ geodist --language it --format rst "Milan|Rome|Palermo" "Berlin|Paris"
=============== ================= ===============
              \ Berlino, Germania Parigi, Francia
--------------- ----------------- ---------------
 Milano, Italia          1.035 km          851 km
   Roma, Italia          1.507 km        1.427 km
Palermo, Italia          2.401 km        2.321 km
=============== ================= ===============


  • 2014-04-07 (0.1.1): First official release.


The recommended way to install geodist is via pip as follows:

$ pip install geodist

Alternatively, you can install the geodist tarball after downloading the file geodist-0.1.1.tar.gz and decompressing it like this:

$ tar xfz geodist-0.1.1.tar.gz

Then change into the newly created directory geodist and install geodist by running the following command:

$ python install

This will install a Python package named geodist in the site-packages subfolder of your Python interpreter and one script tool named geodist in your bin directory, usually in /usr/local/bin.


The geodist distribution contains a Unittest test suite (not installed during installation) which can be run by simply executing the module like the following on the system command-line in the unpacked distribution folder:

$ python
Ran 5 tests in 1.141s


You can also run tox in the main distribution directory to run the tests on several platforms, see the tox.ini file.

Bug reports

Please report bugs and patches to Dinu Gherman <>. Don't forget to include information about the operating system and Python versions being used.