Class: AP::Search

Inherits:
API
  • Object
show all
Defined in:
lib/ap/search.rb

Defined Under Namespace

Classes: InvalidGeocodinates, UnsupportedSearchMethod

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from API

get

Constructor Details

#initialize ⇒ Search

Returns a new Search object



12
13
14
15
 
# File 'lib/ap/search.rb', line 12

def initialize
  clear
  super
end

Instance Attribute Details

#query ⇒ Object (readonly)

Returns the value of attribute query.



3
4
5
 
# File 'lib/ap/search.rb', line 3

def query
  @query
end

#search_type ⇒ Object (readonly)

Returns the value of attribute search_type.



3
4
5
 
# File 'lib/ap/search.rb', line 3

def search_type
  @search_type
end

Class Method Details

.similar(id) ⇒ Object

Returns a new Search object that will search for articled similar to the one provided by the id parameter The id parameter will the same as the id returned by an AP::Article object. Supports limited functionality compared to a standard object:

- clear
- geocode
- location
- sort_by_locaation
- to_s
- per_page
- page
- next_page?
- next_page
- fetch



31
32
33
34
35
36
 
# File 'lib/ap/search.rb', line 31

def self.similar(id)
  obj = self.new
  obj.instance_variable_set(:@search_type, "similar")
  obj.instance_variable_set(:@query, obj.query.merge!(AP.search_query_defaults).merge!({ :searchTerms => id }))
  return obj
end

Instance Method Details

#and ⇒ Object

Represents the AND boolean operator in the query Sample Query Returned Results Obama AND Iraq AND election Returns all documents containing all of the words “Obama,” “Iraq,” and “election.” This is equivalent to Obama Iraq Election. Example:

search.contains("Obama")
search.and()
search.contains("Iraq")

Produces: Obama AND Iraw

Raises:



201
202
203
204
205
 
# File 'lib/ap/search.rb', line 201

def and
  raise UnsupportedSearchMethod unless @search_type == "request"
  @query[:searchTerms] << "AND" unless(@query[:searchTerms].last == "(" || @query[:searchTerms].last == nil || @query[:searchTerms].last == "OR" || @query[:searchTerms].last == "AND" || @query[:searchTerms].last == "AND NOT")
  return self
end

#and_not ⇒ Object

Represents the AND NOT boolean operator in the query Sample Query Returned Results Obama AND Iraq AND NOT Iran Returns all documents that contain both “Obama” and “Iraq,” but not “Iran.” Example:

search.contains("Obama")
search.and()
search.contains("Iraq")
search.and_not()
search.contains("Iran")

Produces: Obama AND Iraq AND NOT Iran

Raises:



231
232
233
234
235
 
# File 'lib/ap/search.rb', line 231

def and_not
  raise UnsupportedSearchMethod unless @search_type == "request"
  @query[:searchTerms] << "AND NOT" unless(@query[:searchTerms].last == "(" || @query[:searchTerms].last == nil || @query[:searchTerms].last == "OR" || @query[:searchTerms].last == "AND" || @query[:searchTerms].last == "AND NOT")
  return self
end

#clear ⇒ Object

Resets every parameter of a Search object When called upon a Search object with a search type of similar it will reset it a request search



41
42
43
44
45
46
47
48
49
 
# File 'lib/ap/search.rb', line 41

def clear
  @query = {}
  @query[:searchTerms] = []
  @query[:startPage] = 1
  @query[:count] = 20
  @total_results = 0
  @search_type = "request"
  self
end

#containing(query) ⇒ Object Also known as: contains, q

Basic Keyword Search A basic query contains one or more words and no operators. Sample Query Returned Results Iraq Returns all documents containing the word “Iraq” and related word variations, such as “Iraqi”, but not “Iran”. iraq Returns the same results as Iraq (case is ignored). Obama Iraq Obama Returns the same results as Obama Iraq (repeated words are ignored). Example Usage:

search.containing("obama")
search.containing("iraq")
search.contains("iraq")
search.q("iraq")

Aliased as contains and q

Raises:



63
64
65
66
67
 
# File 'lib/ap/search.rb', line 63

def containing(query)
  raise UnsupportedSearchMethod unless @search_type == "request"
  @query[:searchTerms] << query
  return self
