Class: Altmetric::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/altmetric.rb

Constant Summary collapse

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 = 
{}

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Client

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



89
90
91
92
93
94
 
# File 'lib/altmetric.rb', line 89

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

Class Method Details

.make_url(template, opts) ⇒ Object

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



61
62
63
64
65
66
67
 
# File 'lib/altmetric.rb', line 61

def self.make_url(template, opts)
  return template.expand( 
      { :host => HOST, 
        :version => VERSION
      }.merge(opts) 
      )
end

.update_limits(headers) ⇒ Object

Update class variable with latest rate limit data

headers

hash of response headers



72
73
74
75
76
 
# File 'lib/altmetric.rb', line 72

def self.update_limits(headers)
  RATE_HEADERS.each do |header|
    LIMITS[header] = headers[header].to_i if headers[header]
  end
end

Instance Method Details

#ads(id, &block) ⇒ Object

Fetch altmetrics for ADS bibcode



124
125
126
 
# File 'lib/altmetric.rb', line 124

def ads(id, &block)
  return get_metrics(["ads", id], &block)
end

#arxiv(id, &block) ⇒ Object

Fetch altmetrics for Arxiv id



119
120
121
 
# File 'lib/altmetric.rb', line 119

def arxiv(id, &block)
  return get_metrics(["arxiv", id], &block)
end

#citations(timeframe, params, &block) ⇒ Object

Fetch citations for a DOI

Read the API documentation for explanation of parameters



104
105
106
 
# File 'lib/altmetric.rb', line 104

def citations(timeframe, params, &block)
  return get_metrics(["citations", timeframe], params, &block)
end

#doi(id, &block) ⇒ Object

Fetch altmetrics for a DOI



97
98
99
 
# File 'lib/altmetric.rb', line 97

def doi(id, &block)
  return get_metrics(["doi", id], &block)
end

#fetch(type, id, params) ⇒ Object 



128
129
130
 
# File 'lib/altmetric.rb', line 128

def fetch(type, id, params)
  return get_metrics(["fetch", type, id], params, &block)
end

#get(uri, query = {}, headers = {}) ⇒ Object 



146
147
148
149
150
151
152
 
# File 'lib/altmetric.rb', line 146

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

#get_metrics(path, query = {}, headers = {}) ⇒ Object

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



136
137
138
139
140
141
142
143
144
 
# File 'lib/altmetric.rb', line 136

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(url, query, response)      
  return JSON.parse( response.content )      
end

#id(id, &block) ⇒ Object

Fetch altmetrics using (unstable) altmetrics ids



109
110
111
 
# File 'lib/altmetric.rb', line 109

def id(id, &block)
  return get_metrics(["id", id], &block)
end

#pmid(id, &block) ⇒ Object

Fetch altmetrics for a Pubmed identifier



114
115
116
 
# File 'lib/altmetric.rb', line 114

def pmid(id, &block)
  return get_metrics(["pmid", id], &block)
end

#validate_response(url, query, response) ⇒ Object 



154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/altmetric.rb', line 154

def validate_response(url, query, response)
  case response.status
  when 200
    #OK
  when 403
    raise UnauthorizedException.new(url, query, response)
  when 404
    raise UnknownArticleException.new(url, query, response)
  when 420
    raise RateLimitedException.new(url, query, response)
  else
    raise APIException.new(url, query, response)     
  end
end