altmetric.rb 0.0.1

data/README.md

@@ -0,0 +1,61 @@
+Ruby Altmetric API Client
+-------------------------
+
+A simple Ruby client for the [Altmetric API][0].
+
+Provides a basic client object for interacting with the API. Provides quick access to the JSON
+results or direct access to API responses.
+
+Installation
+------------
+
+	[sudo] gem install altmetric.rb
+	
+Relies on the `json`, `uri_template` and `httpclient` gems.
+	
+Basic Usage
+-----------
+
+	require 'altmetric'
+
+	client = Altmetric::Client.new()
+	stats = client.doi("10.1038/news.2011.490")
+	#do something with the stats
+	
+Creating A Client
+-----------------
+
+The client can be created with an API key which is required to raise usage limits and also to access 
+the commercial parts of the API (the `fetch`) calls
+
+	opts = {
+	  :apikey => "12345",
+	  :user_agent => "MyCoolApp/1.0"
+	}
+
+	client = Altmetric::Client.new(opts)
+		
+Default `User-Agent` is currently `altmetric-ruby-client/0.0.1`
+
+Read the Altmetric API documentation for notes on the structure of the responses and additional API parameters.
+
+Rate Limiting
+-------------
+
+The client object will automatically inspect all responses and extract the HTTP headers that Altmetric 
+uses for [rate limiting][1]. 
+
+The latest header values are automatically added as integers to the `Altmetric::Client::LIMITS` hash, 
+keyed on the header name. This simplifies monitoring limits over several requests, which may use different 
+clients.
+	
+License
+-------
+
+This work is hereby released into the Public Domain.
+
+To view a copy of the public domain dedication, visit http://creativecommons.org/licenses/publicdomain or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
+
+
+[0]. http://api.altmetric.com/
+[1]. http://api.altmetric.com/index.html#rate_limiting

data/Rakefile

@@ -0,0 +1,32 @@
+require 'rake'
+require 'rdoc/task'
+require 'rake/testtask'
+require 'rake/clean'
+
+CLEAN.include ['*.gem', 'pkg']  
+
+$spec = eval(File.read('altmetric.spec'))
+
+Rake::RDocTask.new do |rdoc|
+    rdoc.rdoc_dir = 'doc/rdoc'
+    rdoc.options += RDOC_OPTS
+    rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+    rdoc.main = "README.md"    
+end
+
+Rake::TestTask.new do |test|
+  test.test_files = FileList['tests/tc_*.rb']
+end
+  
+task :package do
+  sh %{gem build altmetric.spec}  
+end
+
+task :install do
+  sh %{sudo gem install --no-ri --no-rdoc #{$spec.name}-#{$spec.version}.gem}
+end
+
+desc "Uninstall the gem"
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{$spec.name}}
+end

data/bin/doi

@@ -0,0 +1,9 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require 'altmetric'
+
+client = Altmetric::Client.new()
+puts client.doi("10.1038/news.2011.490")
+
+client.doi("10.1038/news.2011.490") do |resp|
+  puts resp.status
+end

data/lib/altmetric.rb

