API reference

Here you can find an overview of all avaliable classes and methods.

Warning

Deprecated methods will be removed in next minor version.

For example: if you rely on some non-deprecated method in version 3.3, then it’s fine to update once to 3.4. If the method gets deprecated in 3.4, then it will be removed in 3.5!

pycaching.login(username=None, password=None)

A shortcut for user login.

Create a Geocaching instance and try to login a user. See Geocaching.login().

Returns:Created Geocaching instance.

Geocaching

class pycaching.geocaching.Geocaching

Provides some basic methods for communicating with geocaching.com website.

Provides methods to login and search. There are also some shortcut methods in this class to make working with pycaching more convinient.

geocode(location)

Return a Point object from geocoded location.

Parameters:location (str) – Location to geocode.
get_cache(wp)

Return a Cache object by its waypoint.

Parameters:wp (str) – Cache waypoint.
get_logged_user(login_page=None)

Return the name of currently logged user.

Parameters:login_page (bs4.BeautifulSoup) – Object containing already loaded page.
Returns:User’s name or None, if no user is logged in.
Return type:str or None
get_trackable(tid)

Return a Trackable object by its trackable ID.

Parameters:tid (str) – Trackable ID.
login(username=None, password=None)

Log in the user for this instance of Geocaching.

If username or password is not set, try to load credentials from file. Then load login page and do some checks about currently logged user. As a last thing post the login form and check result.

Parameters:
  • username (str) – User’s username or None to use data from credentials file.
  • password (str) – User’s password or None to use data from credentials file.
Raises:

LoginFailedException – If login fails either because of bad credentials or non-existing credentials file.

logout()

Log out the user for this instance.

post_log(wp, text, type=<Type.found_it: '2'>, date=None)

Post a log for cache.

Parameters:
search(point, limit=inf)

Return a generator of caches around some point.

Search for caches around some point by loading search pages and parsing the data from these pages. Yield Cache objects filled with data from search page. You can provide limit as a convinient way to stop generator after certain number of caches.

Parameters:
  • point (geo.Point) – Search center point.
  • limit (int) – Maximum number of caches to generate.
search_quick(area, *, strict=False, zoom=None)

Return a generator of caches in some area.

Area is converted to map tiles, each tile is then loaded and Cache objects are then created from its blocks.

Parameters:
  • strict (bool) – Whether to return caches strictly in the area and discard others.
  • zoom (int) – Zoom level of tiles. You can also specify it manually, otherwise it is automatically determined for whole Area to fit into one Tile. Higher zoom level is more precise, but requires more tiles to be loaded.

Cache

class pycaching.cache.Cache(geocaching, wp, **kwargs)

Represents a geocache with its properties and methods for loading them.

Provides some getters and setters for geocache properties like name, size, terrain, etc. Also contains two possibile methods to load cache details and ensures, that these methods are called when accessing a property which hasn’t been filled yet.

There are also methods for posting and loadings logs here. For more detail about Logs, please refer to Log.

In summary, this class contains everything, which is possible to see or do on geocache page on geocaching.com.

classmethod from_block(block)

Return Cache instance from Block.

Used during quick search. The Cache will have only GC code, name and approximate location filled in.

Parameters:block (Block) – Source block
classmethod from_trackable(trackable)

Return Cache instance from Trackable.

This only makes sense, if trackable is currently placed in cache. Otherwise it will have unexpected behavior.

Parameters:trackable (Trackable) – Source trackable.
load()

Load all possible cache details.

Use full cache details page. Therefore all possible properties are filled in, but the loading is a bit slow.

If you want to load basic details about a PM only cache, the PMOnlyException is still thrown, but avaliable details are filled in. If you know, that the cache you are loading is PM only, please consider using load_quick() as it will load the same details, but quicker.

Note

This method is called automatically when you access a property which isn’t yet filled in (so-called “lazy loading”). You don’t have to call it explicitly.

Raises:
  • PMOnlyException – If cache is PM only and current user is basic member.
  • LoadError – If cache loading fails (probably because of not existing cache).
load_by_guid()

Load cache details using the GUID to request and parse the caches ‘print-page’. Loading as many properties as possible except the following ones, since they are not present on the ‘print-page’:

  • original_location
  • state
  • found
  • pm_only
Raises:PMOnlyException – If the PM only warning is shown on the page
load_logbook(limit=inf)

Return a generator of logs for this cache.

Yield instances of Log filled with log data.

Parameters:limit (int) – Maximum number of logs to generate.
load_quick()

Load basic cache details.

