stackconnect 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6bd43f38b8f408dd657b8045fd25f77f91bfbe60
-  data.tar.gz: 7e318ac6b8d9e6ee2bda70cba17a2f61bd4f0a40
+  metadata.gz: 2de51d7518dfcd0b45c0ef3ed60f279fff9097aa
+  data.tar.gz: 8726a8cc6d90d9ebc4b9d4883c89d98cde070bcc
 SHA512:
-  metadata.gz: fcedc0c7268ed8cf41cfe1e356d24bcb0d7f56931c96ca8f0f073e4949ae002123b13f1b3b0390de3b62f66d8cdf786f78c63748ad53b6482a7cd2d68a0e5d9f
-  data.tar.gz: 2db8dce20edf4fa8bd873d9c4ab2f0db56de9fd83ffcb919b7fd873a64ae8384483f1bec8a7969563336d790b894598b2c648abed61ecb16ecb2160dbeb9fb78
+  metadata.gz: e17c4d2d92d6009cb48ce02392081ebe0c36ff059cb9c57a3782b5b724920b684f157f35d2b04bf84ad40943fda131cf58f0d59999fd71ff91f1073a6baf4ebb
+  data.tar.gz: 3ae270f51d823113f757569d5725649a5de0bfb1baa11b9369cfa8ea2db1866ce2a005a703fd6636d73db248f6049c6916c690ac61f0df4aff8fe487326e35c2

data/.gitignore

@@ -1,3 +1,4 @@
+*.swo
 *.gem
 *.swp
 *.rbc

data/README.md

@@ -1,6 +1,10 @@
 # stackconnect
 
-Ruby API for making StackOverflow queries. This is a limited number of the API calls that can be made to the StackOverflow API, and these are all quota limited. So the response you get is not the full amount of data available, just the most popular/highest ranked data based on activity and date. 
+Ruby API for making StackOverflow queries. This is a limited number of the API calls that can be made to the StackOverflow API, mainly dealing with tags, questions, and users. 
+
+## Software Versions
+
+This has been tested and written for Rails 4.0 and above, and Ruby 2.0.0 and above. 
 
 ## Installation
 
@@ -16,9 +20,15 @@ Or install it yourself as:
 
     $ gem install stackconnect
 
+If you want the most current version of the gem, in your Gemfile, add this:
+    
+    gem 'stackconnect', :git => 'git://github.com/stackgems/stackconnect.git'
+
 ## Usage
 
-These methods are quota restricted. The Stack Exchange API only allows a quota of 10000 without an API key: http://api.stackexchange.com/docs/authentication. Once you get over that quota without a key, your IP address will be throttled from making any more requests until the next day. 
+These methods are quota restricted. The Stack Exchange API only allows a quota of 10,000 without an API key: http://api.stackexchange.com/docs/authentication. Once you get over that quota without a key, your IP address will be throttled from making any more requests until the next day. 
+
+If you get an API key, your limit will still be 10,000 (per application), with a limit of 5 applications. 
 
 ### Retrieve Total Number of Questions 
 ```
@@ -26,9 +36,9 @@ These methods are quota restricted. The Stack Exchange API only allows a quota o
  total = sc.retrieve_total_questions(from_date)
 ```
 
-This will return an number. 
+This will return a Ruby Fixnum.
 
-From date has to be in Unix date format. So for example, to retrieve the total number of questions from yesterday, 
+`fromdate` has to be in Unix date format. So for example, to retrieve the total number of questions from yesterday:
 
 ```
  date = Date.today.to_time.to_i
@@ -37,6 +47,8 @@ From date has to be in Unix date format. So for example, to retrieve the total n
 
 ### Retrieve Most Popular Tags of All Time
 
+The default sort is `popular`, and the order is `desc` in order to list the most popular tags first. 
+
 `data = sc.retrieve_most_popular_tags`
 
 This will return a JSON data object which you can then parse. An example:
@@ -80,11 +92,19 @@ The data looks like this:
 }
 ```
 
-### Retrieving the Most Popular Tags of the Day
+### Retrieving the Most Popular Tags from a Particular Date
 
-These are sorted based on activity.
+The way StackOverflow handles date ranges for tags is not what you would expect: the count returned with each tag is actually the all-time count for that tag, not the count of the tag for that particular day, or date range. If you want to get the total number of tags for a particular day, you would have to parse the `/questions` API call return data, and iterate through all the questions for that day.
 
