quandl_ruby 0.0.3 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c2169fcb001f481bf93cdbb46ee7a9bc8e34513
-  data.tar.gz: 635b03bfe0a03217d23f6dcd86bdf6ecffc37fae
+  metadata.gz: 9275405a269d7f57d7b7f64d5dd6ace2c0ceb352
+  data.tar.gz: b284408ee8bc65da6d986ec06dcf8d65184196ba
 SHA512:
-  metadata.gz: 8e70f2a1c36677ecd9c19a4fe22f4d59e8e94e115d9f94099afa76a0b69fcc6fcbee2bb046b6629783edeae3311816b9873bcf161190b3ad10b147bcf188a61b
-  data.tar.gz: e9d86debe8f31abf4f9f0decdb7e44b6a78881c5fefb96cb91011b2aa2cb673255922a2f93af1b3c5bced15c055892d227739d3a87c21229d74ff5d91a003fc8
+  metadata.gz: 23695cec4f2250f0087b07b4571ca9cbfec10a4972b76f0196c9c9ba5b357d69951e139d32fd2f7cb13a0615fafcaa471dfaf5cdd8e96d12fb217faa19f2219a
+  data.tar.gz: c4b87f47728e8c1152f13c8b625381d4044484f3b9f8d57e45c288d942575edc225b8838102c88b92ebab1228e90acb16cad3e73ecfcf1b0769e5fd14b3d9246

data/README.md

