dealmap 0.0.2 → 0.0.3

data/.gitignore

@@ -4,4 +4,6 @@ Gemfile.lock
 pkg/*
 *.swp
 *.swo
-coverage
+coverage
+doc
+.yardoc

data/.rvmrc

@@ -0,0 +1 @@
+rvm 1.9.2@dealmap

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+--protected
+--markup markdown
+-

data/README.md

@@ -0,0 +1,46 @@
+# Dealmap
+
+Simple Ruby wrapper for the Dealmap [API](http://www.thedealmap.com/api/). [TheDealMap](http://thedealmap.com) features deals aggregated from a number of sources, includng Groupon, LivingSocial, Restaurants.com, and more.
+
+## Installation
+
+    sudo gem install dealmap
+    
+## Usage
+
+You'll need a Dealmap [API key](http://www.thedealmap.com/api/keys/).
+
+    require 'dealmap'
+    client = Dealmap::Client.new(YOUR_API_KEY)
+    
+### Searching for deals in Brooklyn, NY
+    deals, total = client.search_deals(:l => "Brooklyn, NY")
+
+### Searching for deals based on lat/lng (Brooklyn, NY)
+    deals, total = client.search_deals(:l => "40.6500000, -73.9500000")
+
+Dealmap uses a [`Hashie::Mash`](http://github.com/intridea/hashie) for return values, providing a handy hash that supports dot notation:
+
+    deals.first.title
+    => "$100 Gift Certificate, Your Price $40"
+    deals.first.city
+    => "Brooklyn"
+    
+<a name="changelog"></a>
+## Changelog
+
+### 0.0.3 - March 13, 2011
+
+* Initial version
+
+## How to contribute
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+Copyright (c) 2011 [Josh Deeden](http://twitter.com/jdeeden). 

data/dealmap.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency('vcr', '~> 1.7.0')
   s.add_development_dependency('fakeweb')
   s.add_development_dependency('yard', '~> 0.6')
+  s.add_development_dependency('maruku', '~> 0.6')
   s.add_runtime_dependency("faraday", '~> 0.5.7')
   s.add_runtime_dependency("typhoeus", '~> 0.2.4')
   s.add_runtime_dependency('nokogiri', '~> 1.4')

data/lib/{ext → core_ext}/string.rb

@@ -1,4 +1,6 @@
+# Custom string extensions
 class String
+  # {http://www.urbandictionary.com/define.php?term=ganked Ganked} from ActiveSupport::Inflections.  Works the same way it does in rails.
   def underscore
     word = self.to_s.dup
     word.gsub!(/::/, '/')

data/lib/dealmap.rb

@@ -4,9 +4,13 @@ require "ext/string"
 require 'hashie/mash'
 require 'faraday'
 
+# The Dealmap namespace.
 module Dealmap
+  # Defines methods for the Dealmap API
   class Client
     attr :api_key, :conn
+    # Initialize the Dealmap client
+    # @param api_key [String] Your Dealmap API Key
     def initialize(api_key)
       raise Dealmap::ApiKeyMissingError, "You must supply an API key" if api_key.nil?
       @api_key = api_key
@@ -16,6 +20,28 @@ module Dealmap
       end
     end
 
+    # Search for deals  
+    # @param options [Hash] A customizable set of options  
+    # @option options [String] :l Location around which the deals are searched for. This is a required field. This can be text value or lat/lon value. Examples: Seattle, WA or \+43.324-123.432. Note about geocoding: It is recommended that you send latitude/longitude location as it reduces the need for geo-coding (which may slow down your request) and may not be accurate at all times
+    # @option options [String] :q Query keyword. Optional. For example if you want to find beer deals, you send keyword as your query 'q=beer'. If you want to get all deals, either drop q or send q=\*
+    # @option options [Fixnum] :d Distance around the location specified in the query. Optional. Default value is 5 miles. Always expressed in miles.  
+    # @option options [Fixnum] :si Start index of the deals. Used for paging through the results. Optional. Default value is 0 - which means start from the beginning.  
+    # @option options [Fixnum] :ps Page size. Used for paging through the deal results. Optional. Default page size is 20. Maximum number of deals per page is 100.  
+    # @option options [Fixnum] :a {http://apiwiki.thedealmap.com/index.php/Center%27d_Activity Center'd Activity}. Used to filter the results based on the type of activity. For example, send 1 for kid-friendly deals and 8 for romantic deals etc.
+    # @option options [String] :c {http://apiwiki.thedealmap.com/index.php/Deal_capability Deal capability}. Used to filter the results based on the deal type. For example, to get daily deals only, send c=16.
+    # @option options [String] :ed Expiration date. Used to filter the deals based on their expiration date. For example to get deals that are expiring soon (say by April 22nd 2010), you send ed=2010-04-22
+    # @return [Array, Fixnum] An array of Hashie::Mash objects representing deals.  An integer representing the total number of deals available for retrieval.  Note, this value and the size of the results array may differ, as *total* represents all available deals, not only the ones returned in your query.
+    #
+    # @example Search for deals in Miami, FL and get the total # of deals available
+    #   @client = Dealmap::Client.new("YOUR_API_KEY")
+    #   deals, total = @client.search_deals(:l => "Miami, FL")
+    #   deals.each {|deal| puts deal.inspect }
+    # @example Search for all deals within a 50 mile radius of Miami, FL
+    #   deals, total = @client.search_deals(:l => "Miami, FL", :d => 50)
+    # @example Search for beer deals within a 50 mile radius of Miami, FL
+    #   deals, total = @client.search_deals(:l => "Miami, FL", :d => 50, :q => "beer")
+    # @example Search for beer deals within a 50 mile radius of Miami, FL and return 100 results
+    #   deals, total = @client.search_deals(:l => "Miami, FL", :d => 50, :q => "beer", :ps => 100)
     def search_deals(options = {})
       options = options.merge(:key => api_key)
       response = conn.get("/search/deals/") { |req| req.params = options }
@@ -33,6 +59,27 @@ module Dealmap
       return deals, total
     end
 
+
+    # Search for businesses  
+    # @param options [Hash] A customizable set of options  
+    # @option options [String] :l Location around which the businesses are searched for. This is a required field. This can be text value or lat/lon value. Examples: Seattle, WA or \+43.324-123.432. Note about geocoding: It is recommended that you send latitude/longitude location as it reduces the need for geo-coding (which may slow down your request) and may not be accurate at all times
+    # @option options [String] :q Query keyword. Optional. For example if you want to find bars, you send keyword as your query 'q=bar'. 
+    # @option options [Fixnum] :d Distance around the location specified in the query. Optional. Default value is 5 miles. Always expressed in miles.  
+    # @option options [Fixnum] :si Start index of the businesses. Used for paging through the results. Optional. Default value is 0 - which means start from the beginning.  
+    # @option options [Fixnum] :ps Page size. Used for paging through the business listing results. Optional. Default page size is 20. Maximum number of deals per page is 100.  
+    # @option options [Fixnum] :a {http://apiwiki.thedealmap.com/index.php/Center%27d_Activity Center'd Activity}. Used to filter the results based on the type of activity. For example, send 1 for kid-friendly businesses and 8 for romantic businesses (whatever that means) etc.
+    # @return [Array, Fixnum] An array of Hashie::Mash objects representing businesses.  An integer representing the total number of businesses available for retrieval.  Note, this value and the size of the results array may differ, as *total* represents all available businesses, not only the ones returned in your query.
+    #
+    # @example Search for businesses in Miami, FL and get the total # of deals available
+    #   @client = Dealmap::Client.new("YOUR_API_KEY")
+    #   businesses, total = @client.search_businesses(:l => "Miami, FL")
+    #   businesses.each {|business| puts business.inspect }
+    # @example Search for all businesses within a 50 mile radius of Miami, FL
+    #   businesses, total = @client.search_businesses(:l => "Miami, FL", :d => 50)
+    # @example Search for bars within a 50 mile radius of Miami, FL
+    #   businesses, total = @client.search_businesses(:l => "Miami, FL", :d => 50, :q => "bar")
+    # @example Search for bars within a 50 mile radius of Miami, FL and return 100 results
+    #   businesses, total = @client.search_businesses(:l => "Miami, FL", :d => 50, :q => "bar", :ps => 100)
     def search_businesess(options = {})
       options = options.merge(:key => api_key)
       response = conn.get("/search/businesses/") { |req| req.params = options }
@@ -50,7 +97,57 @@ module Dealmap
       return businesses, total
     end
 
-    def details(deal_id, options = {})
+    # Get deal details.
+    # @param deal_id [String] A deal id
+    # @param options [Hash] An optional set of options.  Currently unused.
+    # @return [Hashie::Mash] A Hashie::Mash object representing a deal
+    # @example Example response:
+    #   {"activity"=>"0",
+    #    "added_by"=>"",
+    #    "additional_discount_coupon_code"=>"",
+    #    "additional_discount_coupon_effective_time"=>"0001-01-01T00:00:00",
+    #    "additional_discount_coupon_expiration_time"=>"0001-01-01T00:00:00",
+    #    "additional_discount_deal_unit"=>"0",
+    #    "additional_discounted_value"=>"0",
+    #    "address_line"=>"7726 W Sand Lake Rd",
+    #    "affiliation"=>"",
+    #    "b_description"=>"",
+    #    "business_id"=>"",
+    #    "business_name"=>"Shala Salon & Spa",
+    #    "capability"=>"211",
+    #    "category"=>"Beauty & Spas,Waxing",
+    #    "city"=>"Orlando",
+    #    "country"=>"",
+    #    "currency"=>"1",
+    #    "deal_source"=>"Groupon",
+    #    "deal_type"=>"8",
+    #    "deal_unit"=>"1",
+    #    "description"=>"",
+    #    "discounted_value"=>"10",
+    #    "effective_time"=>"2011-03-13T03:01:00",
+    #    "expiration_time"=>"2011-03-13T20:59:00",
+    #    "face_value"=>"20",
+    #    "id"=>"5-4A3EDD412F8C1ECF7F5A6AEDDAF7DA2A",
+    #    "icon_url"=>"",
+    #    "image_url"=>
+    #    "http://www.groupon.com/images/site_images/0686/1969/Shala-Salon-_-Spa.jpg",
+    #    "keywords"=>"",
+    #    "latitude"=>"28.4498819801956",
+    #    "longitude"=>"-81.4899128861725",
+    #    "more_info_link"=>
+    #    "http://www.thedealmap.com/deal/?dealid=5-4A3EDD412F8C1ECF7F5A6AEDDAF7DA2A&s=2-500726978-634341593775180000&utm_campaign=api",
+    #    "phone"=>"",
+    #    "state"=>"FL",
+    #    "tags"=>"",
+    #    "terms"=>"",
+    #    "title"=>
+    #    "$20 For A Full-Face Threading ($40 Value) Or $10 For An Eyebrow Threading ($20 Value) At Shala Salon & Day Spa",
+    #    "tracking_url"=>"",
+    #    "transaction_url"=>
+    #    "http://www.thedealmap.com/x/?s=2-500726978-634341593775180000&id=5-4A3EDD412F8C1ECF7F5A6AEDDAF7DA2A",
+    #    "you_save"=>"50 %",
+    #    "zip_code"=>""}
+    def deal_details(deal_id, options = {})
       options = options.merge(:key => api_key)
       response = conn.get("/deals/#{deal_id}") { |req| req.params = options }
       doc = Nokogiri::XML(response.body)

data/lib/dealmap/version.rb

@@ -1,3 +1,3 @@
 module Dealmap
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -2,7 +2,7 @@
 name: dealmap
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Joshua Deeden
@@ -80,49 +80,60 @@ dependencies:
   type: :development
   version_requirements: *id006
 - !ruby/object:Gem::Dependency 
-  name: faraday
+  name: maruku
   prerelease: false
   requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "0.6"
+  type: :development
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: faraday
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
         version: 0.5.7
   type: :runtime
-  version_requirements: *id007
+  version_requirements: *id008
 - !ruby/object:Gem::Dependency 
   name: typhoeus
   prerelease: false
-  requirement: &id008 !ruby/object:Gem::Requirement 
+  requirement: &id009 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
         version: 0.2.4
   type: :runtime
-  version_requirements: *id008
+  version_requirements: *id009
 - !ruby/object:Gem::Dependency 
   name: nokogiri
   prerelease: false
-  requirement: &id009 !ruby/object:Gem::Requirement 
+  requirement: &id010 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
         version: "1.4"
   type: :runtime
-  version_requirements: *id009
+  version_requirements: *id010
 - !ruby/object:Gem::Dependency 
   name: hashie
   prerelease: false
-  requirement: &id010 !ruby/object:Gem::Requirement 
+  requirement: &id011 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
         version: 1.0.0
   type: :runtime
-  version_requirements: *id010
+  version_requirements: *id011
 description: A very simple client for the DealMap API
 email: 
 - jdeeden@gmail.com
@@ -134,13 +145,15 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- .rvmrc
+- .yardopts
 - Gemfile
 - README.md
 - Rakefile
 - dealmap.gemspec
+- lib/core_ext/string.rb
 - lib/dealmap.rb
 - lib/dealmap/version.rb
-- lib/ext/string.rb
 - spec/cassettes/Dealmap_Client/api/search_deals.yml
 - spec/client/client_spec.rb
 - spec/spec_helper.rb