Class: BingSearch::Client

Inherits:

Object

Object
BingSearch::Client

show all

Defined in:: lib/bing-search/client.rb

Instance Attribute Summary collapse

#account_key ⇒ String readonly

The Account Key obtained from the Azure Marketplace.
#web_only ⇒ Boolean readonly

Whether to use the less expensive web-only API.

Constructors collapse

#initialize(account_key: nil, web_only: nil) ⇒ Client constructor

A new instance of Client.

Sessions collapse

.open(*args) {|client| ... } ⇒ Client

Opens a client and yields it to the given block.
#close ⇒ self

Closes the client.
#open { ... } ⇒ Object, self

Opens the client, creating a new TCP connection.
#open? ⇒ Boolean

Whether the client is open.

Searching collapse

#composite(query, sources, opts = {}) ⇒ CompositeSearchResult

Searches multiple sources.
#image(query, opts = {}) ⇒ Array<ImageResult>

Searches for images.
#news(query, opts = {}) ⇒ Array<NewsResult>

Searches for news.
#related_search(query, opts = {}) ⇒ Array<RelatedSearchResult> (also: #related)

Searches for related queries.
#spelling_suggestions(query, opts = {}) ⇒ Array<SpellingSuggestionsResult> (also: #spelling)

Corrects spelling in the query text.
#video(query, opts = {}) ⇒ Array<VideoResult>

Searches for videos.
#web(query, opts = {}) ⇒ Array<WebResult>

Searches for web pages.

Constructor Details

#initialize(account_key: nil, web_only: nil) ⇒ `Client`

Returns a new instance of Client.

Parameters:

account_key (String, nil) (defaults to: nil) —

An Account Key obtained from the Azure Marketplace. If nil, BingSearch.account_key is assumed.
web_only (Boolean, nil) (defaults to: nil) —

Whether to use the less expensive web-only API. If nil, BingSearch.web_only is assumed.

# File 'lib/bing-search/client.rb', line 26

def initialize(account_key: nil, web_only: nil)
  @session = nil
  @account_key = account_key || BingSearch.account_key
  @web_only = web_only.nil? ? BingSearch.web_only : web_only

  unless @account_key
    raise ArgumentError, "Pass an Account Key or set BingSearch.account_key"
  end
end

Instance Attribute Details

#account_key ⇒ `String` (readonly)

The Account Key obtained from the Azure Marketplace

Returns:

(String)



10
11
12

# File 'lib/bing-search/client.rb', line 10

def account_key
  @account_key
end

#web_only ⇒ `Boolean` (readonly)

Whether to use the less expensive web-only API

Returns:

(Boolean)



14
15
16

# File 'lib/bing-search/client.rb', line 14

def web_only
  @web_only
end

Class Method Details

.open(*args) {|client| ... } ⇒ `Client`

Opens a client and yields it to the given block. Takes the same arguments as #initialize.

Yield Parameters:

client (Client)

Returns:

(Client)

See Also:

# File 'lib/bing-search/client.rb', line 46

def self.open(*args)
  raise "Block required" unless block_given?
  client = new(*args)
  client.open { yield client }
  client
end

Instance Method Details

#close ⇒ `self`

Closes the client. Must be called after #open is called without a block.

Returns:

(self)

See Also:

#open

# File 'lib/bing-search/client.rb', line 91

def close
  @session.finish if open?
  @session = nil
  self
end

#composite(query, sources, opts = {}) ⇒ `CompositeSearchResult`

Searches multiple sources. At most 15 news results are returned by a composite query regardless of the :limit option.

Parameters:

query (String) —

The query text; supports the Bing Query Language
opts (Hash{Symbol => Object}) (defaults to: {})
sources (Array<Source>) —

The sources to search

Options Hash (opts):

:limit (Integer) —

The maximum number of results to return
:offset (Integer) —

The zero-based ordinal of the first result to return
:adult (Adult, Symbol) —

The level of filtering of sexually explicit content. If omitted, Bing uses the default level for the market.
:latitude (Float) —

May range from -90 to 90
:longitude (Float) —

May range from -180 to 180
:market (String) —

A language tag specifying the market in which to search (e.g. en-US). If omitted, Bing infers the market from IP address, etc.
:location_detection (Boolean) — default: true —

Whether to infer location from the query text
:highlighting (Boolean) — default: false —

Whether to surround query terms in NewsResult#description and WebResult#description with the delimiter HIGHLIGHT_DELIMITER.
:web_file_type (FileType) —

Type of file to return. Applies to Source::Web; also affects Source::Image and Source::Video if Source::Web is specified.
:web_host_collapsing (Boolean) — default: true —

Whether to suppress results from the same ‘top-level URL.’ Applies to Source::Web.
:web_query_alterations (Boolean) — default: true —

