twm-ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 82eedfd49645226dc1b0660ccab0d298216e8b8b
+  data.tar.gz: 5feb1f95a11d91a0fe4369983e73a7fc34d4df10
+SHA512:
+  metadata.gz: 3ba82700f5b3d05c9c2a6cf698147ddb2a769b72a9be001c491a5da34dc979df3d831b69bad78b402f869263cddd37af76c7491566c4ea1c101d0ea5ba0b17ed
+  data.tar.gz: e3b3f15925f17c2a057820c140aab8f2a0ec46638d4c6eb35793032aece065d97c467c86c11778175e0b768a7c6fb2d14aef8c25f5644e7b766707d72b5004f5

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.ruby-version
+.rbenv-gemsets
+.rbenv-vars

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in twm-ruby.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Brian Getting
+
+MIT License
+
+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.md

@@ -0,0 +1,44 @@
+# The Whale Museum API's
+
+A Ruby gem for interacting with [The Whale Museum](http://whalemuseum.org) API's.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'twm-ruby'
+```
+
+## Usage
+
+Currently only the [Whale Hotline API](http://hotline.whalemuseum.org/api) is supported. There is no authentication required, however usage of the API requires that The Whale Museum receive full acknowledgment as the data source through citation where the data is used.
+
+```ruby
+require 'twm-ruby'
+
+twm = TWM::API.new
+
+total_count = twm.sightings.count
+=> 17829
+
+sightings = twm.sightings.search(limit: 1000)
+=> [...]
+
+orca_count = twm.sightings.count(species: 'orca')
+=> 17179
+
+pages = (orca_count.to_f/1000.to_f).ceil
+orca_sightings = []
+1.upto(pages) do |page|
+  orca_sightings.concat twm.sightings.search(limit: 1000, page: page)
+end
+
+orca_sightings.first['id']
+=> "52c4a6da686f741c25000000"
+
+sighting = twm.sightings.find("52c4a6da686f741c25000000")
+sighting['species']
+=> 'orca'
+
+```

data/Rakefile

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

data/lib/twm-ruby.rb

@@ -0,0 +1,83 @@
+require 'faraday'
+require 'multi_json'
+
+require 'twm-ruby/version'
+require 'twm-ruby/errors'
+require 'twm-ruby/api'
+
+module TWM
+  class API
+    attr_accessor :debug, :session
+
+    def initialize(debug=false)
+      @debug = debug
+    end
+
+    def create_session(url) # :nodoc:
+      @session = Faraday.new(url: url, headers: set_headers)
+    end
+
+    # Make a GET request with the session
+    #
+    def get(path, params={}) # :nodoc:
+      handle_response(@session.get(path, params))
+    end
+
+    # Make a POST request with the session
+    #
+    def post(path, params={}) # :nodoc:
+      handle_response(@session.post(path, MultiJson.dump(params)))
+    end
+
+    # Make a PUT request with the session
+    #
+    def put(path, params={}) # :nodoc:
+      handle_response(@session.put(path, MultiJson.dump(params)))
+    end
+
+    # Make a DELETE request with the session
+    #
+    def delete(path, params={}) # :nodoc:
+      handle_response(@session.delete(path, MultiJson.dump(params)))
+    end
+
+    def handle_response(response)
+      case response.status # :nodoc:
+      when 400
+        raise BadRequest.new response.body
+      when 401
+        raise Unauthorized.new
+      when 404
+        raise NotFound.new
+      when 400...500
+        raise ClientError.new response.body
+      when 500...600
+        raise ServerError.new
+      else
+        case response.body
+        when ''
+          true
+        when is_a?(Integer)
+          response.body
+        else
+          MultiJson.load(response.body)
+        end
+      end
+    end
+
+    # Set the request headers
+    def set_headers # :nodoc:
+      {
+        'User-Agent' => "twm-ruby-#{VERSION}",
+        'Content-Type' => 'application/json; charset=utf-8',
+        'Accept' => 'application/json'
+      }
+    end
+
+    # API nodes
+    def sightings # :nodoc:
+      Sightings.new self
+    end
+
+  end
+end

data/lib/twm-ruby/api.rb

@@ -0,0 +1,87 @@
+module TWM
+  #
+  # The Whale Hotline API
+  # http://hotline.whalemuseum.org/api
+  #
+  class Sightings
+    attr_accessor :api
+
+    def initialize(api)
+      @api = api
+      @api.create_session('http://hotline.whalemuseum.org')
+    end
+
+    # Retrieve Hotline sighting reports
+    # 
+    # @param [Hash] params Optional params or filters:
+    # @option params [String] species Get sighting reports for a species.
+    # @option params [String] orca_type Get sighting reports for a type of orca.
+    # @option params [String] orca_pod Get sighting reports for a pod of orca.
+    # @option params [String] since Get sighting reports after this date.
+    # @option params [String] until Get sighting reports before this date.
+    # @option params [String] near Get sighting reports near a Lat/Lng point.
+    # @option params [String] radius Get sighting reports within this distance of center point.
+    #
+    # @return [Integer] The count of sighting reports.
+    #
+    # @see http://hotline.whalemuseum.org/api
+    # 
+    # @example
+    #
+    #   count = twm.sightings.count
+    #   => 17000
+    #
+    #   count = twm.sightings.count(species: 'orca')
+    #
+    def count(params = {})
+      @api.get("api/count.json", params)
+    end
+
+    # Retrieve a specific sighting report
+    # 
+    # @param [String] id The ID of the sighting report to retrieve.
+    #
+    # @return [JSON] A sighting report object.
+    #
+    # @see http://hotline.whalemuseum.org/api
+    # 
+    # @example
+    #
+    #   sighting = twm.sightings.find('52b158c0686f7438d8ac0600')
+    #   sighting['species']
+    #   => "orca"
+    #
+    def find(id)
+      @api.get("api/#{id.to_s}.json")
+    end
+
+    # Retrieve Hotline sighting reports
+    # 
+    # @param [Hash] params Optional params or filters:
+    # @option params [String] species Get sighting reports for a species.
+    # @option params [String] orca_type Get sighting reports for a type of orca.
+    # @option params [String] orca_pod Get sighting reports for a pod of orca.
+    # @option params [Integer] limit The number of sighting reports to return.
+    # @option params [Integer] page The page number to return.
+    # @option params [String] since Get sighting reports after this date.
+    # @option params [String] until Get sighting reports before this date.
+    # @option params [String] near Get sighting reports near a Lat/Lng point.
+    # @option params [String] radius Get sighting reports within this distance of center point.
+    #
+    # @return [JSON] An array of matching sighting reports.
+    #
+    # @see http://hotline.whalemuseum.org/api
+    # 
+    # @example
+    #
+    #   sightings = twm.sightings.search
+    #   sightings.size
+    #   => 17000
+    #
+    #   sightings = twm.sightings.search(species: 'orca', limit: 250)
+    #
+    def search(params = {})
+      @api.get("api.json", params)
+    end
+  end
+end

data/lib/twm-ruby/errors.rb

@@ -0,0 +1,18 @@
+module TWM
+  class Error < StandardError
+  end
+  class BadRequest < Error
+  end
+  class ClientError < Error
+  end
+  class NotFound < Error
+  end
+  class ServerError < Error
+  end
+  class TooManyRequests < Error
+  end
+  class Unauthorized < Error
+  end
+  class Unavailable < Error
+  end
+end

data/lib/twm-ruby/version.rb

@@ -0,0 +1,3 @@
+module TWM
+  VERSION = "0.0.1"
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'twm-ruby'

data/twm-ruby.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'twm-ruby/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "twm-ruby"
+  gem.version       = TWM::VERSION
+  gem.platform      = Gem::Platform::RUBY
+  gem.authors       = ["Brian Getting"]
+  gem.email         = ["brian@tatem.ae"]
+  gem.homepage      = "https://github.com/tatemae-consultancy/twm-ruby"
+  gem.summary       = "Ruby wrapper for The Whale Museum API's"
+  gem.description   = "A Ruby gem for interacting with The Whale Museum API's."
+  
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  
+  gem.add_dependency 'faraday', '>= 0.8.7'
+  gem.add_dependency 'multi_json', '~> 1.7.3'
+   
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: twm-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Brian Getting
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.3
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby gem for interacting with The Whale Museum API's.
+email:
+- brian@tatem.ae
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/twm-ruby.rb
+- lib/twm-ruby/.DS_Store
+- lib/twm-ruby/api.rb
+- lib/twm-ruby/errors.rb
+- lib/twm-ruby/version.rb
+- rails/init.rb
+- twm-ruby.gemspec
+homepage: https://github.com/tatemae-consultancy/twm-ruby
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: Ruby wrapper for The Whale Museum API's
+test_files: []