end

#exact(query) ⇒ Object

Exact Keyword Search (quotation marks) Sample Query Returned Results “Iraq” Returns all documents containing the word “Iraq”. Since stemming is not applied to the words in quotation marks, the query will match “Iraq” but not “Iraqi”. “iraq” Returns the same results as Iraq (case is still ignored in quoted text). “Barack Obama” Iraq Returns all documents containing “Barack Obama” and “Iraq”. Stemming is applied to “Iraq”, so the query will match “Barack Obama announces Iraqi elections”, but will not match “President Obama visits Iraq”. “The Who” Performed Stop words are not ignored in the quoted text. This query will match “The Who performed at MSG”, but will not match “Who performed at MSG?” Example Usage: For the query “Iraq”:

search.exact("Iraq")

For the query “Barack Obama” Iraq:

search.exact("Brack Obama")
search.contains("Iraq")

Raises:



83
84
85
86
87
 
# File 'lib/ap/search.rb', line 83

def exact(query)
  raise UnsupportedSearchMethod unless @search_type == "request"
  @query[:searchTerms] << "\"#{query}\""
  return self
end

#fetch ⇒ Object

Fetches and parses the search response. An array of AP::Article objects are returned Example:

search.contains("Obama").and.contains("Iraq").fetch



268
269
270
271
272
273
 
# File 'lib/ap/search.rb', line 268

def fetch
  data = self.class.get("/v2/search.svc/#{@search_type}/", :query => @query.merge({ :searchTerms => CGI.escape(@query[:searchTerms].join(" ")) }))
  r = data["feed"]["entry"].collect { |e| AP::Article.new_from_api_data(e) }
  @total_results = data["feed"]["opensearch:totalResults"].to_i
  return r
end

#geocode(latitude, longitude, radius = 50) ⇒ Object

Filter search results to latitude & longitude within a specific radius Parameters:

  • latitude: The latitude of the location. The range of possible values is -90 to 90.

  • longitude: The longitude of the location. The range of possible values is -180 to 180. (Note: If both latitude and longitude are specified, they wil take priority over all other location parameters - for example the location method)

  • radius: The distance in miles from the specified location. The default is 50

Example:

search.geocode(37.760401, -122.416534)

The example above would limit results to the San Francisco bay area, shown by this map

Raises:



123
124
125
126
127
128
129
 
# File 'lib/ap/search.rb', line 123

def geocode(latitude, longitude, radius = 50)
  raise InvalidGeocodinates unless (-90 <= latitude && latitude <= 90 && -180 <= longitude && longitude <= 180)
  @query[:latitude] = latitude
  @query[:longitude] = longitude
  @query[:radius] = radius
  return self
end

#location(opts = {}) ⇒ Object

Filter a search around a City/State/Zip Code Valid combinations:

  • US zip code

  • City, State

  • City, State, Zip

Note: If zip code is specified, it will take priority over city and state. The options hash takes three parameters:

  • :city

  • :state should be in two letter form; e.g. TX for Texas, AZ for Arizona

  • :zip_code

Examples:

search.location(:city => "Fremont", :state => "CA", :zip_code => "94536")
search.location(:city => "Los Angeles", :state => "CA")
search.location(:zip_code => "99652")



145
146
147
148
149
150
151
152
153
154
 
# File 'lib/ap/search.rb', line 145

def location(opts = {})
  if opts[:city] && opts[:state] && opts[:zip_code]
    @query[:location] = opts[:city] + ", " + opts[:state] + ", " + opts[:zip_code].to_s
  elsif opts[:zip_code]
    @query[:location] = opts[:zip_code].to_s
  elsif opts[:city] && opts[:state]
    @query[:location] = opts[:city] + ", " + opts[:state]
  end
  return self
end

#loose_match(str) ⇒ Object

Matches words beginning with passed string Sample Query Returned Results ira* This query matches any word beginning with “ira.” It matches “Iraq,” “Iran,” “IRA” and “IRAAM.” It does not match “Iris,” “miracle” or “aardvark.” Example usage:

search.loose_match("ira")

Raises:



108
109
110
111
112
 
# File 'lib/ap/search.rb', line 108

