billboard 0.1.0

data/History

@@ -0,0 +1 @@
+0.1.0 - initial release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Wynn Netherland
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL 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.

data/README.markdown

@@ -0,0 +1,37 @@
+# billboard
+
+Ruby wrapper for the Billboard charts API. Great for cheating at trivia games.
+
+## Installation
+
+    sudo gem install billboard
+    
+## Usage
+    
+    api_key = 'OU812' # get yours at http://developer.billboard.com/apps/register
+    client = Billboard::Client.new(api_key)
+    
+### Find a chart by type
+
+    charts = client.chart_specs(:type => 'Videos').charts
+    
+### Find items on a chart
+
+    items = client.search(:id => charts.last.id).chart_items
+    items.last.song = "Lost: The Complete Third Season"
+    items.last.weeks_on = 21
+
+## Note on Patches/Pull Requests
+ 
+* 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
+
+Copyright (c) 2009 Wynn Netherland. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,91 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "billboard"
+    gem.summary = %Q{Ruby wrapper for the Billboard charts API}
+    gem.description = %Q{Great for cheating at trivia games}
+    gem.email = "wynn@squeejee.com"
+    gem.homepage = "http://github.com/pengwynn/billboard"
+    gem.authors = ["Wynn Netherland"]
+    gem.rubyforge_project = "billboard"
+    gem.files             = FileList["[A-Z]*", "{examples,lib,test}/**/*"]
+    
+    gem.add_dependency('mash', '0.0.3')
+    gem.add_dependency('httparty', '0.4.3')
+    
+    gem.add_development_dependency('thoughtbot-shoulda')
+    gem.add_development_dependency('jeremymcanally-matchy')
+    gem.add_development_dependency('mocha')
+    gem.add_development_dependency('fakeweb')
+    gem.add_development_dependency('mash')
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "billboard #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+    
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+    
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/remixr/rdoc"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 0
+:major: 0
+:minor: 1

data/lib/billboard.rb

@@ -0,0 +1,47 @@
+require 'rubygems'
+
+gem 'mash', '0.0.3'
+require 'mash'
+
+gem 'httparty', '0.4.3'
+require 'httparty'
+
+gem 'activesupport', '~> 2.3.2'
+require 'activesupport'
+
+class APIKeyNotSet   < StandardError; end
+
+module Billboard
+  
+  # Get your API key from http://developer.billboard.com/apps/register
+  def self.api_key
+    raise APIKeyNotSet if @api_key.nil?
+  
+    @api_key
+  end
+  
+  def self.api_key=(api_key)
+    @api_key = api_key
+  end
+  
+end
+
+class Hash
+  
+  # Converts all of the keys to strings, optionally formatting key name
+  def rubyify_keys!
+    keys.each{|k|
+      v = delete(k)
+      new_key = k.to_s.underscore
+      self[new_key] = v
+      v.rubyify_keys! if v.is_a?(Hash)
+      v.each{|p| p.rubyify_keys! if p.is_a?(Hash)} if v.is_a?(Array)
+    }
+    self
+  end
+  
+end
+
+directory = File.expand_path(File.dirname(__FILE__))
+
+require File.join(directory, 'billboard', 'client')

data/lib/billboard/client.rb

