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. SeeGeocaching.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.
- advanced_search(options: dict, limit: int = inf, per_query: int = 200, wait_sleep: bool = True) Generator[Cache | None, None, None] ¶
Perform an advanced search for geocaches with specific search criteria.
The search is performed using the options provided in the
options
parameter. Example of theoptions
parameter:# https://www.geocaching.com/play/search?owner[0]=Geocaching%20HQ&a=0 options = {"owner[0]": "Geocaching HQ", "a": "0"}
- Parameters:
options – A dictionary of search options.
limit – The maximum number of caches to load. Defaults to infinity.
per_query – The number of caches to request in each query. Defaults to
200
.wait_sleep – In case of rate limits exceeding, wait appropriate time if set to
True
, otherwise just yieldNone
. Defaults toTrue
.
- Returns:
A generator that yields
Cache
objects.
- 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.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
orNone
- 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.
- 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 toNone
, 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, 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: Point, limit: int = inf, *, sort_by: str | SortOrder = SortOrder.date_last_visited, reverse: bool = False, per_query: int = 200, wait_sleep: bool = True) Generator[Cache | None, None, None] ¶
Search for caches around a specified location using a search API.
- Parameters:
point – The
geo.Point
object representing the center point of the search.limit – The maximum number of caches to load. Defaults to infinity.
sort_by – The criterion to sort the caches by. Defaults to
SortOrder.date_last_visited
.reverse – If
True
, the order of the results is reversed. Defaults toFalse
.per_query – The number of caches to request in each query. Defaults to
200
.wait_sleep – In case of rate limits exceeding, wait appropriate time if set to
True
, otherwise just yieldNone
. Defaults toTrue
.
- Returns:
A generator that yields
Cache
objects.
- search_quick(area)¶
Search for caches in a specified
Rectangle
area.- Parameters:
rect (geo.Rectangle) – The
Rectangle
object representing the search area.- Returns:
A generator that yields
Cache
objects.- Return type:
Generator[Optional[Cache], None, None]
- search_rect(rect: Rectangle, limit: int = inf, *, sort_by: str | SortOrder = SortOrder.date_last_visited, reverse: bool = False, per_query: int = 200, origin: Point | None = None, wait_sleep: bool = True) Generator[Cache | None, None, None] ¶
Search for caches in a specified
Rectangle
area using a search API.- Parameters:
rect – The
Rectangle
object representing the search area.limit – The maximum number of caches to load. Defaults to infinity.
sort_by – The criterion to sort the caches by. Defaults to
SortOrder.date_last_visited
.reverse – If
True
, the order of the results is reversed. Defaults toFalse
.per_query – The number of caches to request in each query. Defaults to
200
.origin – The origin point for search by distance, required when sorting by distance.
wait_sleep – In case of rate limits exceeding, wait appropriate time if set to
True
, otherwise just yieldNone
. Defaults toTrue
.
- Returns:
A generator that yields
Cache
objects.
- class pycaching.geocaching.SortOrder(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
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 fromBlock
.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 fromTrackable
.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 usingload_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, size, difficulty, terrain, hidden, author, favorites and pm_only. It also loads status, but only for enabled caches. For other states, it can’t be completely determined (can’t distinguish between archived and locked caches), so lazy loading is used.
- 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.
- property attributes¶
The cache attributes.
- property difficulty¶
The cache difficulty.
- Setter:
Set a cache difficulty. It must be in a common range - 1 to 5 in 0.5 steps.
- Type:
- property found¶
The cache found status.
True
if cache is found by current user,False
if not.- Type:
- property geocaching¶
A reference to
Geocaching
used for communicating with geocaching.com.- Type:
Geocaching
instance
The cache hidden date.
- Setter:
Set a cache hidden date. If
str
is passed, thenutil.parse_date()
is used and its return value is stored as a date.- Type:
- property hint¶
The cache hint.
- Setter:
Set a cache hint. Don’t decode text, you have to use
util.rot13()
before.- Type:
- property location¶
The cache location.
- Setter:
Set a cache location. If
str
is passed, thenPoint.from_string()
is used and its return value is stored as a location.- Type:
- property 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:
- property original_location¶
The cache original location.
- Setter:
Set a cache original location. If
str
is passed, thenPoint.from_string()
is used and its return value is stored as a location.- Type:
- property size¶
The cache size.
- Setter:
Set a cache size. If
str
is passed, thencache.Size.from_string()
is used and its return value is stored as a size.- Type:
- property status¶
The cache status (Enabled, Disabled, Archived, Unpublished, Locked).
- Type:
cache.Status
- property terrain¶
The cache terrain.
- Setter:
Set a cache terrain. It must be in a common range - 1 to 5 in 0.5 steps.
- Type:
- property type¶
The cache type.
- Setter:
Set a cache type. If
str
is passed, thencache.Type.from_string()
is used and its return value is stored as a type.- Type:
- property 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, thenutil.parse_date()
is used and its return value is stored as a date.- Type:
- property waypoints¶
Any waypoints listed in the cache.
- Setter:
Store a dictionary of locations using their lookup.
- Type:
- 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:
- class pycaching.cache.Type(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
Enum of possible cache types.
- according to
- classmethod from_filename(filename)¶
Return a cache type from its image filename.
Values are cache image filenames - http://www.geocaching.com/images/WptTypes/[VALUE].gif
- classmethod from_string(name)¶
Return a cache type from its human readable name.
- Raises:
.ValueError – If cache type cannot be determined.
- cache_in_trash_out_event = '13'¶
- cito = '13'¶
- community_celebration = '3653'¶
- earthcache = '137'¶
- event = '6'¶
- geocaching_hq = '3773'¶
- geocaching_hq_block_party = '4738'¶
- 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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
Enum of possible cache sizes.
Naming follows Groundspeak image filenames, values are human readable names.
- classmethod from_filename(filename)¶
Return a cache size from its image filename.
- classmethod from_number(number)¶
Return a cache size from its numeric id.
- Raises:
.ValueError – If cache size cannot be determined.
- classmethod from_string(name)¶
Return a cache size from its human readable name.
- Raises:
.ValueError – If cache size cannot be determined.
- 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.
- class pycaching.log.Type(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
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
- classmethod from_filename(filename)¶
Return a log type from its image filename.
- 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.
- 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 trackable).
- 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.
- property geocaching¶
A reference to
Geocaching
used for communicating with geocaching.com.- Type:
Geocaching
instance
- property location¶
The trackable current location.
Can be either string with location description (eg. “in the hands of someone”) or cache URL.
- Type:
Geo utilities¶
- pycaching.geo.to_decimal(deg, min)¶
Convert coordinates from degrees minutes to decimal degrees format.
- class pycaching.geo.Point(*args, **kwargs)¶
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
orN 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
.
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.