shoutcast-api-client 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 047b193a31dcd4eefe97edc0a15b9a46b93d249f
-  data.tar.gz: f86bd2588fb027bc6f521ee849c5fe76d6bd5923
+  metadata.gz: 5976988c6aa0bc0b1d82bc453876140b4a4fa398
+  data.tar.gz: bc73d51e243f914efed4651c89b98992df3c3f64
 SHA512:
-  metadata.gz: da627a4b652f19fc276c5a382303fd38ecec1816746a9187f7c54130f0ba836b29d35d02a023c65b68b9ee746e69ab3b0fcacefc4a62221af3e700b942584829
-  data.tar.gz: e6b65f76c9631c4deafed6f8ce99c606bdda7d1145c8a69fdd042bafad65a9578dce29149f014f6b08d1d6046c384d60e8f93b4a383e7cf55e5777f813770105
+  metadata.gz: 56d7dfa5035e2e1403c5285a792d78825d4607d0d3a9b1bbcabff3134828c6f147987a920bdb934805a25946421235de5e4a55531d252e3e95a48df9b68d549f
+  data.tar.gz: 00436bb636759e7c64b1191ea170c9dae2220122a6c198b586952b932cf2c5103d7dfe03897fd7e2d399aebfaafceb91d99d52e240642009d4bc612b524a9a06

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/.rubocop.yml

@@ -4,5 +4,11 @@ AllCops:
 Style/FrozenStringLiteralComment:
   Enabled: false
 
+Style/BlockDelimiters:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+
 Documentation:
   Enabled: false

data/.travis.yml

@@ -2,4 +2,7 @@ sudo: false
 language: ruby
 rvm:
   - 2.3.0