@@ -0,0 +1,85 @@
+module Billboard
+  class Client
+    include HTTParty
+    base_uri 'api.billboard.com/apisvc/chart/v1'
+    format :json
+    
+    attr_reader :api_key
+    
+    # Get your api_key found here http://developer.billboard.com/apps/register
+    def initialize(api_key=nil)
+      @api_key = api_key
+      @api_key ||= Billboard.api_key
+      
+      @api_path = ''
+
+    end
+    
+    # Use this resource to search Billboard data for chart items by 
+    # id, by date, by artist, or by song.
+    #
+    # Parameters:
+    # 
+    #     id          string(optional)  Chart spec(format) id - this can be retrieved by spec service
+    #     start_date  string(optional)  Chart issue date range start
+    #     end_date    string(optional)  Chart issue date range end
+    #     artist      string(optional)  Artist name to search
+    #     song        string(optional)  Song name to search
+    #
+    #     start       default: 1              Start position of raw ResultSet
+    #     count       default: 50             number of data might be returned. Maximum 50
+    #     sort        default: date-, name+   Sort order desired, with "+" or "-" suffix to indicate ascending or descending. For example, date+
+    #
+    def search(query={})
+      results = Mash.new(self.class.get('/list', :query => scrub_query(query))['searchResults']).rubyify_keys!
+      results.chart_items = results.delete('chart_item')
+      results.chart_items = [] if results.chart_items.nil?
+      results
+    end
+    
+    
+    # Get chart data based on chart ID
+    #
+    # Parameters
+    #
+    #     id  String
+    #
+    def chart(id, query={})
+      chart = Mash.new(self.class.get('/item', :query => {:id => id}.merge(query).merge(self.default_options))).chart
+      chart.rubyify_keys!
+      chart.chart_items.items = chart.chart_items.delete('chart_item')
+      chart
+    end
+    
+    # This resource returns data on the different chart names 
+    # and chart types. 
+    #
+    # The API orders the results ascending by ChartSpecId.
+    #
+    # Parameters
+    #
+    #     name   string(optional)  chart name, for example: The Billboard Hot 100
+    #     type   string(optional)  chart type, for example: Singles
+    #
+    def chart_specs(query={})
+      results = Mash.new(self.class.get('/list/spec', :query => query.merge(self.default_options))['chartSpecs'])
+      results.rubyify_keys!
+      results.charts = results.delete('chart_spec')
+      results
+    end
+    
+    protected
+    
+      def default_options
+        {:api_key => @api_key, :format => 'json'}
+      end
+      
+      def scrub_query(query)
+        query[:sdate] = query[:start_date] unless query[:start_date].blank?
+        query[:edate] = query[:end_date] unless query[:end_date].blank?
+        query[:sort] = query[:sort].gsub('+', ' ') unless query[:sort].blank?
+        query.merge(self.default_options)
+      end
+    
+  end
+end

data/test/billboard/client_test.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class ClientTest < Test::Unit::TestCase
+  include Billboard
+  
+  context "Hitting the Billboard API" do
+    setup { @client = Billboard::Client.new('OU812') }
+    
+    should "find chart data based on chart id" do
+      stub_get 'http://api.billboard.com/apisvc/chart/v1/item?id=3064446&format=json&api_key=OU812', 'chart.json'
+      chart = @client.chart(3064446)
+      chart.description.should == 'Chart'
+      chart.chart_items.items.size.should == 10
+      chart.chart_items.items.last.artist_name.should == 'Sade'
+    end
+    
+    should "find chart data based on artist name and date range" do
+      stub_get 'http://api.billboard.com/apisvc/chart/v1/list?end_date=1975-12-31&format=json&sdate=1975-01-01&artist=Waylon%20Jennings&sort=date%20&edate=1975-12-31&start_date=1975-01-01&api_key=OU812', 'artist_search_with_date_range.json'
+      results = @client.search(:artist => 'Waylon Jennings', :start_date => '1975-01-01', :end_date => '1975-12-31', :sort => 'date+')
+      results.total_records.should == 927
+      results.chart_items.size.should == 50
+      results.chart_items.last.song.should == "Sweet Dream Woman"
+      results.chart_items.last.weeks_on.should == 13
+    end
+    
+    should "find album charts" do
+      stub_get 'http://api.billboard.com/apisvc/chart/v1/list/spec?type=album&api_key=OU812&format=json', 'album_charts.json'
+      results = @client.chart_specs(:type => 'album')
+      results.total_records.should == 589
+      results.total_returned.should == 50
+      results.charts.last.name.should == 'Latin Rhythm Albums'
+      
+    end
+    
+  end
+end

data/test/fixtures/album_charts.json

