Class: Nytimes::Articles::Article

Inherits:
Base
  • Object
show all
Defined in:
lib/nytimes_articles/article.rb

Overview

The Article class represents a single article returned from the New York Times Article Search API. Note that an article can have many attributes but these are not necessarily populated unless you explicitly request them in the reply from the server via the :fields parameter to search (or use :fields => :all).

Constant Summary collapse

RAW_FIELDS = 
%w(url)
TEXT_FIELDS = 
%w(abstract author body byline lead_paragraph nytd_lead_paragraph nytd_title title)
NUMERIC_FIELDS = 
%w(word_count)
BOOLEAN_FIELDS = 
%w(fee small_image)
IMAGE_FIELDS = 
%w(small_image small_image_url small_image_height small_image_width)
MULTIMEDIA_FIELDS = 
%w(multimedia related_multimedia)
ALL_FIELDS = 
TEXT_FIELDS + RAW_FIELDS + NUMERIC_FIELDS + BOOLEAN_FIELDS + MULTIMEDIA_FIELDS + Facet::ALL_FACETS + IMAGE_FIELDS
EARLIEST_BEGIN_DATE = 
'19810101'

Constants inherited from Base

Base::API_BASE, Base::API_NAME, Base::API_SERVER, Base::API_VERSION

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

api_key, api_key=, boolean_field, build_request_url, date_field, debug=, integer_field, invoke, text_field

Constructor Details

#initialize(params = {}) ⇒ Article

Create a new Article from hash arguments. You really don’t need to call this as Article instances are automatically returned from the API



36
37
38
39
40
 
# File 'lib/nytimes_articles/article.rb', line 36

def initialize(params={})
  params.each_pair do |k,v|
    instance_variable_set("@#{k}", v)
  end
end

Instance Attribute Details

#classifiers ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def classifiers
  @classifiers
end

#column ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def column
  @column
end

#date ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def date
  @date
end

#day_of_week ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def day_of_week
  @day_of_week
end

#descriptions ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def descriptions
  @descriptions
end

#desk ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def desk
  @desk
end

#geo ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def geo
  @geo
end

#material_types ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def material_types
  @material_types
end

#nytd_bylines ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def nytd_bylines
  @nytd_bylines
end

#nytd_descriptions ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def nytd_descriptions
  @nytd_descriptions
end

#nytd_geo ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def nytd_geo
  @nytd_geo
end

#nytd_organizations ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def nytd_organizations
  @nytd_organizations
end

#nytd_persons ⇒ Object (readonly) Also known as: nytd_people

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def nytd_persons
  @nytd_persons
end

#nytd_sections ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def nytd_sections
  @nytd_sections
end

#nytd_works_mentioned ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def nytd_works_mentioned
  @nytd_works_mentioned
end

#organizations ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def organizations
  @organizations
end

#page ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def page
  @page
end

#persons ⇒ Object (readonly) Also known as: people

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def persons
  @persons
end

#pub_day ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def pub_day
  @pub_day
end

#pub_month ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def pub_month
  @pub_month
end

#pub_year ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def pub_year
  @pub_year
end

#section_page ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def section_page
  @section_page
end

#source ⇒ Object (readonly)

Scalar facets



27
28
29
 
# File 'lib/nytimes_articles/article.rb', line 27

def source
  @source
end

#thumbnail ⇒ Object (readonly)

special additional objects



24
25
26
 
# File 'lib/nytimes_articles/article.rb', line 24

def thumbnail
  @thumbnail
end

#works_mentioned ⇒ Object (readonly)

Facets that return multiple values



30
31
32
 
# File 'lib/nytimes_articles/article.rb', line 30

def works_mentioned
  @works_mentioned
end

Class Method Details

.init_from_api(params) ⇒ Object

Creates a new Article from the a hash returned from the API. This is called on search results. You have no reason to call it.



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/nytimes_articles/article.rb', line 54

