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 comments)
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=, decode_html_entities=, 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



40
41
42
43
44
 
# File 'lib/nytimes_articles/article.rb', line 40

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) Also known as: subjects

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) Also known as: places

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) Also known as: nytd_subjects

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) Also known as: nytd_places

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.



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
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/nytimes_articles/article.rb', line 62

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']),
	:comments => boolean_field(params['comments']),
	: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),
	:dbpedia_resources => facet_params(params, Facet::DBPEDIA_RESOURCE),
	:dbpedia_urls => facet_params(params, Facet::DBPEDIA_URL),
	: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, all fields are returned. 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

  • :basic - return only the body, byline, date, title, and url

  • :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.



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/nytimes_articles/article.rb', line 212

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) 


52
53
54
 
# File 'lib/nytimes_articles/article.rb', line 52

def free?
	not(fee?)
end