semantics3 0.04 → 0.10

data/Changes

@@ -1,5 +1,8 @@
 Revision history for semantics3-ruby
 
+0.04    11-03-2014
+        Use CGI.escape instead of URI.escape [Thanks to Mark Evans/ShopGenius App (mark@shopgeniusapp.com)]
+
 0.03    07-02-2014
         Made library thread safe [Thanks to Mark Evans/ShopGenius App (mark@shopgeniusapp.com)]
 

data/README.md

@@ -3,7 +3,6 @@
 semantics3-ruby is a Ruby client for accessing the Semantics3 Products API, which provides structured information, including pricing histories, for a large number of products.
 See https://www.semantics3.com for more information.
 
-Quickstart guide: https://www.semantics3.com/quickstart
 API documentation can be found at https://www.semantics3.com/docs/
 
 ## Installation
@@ -46,119 +45,199 @@ API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
 sem3 = Semantics3::Products.new(API_KEY,API_SECRET)
 ```
 
-### First Query aka 'Hello World':
+### First Request aka 'Hello World':
 
-Let's make our first query! For this query, we are going to search for all Toshiba products that fall under the category of "Computers and Accessories", whose cat_id is 4992. 
+Let's run our first request! We are going to run a simple search fo the word "iPhone" as follows:
 
 ```ruby
-# Build the query
-sem3.products_field( "cat_id", 4992 )
-sem3.products_field( "brand", "Toshiba" )
+# Build the request
+sem3.products_field( "search", "iphone" )
 
-# Make the query
+# Run the request
 productsHash = sem3.get_products()
 
-# View the results of the query
+# View the results of the request
 puts productsHash.to_json
 ```
 
-## Examples
+## Sample Requests
 
-The following examples show you how to interface with some of the core functionality of the Semantics3 Products API. For more detailed examples check out the Quickstart guide: https://www.semantics3.com/quickstart
+The following requests show you how to interface with some of the core functionality of the Semantics3 Products API:
 
-### Explore the Category Tree
+### Pagination
 
-In this example we are going to be accessing the categories endpoint. We are going to be specifically exploring the "Computers and Accessories" category, which has a cat_id of 4992. For more details regarding our category tree and associated cat_ids check out our API docs at https://www.semantics3.com/docs
+The example in our "Hello World" script returns the first 10 results. In this example, we'll scroll to subsequent pages, beyond our initial request:
 
 ```ruby
-# Build the query
-sem3.categories_field( "cat_id", 4992 )
+# Build the request
+sem3.products_field( "search", "iphone" )
 
-# Make the query
-categoriesHash = sem3.get_categories()
+# Run the request
+productsHash = sem3.get_products()
 
-# View the results of the query
-puts categoriesHash.to_json
+# View the results of the request
+puts productsHash.to_json
+
+# Goto the next 'page'
+page = 0 
+while (productsHash = sem3.iterate_products) do
+    page = page + 1 
+    puts "We are at page = #{page}"
+    puts "The results for this page are:\n"
+    puts productsHash.to_json
+end
 ```
 
-### Nested Search Query
+### UPC Query
+
+Running a UPC/EAN/GTIN query is as simple as running a search query:
+
+```ruby
+# Build the request
+sem3.products_field( "upc", "883974958450" )
+sem3.products_field( "field", ["name","gtins"] )
+
+# Run the request
+productsHash = sem3.get_products()
 
-You can construct complex queries by just repeatedly calling the products_field() or add() methods. Here is how we translate the following JSON query - '{"cat_id":4992,"brand":"Toshiba","weight":{"gte":1000000,"lt":1500000},"sitedetails":{"name":"newegg.com","latestoffers":{"currency":"USD","price":{"gte":100}}}}'.
+# View the results of the request
+puts productsHash.to_json
+```
 
-This query returns all Toshiba products within a certain weight range narrowed down to just those that retailed recently on newegg.com for >= USD 100.
+### URL Query
+
+Get the picture? You can run URL queries as follows:
 
 ```ruby
