Quickstart

Installation

Stable version - using pip:

pip install pycaching

Dev version - manually from GIT:

git clone https://github.com/tomasbedrich/pycaching.git
cd pycaching
pip install .

Pycaching has following requirements:

Python>=3.4
requests>=2.8
beautifulsoup4>=4.4
geopy>=1.11

Examples

Login

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" }
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 geocaching.com/myUsername" }

Note that the password and password_cmd keys are mutually exclusisive.

Load a cache details

cache = geocaching.get_cache("GC1PAR2")
print(cache.name)  # 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(cache.name)  # 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.author, log.text)

Or its trackables:

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

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 geocaching.search(point, limit=50):
    if cache.type == Type.traditional:
        print(cache.name)

Notice the limit in the search function. It is because geocaching.search() 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 geocaching.search(point, limit=10):
    print(cache.name)

Find caches with their approximate locations in some area

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.name, cache.location.precision)

Load a trackable details

trackable = geocaching.get_trackable("TB3ZGT2")
print(trackable.name, 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!", visited=datetime.date.today())
tracking_code = "ABCDEF"
trackable.post_log(log, tracking_code)