def self.init_from_api(params)
  article = Article.new(
  :abstract => text_field(params['abstract']),
  :author => text_field(params['author']),
  :body => text_field(params['body']),
  :byline => text_field(params['byline']),
  :fee => boolean_field(params['fee']),
  :lead_paragraph => text_field(params['lead_paragraph']),
  :nytd_title => text_field(params['nytd_title']),
  :nytd_lead_paragraph => text_field(params['nytd_lead_paragraph']),
  :related_multimedia => nil, # FIXME
  :thumbnail => Thumbnail.init_from_api(params),
  :title => text_field(params['title']),
  :url => params['url'],
  :word_count => integer_field(params['word_count']),

  # FACETS THAT RETURN SCALARS
  :page => integer_field(params[Facet::PAGE]),
  :column => text_field(params[Facet::COLUMN]),
  :pub_month => integer_field(params[Facet::PUB_MONTH]),
  :pub_year => integer_field(params[Facet::PUB_YEAR]),
  :pub_day => integer_field(params[Facet::PUB_DAY]),
  :day_of_week => params[Facet::DAY_OF_WEEK],
  :desk => text_field(params[Facet::DESK]),
  :date => date_field(params[Facet::DATE]),
  :section_page => params[Facet::SECTION_PAGE],
  :source => text_field(params[Facet::SOURCE]),

  # FIXME! MORE FACET PARAMS
  # FACETS THAT RETURN ARRAYS
  :classifiers => facet_params(params, Facet::CLASSIFIERS),
  :descriptions => facet_params(params, Facet::DESCRIPTION),
  :geo => facet_params(params, Facet::GEO),
  :material_types => facet_params(params, Facet::MATERIAL_TYPE),
  :organizations => facet_params(params, Facet::ORGANIZATION),
  :persons => facet_params(params, Facet::PERSON),
  :nytd_bylines => facet_params(params, Facet::NYTD_BYLINE),
  :nytd_descriptions => facet_params(params, Facet::NYTD_DESCRIPTION),
  :nytd_geo => facet_params(params, Facet::NYTD_GEO),
  :nytd_organizations => facet_params(params, Facet::NYTD_ORGANIZATION),
  :nytd_persons => facet_params(params, Facet::NYTD_PERSON),
  :nytd_sections => facet_params(params, Facet::NYTD_SECTION),
  :nytd_works_mentioned => facet_params(params, Facet::NYTD_WORKS_MENTIONED),
  :works_mentioned => facet_params(params, Facet::WORKS_MENTIONED)
  )

  article
end

.search(query, params = {}) ⇒ Object

The :facets argument can be used to specify up to 5 facet fields to be returned alongside the search that provide overall counts of how much each facet term appears in the search results. FIXME provide list of available facets as well as description of :nytd parameter.

ARTICLE FIELDS

The :fields parameter is used to indicate what fields are returned with each article from the search results. If not specified, only the following fields are returned for each article: body, byline, date, title, and url. To return specific fields, any of the search fields from above can be explicitly specified in a comma-delimited list, as well as the additional display-only (not searchable) fields below (these are strings or symbols):

  • :all - return all fields for the article

  • :none - display only the facet breakdown and no article results

  • :multimedia - return any related multimedia links for the article

  • :thumbnail - return information for a related thumbnail image (if the article has one)

  • :word_count - the word_count of the article.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/nytimes_articles/article.rb', line 196

def self.search(query, params={})
  params = params.dup

  case query
  when String
    params[:query] = query
  when Hash
    params.merge! query
  end

  api_params = {}

  add_query_params(api_params, params)
  add_facet_conditions_params(api_params, params)
  add_boolean_params(api_params, params)
  add_facets_param(api_params, params)
  add_fields_param(api_params, params)
  add_rank_params(api_params, params)
  add_date_params(api_params, params)
  add_offset_params(api_params, params)

  reply = invoke(api_params)
  parse_reply(reply)
end

Instance Method Details

#free? ⇒ Boolean

Is this article available for free?

Returns:

  • (Boolean) 


48
49
50
 
# File 'lib/nytimes_articles/article.rb', line 48

def free?
  not(fee?)
end