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



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

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



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

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



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

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



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

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

#arxiv(id, &block) ⇒ Object

Fetch altmetrics for Arxiv id



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

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



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

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

#doi(id, &block) ⇒ Object

Fetch altmetrics for a DOI



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

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

#fetch(type, id, params) ⇒ Object 



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

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

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



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

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



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

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



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

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

#pmid(id, &block) ⇒ Object

Fetch altmetrics for a Pubmed identifier



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

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

#validate_response(url, query, response) ⇒ Object 



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

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