Whether to alter the query in case of, e.g., supposed spelling errors. Applies to Source::Web.
:image_minimum_width (Integer) —

In pixels; ANDed with other filters. Applies to Source::Image.
:image_minimum_height (Integer) —

In pixels; ANDed with other image filters. Applies to Source::Image.
:image_filters (Array<ImageFilter>) —

Multiple filters are ANDed. Applies to Source::Image.
:video_filters (Array<VideoFilter>) —

Multiple filters are ANDed. At most one duration is allowed. Applies to Source::Video.
:video_sort (VideoSort) —

Applies to Source::Video
:news_category (NewsCategory) —

Only applies in the en_US market. If no news matches the category, Bing returns results from a mix of categories. Applies to Source::News.
:news_location_override (String) —

Overrides Bing’s location detection. Example: US.WA. Applies to Source::News.
:news_sort (NewsSort) —

Applies to Source::News.

Returns:

(CompositeSearchResult)

Raises:

(ServiceError) —

The Bing Search service returned an error
(StandardError) —

Invalid argument, unable to parse Bing response, networking error, and other error conditions

See Also:

Bing Query Language reference

# File 'lib/bing-search/client.rb', line 268

def composite(query, sources, opts = {})
  results = invoke('Composite',
    query,
    opts,
    passthrough_opts: %i(
      web_file_type
      video_filters
      video_sort
      news_category
      news_location_override
      news_sort
    ),
    enum_opt_to_module: {
      web_file_type: FileType,
      video_filters: VideoFilter,
      video_sort: VideoSort,
      news_category: NewsCategory,
      news_sort: NewsSort
    },
    param_name_replacements: {
      video_sort: 'VideoSortBy',
      news_sort: 'NewsSortBy'
    },
    params: {
      sources: sources.collect { |source| enum_value(source, Source) },
      web_search_options: web_search_options_from_opts(opts, :web_),
      image_filters: image_filters_from_opts(opts, :image_)
    }
  )

  results.first
end

#image(query, opts = {}) ⇒ `Array<ImageResult>`

Searches for images

Parameters:

query (String) —

The query text; supports the Bing Query Language
opts (Hash{Symbol => Object}) (defaults to: {})

Options Hash (opts):

:limit (Integer) —

The maximum number of results to return
:offset (Integer) —

The zero-based ordinal of the first result to return
:adult (Adult, Symbol) —

The level of filtering of sexually explicit content. If omitted, Bing uses the default level for the market.
:latitude (Float) —

May range from -90 to 90
:longitude (Float) —

May range from -180 to 180
:market (String) —

A language tag specifying the market in which to search (e.g. en-US). If omitted, Bing infers the market from IP address, etc.
:location_detection (Boolean) — default: true —

Whether to infer location from the query text
:minimum_height (Integer) —

In pixels; ANDed with other filters
:minimum_width (Integer) —

In pixels; ANDed with other filters
:filters (Array<ImageFilter>) —

Multiple filters are ANDed

Returns:

(Array<ImageResult>)

Raises:

(ServiceError) —

The Bing Search service returned an error
(StandardError) —

Invalid argument, unable to parse Bing response, networking error, and other error conditions

See Also:

Bing Query Language reference

# File 'lib/bing-search/client.rb', line 169

def image(query, opts = {})
  invoke 'Image',
    query,
    opts,
    param_name_replacements: {filters: 'ImageFilters'},
    params: {filters: image_filters_from_opts(opts)}
end

#news(query, opts = {}) ⇒ `Array<NewsResult>`

Searches for news

Parameters:

query (String) —

The query text; supports the Bing Query Language
opts (Hash{Symbol => Object}) (defaults to: {})

Options Hash (opts):

:limit (Integer) —

The maximum number of results to return
:offset (Integer) —

The zero-based ordinal of the first result to return
:adult (Adult, Symbol) —

The level of filtering of sexually explicit content. If omitted, Bing uses the default level for the market.
:latitude (Float) —

May range from -90 to 90
:longitude (Float) —

May range from -180 to 180
:market (String) —

A language tag specifying the market in which to search (e.g. en-US). If omitted, Bing infers the market from IP address, etc.
:location_detection (Boolean) — default: true —

Whether to infer location from the query text
:highlighting (Boolean) — default: false —

Whether to surround query terms in NewsResult#description with the delimiter HIGHLIGHT_DELIMITER.
:category (NewsCategory) —

Only applies in the en-US market. If no news matches the category, Bing returns results from a mix of categories.
:location_override (String) —

Overrides Bing’s location detection. Example: US.WA
:sort (NewsSort)

Returns:

(Array<NewsResult>)

Raises:

(ServiceError) —

