README.md in pollster-0.2.3 vs README.md in pollster-2.0.0

@@ -1,151 +1,108 @@
-          :::::::::   ::::::::  :::        :::        :::::::: ::::::::::: :::::::::: :::::::::    |                   ,*
-         :+:    :+: :+:    :+: :+:        :+:       :+:    :+:    :+:     :+:        :+:    :+:    |                 ,*
-        +:+    +:+ +:+    +:+ +:+        +:+       +:+           +:+     +:+        +:+    +:+     |             ,*,*
-       +#++:++#+  +#+    +:+ +#+        +#+       +#++:++#++    +#+     +#++:++#   +#++:++#:       |     ,*,   ,*
-      +#+        +#+    +#+ +#+        +#+              +#+    +#+     +#+        +#+    +#+       |   ,*   *,*
-     #+#        #+#    #+# #+#        #+#       #+#    #+#    #+#     #+#        #+#    #+#        | ,*
-    ###         ########  ########## ########## ########     ###     ########## ###    ###         |*
-                                                                                                    - - - - - - - - - - - 
-  
+# pollster
 
-A Ruby wrapper for the [Pollster API](http://elections.huffingtonpost.com/pollster/api) 
-which provides access to political opinion polling data and trend estimates from The Huffington Post.
+Pollster - the Ruby gem for the Pollster API
 
-The Pollster gem has been tested under Ruby 1.8.7, 1.9.2 and 1.9.3.
+Download election-related polling data from Pollster.
 
-## Installation
+[HuffPost Pollster](https://elections.huffingtonpost.com/pollster) is a website that tracks public opinion. Pollster's editors enter polling data for the \"Questions\" they care about -- questions the public answers in \"Polls\".
 
-    gem install pollster
+The Pollster website is organized into \"Charts\" and Pollster-calculated trendlines (descriptions of how the public felt each day, based on the polls and public algorithms). Each Chart is based on a single Question.  The Pollster API provides every point plotted on all the \"Charts\" on the Pollster website. Furthermore, it provides the raw polling data that went into those charts: every response to every Question, at whichever level of detail the developer requests.
 
-## Getting Started
+This SDK was originally generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:
 
-    require 'pollster'
-    include Pollster
+- API version: 2.0.0
+- Package version: 2.0.0
+- Build package: class io.swagger.codegen.languages.RubyClientCodegen
 
-See the current estimate of the president's job approval
+For more information, please visit [https://groups.google.com/forum/#!forum/pollster-users](https://groups.google.com/forum/#!forum/pollster-users)
 
-    Chart.find('obama-job-approval').estimates
+## Installation
 
-List charts about 2012 senate races
+In short: add `gem 'pollster', '~> 2.0.0'` to your Gemfile.
 
-    Chart.where(:topic => '2012-senate')
+Full installation options:
 
-List charts about Wisconsin
+### Build a gem
 
-    Chart.where(:state => 'WI')
+To build the Ruby code into a gem:
 
-Calculate the margin between Obama and Romney from a recent general election poll
+```shell
+gem build pollster.gemspec
+```
 
-    poll = Poll.where(:chart => '2012-general-election-romney-vs-obama').first
-    responses = poll.questions.detect { |question| question.chart == '2012-general-election-romney-vs-obama' }.responses
-    obama = responses.detect { |response| response[:choice] == "Obama" }
-    romney = responses.detect { |response| response[:choice] == "Romney" }
-    obama[:value] - romney[:value]
+Then either install the gem locally:
 
-See the methodology used in recent polls about the Affordable Care Act
+```shell
+gem install ./pollster-2.0.0.gem
+```
+(for development, run `gem install --dev ./pollster-1.0.0.gem` to install the development dependencies)
 
-    chart = Chart.find 'us-health-bill'
-    chart.polls.map { |poll| [poll.pollster, poll.method] }
+or publish the gem to a gem hosting service, e.g. [RubyGems](https://rubygems.org/).
 
-## Usage
+Finally add this to the Gemfile:
 
-Pollster provides three classes:
+    gem 'pollster', '~> 2.0.0'
 
-    Pollster::Chart
+### Install from Git
 
-represents the current estimates for a Pollster chart (e.g. [Romney vs. Obama](http://elections.huffingtonpost.com/pollster/2012-general-election-romney-vs-obama)).
+If the Ruby gem is hosted at a git repository: https://github.com/YOUR_GIT_USERNAME/YOUR_GIT_REPO, then add the following in the Gemfile:
 
-    Pollster::Poll
+    gem 'pollster', :git => 'https://github.com/YOUR_GIT_USERNAME/YOUR_GIT_REPO.git'
 
-represents a specific poll conducted by a polling firm.
+### Include the Ruby code directly
 
-    Pollster::Question
+Include the Ruby code directly using `-I` as follows:
 
-represents a question asked as part of a poll.
+```shell
+ruby -Ilib script.rb
+```
 
-### Accessing data
+## Getting Started
 
-List all the charts available from Pollster:
+Please follow the [installation](#installation) procedure and then run the following code:
+```ruby
+# Load the gem
+require 'pollster'
 
-    >> Pollster::Chart.all
-    => [<Pollster::Chart: 2012 Iowa GOP Primary>,
-        <Pollster::Chart: 2012 New Hampshire GOP Primary>,
-        <Pollster::Chart: 2012 South Carolina GOP Primary>,
-        <Pollster::Chart: 2012 Florida GOP Primary>,
-        <Pollster::Chart: 2012 Nevada GOP Primary>,
-        ...]
+api = Pollster::Api.new
 
-This response is not paginated; all charts will be returned.
+opts = { 
+  cursor: nil,                            # Special string to index into the Array
+  tags: "2016-president",                 # Comma-separated list of tag slugs
+  election_date: Date.parse("2013-10-20") # Date of an election
+}
 
-A specific chart may be accessed using Pollster::Chart#find, giving the chart's slug as an argument:
+begin
+  result = api.charts_get(opts)
+  p result
+rescue Pollster::ApiError => e
+  puts "Exception when calling Api->charts_get: #{e}"
+end
 
-    >> Pollster::Chart.find('2012-iowa-gop-primary')
-    => <Pollster::Chart: 2012 Iowa GOP Primary>
+```
 
-All the charts for a topic or state may be accessed using Pollster::Chart#where:
+## API documentation
 
-    >> Pollster::Chart.where(:state => 'MD')
-    => [<Pollster::Chart: 2012 Maryland GOP Primary>,
-        <Pollster::Chart: 2012 Maryland House: 6th District>,
-        <Pollster::Chart: 2012 Maryland President: Romney vs. Obama>]
+Perhaps the best documentation is `example.rb`: it shows how to use all API
+endpoints and how to paginate.
 
-    >> Pollster::Chart.where(:topic => '2012-senate')
-    => [<Pollster::Chart: 2012 Massachusetts Senate: Brown vs Warren>,
-        <Pollster::Chart: 2012 Ohio Senate: Brown vs Mandel>,
-        <Pollster::Chart: 2012 Arizona Senate: Flake vs. Carmona>,
-        <Pollster::Chart: 2012 Florida Senate: Mack vs. Nelson>,
-        ...]
+See https://elections.huffingtonpost.com/pollster/api/v2/help for more details.
 
-    >> Pollster::Chart.where(:topic => '2012-senate', :state => 'MA')
-    => [<Pollster::Chart: 2012 Massachusetts Senate: Brown vs Warren>]
+See https://app.swaggerhub.com/api/huffpostdata/pollster-api/2.0.0 for full API
+documentation. The Ruby-specific warts:
 
-List the polls that were used to create the estimate for a specific chart:
+* For the TSV endpoints `questions/{slug}/poll-responses-clean.tsv` and
+  `charts/{slug}/pollster-chart-poll-questions.tsv`, the return values include a
+  `responses` Hash that maps from `label` (String) to `value` (Float).
+* Ruby API method names are snake-cased versions of the API endpoints and end
+  with `_get`. For example, the Ruby method to access
+  `questions/{slug}/poll-responses-clean.tsv` is
+  `api.questions_slug_poll_responses_clean_tsv_get(slug)`.
 
-    >> chart = Pollster::Chart.find('2012-iowa-gop-primary')
-    >> chart.polls
-    => [#<Pollster::Poll:...
-        @start_date=#<Date: 2012-01-01 (4911855/2,0,2299161)>>,
-        @end_date=#<Date: 2012-01-01 (4911855/2,0,2299161)>,
-        @id=12385,
-        @method="Automated Phone",
-        @pollster="InsiderAdvantage",
-        @questions=
-         [{:name=>"2012 Iowa GOP Primary",
-           :chart=>"2012-iowa-gop-primary",
-           :topic=>"2012-gop-primary",
-           :state=>"IA",
-           :subpopulations=>
-            [{:name=>"Likely Voters",
-              :observations=>729,
-              :margin_of_error=>nil,
-              :responses=>
-               [{:choice=>"Romney", :value=>23},
-                {:choice=>"Bachmann", :value=>6},
-                {:choice=>"Gingrich", :value=>16},
-                {:choice=>"Huntsman", :value=>2},
-                {:choice=>"Paul", :value=>22},
-                {:choice=>"Perry", :value=>10},
-                {:choice=>"Santorum", :value=>18},
-                {:choice=>"Other", :value=>1},
-                {:choice=>"Undecided", :value=>2}]}]}],
-        @source= "http://www.realclearpolitics.com/docs/2012/InsiderAdvantage_Iowa_0102.pdf",
-        ...]
+## Author
 
+Adam Hooper, [e-mail].
 
-You may also list all polls available through Pollster:
-
-    >> Pollster::Poll.all
-
-This response is paginated, with 10 polls per page. To access subsequent pages, provide a page argument:
-
-    >> Pollster::Poll.all(:page => 5)
-
-## Authors
-
-- Aaron Bycoffe, [e-mail]
-- Jay Boice, [e-mail]
-- Andrei Scheinkman, [e-mail]
-
 ## Copyright
 
-Copyright © 2012 The Huffington Post. See LICENSE for details.
+Copyright © 2016 The Huffington Post. See LICENSE for details.