Use information from geocaching map tooltips. Therefore loading is very quick, but the only loaded properties are: name, type, state, size, difficulty, terrain, hidden, author, favorites and pm_only.

Raises:LoadError – If cache loading fails (probably because of not existing cache).
load_trackables(limit=inf)

Return a generator of trackables in this cache.

Yield instances of Trackable filled with trackable data.

Parameters:limit (int) – Maximum number of trackables to generate.
post_log(log)

Post a log for this cache.

Parameters:log (Log) – Previously created Log filled with data.
attributes

The cache attributes.

Setter:Set a cache attributes. Walk through passed dict and use str keys as attribute names and bool values as positive / negative attributes. Unknown attributes are ignored with warning (you can find possible attribute keys in Cache._possible_attributes).
Type:dict
author

The cache author.

Type:str
description

The cache long description.

Type:str
difficulty

The cache difficulty.

Setter:Set a cache difficulty. It must be in a common range - 1 to 5 in 0.5 steps.
Type:float
favorites

The cache favorite points.

Type:int
found

The cache found status.

True if cache is found by current user, False if not.

Type:bool
geocaching

A reference to Geocaching used for communicating with geocaching.com.

Type:Geocaching instance
guid

The cache GUID. An identifier used at some places on geoaching.com

Type:str
hidden

The cache hidden date.

Setter:Set a cache hidden date. If str is passed, then util.parse_date() is used and its return value is stored as a date.
Type:datetime.date
hint

The cache hint.

Setter:Set a cache hint. Don’t decode text, you have to use util.rot13() before.
Type:str
location

The cache location.

Setter:Set a cache location. If str is passed, then Point.from_string() is used and its return value is stored as a location.
Type:Point
name

A human readable name of cache.

Type:str
original_location

The cache original location.

Setter:Set a cache original location. If str is passed, then

Point.from_string() is used and its return value is stored as a location. :type: Point

pm_only

If the cache is PM only.

Type:bool
size

The cache size.

Setter:Set a cache size. If str is passed, then cache.Size.from_string() is used and its return value is stored as a size.
Type:cache.Size
state

The cache status.

True if cache is enabled, False if cache is disabled.

Type:bool
summary

The cache text summary.

Type:str
terrain

The cache terrain.

Setter:Set a cache terrain. It must be in a common range - 1 to 5 in 0.5 steps.
Type:float
type

The cache type.

Setter:Set a cache type. If str is passed, then cache.Type.from_string() is used and its return value is stored as a type.
Type:cache.Type
waypoints

Any waypoints listed in the cache.

Setter:Store a dictionary of locations using their lookup.
Type:dict
wp

The cache GC code, must start with GC.

Type:str
class pycaching.cache.Waypoint(id=None, type=None, location=None, note=None)

Waypoint represents a waypoint related to the cache. This may be a Parking spot, a stage in a multi-cache or similar.

Parameters:
  • identifier (str) – the unique identifier of the location
  • type (str) – type of waypoint
  • location (Point) – waypoint coordinates
  • note (str) – Information about the waypoint
classmethod from_html(soup, table_id)

Return a dictionary of all waypoints found in the page representation

Parameters:
  • soup (bs4.BeautifulSoup) – parsed html document containing the waypoints table
  • table_id (str) – html id of the waypoints table
identifier

The waypoint unique identifier.

Type:str
location

The waypoint location.

Type:Point
note

Any additional information about the waypoint.

Type:str
type

The waypoint type.

Type:str
class pycaching.cache.Type

Enum of possible cache types.

Values are cache image filenames - http://www.geocaching.com/images/WptTypes/[VALUE].gif

cito = '13'
earthcache = '137'
event = '6'
giga_event = 'giga'
gps_adventures_exhibit = '1304'
groundspeak_block_party = '4738'
groundspeak_hq = 'HQ_32'
letterbox = '5'
locationless = '12'
lost_and_found_event = '10Years_32'
mega_event = 'mega'
multicache = '3'
mystery = '8'
project_ape = 'ape_32'
traditional = '2'
virtual = '4'
webcam = '11'
wherigo = '1858'
class pycaching.cache.Size

Enum of possible cache sizes.

Naming follows Groundspeak image filenames, values are human readable names.

large = 'large'
micro = 'micro'
not_chosen = 'not chosen'
other = 'other'
regular = 'regular'
small = 'small'
virtual = 'virtual'

Logs

class pycaching.log.Log(*, type=None, text=None, visited=None, author=None)

Represents a log record with its properties.

author