def loose_match(str) # loose match
  raise UnsupportedSearchMethod unless @search_type == "request"
  @query[:searchTerms] << str.to_s + "*"
  return self
end

#matches(prefix) ⇒ Object

Wildcard search for one character Sample Query Returned Results Ira? This query matches any four-letter word beginning with “ira.” It matches “Iraq” and “Iran,” but does not match “Iris,” “IRA,” “miracle,” “IRAAM” or “Aardvark.” Obama AND ira? This search returns any document containing “Obama” and any four-letter word beginning with “ira.” This query will match “Obama visits Iraq” or “Obama visits Iran.” It will not match “Will Obama meet the IRA?” Obama AND “ira?” Wildcards are considered even when the term is enclosed in quotation marks. This query is equivalent to Obama AND ira? Example usage: For the query Ira?

search.matches("Ira")

Raises:



97
98
99
100
101
 
# File 'lib/ap/search.rb', line 97

def matches(prefix)
  raise UnsupportedSearchMethod unless @search_type == "request"
  @query[:searchTerms] << prefix.to_s + "?"
  return self
end

#next_page ⇒ Object Also known as: fetch_next_page

Returns the next page if next_page? is true



256
257
258
259
260
261
 
# File 'lib/ap/search.rb', line 256

def next_page
  if next_page?
    @query[:startPage] += 1
    fetch
  end
end

#next_page? ⇒ Boolean

Returns whether or not there is a next page

Returns:

  • (Boolean) 


251
252
253
 
# File 'lib/ap/search.rb', line 251

def next_page?
  return (@query[:startPage] * (@query[:count] + 1)) < @total_results
end

#or ⇒ Object

Represents the OR boolean operator in the query Sample Query Returned Results Obama OR Iraq Returns all documents containing either “Obama” or “Iraq.” The query will match both “Barack Obama” and “Iraqi elections.” Example:

search.contains("Obama")
search.or()
search.contains("Iraq")

Produces: Obama OR Iraq

Raises:



215
216
217
218
219
 
# File 'lib/ap/search.rb', line 215

def or
  raise UnsupportedSearchMethod unless @search_type == "request"
  @query[:searchTerms] << "OR" unless(@query[:searchTerms].last == "(" || @query[:searchTerms].last == nil || @query[:searchTerms].last == "OR" || @query[:searchTerms].last == "AND" || @query[:searchTerms].last == "AND NOT")
  return self
end

#page(p = 1) ⇒ Object

Sets the page to the parameter so you can fetch it



245
246
247
248
 
# File 'lib/ap/search.rb', line 245

def page(p = 1)
  @query[:startPage] = p
  return self
end

#per_page(pp = 20) ⇒ Object

Sets the number of results to return per page Defaults to 20



239
240
241
242
 
# File 'lib/ap/search.rb', line 239

def per_page(pp = 20)
  @query[:count] = pp
  return self
end

#scoped {|_self| ... } ⇒ Object

Scopes all of the following commands in parentheses to specify order. It yields itself during the block, so it’s the exact same object you have been working with Examples:

search.scoped do |s|
  s.contains("Obama")
  s.or()
  s.contains("Iraq")
end
search.and()
search.contains("Iran")

Will produce the query: (Obama OR Iraq) AND Iran

Yields:

  • (_self)

Yield Parameters:

  • _self (AP::Search) —

    the object that the method was called on

Raises:



179
180
181
182
183
184
185
 
# File 'lib/ap/search.rb', line 179

def scoped(&block)
  raise UnsupportedSearchMethod unless @search_type == "request"
  @query[:searchTerms] << "("
  yield self
  @query[:searchTerms] << ")"
  return self
end

#sort_by_location(sort = true) ⇒ Object

Orders results by proximity to the specified location Default parameter is true Examples:

search.sort_by_location # will sort by location
search.sort_by_location(true) # same as above
search.sort_by_location(false) # will not sort by proximity



162
163
164
165
 
# File 'lib/ap/search.rb', line 162

def sort_by_location(sort = true)
  @query[:sortByLocation] = sort
  return self
end

#to_s ⇒ Object

Returns the query represented in string form the way it will be submitted to the api



189
190
191
 
# File 'lib/ap/search.rb', line 189

def to_s
  return @query[:searchTerms].join(" ")
end