-# Build the query
-sem3.products_field( "cat_id", 4992 )
-sem3.products_field( "brand", "Toshiba" )
-sem3.products_field( "weight", "gte", 1000000 )
-sem3.products_field( "weight", "lt", 1500000 )
-sem3.products_field( "sitedetails", "name", "newegg.com" )
-sem3.products_field( "sitedetails", "latestoffers", "currency", "USD" )
-sem3.products_field( "sitedetails", "latestoffers", "price", "gte", 100 )
+sem3.products_field( "url", "http://www.walmart.com/ip/15833173" )
+productsHash = sem3.get_products()
+puts productsHash.to_json
+```
 
-# Let's make a modification - say we no longer want the weight attribute
-sem3.remove( "products", "brand", "weight" )
+### Price Filter
 
-# Let's view the JSON query we just constructed. This is a good starting point to debug, if you are getting incorrect 
-# results for your query
-constructedJson = sem3.get_query_json( "products" )
-puts constructedJson
+Filter by price using the "lt" (less than) tag:
 
-# Make the query
-productsHash = sem3.get_products
+```ruby
+sem3.products_field( "search", "iphone" )
+sem3.products_field( "price", "lt", 300 )
+productsHash = sem3.get_products()
+puts productsHash.to_json
+```
 
-# View the results of the query
+### Category ID Query
+
+To lookup details about a cat_id, run your request against the categories resource:
+
+```ruby
+# Build the request
+sem3.products_field( "cat_id", 4992 )
+
+# Run the request
+productsHash = sem3.get_products()
+
+# View the results of the request
 puts productsHash.to_json
 ```
 
-### Pagination
+## Webhooks
+You can use webhooks to get near-real-time price updates from Semantics3. 
+
+### Creating a webhook
 
-Let's now look at doing pagination, continuing from where we stopped previously.
+You can register a webhook with Semantics3 by sending a POST request to `"webhooks"` endpoint.
+To verify that your URL is active, a GET request will be sent to your server with a `verification_code` parameter. Your server should respond with `verification_code` in the response body to complete the verification process.
 
 ```ruby
-# Goto the next 'page'
-page = 0 
-while (productsHash = sem3.iterate_products) do
-    page = page + 1 
-    puts "Iterating through page: #{page}"
-end
+params = {
+    "webhook_uri" => "http://mydomain.com/webhooks-callback-url"
+}
+
+ res = sem3.run_query("webhooks","POST",params)
+ puts res
+```
+To fetch existing webhooks
+```ruby
+res = sem3.run_query("webhooks","GET")
+puts res
 ```
 
-### Explore Price Histories
+To remove a webhook
+```ruby
+webhook_id = "7JcGN81u"
+endpoint = "webhooks/"+webhook_id
+
+res = sem3.run_query(endpoint,"DELETE" )
+puts res
+```
 
-We shall use the add() method, which allows you to access any of the supported endpoints by just specifiying the name of the endpoint. add( "products", param1, param2, ...) is the equivalent of products_field( param1, param2, ... ), add( "offers", param1, param2, ... ) is the equivalent of offers_field( param1, param2, ...)
+### Registering events
+Once you register a webhook, you can start adding events to it. Semantics3 server will send you notifications when these events occur.
+To register events for a specific webhook send a POST request to the `"webhooks/{webhook_id}/events"` endpoint
 
-For this example, we are going to look at a particular product that is sold by select mercgants and whose price is >= USD 30 and seen after a specific date (specified as a UNIX timestamp).
+```ruby
+params = {
+    "type" => "price.change",
+    "product" => {
+            "sem3_id" => "1QZC8wchX62eCYS2CACmka"
+        },
+        "constraints" => {
+            "gte" => 10,
+            "lte" => 100
+        }
+}
+
+webhook_id = '7JcGN81u'
+endpoint = "webhooks/#{webhook_id}/events"
+
+eventObject = sem3.run_query(endpoint,"POST",params)
+puts eventObject["id"]
+puts eventObject["type"]
+puts eventObject["product"]
+```
 
+To fetch all registered events for a give webhook
 ```ruby