-before_install: gem install bundler -v 1.12.3
+before_install:
+  - gem install bundler -v 1.12.3
+after_success:
+  - bundle exec codeclimate-test-reporter

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-Unreleased ([Changelog](https://github.com/colszowka/simplecov/compare/v0.0.1...master))
+Unreleased ([Changelog](https://github.com/marcferna/shoutcast-api-client/compare/v0.0.2...master))
 ==========
 ## Features
 
@@ -6,6 +6,13 @@ Unreleased ([Changelog](https://github.com/colszowka/simplecov/compare/v0.0.1...
 
 ## Bugfixes
 
+0.0.2 ([Changelog](https://github.com/marcferna/shoutcast-api-client/compare/v0.0.1...v0.0.2))
+=================
+## Features
+
+* Added Search API interface.
+* Added Searcy by genre API interface.
+
 0.0.1 ([Changelog](https://github.com/marcferna/shoutcast-api-client/compare/25b8f34...v0.0.1))
 =================
 ## Features

data/README.md

@@ -1,5 +1,5 @@
 # SHOUTcast API Client
-[![Build Status](https://travis-ci.org/marcferna/shoutcast-api-client.svg?branch=master)](https://travis-ci.org/marcferna/shoutcast-api-client) [![Code Climate](https://codeclimate.com/github/marcferna/shoutcast-api-client/badges/gpa.svg)](https://codeclimate.com/github/marcferna/shoutcast-api-client) [![Test Coverage](https://codeclimate.com/github/marcferna/shoutcast-api-client/badges/coverage.svg)](https://codeclimate.com/github/marcferna/shoutcast-api-client/coverage) [![Dependency Status](https://gemnasium.com/badges/github.com/marcferna/shoutcast-api-client.svg)](https://gemnasium.com/github.com/marcferna/shoutcast-api-client)
+[![Build Status](https://travis-ci.org/marcferna/shoutcast-api-client.svg?branch=master)](https://travis-ci.org/marcferna/shoutcast-api-client) [![Code Climate](https://codeclimate.com/github/marcferna/shoutcast-api-client/badges/gpa.svg)](https://codeclimate.com/github/marcferna/shoutcast-api-client) [![Test Coverage](https://codeclimate.com/github/marcferna/shoutcast-api-client/badges/coverage.svg)](https://codeclimate.com/github/marcferna/shoutcast-api-client/coverage) [![Dependency Status](https://gemnasium.com/badges/github.com/marcferna/shoutcast-api-client.svg)](https://gemnasium.com/github.com/marcferna/shoutcast-api-client) [![Gem Version](https://badge.fury.io/rb/shoutcast-api-client.svg)](https://badge.fury.io/rb/shoutcast-api-client)
 
 :exclamation:**Important - You will need a SHOUTcast API key for this gem to work. You can request one from their [developer website](https://www.shoutcast.com/Developer)**
 
@@ -16,8 +16,8 @@ progress description you can check the [CHANGELOG.md](CHANGELOG.md)
 ### Stations
 
 - [x] Top 500 (Passing parameters not implemented yet)
-- [ ] Keyword Search
-- [ ] Stations by Genre
+- [x] Keyword Search
+- [x] Stations by Genre
 - [ ] Stations by Now Playing Info
 - [ ] Stations by Bitrate or Codec Type or Genre ID
 - [ ] Random Stations
@@ -39,16 +39,111 @@ gem 'shoutcast-api-client'
 ```
 
 And then execute:
+```ruby
+$ bundle
+```
+Or install it yourself as:
+```
+$ gem install shoutcast-api-client
+```
+## Usage
 
-    $ bundle
+### Initialization
 
-Or install it yourself as:
+First need to initialize the client with your SHOUTcast API key
 
-    $ gem install shoutcast-api-client
+```ruby
+client = Shoutcast::Api::Client.new(key: 'YOUR_API_KEY_GOES_HERE')
+```
 
-## Usage
+### Top 500
+Get top 500 stations on SHOUTcast Radio directory.
+```ruby
+client.top_500
+```
+
+Returns an array of [Stations](lib/shoutcast/api/station.rb):
+```ruby
+[
+  <Shoutcast::Api::Station:0x007fb3c40361d0 @id="9907", @name=".977 The Hitz Channel-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["Pop Rock Top 40"], @ct="The Fray - You Found Me", @lc="4670", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c5840b68 @id="120149", @name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]", @mt="audio/mpeg", @br="24", @genres=["Malaysia Malay"], @ct="LELAKI IDAMAN MELLY_GOESLOW ", @lc="3961", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583bf50 @id="1264", @name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]", @mt="audio/mpeg", @br="96", @genres=["Soft Smooth Jazz"], @ct="Oli Silk - De-stress Signal", @lc="3507", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583b6b8 @id="6687", @name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["Ambient Chill"], @ct="Verbrilli Sound - Descender", @lc="2680", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583ae70 @id="6803", @name=".977 The 80s Channel-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["80s Pop Rock"], @ct="Starship - Nothing`s gonna stop us now (1987)", @lc="2192", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583a588 @id="5516", @name="The Alex Jones Show-[SHOUTcast.com]", @mt="audio/mpeg", @br="32", @genres=["Talk"], @ct="Refeed: Hour 1 (Listen by phone 512-646-5000)", @lc="1987", @logo=nil>
+]
+```
+
+
+### Station Search
+Get stations which match the keyword searched on SHOUTcast Radio Directory.
+```ruby
+client.search(
+    keyword:    'SEARCH_KEYWORD', 
+    limit:      PAGE_COUNT_LIMIT, 
+    offset:     PAGE_OFFSET, 
+    bitrate:    STATION_BITRATE, 
+    media_type: 'STATION_MEDIA_TYPE'
+)
+```
 
-TODO: Write usage instructions here
+#### Parameters
+`keyword`: The keyword to search stations for. Matches on Station Name, Now Playing info and Genre.
+
+`limit`: The number of results to be returned by page.
+
+`offset`: Specifies the number of the first station to return in the results. 
+
+`bitrate`: Station bitrate to search for. Ex: "128", "96".
+
+`media_type`: The media type to search for. Ex: "audio/mpeg" or "audio/aacp"
+
+Returns an array of [Stations](lib/shoutcast/api/station.rb):
+```ruby
+[
+  <Shoutcast::Api::Station:0x007fb3c40361d0 @id="9907", @name=".977 The Hitz Channel-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["Pop Rock Top 40"], @ct="The Fray - You Found Me", @lc="4670", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c5840b68 @id="120149", @name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]", @mt="audio/mpeg", @br="24", @genres=["Malaysia Malay"], @ct="LELAKI IDAMAN MELLY_GOESLOW ", @lc="3961", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583bf50 @id="1264", @name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]", @mt="audio/mpeg", @br="96", @genres=["Soft Smooth Jazz"], @ct="Oli Silk - De-stress Signal", @lc="3507", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583b6b8 @id="6687", @name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["Ambient Chill"], @ct="Verbrilli Sound - Descender", @lc="2680", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583ae70 @id="6803", @name=".977 The 80s Channel-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["80s Pop Rock"], @ct="Starship - Nothing`s gonna stop us now (1987)", @lc="2192", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583a588 @id="5516", @name="The Alex Jones Show-[SHOUTcast.com]", @mt="audio/mpeg", @br="32", @genres=["Talk"], @ct="Refeed: Hour 1 (Listen by phone 512-646-5000)", @lc="1987", @logo=nil>
+]
+```
+
+### Station Search By Genre
+Get stations which match the genre specified as query.
+```ruby
+client.search(
+    genre:     'GENRE_TO_SEARCH', 
+    limit:      PAGE_COUNT_LIMIT, 
+    offset:     PAGE_OFFSET, 
+    bitrate:    STATION_BITRATE, 
+    media_type: 'STATION_MEDIA_TYPE'
+)
+```
+
+#### Parameters
+`genre`: The genre to search stations for.
+
+`limit`: The number of results to be returned by page.
+
+`offset`: Specifies the number of the first station to return in the results. 
+
+`bitrate`: Station bitrate to search for. Ex: "128", "96".
+
+`media_type`: The media type to search for. Ex: "audio/mpeg" or "audio/aacp"
+
+Returns an array of [Stations](lib/shoutcast/api/station.rb):
+```ruby
+[
+  <Shoutcast::Api::Station:0x007fb3c40361d0 @id="9907", @name=".977 The Hitz Channel-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["Pop Rock Top 40"], @ct="The Fray - You Found Me", @lc="4670", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c5840b68 @id="120149", @name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]", @mt="audio/mpeg", @br="24", @genres=["Malaysia Malay"], @ct="LELAKI IDAMAN MELLY_GOESLOW ", @lc="3961", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583bf50 @id="1264", @name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]", @mt="audio/mpeg", @br="96", @genres=["Soft Smooth Jazz"], @ct="Oli Silk - De-stress Signal", @lc="3507", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583b6b8 @id="6687", @name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["Ambient Chill"], @ct="Verbrilli Sound - Descender", @lc="2680", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583ae70 @id="6803", @name=".977 The 80s Channel-[SHOUTcast.com]", @mt="audio/mpeg", @br="128", @genres=["80s Pop Rock"], @ct="Starship - Nothing`s gonna stop us now (1987)", @lc="2192", @logo=nil>,
+  <Shoutcast::Api::Station:0x007fb3c583a588 @id="5516", @name="The Alex Jones Show-[SHOUTcast.com]", @mt="audio/mpeg", @br="32", @genres=["Talk"], @ct="Refeed: Hour 1 (Listen by phone 512-646-5000)", @lc="1987", @logo=nil>
+]
+```
 
 ## Contributing
 

data/lib/shoutcast/api.rb

@@ -1,6 +1,7 @@
 require 'shoutcast/api/version'
 require 'shoutcast/api/client'
 require 'shoutcast/api/station'
+require 'shoutcast/api/url'
 
 module Shoutcast
   module Api

data/lib/shoutcast/api/client.rb

@@ -9,22 +9,81 @@ module Shoutcast
       end
 
       def top_500
-        response = RestClient.get url('/legacy/Top500')
-        Nori.new.parse(response)['stationlist']['station'].map do |attributes|
-          Shoutcast::Api::Station.parse(attributes)
-        end
+        response = RestClient.get(
+          url(path: '/legacy/Top500')
+        )
+        parse_stations(response)
+      end
+
+      def search(
+        keyword:,
+        limit:      nil,
+        offset:     nil,
+        bitrate:    nil,
+        media_type: nil
+      )
+        response = RestClient.get(
+          url(
+            path: '/legacy/stationsearch',
+            parameters: {
+              search: keyword,
+              limit:  build_limit_parameter(limit: limit, offset: offset),
+              br:     bitrate,
+              mt:     media_type
+            }
+          )
+        )
+        parse_stations(response)
+      end
+
+      def genre_search(
+        genre:,
+        limit:      nil,
+        offset:     nil,
+        bitrate:    nil,
+        media_type: nil
+      )
+        response = RestClient.get(
+          url(
+            path: '/legacy/genresearch',
+            parameters: {
+              genre: genre,
+              limit: build_limit_parameter(limit: limit, offset: offset),
+              br:    bitrate,
+              mt:    media_type
+            }
+          )
+        )
+        parse_stations(response)
       end
 
       private
 
       attr_accessor :key
 
-      def base_url
-        'http://api.shoutcast.com'
+      def url(path:, parameters: {})
+        Shoutcast::Api::Url.new(
+          path:       path,
+          key:        key,
+          parameters: parameters
+        ).to_s
+      end
+
+      def parse_stations(response)
+        return [] if response.nil?
+        parsed_response = Nori.new.parse(response)
+        return [] if parsed_response['stationlist'].nil?
+        return [] if parsed_response['stationlist']['station'].nil?
+        Nori.new.parse(response)['stationlist']['station'].map do |attributes|
+          Shoutcast::Api::Station.parse(attributes)
+        end
       end
 
-      def url(path)
-        "#{base_url}#{path}?k=#{key}"
+      def build_limit_parameter(limit: nil, offset: nil)
+        return nil if limit.nil?
+        parameter = limit.to_s
+        parameter += ",#{offset}" unless offset.nil?
+        parameter
       end
     end
   end

data/lib/shoutcast/api/url.rb

@@ -0,0 +1,41 @@
+module Shoutcast
+  module Api
+    class Url
+      def initialize(path:, key:, parameters: {})
+        @path = path
+        @parameters = { k: key }
+        @parameters.merge!(parameters) unless parameters.nil?
+        @parameters.delete_if { |_, value| value.nil? }
+      end
+
+      def to_s
+        URI::HTTP.build(
+          host:  base_uri.host,
+          path:  base_uri.path,
+          query: parameters_query
+        ).to_s
+      end
+
+      private
+
+      attr_accessor :path, :parameters
+
+      def scheme
+        'http'
+      end
+
+      def host
+        'api.shoutcast.com'
+      end
+
+      def base_uri
+        @base_uri ||= URI.join("#{scheme}://#{host}", path)
+      end
+
+      def parameters_query
+        return '' if parameters.empty?
+        URI.encode_www_form(parameters)
+      end
+    end
+  end
+end

data/lib/shoutcast/api/version.rb

@@ -1,5 +1,5 @@
 module Shoutcast
   module Api
-    VERSION = '0.0.1'.freeze
+    VERSION = '0.0.2'.freeze
   end
 end

data/shoutcast-api-client.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   # 'allowed_push_host' to allow pushing to a single host or delete this section
   # to allow pushing to any host.
   if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   else
     raise 'RubyGems 2.0 or newer is required to protect against public gem '\
       'pushes.'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shoutcast-api-client
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Marc Fernandez
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-14 00:00:00.000000000 Z
+date: 2017-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -172,6 +172,7 @@ files:
 - lib/shoutcast/api.rb
 - lib/shoutcast/api/client.rb
 - lib/shoutcast/api/station.rb
+- lib/shoutcast/api/url.rb
 - lib/shoutcast/api/version.rb
 - shoutcast-api-client.gemspec
 homepage: https://github.com/marcferna/shoutcast-api-client