Class: AlchemyAPI

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

Constant Summary collapse

@@ENDPOINTS =

Setup the endpoints

{}
@@BASE_URL = 
'http://access.alchemyapi.com/calls'

Instance Method Summary collapse

Constructor Details

#initialize(key) ⇒ AlchemyAPI

Returns a new instance of AlchemyAPI.



90
91
92
93
94
95
96
97
 
# File 'lib/alchemyapi.rb', line 90

def initialize(key)

  if key.is_a?(String) && key.size == 40
    @apiKey = key
  else
    raise 'Invalid key for AlchemyAPI.'
  end
end

Instance Method Details

#author(flavor, data, options = {}) ⇒ Object

Extracts the author from a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/author-extraction/ For the docs, please refer to: www.alchemyapi.com/api/author-extraction/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: none

OUTPUT: The response, already converted from JSON to a Ruby object.



201
202
203
204
205
206
207
208
209
 
# File 'lib/alchemyapi.rb', line 201

def author(flavor, data, options = {})
  unless @@ENDPOINTS['author'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'author extraction for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['author'][flavor], options)
end

#category(flavor, data, options = {}) ⇒ Object

Categorizes the text for text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/text-categorization/ For the docs, please refer to: www.alchemyapi.com/api/text-categorization/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: showSourceText -> 0: disabled (default), 1: enabled

OUTPUT: The response, already converted from JSON to a Ruby object.



276
277
278
279
280
281
282
283
284
 
# File 'lib/alchemyapi.rb', line 276

def category(flavor, data, options = {})
  unless @@ENDPOINTS['category'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'text categorization for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['category'][flavor], options)
end

#combined(flavor, data, options = {}) ⇒ Object

Combined call (see options below for available extractions) for a URL or text.

INPUT: flavor -> which version of the call, i.e. url or text. data -> the data to analyze, either the the url or text. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: extract -> VALUE,VALUE,VALUE,… (possible VALUEs: page-image,entity,keyword,title,author,taxonomy,concept,relation,doc-sentiment) extractMode -> (only applies when ‘page-image’ VALUE passed to ‘extract’ option)

trust-metadata: less CPU-intensive, less accurate
always-infer: more CPU-intensive, more accurate

disambiguate -> whether to disambiguate detected entities, 0: disabled, 1: enabled (default) linkedData -> whether to include Linked Data content links with disambiguated entities, 0: disabled, 1: enabled (default). disambiguate must be enabled to use this. coreference -> whether to he/she/etc coreferences into detected entities, 0: disabled, 1: enabled (default) quotations -> whether to enable quotations extraction, 0: disabled (default), 1: enabled sentiment -> whether to enable entity-level sentiment analysis, 0: disabled (default), 1: enabled. Requires one additional API transaction if enabled. showSourceText -> 0: disabled (default), 1: enabled. maxRetrieve -> maximum number of named entities to extract (default: 50)

OUTPUT: The response, already converted from JSON to a Ruby object.



519
520
521
522
523
524
525
526
527
 
# File 'lib/alchemyapi.rb', line 519

def combined(flavor, data, options = {})
  unless @@ENDPOINTS['combined'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'Combined data for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['combined'][flavor], options)
end

#concepts(flavor, data, options = {}) ⇒ Object

Tags the concepts for text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/concept-tagging/ For the docs, please refer to: www.alchemyapi.com/api/concept-tagging/

Available Options: maxRetrieve -> the maximum number of concepts to retrieve (default: 8) linkedData -> include linked data, 0: disabled, 1: enabled (default) showSourceText -> 0:disabled (default), 1: enabled

OUTPUT: The response, already converted from JSON to a Ruby object.



251
252
253
254
255
256
257
258
259
 
# File 'lib/alchemyapi.rb', line 251

def concepts(flavor, data, options = {})
  unless @@ENDPOINTS['concepts'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'concept tagging for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['concepts'][flavor], options)
end

#entities(flavor, data, options = {}) ⇒ Object

Extracts the entities for text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/entity-extraction/ For the docs, please refer to: www.alchemyapi.com/api/entity-extraction/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: disambiguate -> disambiguate entities (i.e. Apple the company vs. apple the fruit). 0: disabled, 1: enabled (default) linkedData -> include linked data on disambiguated entities. 0: disabled, 1: enabled (default) coreference -> resolve coreferences (i.e. the pronouns that correspond to named entities). 0: disabled, 1: enabled (default) quotations -> extract quotations by entities. 0: disabled (default), 1: enabled. sentiment -> analyze sentiment for each entity. 0: disabled (default), 1: enabled. Requires 1 additional API transction if enabled. showSourceText -> 0: disabled (default), 1: enabled maxRetrieve -> the maximum number of entities to retrieve (default: 50)

OUTPUT: The response, already converted from JSON to a Ruby object.



176
177
178
179
180
181
182
183
184
 
# File 'lib/alchemyapi.rb', line 176

def entities(flavor, data, options = {})
  unless @@ENDPOINTS['entities'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'entity extraction for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['entities'][flavor], options)
end

#feeds(flavor, data, options = {}) ⇒ Object

Detects the RSS/ATOM feeds for a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/feed-detection/ For the docs, please refer to: www.alchemyapi.com/api/feed-detection/

INPUT: flavor -> which version of the call, i.e. url or html. data -> the data to analyze, either the the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: none

OUTPUT: The response, already converted from JSON to a Ruby object.



461
462
463
464
465
466
467
468
469
 
# File 'lib/alchemyapi.rb', line 461

def feeds(flavor, data, options = {})
  unless @@ENDPOINTS['feeds'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'feed detection for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['feeds'][flavor], options)
end

#image_extract(flavor, data, options = {}) ⇒ Object

Extract image from a URL.

INPUT: flavor -> which version of the call, i.e. url. data -> the data to analyze, i.e. the url. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: extractMode -> trust-metadata: less CPU-intensive and less accurate, always-infer: more CPU-intensive and more accurate

OUTPUT: The response, already converted from JSON to a Ruby object.



542
543
544
545
546
547
548
549
550
 
# File 'lib/alchemyapi.rb', line 542

def image_extract(flavor, data, options = {})
  unless @@ENDPOINTS['image_extract'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'Image for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['image_extract'][flavor], options)
end

#image_tag(flavor, data, options = {}, image = '') ⇒ Object

Tag image from a URL or raw image data. For an overview, please refer to: www.alchemyapi.com/products/features/image-tagging/ For the docs, please refer to: www.alchemyapi.com/api/image-tagging/

INPUT: flavor -> which version of the call, i.e. url or image. data -> the data to analyze, the url options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: extractMode -> trust-metadata: less CPU-intensive and less accurate, always-infer: more CPU-intensive and more accurate (image flavor only) imagePostMode -> how you will post the image

raw: pass an unencoded image file using POST

OUTPUT: The response, already converted from JSON to a Ruby object.



570
571
572
573
574
575
576
577
578
579
580
 
# File 'lib/alchemyapi.rb', line 570

def image_tag(flavor, data, options = {}, image = '')
  unless @@ENDPOINTS['image_tag'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'Image tagging for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  unless data.empty?
    options[flavor] = data
  end
  return analyze_image(@@ENDPOINTS['image_tag'][flavor], options, image)
end

#keywords(flavor, data, options = {}) ⇒ Object

Extracts the keywords from text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/keyword-extraction/ For the docs, please refer to: www.alchemyapi.com/api/keyword-extraction/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: keywordExtractMode -> normal (default), strict sentiment -> analyze sentiment for each keyword. 0: disabled (default), 1: enabled. Requires 1 additional API transaction if enabled. showSourceText -> 0: disabled (default), 1: enabled. maxRetrieve -> the max number of keywords returned (default: 50)

OUTPUT: The response, already converted from JSON to a Ruby object.



229
230
231
232
233
234
235
236
237
 
# File 'lib/alchemyapi.rb', line 229

def keywords(flavor, data, options = {})
  unless @@ENDPOINTS['keywords'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'keyword extraction for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['keywords'][flavor], options)
end

#language(flavor, data, options = {}) ⇒ Object

Detects the language for text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/api/language-detection/ For the docs, please refer to: www.alchemyapi.com/products/features/language-detection/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: none

OUTPUT: The response, already converted from JSON to a Ruby object.



335
336
337
338
339
340
341
342
343
 
# File 'lib/alchemyapi.rb', line 335

def language(flavor, data, options = {})
  unless @@ENDPOINTS['language'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'language detection for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['language'][flavor], options)
end

#microformats(flavor, data, options = {}) ⇒ Object

Parses the microformats for a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/microformats-parsing/ For the docs, please refer to: www.alchemyapi.com/api/microformats-parsing/

INPUT: flavor -> which version of the call, i.e. url or html. data -> the data to analyze, either the the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: none

OUTPUT: The response, already converted from JSON to a Ruby object.



436
437
438
439
440
441
442
443
444
 
# File 'lib/alchemyapi.rb', line 436

def microformats(flavor, data, options = {})
  unless @@ENDPOINTS['microformats'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'microformats parsing for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['microformats'][flavor], options)
end

#relations(flavor, data, options = {}) ⇒ Object

Extracts the relations for text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/relation-extraction/ For the docs, please refer to: www.alchemyapi.com/api/relation-extraction/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: sentiment -> 0: disabled (default), 1: enabled. Requires one additional API transaction if enabled. keywords -> extract keywords from the subject and object. 0: disabled (default), 1: enabled. Requires one additional API transaction if enabled. entities -> extract entities from the subject and object. 0: disabled (default), 1: enabled. Requires one additional API transaction if enabled. requireEntities -> only extract relations that have entities. 0: disabled (default), 1: enabled. sentimentExcludeEntities -> exclude full entity name in sentiment analysis. 0: disabled, 1: enabled (default) disambiguate -> disambiguate entities (i.e. Apple the company vs. apple the fruit). 0: disabled, 1: enabled (default) linkedData -> include linked data with disambiguated entities. 0: disabled, 1: enabled (default). coreference -> resolve entity coreferences. 0: disabled, 1: enabled (default) showSourceText -> 0: disabled (default), 1: enabled. maxRetrieve -> the maximum number of relations to extract (default: 50, max: 100)

OUTPUT: The response, already converted from JSON to a Ruby object.



310
311
312
313
314
315
316
317
318
 
# File 'lib/alchemyapi.rb', line 310

def relations(flavor, data, options = {})
  unless @@ENDPOINTS['relations'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'relation extraction for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['relations'][flavor], options)
end

#sentiment(flavor, data, options = {}) ⇒ Object

Calculates the sentiment for text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/sentiment-analysis/ For the docs, please refer to: www.alchemyapi.com/api/sentiment-analysis/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: showSourceText -> 0: disabled (default), 1: enabled

OUTPUT: The response, already converted from JSON to a Ruby object.



114
115
116
117
118
119
120
121
122
 
# File 'lib/alchemyapi.rb', line 114

def sentiment(flavor, data, options = {})
  unless @@ENDPOINTS['sentiment'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'sentiment analysis for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['sentiment'][flavor], options)
end

#sentiment_targeted(flavor, data, target, options = {}) ⇒ Object

Calculates the targeted sentiment for text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/sentiment-analysis/ For the docs, please refer to: www.alchemyapi.com/api/sentiment-analysis/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. target -> the word or phrase to run sentiment analysis on. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: showSourceText -> 0: disabled, 1: enabled

OUTPUT: The response, already converted from JSON to a Ruby object.



140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/alchemyapi.rb', line 140

def sentiment_targeted(flavor, data, target, options = {})
  if target == '' || target.nil?
    return { 'status' => 'ERROR', 'statusMessage' => 'targeted sentiment requires a non-null target' }
  end

  unless @@ENDPOINTS['sentiment_targeted'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'targeted sentiment analysis for ' + flavor + ' not available' }
  end

  # Add the URL encoded data and the target to the options and analyze
  options[flavor] = data
  options['target'] = target
  return analyze(@@ENDPOINTS['sentiment_targeted'][flavor], options)
end

#taxonomy(flavor, data, options = {}) ⇒ Object

Categorizes the text for a URL, text or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/text-categorization/ For the docs, please refer to: www.alchemyapi.com/api/taxonomy/

INPUT: flavor -> which version of the call, i.e. url, text or html. data -> the data to analyze, either the the url, text or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: showSourceText -> 0: disabled (default), 1: enabled.

OUTPUT: The response, already converted from JSON to a Ruby object.



486
487
488
489
490
491
492
493
494
 
# File 'lib/alchemyapi.rb', line 486

def taxonomy(flavor, data, options = {})
  unless @@ENDPOINTS['taxonomy'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'Taxonomy info for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['taxonomy'][flavor], options)
end

#text(flavor, data, options = {}) ⇒ Object

Extracts the cleaned text (removes ads, navigation, etc.) for text, a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/text-extraction/ For the docs, please refer to: www.alchemyapi.com/api/text-extraction/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: useMetadata -> utilize meta description data, 0: disabled, 1: enabled (default) extractLinks -> include links, 0: disabled (default), 1: enabled.

OUTPUT: The response, already converted from JSON to a Ruby object.



361
362
363
364
365
366
367
368
369
 
# File 'lib/alchemyapi.rb', line 361

def text(flavor, data, options = {})
  unless @@ENDPOINTS['text'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'clean text extraction for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['text'][flavor], options)
end

#text_raw(flavor, data, options = {}) ⇒ Object

Extracts the raw text (includes ads, navigation, etc.) for a URL or HTML. For an overview, please refer to: www.alchemyapi.com/products/features/text-extraction/ For the docs, please refer to: www.alchemyapi.com/api/text-extraction/

INPUT: flavor -> which version of the call, i.e. text, url or html. data -> the data to analyze, either the text, the url or html code. options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.

Available Options: none

OUTPUT: The response, already converted from JSON to a Ruby object.



386
387
388
389
390
391
392
393
394
 
# File 'lib/alchemyapi.rb', line 386

def text_raw(flavor, data, options = {})
  unless @@ENDPOINTS['text_raw'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'raw text extraction for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['text_raw'][flavor], options)
end

#title(flavor, data, options = {}) ⇒ Object

OUTPUT: The response, already converted from JSON to a Ruby object.



411
412
413
414
415
416
417
418
419
 
# File 'lib/alchemyapi.rb', line 411

def title(flavor, data, options = {})
  unless @@ENDPOINTS['title'].key?(flavor)
    return { 'status' => 'ERROR', 'statusInfo' => 'title extraction for ' + flavor + ' not available' }
  end

  # Add the URL encoded data to the options and analyze
  options[flavor] = data
  return analyze(@@ENDPOINTS['title'][flavor], options)
end