The log author.

Type:str
text

The log text.

Type:str
type

The log type.

Type:log.Type
visited

The log date.

Setter:Set a log date. If str is passed, then util.parse_date() is used and its return value is stored as a date.
Type:datetime.date
class pycaching.log.Type

Enum of possible log types.

Values are log type IDs (as used in HTML <option value=XX> on the log page). Also the log images can be found there - https://www.geocaching.com/images/logtypes/[VALUE].png

announcement = '74'
archive = '5'
attended = '10'
didnt_find_it = '3'
discovered_it = '48'
enable_listing = '23'
found_it = '2'
grabbed_it = '19'
marked_missing = '16'
needs_archive = '7'
needs_maintenance = '45'
note = '4'
oc_team_comment = '83'
owner_maintenance = '46'
placed_it = '14'
post_reviewer_note = '18'
publish_listing = '24'
retract = '25'
retrieved_it = '13'
submit_for_review = '76'
temp_disable_listing = '22'
unarchive = '12'
update_coordinates = '47'
visit = '75'
webcam_photo_taken = '11'
will_attend = '9'

Trackables

class pycaching.trackable.Trackable(geocaching, tid, *, name=None, location=None, owner=None, type=None, description=None, goal=None, url=None)

Represents a trackable with its properties.

get_KML()

Return the KML route of the trackable.

Return type:str
load()

Load all possible details about the trackable.

Note

This method is called automatically when you access a property which isn’t yet filled in (so-called “lazy loading”). You don’t have to call it explicitly.

Raises:LoadError – If trackable loading fails (probably because of not existing cache).
post_log(log, tracking_code)

Post a log for this trackable.

Parameters:
  • log (Log) – Previously created Log filled with data.
  • tracking_code (str) – A tracking code to verify current trackable holder.
description

The trackable long description.

Type:str
geocaching

A reference to Geocaching used for communicating with geocaching.com.

Type:Geocaching instance
goal

The trackable goal.

Type:str
location

The trackable current location.

Can be either string with location description (eg. “in the hands of someone”) or cache URL.

Type:str
name

A human readable trackable name.

Type:str
owner

The trackable owner.

Type:str
tid

The trackable ID, must start with TB.

Type:str
type

The trackable type.

A type depends on the trackable icon. It can be either “Travel Bug Dog Tag” or specific
geocoin name, eg. “Adventure Race Hracholusky 2015 Geocoin”.
Type:str

Geo utilities

pycaching.geo.to_decimal(deg, min)

Convert coordinates from degrees minutes to decimal degrees format.

class pycaching.geo.Point

A point on earth defined by its latitude, longitude and possibly more attributes.

Subclass of geopy.Point.

classmethod from_location(geocaching, location)

Return a Point instance from geocoded location.

Parameters:
  • geocaching (Geocaching) – Reference to Geocaching instance, used to do a geocoding request.
  • location (str) – Location to geocode.
Raises:

GeocodeError – If location cannot be geocoded (not found).

classmethod from_string(string)

Return a Point instance from coordinates in degrees minutes format.

This method can handle various malformed formats. Example inputs are:

  • S 36 51.918 E 174 46.725 or
  • N 6 52.861  W174   43.327
Parameters:string (str) – Coordinates to parse.
Raises:ValueError – If string cannot be parsed as coordinates.
class pycaching.geo.Polygon(*points)

Area defined by bordering Point instances.

Subclass of Area.

bounding_box

Get area’s bounding box (Rectangle computed from min and max coordinates).

mean_point

Return Point with average latitude and longitude of all area’s points.

class pycaching.geo.Rectangle(point_a, point_b)

Upright rectangle.

Subclass of Polygon.

__contains__(p)

Return if the rectangle contains a point.

Parameters:p (Point) – Examined point.
diagonal

Return a lenght of bounding box diagonal in meters as int.

Errors

exception pycaching.errors.Error

General pycaching error.

exception pycaching.errors.GeocodeError

Geocoding failed.

Probably because of non-existing location.

exception pycaching.errors.LoadError

Object loading failed.

Probably because of non-existing object or missing informations required to load it.

exception pycaching.errors.LoginFailedException

Login failed.

The provided credentials probably doesn’t work to log in.

exception pycaching.errors.NotLoggedInException

Tried to perform an operation which requires logging in first.

exception pycaching.errors.PMOnlyException

Requested cache is PM only.

exception pycaching.errors.ValueError

Wrapper for Pythons native ValueError.

Can be raised in various situations, but most commonly when unexpected property value is set.