@@ -1,14 +1,8 @@
-# Quandl
+[![Gem Version](https://badge.fury.io/rb/quandl_ruby.svg)](http://badge.fury.io/rb/quandl_ruby)
 
-Ruby wrapper for the Quandl API (www.quandle.com).
+# Quandl Ruby
 
-Supports:
-
-- Datasets
-- Metadata
-- Multisets
-- Searches
-- Favorites
+A Ruby wrapper for the Quandl API (www.quandl.com).
 
 ## Installation
 
@@ -26,79 +20,124 @@ Or install it yourself as:
 
 ## Usage
 
-### Configuration
+### Getting Started
 
-If you've got a Quandl API key, configure the Ruby API as below. If not, skip this step.
+If you've got an API key from Quandl, set it up as below. Feel free to otherwise skip this step.
 
 ```ruby
 Quandl.configure do |config|
-  config.auth_token = 'your auth token here'
+  config.auth_token = 'your quandl api key'
 end
 ```
 
-### Getting A Dataset
+### The API
 
-To get a dataset, create a new `Quandl::Dataset`:
+This library includes the following classes all namespaced under the `Quandl` module:
 
-```ruby
-gdp = Quandl::Dataset.get('FRED/GDP')
-```
+- [Dataset](http://www.quandl.com/help/api#A-Simple-Example)
+- [Multiset](http://www.quandl.com/help/api#Multiple-Datasets)
+- [Search](http://www.quandl.com/help/api#Doing-a-Search)
+- [Metadata](http://www.quandl.com/help/api#Getting-Metadata)
+- [Favorites](http://www.quandl.com/help/api#Getting-Favourites)
 
-`Quandl::Dataset#new` accepts an options hash as a second argument. Put anything that you would otherwise but as an argument in the url here.
+All the above classes have the same API:
 
 ```ruby
-aapl = Quandl::Dataset.get('WIKI/AAPL', {
-  format: 'csv',
-  column: 4,
-  collapse: 'annual'
-})
-```
+# Replace `Class` below with the relevant class from above.
 
+# Query is the specific query for that class
+# Options is an options hash containing data manipulation options
 
-### Getting Metadata
+# Data manipulation docs:
+#   http://www.quandl.com/help/api#Data-Manipulation
 
-The `Quandl::Metadata` API is exactly the same as the `Quandl::Dataset` API, except that it only returns metadata.
+# Creating an instance doesn't retrieve the data
+# Data format options:
+#   `:json` => parsed JSON (default)
+#   `:csv`  => parsed CSV into hashes
+#   `:xml`  => a string of unparsed xml
+# Set the format by providing a `:format` key in the options hash
+query = Quandl::Class.new(query, options)
 
-```ruby
-oil = Quandl::Metadata.get('NSE/OIL')
-```
+# Use instance#get to retrieve data from Quandl
+data = query.get
 
+# Instantiating and then calling the `get` method memoizes the response
+# Pass in `true` to instance#get to clear the cache and reload the data
+data = query.get(true)
 
-### Using Multisets
+# The following is a shortcut to Class.new(query, options).get,
+# albeit with no build-in memoization:
+data = Quandl::Class.get(query, options)
+```
 
-The `Quandl::Multiset` class allows you to build multisets for yourself. Accepts `options` hash as a secondary argument to the initializer.
+### A Simple Example
 
 ```ruby
-example = Quandl::Multiset.get(['FRED/GDP/1', 'WIKI/AAPL/4'])
+# Get the US GDP in JSON
+#   Example from: http://www.quandl.com/help/api#A-Simple-Example
+gdp = Quandl::Dataset.get('FRED/GDP')
 ```
 
-Unlike the official Quandl API, use `/` (instead of `.`) as your delimiter for source, table, and column number to maintain consistency with `Quandl::Dataset`.
+### A Multiset Example
+```ruby
+# Annual percentage changes of US GDP, crude oil prices, and Apple stock for the last 10 years
+#   Example from: http://www.quandl.com/help/api#A-Multiset-Example
+
+datasets = ['FRED/GDP/1', 'DOE/RWTC/1', 'WIKI/AAPL/4']
+options = {
+  collapse: 'annual',
+  transformation: 'rdiff',
+  rows: 10
+}
+comparison = Quandl::Multiset.new(datasets, options)
+# Unlike the official Quandl REST API, separate source, table, and column numbers
+# With `/` as opposed to `.` to maintain consistency with Quandl::Dataset
+```
 
+### Doing A Search
 
-### Searching Quandl
+```ruby
+# Get search results for crude oil
+#   Example from: http://www.quandl.com/help/api#Doing-a-Search
+query = 'crude oil'
+options = {
+  per_page: 50,
+  page: 2
+}
+results = Quandl::Search.get(query, options)
+```
 
-The `Quandl::Search` API is exactly the same as the `Quandl::Dataset` API, except that it returns a query.
+### Getting Metadata
 
 ```ruby
-results = Quandl::Search.get('crude oil')
+# Retrieve only the metadata for a dataset
+#   Example from: http://www.quandl.com/help/api#Getting-Metadata
+oil_metadata = Quandl::Metadata.get('NSE/OIL')
 ```
 
 
-### Retrieving Favorites
-
-The `Quandl::Favorites` API allows you to retrieve the favorites of any user.
+### Getting Favorites
 
 ```ruby
-# If an authorization token was previously configured with Quandl.configure,
-# then one is not required for Quandl::Favorites.get
+# Retrieve a user's favorites
+#   Example from: http://www.quandl.com/help/api#Getting-Favourites
 
-favs = Quandl::Favorites.get(
-  :auth_token => 'an auth token here'
-  # Any other options here
-)
+# Defaults to getting the favorites of the user who's API key you've configured
+my_favorites = Quandl::Favorites.get
+
+# Or pass in another API key as the first argument to override your own
+some_other_guys_favorites = Quandl::Favorites.get('that_guys_api_key')
+
+# For Brits and Canucks, Quandl::Favorites is aliased as Quandl::Favourites
 ```
 
 
+### Further Resources
+
+Consult the [official API docs](http://www.quandl.com/help/api).
+
+
 ## Contributing
 
 1. [Fork it](https://github.com/knrz/quandl/fork)

data/Rakefile

@@ -1,2 +1 @@
 require "bundler/gem_tasks"
-

data/lib/quandl/dataset.rb

@@ -6,9 +6,9 @@ module Quandl
       instance = new(params, options)
       instance.get
       if block_given?
-        yield(data)
+        yield(instance.data)
       else
-        data
+        instance.data
       end
     end
 
@@ -19,10 +19,11 @@ module Quandl
 
     def get(reload = false)
       if !data || reload
-        self.data = Quandl::Request.new('datasets', {
+        raw_data = Quandl::Request.new('datasets', {
           dataset: set,
           options: options
         }).get
+        self.data = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
       end
       if block_given?
         yield(data)

data/lib/quandl/favorites.rb

@@ -19,10 +19,11 @@ module Quandl
 
     def get(reload = false)
       if !data || reload
-        self.data = Quandl::Request.new('current_user/collections/datasets/favourites', {
+        raw_data = Quandl::Request.new('current_user/collections/datasets/favourites', {
           options: options,
           auth_token: auth_token
         }).get
+        self.data = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
       end
       if block_given?
         yield(data)
@@ -31,4 +32,6 @@ module Quandl
       end
     end
   end
+
+  Favourites = Favorites
 end

data/lib/quandl/multiset.rb

@@ -19,10 +19,11 @@ module Quandl
 
     def get
       if !data || reload
-        self.data = Quandl::Request.new('multisets', {
+        raw_data = Quandl::Request.new('multisets', {
           datasets: sets,
           options: options
         }).get
+        self.data = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
       end
       if block_given?
         yield(data)

data/lib/quandl/parse.rb

@@ -0,0 +1,25 @@
+require 'json'
+require 'csv'
+
+module Quandl
+
+  CSV::Converters[:blank_to_nil] = Proc.new do |field|
+    field && field.empty? ? nil : field
+  end
+
+  def self.parse(data, format)
+    case format
+    when :json
+      JSON.parse(data, {
+        symbolize_names: true
+      })
+    when :csv
+      CSV.parse(data, {
+        headers: true,
+        header_converters: :symbol,
+        converters: [:all, :blank_to_nil]
+      }).map(&:to_hash)
+    else data
+    end
+  end
+end

data/lib/quandl/request.rb

@@ -1,3 +1,5 @@
+require 'open-uri'
+
 module Quandl
   API_URI = 'http://www.quandl.com/api/'
 
@@ -22,7 +24,7 @@ module Quandl
       if params[:dataset]
         path += "/#{params[:dataset]}"
       end
-      path += '.' + ((params[:options] || {}).delete(:format) || 'json')
+      path += '.' + (params[:options][:format] || 'json').to_s
       @uri = URI(API_URI + path).tap do |uri|
         uri.query = URI.encode_www_form(params[:options])
       end

data/lib/quandl/search.rb

@@ -8,7 +8,7 @@ module Quandl
       if block_given?
         yield(instance.data)
       else
-        data
+        instance.data
       end
     end
 
@@ -19,10 +19,11 @@ module Quandl
 
     def get
       if !data || reload
-        self.data = Quandl::Request.new('datasets', {
+        raw_data = Quandl::Request.new('datasets', {
           query: query,
           options: options
         }).get
+        self.data = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
       end
       if block_given?
         yield(data)

data/lib/quandl/version.rb

@@ -1,3 +1,3 @@
 module Quandl
-  VERSION = '0.0.3'
+  VERSION = '0.1.1'
 end

data/lib/quandl.rb

@@ -1,9 +1,9 @@
 require_relative 'quandl/version'
 require_relative 'quandl/configuration'
+require_relative 'quandl/parse'
 require_relative 'quandl/dataset'
 require_relative 'quandl/metadata'
 require_relative 'quandl/multiset'
 require_relative 'quandl/search'
 require_relative 'quandl/favorites'
 require_relative 'quandl/request'
-require 'open-uri'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quandl_ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.1
 platform: ruby
 authors:
 - Kash Nouroozi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-19 00:00:00.000000000 Z
+date: 2014-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -56,6 +56,7 @@ files:
 - lib/quandl/favorites.rb
 - lib/quandl/metadata.rb
 - lib/quandl/multiset.rb
+- lib/quandl/parse.rb
 - lib/quandl/request.rb
 - lib/quandl/search.rb
 - lib/quandl/version.rb