geocaching 0.5.0 → 0.6.0

data/README.markdown

@@ -1,44 +1,70 @@
 Ruby API for geocaching.com
 ===========================
 
-This Ruby library provides an API for geocaching.com.  As Groundspeak
-doesn’t offer an official API yet, this library parses the website’s
-HTML code.
+This Ruby library provides an API for geocaching.com.
 
-Documentation
--------------
 
-Documentation is available at
-[rdoc.info](http://rdoc.info/projects/nano/ruby-geocaching).
-
-Example
--------
+Usage
+-----
 
     require "geocaching"
     
+    # Logging in is not always necessary, but some information are only
+    # accessible when logged in.
     Geocaching::HTTP.login("username", "password")
     
-    cache = Geocaching::Cache.fetch(:code => "GCF00")
-    log = Geocaching::Log.fetch(:guid => "...")
+    # Fetch the information for a cache by the cache’s GC code.  You can also
+    # provide the cache’s GUID instead of the GC code.
+    cache = Geocaching::Cache.fetch(:code => "...")
+    
+    # Print some cache information.
+    puts "      Name: #{cache.name}"
+    puts "Difficulty: #{cache.difficulty}"
+    puts "     Owner: #{cache.owner.username}"
+    
+    # Print the number of logs.
+    puts "      Logs: #{cache.logs.size}"
+    
+    # Print the number of users that didn’t find the cache.
+    dnfs = cache.logs.select { |log| log.type == :dnf }.size
+    puts "      DNFs: #{dnfs}"
     
-    puts cache.name #=> "Bridge Over Troubled Waters"
-    puts cache.difficulty #=> 2.5
-    puts cache.logs.size #=> 194
+    # Fetch the information for a log by its GUID.
+    log = Geocaching::Log.fetch(:guid => "...")
     
-    puts log.username #=> "Chris"
-    puts log.message #=> "TFTC ..."
-    puts log.cache #=> #<Geocaching::Cache:...>
+    # Print some log information.
+    puts "Username: #{log.user.name}"
+    puts "   Words: #{log.message.split.size}"
+    puts "   Cache: #{log.cache.name}"
     
     Geocaching::HTTP.logout
 
-Altough some cache information are available without being logged in,
-most information will only be accessible after a successful login.
+The whole library may raise the following exceptions:
+
+* `Geocaching::TimeoutError` when a timeout is hit.
+* `Geocaching::LoginError` when calling a method that requires being
+  logged in and you’re not.
+* `Geocaching::NotFetchedError` when accessing a method that requires the
+  `fetch` method to be called first.
+* `Geocaching::ExtractError` when information could not be extracted
+  out of the website’s HTML code.  This mostly happens after Groundspeak
+  changed their website.
+* `Geocaching::HTTPError` when a HTTP request failed.
+
+All exceptions are subclasses of `Geocaching::Error`.
+
 
 Tests
 -----
 
-Tests are written using RSpec.
+Tests are written using [RSpec](http://relishapp.com/rspec).
 
     $ export GC_USERNAME="username"
     $ export GC_PASSWORD="password"
     $ rake test
+
+Additional environment variables you may specify are:
+
+* `GC_TIMEOUT` — HTTP timeout in seconds
+* `GC_CACHE_TYPES` — A space-separated list of cache types you want to test.
+* `GC_LOG_TYPES` — A space-separated list of log types you want to test.

data/geocaching.gemspec

@@ -16,6 +16,9 @@ Gem::Specification.new do |s|
   s.files += Dir.glob("spec/**/*")
 
   s.has_rdoc = false
+
   s.add_dependency "nokogiri", ">= 1.4.2"
+  s.add_dependency "json", ">= 1.4.6"
+
   s.add_development_dependency "rspec", ">= 2.0.0"
 end

data/lib/geocaching.rb

@@ -1,14 +1,18 @@
 # encoding: utf-8
 
 require "nokogiri"
-require "geocaching/version"
 
 # This is a Ruby library to access information on geocaching.com.  As
 # Groundspeak does not provide a public API yet, one needs to parse the
 # website content.  That’s what this library does.
 #
-# * {Geocaching::Cache} — Represents a cache
-# * {Geocaching::Log} — Represents a log
+# The whole library may raise the following exceptions:
+#
+# * {Geocaching::LoginError}
+# * {Geocaching::NotFetchedError}
+# * {Geocaching::ParseError}
+# * {Geocaching::TimeoutError}
+# * {Geocaching::HTTPError}
 #
 # == Usage
 #
@@ -50,8 +54,15 @@ module Geocaching
   class TimeoutError < Error
   end
 
+  # This exception is raised if a request exceeds 500 results.
+  class TooManyResultsError < Error
+    def initialize
+      super "Your request exceeded 500 results"
+    end
+  end
+
   # This exception is raised when a method is called that requires
-  # the +#fetch+ method to be called first.
+  # the #fetch method to be called first.
   class NotFetchedError < Error
     def initialize
       super "Need to call the #fetch method first"
@@ -61,10 +72,10 @@ module Geocaching
   # This exception is raised when information could not be
   # extracted out of the website’s HTML code.  For example,
   # this may happen if Groundspeak changed their website.
-  class ExtractError < Error
+  class ParseError < Error
   end
 
-  # This exception is raised when a HTTP request fails.
+  # This exception is raised when a HTTP request failed.
   class HTTPError < Error
   end
 
@@ -75,4 +86,7 @@ module Geocaching
   autoload :LogType, "geocaching/log_type"
   autoload :MyLogs, "geocaching/my_logs"
   autoload :User, "geocaching/user"
+  autoload :Watchlist, "geocaching/watchlist"
+  autoload :PocketQuery, "geocaching/pocket_query"
+  autoload :VERSION, "geocaching/version"
 end

data/lib/geocaching/cache.rb

@@ -1,10 +1,11 @@
 # encoding: utf-8
 
 require "time"
+require "json"
 
 module Geocaching
-  # This class is subclass of Array and is used to store all logs
-  # that belong to a cache.  It implements the {#fetch_all} method to
+  # The {LogsArray} class is a subclass of +Array+ and is used to store all
+  # logs that belong to a cache.  It implements the {#fetch_all} method to
   # fetch the information of all logs inside the array.
   class LogsArray < Array
     # Calls {Geocaching::Log#fetch} for each log inside the array.
@@ -16,11 +17,15 @@ module Geocaching
     end
   end
 
-  # This class represents a cache on geocaching.com.  Altough some
+  # The {Cache} class represents a cache on geocaching.com.  Altough some
   # information are available without being logged in, most information
   # will only be accessible after a successful login.
   #
-  # == Example
+  # This class does caching.  That means that multiple calls of, for example,
+  # the {#latitude} method only do one HTTP request.  To override the cached
+  # information, call the {#fetch} method manually.
+  #
+  # == Usage
   #
   #  cache = Geocaching::Cache.fetch(:code => "GCTEST")
   #  
@@ -29,7 +34,7 @@ module Geocaching
   #  puts cache.archived? #=> false
   #
   class Cache
-    # Create a new instance and call the {#fetch} methods afterwards.
+    # Creates a new instance and calls the {#fetch} methods afterwards.
     # One of +:code+ or +:guid+ must be provided as attributes.
     #
     # @param [Hash] attributes A hash of attributes, see {#initialize}
@@ -42,7 +47,78 @@ module Geocaching
       cache
     end
 
-    # Create a new instance. The following attributes may be specified
+    # Returns an array of caches that are located within the given bounds.
+    # If the number of results exceeds 500 caches, a
+    # {Geocaching::TooManyResultsError} exception is raised.
+    #
+    # @param [Array<Numeric>] northeast
+    #   An array containing latitude and longitude of the upper right bound
+    # @param [Array<Numeric>] southwest
+    #   An array containing latitude and longitude of the lower left bound
+    # @return [Array<Geocaching::Cache>]
+    #   Array of caches within given bounds
+    # @raise [ArgumentError]
+    #   Invalid arguments
+    # @raise [Geocaching::TooManyResultsError]
+    #   Number of results exceeds 500 caches
+    def self.within_bounds(northeast, southwest)
+      unless northeast.kind_of?(Array) and southwest.kind_of?(Array)
+        raise ArgumentError, "Arguments must be arrays"
+      end
+
+      unless northeast.size == 2 and southwest.size == 2
+        raise ArgumentError, "Arguments must have two elements"
+      end
+
+      unless northeast.map { |a| a.kind_of?(Numeric) }.all? \
+         and southwest.map { |a| a.kind_of?(Numeric) }.all?
+        raise ArgumentError, "Latitude and longitude must be given as numbers"
+      end
+
+      post_data = {
+        "dto" => {
+          "data" => {
+            "c" => 1,
+            "m" => "",
+            "d" => [northeast[0], southwest[0], northeast[1], southwest[1]].join("|")
+          },
+          "ut" => ""
+        }
+      }
+
+      headers = {
+        "Content-Type" => "application/json; charset=UTF-8"
+      }
+
+      resp, data = HTTP.post("/map/default.aspx/MapAction",
+        JSON.generate(post_data), headers)
+
+      begin
+        outer = JSON.parse(data)
+        raise ParseError, "Invalid JSON response" unless outer["d"]
+        results = JSON.parse(outer["d"])
+      rescue JSON::JSONError
+        raise ParseError, "Could not parse response JSON data"
+      end
+
+      raise ParseError, "Invalid JSON response" unless results["cs"]
+      raise TooManyResultsError if results["cs"]["count"] == 501
+
+      if results["cs"]["cc"].kind_of?(Array)
+        results["cs"]["cc"].map do |result|
+          Cache.new \
+            :name      => result["nn"],
+            :code      => result["gc"],
+            :latitude  => result["lat"],
+            :longitude => result["lon"],
+            :type      => CacheType.for_id(result["ctid"])
+        end
+      else
+        []
+      end
+    end
+
+    # Creates a new instance.  The following attributes may be specified
     # as parameters:
     #
     # * +:code+ — The cache’s GC code
@@ -54,7 +130,7 @@ module Geocaching
       @data, @doc, @code, @guid = nil, nil, nil, nil
 
       attributes.each do |key, value|
-        if [:code, :guid, :name, :type].include?(key)
+        if [:code, :guid, :name, :type, :latitude, :longitude].include?(key)
           if key == :type and not value.kind_of?(CacheType)
             raise TypeError, "Attribute `type' must be an instance of Geocaching::CacheType"
           end
@@ -66,12 +142,10 @@ module Geocaching
       end
     end
 
-    # Fetche cache information from geocaching.com.
+    # Fetches cache information from geocaching.com.
     #
     # @return [void]
     # @raise [ArgumentError] Neither code nor GUID are given
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
     def fetch
       raise ArgumentError, "Neither code nor GUID given" unless @code or @guid
 
@@ -79,19 +153,17 @@ module Geocaching
       @doc = Nokogiri::HTML.parse(@data)
     end
 
-    # Return whether information have successfully been fetched
+    # Returns whether information have successfully been fetched
     # from geocaching.com.
     #
-    # @return [Boolean] Have information been fetched?
+    # @return [Boolean] Have cache information been fetched?
     def fetched?
       @data and @doc
     end
 
-    # Return the cache’s code (GCXXXXXX).
+    # Returns the cache’s code.
     #
     # @return [String] Code
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract code from website
     def code
       @code ||= begin
         raise NotFetchedError unless fetched?
@@ -100,16 +172,14 @@ module Geocaching
         if elements.size == 1 and elements.first.content =~ /(GC[A-Z0-9]+)/
           HTTP.unescape($1)
         else
-          raise ExtractError, "Could not extract code from website"
+          raise ParseError, "Could not extract code from website"
         end
       end
     end
 
-    # Return the cache’s Globally Unique Identifier (GUID).
+    # Returns the cache’s Globally Unique Identifier (GUID).
     #
     # @return [String] GUID
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract GUID from website
     def guid
       @guid ||= begin
         raise NotFetchedError unless fetched?
@@ -122,16 +192,33 @@ module Geocaching
         end
 
         guid || begin
-          raise ExtractError, "Could not extract GUID from website"
+          raise ParseError, "Could not extract GUID from website"
         end
       end
     end
 
-    # Return the cache’s type ID.
+    # Returns the cache’s ID (which is not the UUID).
+    #
+    # @return [Fixnum] ID
+    def id
+      @id ||= begin
+        raise NotFetchedError unless fetched?
+
+        elements = @doc.search("div.CacheDetailNavigationWidget li a[href^='/seek/log.aspx']")
+
+        if elements.size > 0 and elements.first["href"] =~ /ID=(\d+)/
+          @id = $1.to_i
+        end
+
+        @id || begin
+          raise ParseError, "Could not extract ID from website"
+        end
+      end
+    end
+
+    # Returns the cache’s type ID.
     #
     # @return [Fixnum] Type ID
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract cache type ID from website
     def type_id
       @type_id ||= begin
         raise NotFetchedError unless fetched?
@@ -139,25 +226,21 @@ module Geocaching
         if @data =~ /<a.*?title="About Cache Types"><img.*?WptTypes\/(\d+)\.gif".*?<\/a>/
           $1.to_i
         else
-          raise ExtractError, "Could not extract cache type ID from website"
+          raise ParseError, "Could not extract cache type ID from website"
         end
       end
     end
 
-    # Return the cache’s type.
+    # Returns the cache’s type.
     #
     # @return [Geocaching::CacheType] Type
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract cache type ID from website
     def type
       @type ||= CacheType.for_id(type_id)
     end
 
-    # Return the cache’s name.
+    # Returns the cache’s name.
     #
     # @return [String] Name
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract name from website"
     def name
       @name ||= begin
         raise NotFetchedError unless fetched?
@@ -166,16 +249,14 @@ module Geocaching
         if elements.size == 1
           HTTP.unescape(elements.first.content)
         else
-          raise ExtractError, "Could not extract name from website"
+          raise ParseError, "Could not extract name from website"
         end
       end
     end
 
-    # Return the cache’s owner.
+    # Returns the cache’s owner.
     #
-    # @return [Geocaching::User]
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract info from website"
+    # @return [Geocaching::User] Owner
     def owner
       @owner ||= begin
         raise NotFetchedError unless fetched?
@@ -184,26 +265,22 @@ module Geocaching
           @owner_display_name = HTTP.unescape($2)
           User.new(:guid => $1)
         else
-          raise ExtractError, "Could not extract owner from website"
+          raise ParseError, "Could not extract owner from website"
         end
       end
     end
 
-    # Return the displayed cache owner name.
+    # Returns the displayed cache owner name.
     #
-    # @return [String]
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract info from website"
+    # @return [String] Displayed owner name
     def owner_display_name
       owner unless @owner_display_name
       @owner_display_name
     end
 
-    # Return the cache’s difficulty rating.
+    # Returns the cache’s difficulty rating.
     #
     # @return [Float] Difficulty rating
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract difficulty rating from website
     def difficulty
       @difficulty ||= begin
         raise NotFetchedError unless fetched?
@@ -211,16 +288,14 @@ module Geocaching
         if @data =~ /<strong>\s*?Difficulty:<\/strong>\s*?<img.*?alt="([\d\.]{1,3}) out of 5" \/>/
           $1.to_f
         else
-          raise ExtractError, "Could not extract difficulty rating from website"
+          raise ParseError, "Could not extract difficulty rating from website"
         end
       end
     end
 
-    # Return the cache’s terrain rating.
+    # Returns the cache’s terrain rating.
     #
     # @return [Float] Terrain rating
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract terrain rating from website
     def terrain
       @terrain ||= begin
         raise NotFetchedError unless fetched?
@@ -228,16 +303,14 @@ module Geocaching
         if @data =~ /<strong>\s+?Terrain:<\/strong>\s+?<img.*?alt="([\d\.]{1,3}) out of 5" \/>/
           $1.to_f
         else
-          raise ExtractError, "Could not extract terrain rating from website"
+          raise ParseError, "Could not extract terrain rating from website"
         end
       end
     end
 
-    # Return the date the cache has been hidden at.
+    # Returns the date the cache has been hidden at.
     #
     # @return [Time] Hidden date
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract hidden date from website
     def hidden_at
       @hidden_at ||= begin
         raise NotFetchedError unless fetched?
@@ -245,16 +318,14 @@ module Geocaching
         if @data =~ /<strong>\s*?Hidden\s*?:\s*?<\/strong>\s*?(\d{1,2})\/(\d{1,2})\/(\d{4})/
           Time.mktime($3, $1, $2)
         else
-          raise ExtractError, "Could not extract hidden date from website"
+          raise ParseError, "Could not extract hidden date from website"
         end
       end
     end
 
-    # Return the date the event has been held.
+    # Returns the date the event has been held.
     #
     # @return [Time] Event date
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract event date from website
     def event_date
       @event_date ||= begin
         raise NotFetchedError unless fetched?
@@ -263,16 +334,23 @@ module Geocaching
         if @data =~ /<strong>\s*?Event Date:\s*?<\/strong>\s*?\w+, (\d+) (\w+) (\d{4})/
           Time.parse([$1, $2, $3].join)
         else
-          raise ExtractError, "Could not extract event date from website"
+          raise ParseError, "Could not extract event date from website"
         end
       end
     end
 
-    # Return the cache’s container size.
+    # Returns the cache’s container size.  One of the following symbols
+    # is returned:
+    #
+    # * +:micro+
+    # * +:small+
+    # * +:regular+
+    # * +:large+
+    # * +:other+
+    # * +:not_chosen+
+    # * +:virtual+
     #
     # @return [Symbol] Cache container size
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract cache container size from website
     def size
       @size ||= begin
         raise NotFetchedError unless fetched?
@@ -283,16 +361,14 @@ module Geocaching
         end
 
         size || begin
-          raise ExtractError, "Could not extract cache container size from website"
+          raise ParseError, "Could not extract cache container size from website"
         end
       end
     end
 
-    # Return the cache’s latitude.
+    # Returns the cache’s latitude.
     #
     # @return [Float] Latitude
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract latitude from website
     def latitude
       @latitude ||= begin
         raise NotFetchedError unless fetched?
@@ -306,16 +382,14 @@ module Geocaching
         end
 
         latitude || begin
-          raise ExtractError, "Could not extract latitude from website"
+          raise ParseError, "Could not extract latitude from website"
         end
       end
     end
 
-    # Return the cache’s longitude.
+    # Returns the cache’s longitude.
     #
     # @return [Float] Longitude
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract longitude from website
     def longitude
       @longitude ||= begin
         raise NotFetchedError unless fetched?
@@ -329,16 +403,14 @@ module Geocaching
         end
 
         longitude || begin
-          raise ExtractError, "Could not extract longitude from website"
+          raise ParseError, "Could not extract longitude from website"
         end
       end
     end
 
-    # Return the cache’s location name (State, Country).
+    # Returns the cache’s location name (State, Country).
     #
     # @return [String] Location name
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract location from website
     def location
       @location ||= begin
         raise NotFetchedError unless fetched?
@@ -353,15 +425,14 @@ module Geocaching
         end
 
         location || begin
-          raise ExtractError, "Could not extract location from website"
+          raise ParseError, "Could not extract location from website"
         end
       end
     end
 
-    # Return whether the cache is unpublished or not.
+    # Returns whether the cache is unpublished or not.
     #
     # @return [Boolean] Is cache unpublished?
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
     def unpublished?
       @is_unpublished ||= begin
         raise NotFetchedError unless fetched?
@@ -369,10 +440,9 @@ module Geocaching
       end
     end
 
-    # Return whether the cache has been archived or not.
+    # Returns whether the cache has been archived or not.
     #
     # @return [Boolean] Has cache been archived?
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
     def archived?
       @is_archived ||= begin
         raise NotFetchedError unless fetched?
@@ -380,10 +450,9 @@ module Geocaching
       end
     end
 
-    # Return whether the cache is only viewable to Premium Member only.
+    # Returns whether the cache is only viewable to Premium Member only.
     #
     # @return [Boolean] Is cache PM-only?
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
     def pmonly?
       @is_pmonly ||= begin
         raise NotFetchedError unless fetched?
@@ -393,10 +462,9 @@ module Geocaching
       end
     end
 
-    # Return whether the cache is currently in review.
+    # Returns whether the cache is currently in review.
     #
     # @return [Boolean] Is cache currently in review?
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
     def in_review?
       @in_review ||= begin
         raise NotFetchedError unless fetched?
@@ -405,12 +473,9 @@ module Geocaching
       end
     end
 
-    # Return an array of logs for this cache. A log is an instance of
-    # {Geocaching::Log}.
+    # Returns an array of the cache’s logs.
     #
     # @return [Geocaching::LogsArray<Geocaching::Log>] Array of logs
-    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
-    # @raise [Geocaching::ExtractError] Could not extract logs from website
     def logs
       @logs ||= begin
         raise NotFetchedError unless fetched?
@@ -419,36 +484,114 @@ module Geocaching
         tds = @doc.search("table.Table.LogsTable > tr > td")
 
         if tds.size == 0
-          raise ExtractError, "Could not extract logs from website"
+          raise ParseError, "Could not extract logs from website"
         end
 
         tds.each do |td|
           strongs = td.search("strong")
           next unless strongs.size > 0
 
-          imgs = strongs.first.search("img")
-          as = strongs.first.search("a")
+          imgs    = strongs.first.search("img")
+          user_as = strongs.first.search("a[href^='/profile/']")
+          log_as  = td.search("small > a[href^='log.aspx']")
 
-          unless imgs.size == 1 and as.size == 1
-            raise ExtractError, "Could not extract logs from website"
+          unless imgs.size == 1 and user_as.size == 1 and log_as.size == 1
+            raise ParseError, "Could not extract logs from website"
           end
 
-          title = imgs.first["title"]
-          guid = as.first["href"] =~ /guid=([a-f0-9-]{36})/ ? $1 : nil
+          log_title = imgs.first["title"]
+          user_name = user_as.first.text.strip
+          user_guid = user_as.first["href"] =~ /guid=([a-f0-9-]{36})/ ? $1 : nil
+          log_guid  = log_as.first["href"] =~ /LUID=([a-f0-9-]{36})/ ? $1 : nil
+
+          # XXX Fix log title as Groundspeak is unable to escape their
+          # HTML code properly.
+          log_title = "Didn't find it" if log_title == "Didn"
 
-          unless title and guid
-            raise ExtractError, "Could not extract logs from website"
+          unless log_title and user_name and user_guid and log_guid
+            raise ParseError, "Could not extract logs from website"
           end
 
-          logs << Log.new(:guid => guid, :title => title, :cache => self)
+          user = User.new(:guid => user_guid, :name => user_name)
+          log = Log.new \
+            :guid  => log_guid,
+            :title => log_title,
+            :cache => self,
+            :user  => user
+
+          logs << log
         end
 
         logs
       end
     end
 
+    # Puts the cache on the user’s watchlist.  Obviously, you need to be logged
+    # in when calling this method.
+    #
+    # @return [void]
+    def watch
+      unless HTTP.loggedin?
+        raise LoginError
+      end
+
+      HTTP.get("/my/watchlist.aspx?w=#{id}")
+    end
+
+    # Removes the cache from the user’s watchlist.  This method doesn’t check
+    # if the cache you want to remove from the watchlist actually is on your
+    # watchlist.
+    #
+    # @return [void]
+    def unwatch
+      unless HTTP.loggedin?
+        raise LoginError
+      end
+
+      HTTP.post("/my/watchlist.aspx?ds=1&id=#{id}&action=rem", {
+        "ctl00$ContentBody$btnYes" => "Yes"
+      })
+    end
+
+    # Returns a Hash representation of this class.
+    #
+    # @return [Hash] Hash representing this class
+    def to_hash
+      hash = {
+        :id         => id,
+        :code       => code,
+        :guid       => guid,
+        :name       => name,
+        :difficulty => difficulty,
+        :terrain    => terrain,
+        :latitude   => latitude,
+        :longitude  => longitude,
+        :size       => size,
+        :type       => type,
+        :location   => location,
+        :owner      => owner,
+        :owner_display_name => owner_display_name,
+        :logs       => logs,
+        :pmonly?    => pmonly?,
+        :archived?  => archived?,
+        :in_review? => in_review?,
+        :unpublished? => unpublished?
+      }
+
+      if [:event, :megaevent, :lfevent].include?(type)
+        hash[:event_date] = event_date
+      else
+        hash[:hidden_at] = hidden_at
+      end
+
+      hash
+    end
+
   private
 
+    # Returns the HTTP request path.
+    #
+    # @return [String] HTTP request path
     def path
       "/seek/cache_details.aspx?log=y&" + (@code ? "wp=#{@code}" : "guid=#{@guid}")
     end