API reference¶

Here you can find an overview of all available 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(*, session=None)¶

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=None, guid=None)¶

Return a Cache object by its waypoint or GUID.

Parameters:	wp (str) – Cache waypoint. guid (str) – Cache GUID.

Note

Provide only the GUID or the waypoint, not both.

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.

my_dnfs(limit=inf)¶

Get an iterable of the logged-in user’s DNFs.

Parameters:	limit – The maximum number of results to return (default: infinity).

my_finds(limit=inf)¶

Get an iterable of the logged-in user’s finds.

Parameters:	limit – The maximum number of results to return (default: infinity).

my_logs(log_type=None, limit=inf)¶

Get an iterable of the logged-in user’s logs.

Parameters:	log_type – The log type to search for. Use a `Type` value. If set to `None`, all logs will be returned (default: `None`). limit – The maximum number of results to return (default: infinity).

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

Post a log for cache.

Parameters:	wp (str) – Cache waypoint. text (str) – Log text. type (log.Type) – Type of log. date (datetime.date) – Log date. If set to `None`, `datetime.date.today()` is used instead.

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 convenient 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.

search_rect(rect: pycaching.geo.Rectangle, *, per_query: int = 200, sort_by: Union[str, pycaching.geocaching.SortOrder] = <SortOrder.date_last_visited: 'datelastvisited'>, origin: Optional[pycaching.geo.Point] = None, wait_sleep: bool = True)¶

Return a generator of caches in given Rectange area.

Parameters:	rect – Search area. per_query (int) – Number of caches requested in single query. sort_by – Order cached by given criterion. origin – Origin point for search by distance. wait_sleep – In case of rate limits exceeding, wait appropriate time if set True, otherwise just yield None.

class pycaching.geocaching.SortOrder¶: Enum of possible cache sort orderings returned in Groundspeak API.

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`

log_counts¶

The log count for each log type.

Setter:	Store a dictionary of log counts for each type used in the logbook of the current cache.
Type:	`dict`

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`

visited¶

The cache log date (filled by function geocaching.my_logs() if cache is created there)

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

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.

according to

cache_in_trash_out_event = '13'¶

cito = '13'¶

community_celebration = '3653'¶

earthcache = '137'¶

event = '6'¶

from_filename = <bound method Type.from_filename of <enum 'Type'>>¶

from_number = <bound method Type.from_number of <enum 'Type'>>¶

from_string = <bound method Type.from_string of <enum 'Type'>>¶

geocaching_hq = '3773'¶

giga_event = '7005'¶

gps_adventures_exhibit = '1304'¶

gps_maze = '1304'¶

groundspeak_block_party = '4738'¶

groundspeak_hq = '3773'¶

hq_celebration = '3774'¶

letterbox = '5'¶

locationless = '12'¶

lost_and_found_event = '3653'¶

mega_event = '453'¶

multicache = '3'¶

mystery = '8'¶

project_ape = '9'¶

puzzle = '8'¶

reverse = '12'¶

traditional = '2'¶

unknown = '8'¶

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.

from_filename = <bound method Size.from_filename of <enum 'Size'>>¶

from_number = <bound method Size.from_number of <enum 'Size'>>¶

from_string = <bound method Size.from_string of <enum 'Size'>>¶

large = 'large'¶

micro = 'micro'¶

not_chosen = 'not chosen'¶

other = 'other'¶

regular = 'regular'¶

small = 'small'¶

virtual = 'virtual'¶

Logs¶

class pycaching.log.Log(*, uuid=None, 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`

uuid¶

The log unique identifier.

Type:	`str`

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'¶

from_filename = <bound method Type.from_filename of <enum 'Type'>>¶

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.BadBlockError¶

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.TooManyRequestsError(url: str, rate_limit_reset: int = 0)¶

Geocaching API rate limit has been reached.

wait_for()¶: Wait enough time to release Rate Limits.

exception pycaching.errors.ValueError¶

Wrapper for Pythons native ValueError.

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