The Bing Search service returned an error
(StandardError) —

Invalid argument, unable to parse Bing response, networking error, and other error conditions

See Also:

Bing Query Language reference

# File 'lib/bing-search/client.rb', line 206

def news(query, opts = {})
  invoke 'News',
    query,
    opts,
    passthrough_opts: %i(category location_override sort),
    enum_opt_to_module: {category: NewsCategory, sort: NewsSort},
    param_name_replacements: {category: 'NewsCategory', location_override: 'NewsLocationOverride', sort: 'NewsSortBy'}
end

#open { ... } ⇒ `Object`, `self`

Opens the client, creating a new TCP connection.

If a block is given, yields to the block, closes the client when the block returns, and returns the return value of the block. If a block is not given, returns self and leaves the client open, relying on the caller to close the client with #close.

Note that opening and closing the client is only required if you want to make several calls under one TCP connection. Otherwise, you can simply call the search methods (#web, #image, etc.), which call #open for you if necessary.

Yields:

If a block is given, the client is closed when the block returns.

Returns:

(Object, self) —

If a block is given, the return value of the block; otherwise, self.

Raises:

(StandardError) —

The client is already open

# File 'lib/bing-search/client.rb', line 72

def open
  raise "Already open" if open?

  @session = Net::HTTP.new(HOST, Net::HTTP.https_default_port)
  @session.use_ssl = true

  begin
    @session.start
    block_given? ? yield : self
  ensure
    close if block_given?
  end
end

#open? ⇒ `Boolean`

Whether the client is open

Returns:

(Boolean)

See Also:

#open



101
102
103

# File 'lib/bing-search/client.rb', line 101

def open?
  @session && @session.started?
end

#related_search(query, opts = {}) ⇒ `Array<RelatedSearchResult>` Also known as: related

Searches for related queries

Parameters:

query (String) —

The query text; supports the Bing Query Language
opts (Hash{Symbol => Object}) (defaults to: {})

Options Hash (opts):

:limit (Integer) —

The maximum number of results to return
:offset (Integer) —

The zero-based ordinal of the first result to return
:adult (Adult, Symbol) —

The level of filtering of sexually explicit content. If omitted, Bing uses the default level for the market.
:latitude (Float) —

May range from -90 to 90
:longitude (Float) —

May range from -180 to 180
:market (String) —

A language tag specifying the market in which to search (e.g. en-US). If omitted, Bing infers the market from IP address, etc.
:location_detection (Boolean) — default: true —

Whether to infer location from the query text

Returns:

(Array<RelatedSearchResult>)

Raises:

(ServiceError) —

The Bing Search service returned an error
(StandardError) —

Invalid argument, unable to parse Bing response, networking error, and other error conditions

See Also:

Bing Query Language reference



219
220
221

# File 'lib/bing-search/client.rb', line 219

def related_search(query, opts = {})
  invoke 'RelatedSearch', query, opts
end

#spelling_suggestions(query, opts = {}) ⇒ `Array<SpellingSuggestionsResult>` Also known as: spelling

Corrects spelling in the query text

Parameters:

query (String) —

The query text; supports the Bing Query Language
opts (Hash{Symbol => Object}) (defaults to: {})

Options Hash (opts):

:limit (Integer) —

The maximum number of results to return
:offset (Integer) —

The zero-based ordinal of the first result to return
:adult (Adult, Symbol) —

The level of filtering of sexually explicit content. If omitted, Bing uses the default level for the market.
:latitude (Float) —

May range from -90 to 90
:longitude (Float) —

May range from -180 to 180
:market (String) —

A language tag specifying the market in which to search (e.g. en-US). If omitted, Bing infers the market from IP address, etc.
:location_detection (Boolean) — default: true —

Whether to infer location from the query text

Returns:

(Array<SpellingSuggestionsResult>)

Raises:

(ServiceError) —

The Bing Search service returned an error
(StandardError) —

Invalid argument, unable to parse Bing response, networking error, and other error conditions

See Also:

Bing Query Language reference



228
229
230

# File 'lib/bing-search/client.rb', line 228

def spelling_suggestions(query, opts = {})
  invoke 'SpellingSuggestions', query, opts
end

#video(query, opts = {}) ⇒ `Array<VideoResult>`

Searches for videos

Parameters:

query (String) —

The query text; supports the Bing Query Language
opts (Hash{Symbol => Object}) (defaults to: {})

Options Hash (opts):

:limit (Integer) —

The maximum number of results to return
:offset (Integer) —

The zero-based ordinal of the first result to return
:adult (Adult, Symbol) —

The level of filtering of sexually explicit content. If omitted, Bing uses the default level for the market.
:latitude (Float) —

May range from -90 to 90
:longitude (Float) —

May range from -180 to 180
:market (String) —

A language tag specifying the market in which to search (e.g. en-US). If omitted, Bing infers the market from IP address, etc.
:location_detection (Boolean) — default: true —

Whether to infer location from the query text
:filters (Array<VideoFilter>) —

Multiple filters are ANDed. At most one duration is allowed.
:sort (VideoSort)

Returns:

(Array<VideoResult>)

Raises:

(ServiceError) —

The Bing Search service returned an error
(StandardError) —

Invalid argument, unable to parse Bing response, networking error, and other error conditions

See Also:

Bing Query Language reference

# File 'lib/bing-search/client.rb', line 184

def video(query, opts = {})
  invoke 'Video',
    query,
    opts,
    passthrough_opts: %i(filters sort),
    enum_opt_to_module: {filters: VideoFilter, sort: VideoSort},
    param_name_replacements: {filters: 'VideoFilters', sort: 'VideoSortBy'}
end

#web(query, opts = {}) ⇒ `Array<WebResult>`

Searches for web pages

Parameters:

query (String) —

The query text; supports the Bing Query Language
opts (Hash{Symbol => Object}) (defaults to: {})

Options Hash (opts):

:limit (Integer) —

The maximum number of results to return
:offset (Integer) —

The zero-based ordinal of the first result to return
:adult (Adult, Symbol) —

The level of filtering of sexually explicit content. If omitted, Bing uses the default level for the market.
:latitude (Float) —

May range from -90 to 90
:longitude (Float) —

May range from -180 to 180
:market (String) —

A language tag specifying the market in which to search (e.g. en-US). If omitted, Bing infers the market from IP address, etc.
:location_detection (Boolean) — default: true —

Whether to infer location from the query text
:file_type (FileType) —

Type of file to return
:highlighting (Boolean) — default: false —

Whether to surround query terms in WebResult#description with the delimiter HIGHLIGHT_DELIMITER.
:host_collapsing (Boolean) — default: true —

Whether to suppress results from the same ‘top-level URL’
:query_alterations (Boolean) — default: true —

Whether to alter the query in case of, e.g., supposed spelling errors

Returns:

(Array<WebResult>)

Raises:

(ServiceError) —

The Bing Search service returned an error
(StandardError) —

Invalid argument, unable to parse Bing response, networking error, and other error conditions

See Also:

Bing Query Language reference

# File 'lib/bing-search/client.rb', line 149

def web(query, opts = {})
  invoke 'Web',
    query,
    opts,
    passthrough_opts: %i(file_type),
    enum_opt_to_module: {file_type: FileType},
    param_name_replacements: {file_type: 'WebFileType'},
    params: {web_search_options: web_search_options_from_opts(opts)}
end

Class: BingSearch::Client

Instance Attribute Summary collapse

Constructors collapse

Sessions collapse

Searching collapse

Constructor Details

#initialize(account_key: nil, web_only: nil) ⇒ Client

Instance Attribute Details

#account_key ⇒ String (readonly)

#web_only ⇒ Boolean (readonly)

Class Method Details

.open(*args) {|client| ... } ⇒ Client

Instance Method Details

#close ⇒ self

#composite(query, sources, opts = {}) ⇒ CompositeSearchResult

#image(query, opts = {}) ⇒ Array<ImageResult>

#news(query, opts = {}) ⇒ Array<NewsResult>

#open { ... } ⇒ Object, self

#open? ⇒ Boolean

#related_search(query, opts = {}) ⇒ Array<RelatedSearchResult> Also known as: related

#spelling_suggestions(query, opts = {}) ⇒ Array<SpellingSuggestionsResult> Also known as: spelling

#video(query, opts = {}) ⇒ Array<VideoResult>

#web(query, opts = {}) ⇒ Array<WebResult>

#initialize(account_key: nil, web_only: nil) ⇒ `Client`

#account_key ⇒ `String` (readonly)

#web_only ⇒ `Boolean` (readonly)

.open(*args) {|client| ... } ⇒ `Client`

#close ⇒ `self`

#composite(query, sources, opts = {}) ⇒ `CompositeSearchResult`

#image(query, opts = {}) ⇒ `Array<ImageResult>`

#news(query, opts = {}) ⇒ `Array<NewsResult>`

#open { ... } ⇒ `Object`, `self`

#open? ⇒ `Boolean`

#related_search(query, opts = {}) ⇒ `Array<RelatedSearchResult>` Also known as: related

#spelling_suggestions(query, opts = {}) ⇒ `Array<SpellingSuggestionsResult>` Also known as: spelling

#video(query, opts = {}) ⇒ `Array<VideoResult>`

#web(query, opts = {}) ⇒ `Array<WebResult>`