@@ -0,0 +1,133 @@
+require 'json'
+require 'rest-client'
+require 'httpclient'
+require 'uri_template'
+
+module Altmetric
+  
+  class Client
+    
+    DEFAULT_USER_AGENT = "altmetric-ruby-client/0.0.1"
+    URI_TEMPLATE = URITemplate.new("http://{host}/{version}{/path*}")
+    
+    HOST = "api.altmetric.com"
+    VERSION = "v1"
+    KEY_PARAM="key"
+    
+    HOURLY_RATE_LIMIT="X-HourlyRateLimit-Limit"
+    DAILY_RATE_LIMIT="X-DailyRateLimit-Limit"    
+    HOURLY_RATE_LIMIT_REMAINING="X-HourlyRateLimit-Remaining"
+    DAILY_RATE_LIMIT_REMAINING="X-DailyRateLimit-Remaining"
+    
+    RATE_HEADERS = [HOURLY_RATE_LIMIT, DAILY_RATE_LIMIT, HOURLY_RATE_LIMIT_REMAINING, DAILY_RATE_LIMIT_REMAINING]
+    
+    LIMITS = {}
+    
+    #Format a URL according to provided template
+    #
+    #Automatically injects the correct :host and :version params for
+    #the API
+    #
+    #template:: a valid URI template
+    #opts:: additional template params, should include :path 
+    def self.make_url(template, opts)
+      return template.expand( 
+          { :host => HOST, 
+            :version => VERSION
+          }.merge(opts) 
+          )
+    end
+    
+    #Update class variable with latest rate limit data
+    #
+    #headers:: hash of response headers
+    def self.update_limits(headers)
+      RATE_HEADERS.each do |header|
+        LIMITS[header] = headers[header].to_i if headers[header]
+      end
+    end
+    
+    #Create a new client object
+    #
+    #Supports several options in the provided hash, including:
+    #
+    #[apikey]:: specify altmetric API key, only required for +fetch+ method and increased rate limits
+    #[client]:: specify a pre-created HTTPClient object (e.g. for mocking during testing)
+    #[user_agent]]:: specify a user agent. Default is +DEFAULT_USER_AGENT+ 
+    # 
+    #Method params:
+    #
+    #opts:: options for configuring client
+    def initialize(opts={})
+      name = opts[:user_agent] || DEFAULT_USER_AGENT
+      @client = opts[:client] || HTTPClient.new( :agent_name => name )
+      @apikey = opts[:apikey] || nil                    
+      @opts = opts
+    end
+        
+    #Fetch altmetrics for a DOI
+    def doi(id, &block)
+      return get_metrics(["doi", id], &block)
+    end
+
+    #Fetch citations for a DOI    
+    #    
+    #Read the {API documentation}[http://api.altmetric.com/docs/call_citations.html] for explanation of parameters
+    def citations(timeframe, params, &block)
+      return get_metrics(["citations", timeframe], params, &block)
+    end
+    
+    #Fetch altmetrics using (unstable) altmetrics ids    
+    def id(id, &block)
+      return get_metrics(["id", id], &block)
+    end
+    
+    #Fetch altmetrics for a Pubmed identifier    
+    def pmid(id, &block)
+      return get_metrics(["pmid", id], &block)
+    end
+    
+    #Fetch altmetrics for Arxiv id    
+    def arxiv(id, &block)
+      return get_metrics(["arxiv", id], &block)
+    end
+    
+    #Fetch altmetrics for ADS bibcode    
+    def ads(id, &block)
+      return get_metrics(["ads", id], &block)
+    end
+    
+    def fetch(type, id, params)
+      return get_metrics(["fetch", type, id], params, &block)
+    end
+
+    #Get metrics, specifying path, query parameters, and headers
+    #
+    #Accepts a block for direct processing of the result, otherwise
+    #response is validated to ensure its a success then parsed as JSON    
+    def get_metrics(path, query={}, headers={})
+      url = Client::make_url(URI_TEMPLATE, {:path=>path} )
+      response = get( url, query, headers )
+      if block_given?
+        yield response
+      end
+      validate_response(response)      
+      return JSON.parse( response.content )      
+    end
+    
+    def get(uri, query={}, headers={})
+      query[KEY_PARAM] = @apikey if @apikey
+      headers["Accept"] = "application/json"
+      response = @client.get(uri, query, headers)
+      Client.update_limits(response.headers) 
+      return response
+    end
+        
+    def validate_response(response)
+      if response.status != 200
+        raise "Unable to perform request. Status: #{response.status}. Message: #{response.content}"
+      end      
+    end
+    
+  end
+end

data/tests/ts_altmetric.rb

@@ -0,0 +1,4 @@
+$:.unshift File.dirname(__FILE__)
+require 'test/unit'
+
+require 'tc_altmetric.rb'

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: altmetric.rb
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Leigh Dodds
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: httpclient
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: uri_template
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Altmetric API Client
+email: leigh@ldodds.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- Rakefile
+- bin/doi
+- lib/altmetric.rb
+- tests/ts_altmetric.rb
+homepage: http://github.com/ldodds/altmetric
+licenses: []
+post_install_message: 
+rdoc_options:
+- --quiet
+- --title
+- Altmetric Client
+- --main
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Altmetric API Client
+test_files:
+- tests/ts_altmetric.rb