@@ -0,0 +1,257 @@
+{
+    "chartSpecs": {
+        "firstPosition": 1,
+        "totalReturned": 50,
+        "chartSpec": [{
+            "type": "Albums",
+            "name": "Billboard Comprehensive Albums",
+            "id": 292
+        },
+        {
+            "type": "Albums",
+            "name": "European Top 100 Albums",
+            "id": 293
+        },
+        {
+            "type": "Albums",
+            "name": "Heatseekers",
+            "id": 294
+        },
+        {
+            "type": "Albums",
+            "name": "Latin Pop Albums",
+            "id": 295
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers (East North Central)",
+            "id": 296
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers (Middle Atlantic)",
+            "id": 297
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers (Mountain)",
+            "id": 298
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers (Northeast)",
+            "id": 299
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers (Pacific)",
+            "id": 300
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers (South Atlantic)",
+            "id": 301
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers (South Central)",
+            "id": 302
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers (West North Central)",
+            "id": 303
+        },
+        {
+            "type": "Albums",
+            "name": "Regional Mexican Albums",
+            "id": 304
+        },
+        {
+            "type": "Albums",
+            "name": "The Billboard 200",
+            "id": 305
+        },
+        {
+            "type": "Albums",
+            "name": "The Billboard Classical 50",
+            "id": 306
+        },
+        {
+            "type": "Albums",
+            "name": "Top Bluegrass Albums",
+            "id": 307
+        },
+        {
+            "type": "Albums",
+            "name": "Top Blues Albums",
+            "id": 308
+        },
+        {
+            "type": "Albums",
+            "name": "Top Canadian Albums",
+            "id": 309
+        },
+        {
+            "type": "Albums",
+            "name": "Top Christian Albums",
+            "id": 310
+        },
+        {
+            "type": "Albums",
+            "name": "Top Classical Albums",
+            "id": 311
+        },
+        {
+            "type": "Albums",
+            "name": "Top Classical Budget Albums",
+            "id": 312
+        },
+        {
+            "type": "Albums",
+            "name": "Top Classical Crossover Albums",
+            "id": 313
+        },
+        {
+            "type": "Albums",
+            "name": "Top Classical Midline Albums",
+            "id": 314
+        },
+        {
+            "type": "Albums",
+            "name": "Top Comedy Albums",
+            "id": 315
+        },
+        {
+            "type": "Albums",
+            "name": "Top Compilation Albums",
+            "id": 316
+        },
+        {
+            "type": "Albums",
+            "name": "Top Contemporary Christian",
+            "id": 317
+        },
+        {
+            "type": "Albums",
+            "name": "Top Contemporary Jazz",
+            "id": 318
+        },
+        {
+            "type": "Albums",
+            "name": "Top Contemporary Jazz Albums",
+            "id": 319
+        },
+        {
+            "type": "Albums",
+            "name": "Top Country Albums",
+            "id": 320
+        },
+        {
+            "type": "Albums",
+            "name": "Top Country Catalog Albums",
+            "id": 321
+        },
+        {
+            "type": "Albums",
+            "name": "Top Electronic Albums",
+            "id": 322
+        },
+        {
+            "type": "Albums",
+            "name": "Top Gospel Albums",
+            "id": 323
+        },
+        {
+            "type": "Albums",
+            "name": "Top Heatseekers",
+            "id": 324
+        },
+        {
+            "type": "Albums",
+            "name": "Top Holiday Albums",
+            "id": 325
+        },
+        {
+            "type": "Albums",
+            "name": "Top Independent Albums",
+            "id": 326
+        },
+        {
+            "type": "Albums",
+            "name": "Top Internet Albums",
+            "id": 327
+        },
+        {
+            "type": "Albums",
+            "name": "Top Jazz Albums",
+            "id": 328
+        },
+        {
+            "type": "Albums",
+            "name": "Top Kid Audio",
+            "id": 329
+        },
+        {
+            "type": "Albums",
+            "name": "Top Latin Albums",
+            "id": 330
+        },
+        {
+            "type": "Albums",
+            "name": "Top New Age Albums",
+            "id": 331
+        },
+        {
+            "type": "Albums",
+            "name": "Top Pop Catalog",
+            "id": 332
+        },
+        {
+            "type": "Albums",
+            "name": "Top R&B\/Hip-Hop Albums",
+            "id": 333
+        },
+        {
+            "type": "Albums",
+            "name": "Top R&B\/Hip-Hop Catalog Albums",
+            "id": 334
+        },
+        {
+            "type": "Albums",
+            "name": "Top Rap Albums",
+            "id": 335
+        },
+        {
+            "type": "Albums",
+            "name": "Top Reggae Albums",
+            "id": 336
+        },
+        {
+            "type": "Albums",
+            "name": "Top Soundtracks",
+            "id": 337
+        },
+        {
+            "type": "Albums",
+            "name": "Latin Tropical Albums",
+            "id": 338
+        },
+        {
+            "type": "Albums",
+            "name": "Top World Albums",
+            "id": 339
+        },
+        {
+            "type": "Albums",
+            "name": "Tropical\/Salsa",
+            "id": 340
+        },
+        {
+            "type": "Albums",
+            "name": "Latin Rhythm Albums",
+            "id": 399
+        }],
+        "totalRecords": 589
+    }
+}