Skip to main content
Join the official 2019 Python Developers SurveyStart the survey! site crawler. Provides tools for searching, fetching caches and geocoding.

Project description

Complete documentation can be found at Read the Docs.


  • login to
  • search caches
    • normal search (unlimited number of caches from any point)
    • quick search (all caches inside some area) - currently not working, see bellow
  • get cache and its details
    • normal loading (can load all details)
    • quick loading (can load just basic info but very quickly)
    • load logbook for given cache
  • get trackable details by tracking code
  • post log for a cache or a trackable
  • geocode given location


Stable version - using pip:

pip install pycaching

Dev version - manually from GIT:

git clone
cd pycaching
pip install .

Pycaching has following requirements:


Pycaching tests have the following additional requirements:

betamax >=0.8, <0.9
betamax-serializers >=0.2, <0.3



Simly call pycaching.login() method and it will do everything for you.

import pycaching
geocaching = pycaching.login("user", "pass")

If you won’t provide an username or password, pycaching will try to load .gc_credentials file from current directory or home folder. It will try to parse it as JSON and use the keys username and password from that file as login credentials.

# sample .gc_credentials JSON file
{ "username": "myusername", "password": "mypassword" }

You can also provide multiple username and password tuples in a file as login credentials. The tuple to be used can be chosen by providing its username when calling pycaching.login(), e.g. pycaching.login(“myusername2”). The first username and password tuple specified will be used as default if pycaching.login() is called without providing a username.

# sample .gc_credentials JSON file with mutiple users
[ { "username": "myusername1", "password": "mypassword1" },
  { "username": "myusername2", "password": "mypassword2" } ]
import pycaching
geocaching = pycaching.login()  # assume the .gc_credentials file is presented

In case you have a password manager in place featuring a command line interface (e.g. GNU pass) you may specify a password retrieval command using the password_cmd key instead of password.

# sample .gc_credentials JSON file with password command
{ "username": "myusername", "password_cmd": "pass" }

Note that the password and password_cmd keys are mutually exclusisive.

Load a cache details

cache = geocaching.get_cache("GC1PAR2")
print(  # cache.load() is automatically called
print(cache.location)  # stored in cache, printed immediately

This uses lazy loading, so the Cache object is created immediately and the page is loaded when needed (accessing the name).

You can use different method of loading cache details. It will be much faster, but it will load less details:

cache = geocaching.get_cache("GC1PAR2")
cache.load_quick()  # takes a small while
print(  # stored in cache, printed immediately
print(cache.location)  # NOT stored in cache, will trigger full loading

You can also load a logbook for cache:

for log in cache.load_logbook(limit=200):
    print(log.visited, log.type,, log.text)

Or its trackables:

for trackable in cache.load_trackables(limit=5):

Post a log to cache

geocaching.post_log("GC1PAR2", "Found cache in the rain. Nice place, TFTC!")

It is also possible to call post_log on Cache object, but you would have to create Log object manually and pass it to this method.

Search for all traditional caches around

from pycaching import Point
from pycaching.cache import Type

point = Point(56.25263, 15.26738)

for cache in, limit=50):
    if cache.type == Type.traditional:

Notice the limit in the search function. It is because returns a generator object, which would fetch the caches forever in case of simple loop.

Geocode adress and search around

point = geocaching.geocode("Prague")

for cache in, limit=10):

Find caches with their approximate locations in some area


This is currently not working because of this issue. Contributions are very welcome!

from pycaching import Point, Rectangle

rect = Rectangle(Point(60.15, 24.95), Point(60.17, 25.00))

for cache in geocaching.search_quick(rect, strict=True):
    print(, cache.location.precision)

Load a trackable details

trackable = geocaching.get_trackable("TB3ZGT2")
print(, trackable.goal, trackable.description, trackable.location)

Post a log for trackable

from pycaching.log import Log, Type as LogType
import datetime

log = Log(type=LogType.discovered_it, text="Nice TB!",
tracking_code = "ABCDEF"
trackable.post_log(log, tracking_code)

Get geocaches by log type

from pycaching.log import Type as LogType

for find in geocaching.my_finds(limit=5):

for dnf in geocaching.my_dnfs(limit=2):

for note in geocaching.my_logs(LogType.note, limit=6):


Pycaching uses Betamax for testing, which speeds it up by recording network requests so that they can be mocked.

If you haven’t written or modified any tests, tests can be run like so:

python3 test

If you have written or modified tests, you must provide a username and password for testing. Don’t worry, these will not leave your computer. Betamax will insert a placeholder when it records any new cassettes. To run new tests, first set up the following environment variables:

PYCACHING_TEST_USERNAME="yourusername" PYCACHING_TEST_PASSWORD="yourpassword" python3 test

Substitute your username for yourusername and your password for yourpassword. After you have exported the environment variables once, you do not need to export them again, and can run tests with just python3 test.



Original version was inspired by these packages:

Although the new version was massively rewritten, I’d like to thank to their authors.


Authors of this project are all contributors. Maintainer is Tomáš Bedřich.

Build Status Coverage Status PyPI monthly downloads

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 pycaching, version 4.0.0
Filename, size File type Python version Upload date Hashes
Filename, size pycaching-4.0.0-py3.6.egg (34.8 kB) File type Egg Python version 3.6 Upload date Hashes View hashes
Filename, size pycaching-4.0.0-py3-none-any.whl (37.8 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pycaching-4.0.0.tar.gz (46.2 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