-# Build the query
-sem3.add( "offers", "sem3_id", "4znupRCkN6w2Q4Ke4s6sUC")
-sem3.add( "offers", "seller", ["LFleurs","Frys","Walmart"] )
-sem3.add( "offers", "currency", "USD")
-sem3.add( "offers", "price", "gte", 30)
-sem3.add( "offers", "lastrecorded_at", "gte", 1348654600)
+webhook_id = "7JcGN81u"
+endpoint = "webhooks/#{webhook_id}/events"
 
-# Make the query
-offersHash = sem3.get_offers
-#Alternatively we could also do
-offersHash = sem3.run_query( "offers" )
+res = sem3.run_query(endpoint,"GET")
+puts res
+```
 
-# View the results of the query
-puts offersHash.to_json
+### Webhook Notifications
+Once you have created a webhook and registered events on it, notifications will be sent to your registered webhook URI via a POST request when the corresponding events occur. Make sure that your server can accept POST requests. Here is how a sample notification object looks like
+```javascript
+{
+    "type": "price.change",
+    "event_id": "XyZgOZ5q",
+    "notification_id": "X4jsdDsW",
+    "changes": [{
+        "site": "abc.com",
+        "url": "http://www.abc.com/def",
+        "previous_price": 45.50,
+        "current_price": 41.00
+    }, {
+        "site": "walmart.com",
+        "url": "http://www.walmart.com/ip/20671263",
+        "previous_price": 34.00,
+        "current_price": 42.00
+    }]
+}
 ```
 
 ## Contributing
 
 Use GitHub's standard fork/commit/pull-request cycle.  If you have any questions, email <support@semantics3.com>.
 
-## Author
+## Authors
 
 * Sivamani VARUN <varun@semantics3.com>
+* Mounarajan <mounarajan@semantics3.com>
 
 ## Copyright
 
-Copyright (c) 2013 Semantics3 Inc.
+Copyright (c) 2015 Semantics3 Inc.
 
 ## License
 
@@ -180,6 +259,4 @@ Copyright (c) 2013 Semantics3 Inc.
     THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-    DEALINGS IN THE SOFTWARE.
-
-
+    DEALINGS IN THE SOFTWARE.

data/lib/semantics3.rb

@@ -22,21 +22,37 @@ module Semantics3
             raise Error.new('API Credentials Missing','You did not supply an api_key. Please sign up at https://semantics3.com/ to obtain your api_key.','api_key') if api_key == ''
             raise Error.new('API Credentials Missing','You did not supply an api_secret. Please sign up at https://semantics3.com/ to obtain your api_secret.','api_secret') if api_secret == ''
 
-            consumer = OAuth::Consumer.new(@api_key, @api_secret)
-            @auth = OAuth::AccessToken.new(consumer)
+            @consumer = OAuth::Consumer.new(@api_key, @api_secret)
+            @auth = OAuth::AccessToken.new(@consumer)
         end
 
         private
-
+        
+        #def oauth(response)
         #returns a value
-        def _make_request(endpoint, params)
-            url = 'https://api.semantics3.com/v1/' + endpoint + '?q=' + CGI.escape(params)
-
-            #puts "url = #{url}"
-            response = @auth.get(url)
-
-            #-- Response.code - TBD
-            JSON.parse response.body
+        def _make_request(endpoint,method = "GET",params)
+            base_url = 'https://api-staging.semantics3.com/v1/' #+ endpoint + '?q=' + CGI.escape(params)
+
+            if method == "GET"
+                request_data = CGI.escape(params)
+                encoded_url = base_url + endpoint + '?q=' + request_data
+                response = @auth.get(encoded_url)
+                JSON.parse response.body
+            elsif method == "DELETE"
+                url = base_url + endpoint
+                response = @auth.delete(url,params)
+                JSON.parse response.body
+            else    
+                url = URI(base_url+endpoint)
+                request = Net::HTTP::Post.new url.request_uri,params
+                http             = Net::HTTP.new url.host, url.port
+                http.use_ssl     = true
+                http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+                request.oauth! http, @consumer,@auth
+                http.start
+                response = http.request request
+                  JSON.parse response.body
+            end
         end
 
     end
@@ -204,7 +220,7 @@ module Semantics3
             @query_result={}
         end
 
-        def run_query(endpoint,*params)
+        def run_query(endpoint,method = "GET",*params)
 
             #-- If not defined endpoint, throw error
             if not ( endpoint.kind_of? String and endpoint != '')
@@ -214,7 +230,7 @@ module Semantics3
             data = params[0]
 
             if data == nil
-                @query_result = _make_request(endpoint,@data_query[endpoint].to_json)
+                @query_result = _make_request(endpoint,method,@data_query[endpoint].to_json)
             else
                 if not data.is_a?(Hash) and not data.is_a?(String)
                     #-- Throw error - neither string nor hash
@@ -222,12 +238,12 @@ module Semantics3
                 else
                     #-- Data is Hash ref. Great just send it.
                     if data.is_a?(Hash)
-                        @query_result = _make_request(endpoint,data.to_json)
+                        @query_result = _make_request(endpoint,method,data)
                     #-- Data is string
                     elsif data.is_a?(String)
                         #-- Check if it's valid JSON
                         if JSON.is_json?(data)
-                            @query_result = _make_request(endpoint,data)
+                            @query_result = _make_request(endpoint,method,data)
                         else
                             raise Error.new('Invalid Input','You submitted an invalid JSON query string')
                         end
@@ -261,6 +277,4 @@ module JSON
             false
         end 
     end
-end
-
-
+end

data/semantics3.gemspec

@@ -2,10 +2,10 @@ $:.unshift(File.join(File.dirname(__FILE__), 'lib'))
 
 spec = Gem::Specification.new do |s|
   s.name = 'semantics3'
-  s.version = '0.04'
+  s.version = '0.10'
   s.summary = 'Ruby bindings for the Semantics3 API'
   s.description = 'Get access to a constantly updated database of product and price data. See https://semantics3.com/ for more information.'
-  s.authors = ['Sivamani Varun']
+  s.authors = ['Sivamani Varun', 'Mounarajan P A']
   s.email = ['varun@semantics3.com']
   s.homepage = 'https://semantics3.com'
   s.require_paths = %w{lib}

metadata

@@ -1,52 +1,69 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: semantics3
-version: !ruby/object:Gem::Version 
-  version: "0.04"
+version: !ruby/object:Gem::Version
+  version: '0.10'
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Sivamani Varun
+- Mounarajan P A
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2014-03-11 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2015-03-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: json
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    requirements: 
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "1.8"
-    - - ">="
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 1.8.1
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: oauth
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    requirements: 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+- !ruby/object:Gem::Dependency
+  name: oauth
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "0.4"
-    - - ">="
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.4.6
   type: :runtime
-  version_requirements: *id002
-description: Get access to a constantly updated database of product and price data. See https://semantics3.com/ for more information.
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.4.6
+description: Get access to a constantly updated database of product and price data.
+  See https://semantics3.com/ for more information.
+email:
 - varun@semantics3.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Changes
 - Gemfile
@@ -57,29 +74,26 @@ files:
 - semantics3.gemspec
 homepage: https://semantics3.com
 licenses: []
-
-metadata: {}
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - &id003 
-    - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - *id003
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 1.8.23
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Ruby bindings for the Semantics3 API
 test_files: []
-

checksums.yaml

@@ -1,7 +0,0 @@
---- 
-SHA512: 
-  metadata.gz: ec1c393a4622410f28f72e856d70bcfb86a2ae4fa7a833379d699900d51a9b91e0e81b179227db0163083bbe8212e9bfc10d13eda005dac9a73810a9f397dafe
-  data.tar.gz: c31391dfd60d7d21a02fb485c162eeb23d3d24fb58cf8f60ff5de29feb4aae22358295cb5285290b9ecce49c2b104d0e12d649e9dc9c4a6930047654dc387ce8
-SHA1: 
-  metadata.gz: af7ad4b7caafa920f0ba0f66e27e4d94d1d02600
-  data.tar.gz: 2dbc54c3143cfc6adebd9e82a83f5fded103e13b