-`data = StackConnect.retrieve_day_popular_tags(from_date)`
+When you give a date range for the `/tags` call, the `'todate'` parameter is ignored, and will give the same response if it wasn't included at all. However, querying StackOverflow with a `'fromdate'` and sorting on `'popular'` will return the most popular tags for that particular time. Therefore, given the way the data is returned, `retrieve_tags(from_date)` already sorts on popular by default, otherwise, the data isn't very meaningful.
+
+The date range is also restricted to be after January 1st, 2009. If a date before this time is given inside the query, an exception will be thrown. 
+
+If the API call is given any other sort type, such as `'popular'` or `'name'`, and the fromdate is before January 1st, 2009, StackOverflow will return the most popular tags of all time. If the sort type is `'activity'`, no data will be returned. 
+
+The order is also `'desc'` (descending) by default, so that the most popular tags are shown first. 
+
+`data = StackConnect.retrieve_tags(from_date)`
 
 Sample Data:
 
@@ -98,13 +118,6 @@ Sample Data:
       "count": 1,
       "name": "microsoft-net-http"
     },
-    {
-      "has_synonyms": false,
-      "is_moderator_only": false,
-      "is_required": false,
-      "count": 1,
-      "name": "owin-middleware"
-    },
     {
       "has_synonyms": false,
       "is_moderator_only": false,
@@ -119,6 +132,79 @@ Sample Data:
 }
 ```
 
+### Retrieving User Data
+
+This call will retrieve all time user data, since the creation of the site. When making this API call, check for the `'has_more'` attribute to see if there are more pages. If `'has_more'` returns true, then increase the `'page'` parameter before calling the function again to retrieve the next page of data.
+
+The query is called with a sort on `'reputation'`, and ordered in descending order. Therefore, the users with the highest reputation will appear first. 
+
+```
+  sc = StackConnect.new
+  data = sc.retrieve_users(1)
+```
+
+Sample data:
+
+```
+{
+  "items": [
+    {
+      "badge_counts": {
+        "bronze": 5498,
+        "silver": 4081,
+        "gold": 261
+      },
+      "account_id": 11683,
+      "is_employee": false,
+      "last_modified_date": 1394538684,
+      "last_access_date": 1394629373,
+      "reputation_change_year": 21465,
+      "reputation_change_quarter": 21465,
+      "reputation_change_month": 3600,
+      "reputation_change_week": 1085,
+      "reputation_change_day": 215,
+      "reputation": 656402,
+      "creation_date": 1222430705,
+      "user_type": "registered",
+      "user_id": 22656,
+      "age": 37,
+      "accept_rate": 83,
+      "location": "Reading, United Kingdom",
+      "website_url": "http://csharpindepth.com",
+      "link": "http://stackoverflow.com/users/22656/jon-skeet",
+      "display_name": "Jon Skeet",
+      "profile_image": "https://www.gravatar.com/avatar/6d8ebb117e8d83d74ea95fbdd0f87e13?s=128&d=identicon&r=PG"
+    }
+  ],
+  "has_more": true,
+  "quota_max": 10000,
+  "quota_remaining": 9990
+}
+```
+The sample data here only has one item, normally, you'd get the first 30 results. In order to check if there is more data:
+
+```
+has_more = data["has_more"]
+```
+If `'has_more'` returns true, then increase the page count, and call again:
+
+```
+page = 1
+begin
+  data = sc.retrieve_users(page)
+
+  # work with data
+  ..
+
+  has_more = data["has_more"]
+  page += 1
+  sleep(1)
+end while has_more == true
+ 
+```
+
+Make sure that in before making the call, you call `sleep()` for at least one second, otherwise, the StackExchange API will throttle your requests and require you to wait a certain amount of time before making another request. Usually increasing this time to about 10 seconds will guarantee your calls won't get throttled for the remainder of the pages. 
+
 ## Contributing
 
 1. Fork it ( http://github.com/[my-github-username]/stack-connect/fork )

data/lib/stackconnect.rb

@@ -1,11 +1,11 @@
-require 'active_support/all'
+require 'active_support/core_ext/hash'
 require 'open-uri'
 require 'uri'
 
 class StackConnect
   attr_accessor :api, :site, :uri
   
-  @@VERSION = "0.1.5"
+  @@VERSION = "0.1.6"
   @@api = 'http://api.stackexchange.com/'
   @@site = 'stackoverflow'
   @@api_v = '/2.2/'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stackconnect
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - amirtcheva
@@ -115,6 +115,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .README.md.swo
 - .gitignore
 - Gemfile
 - LICENSE.txt