bing-search 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3f89243c5039d162db74eea16a768640ca39c090
+  data.tar.gz: 5bbed193646f93ccd1b1bfa802cea73612a426ee
+SHA512:
+  metadata.gz: 7502295d14673dbe7880875c4db6b52edc09c97d9e39a2ff50a178ab18832bc784e1ba0af297b4d5a4c86aeea44bb34ecc99c5bb10e4e151a4f2a2c263bcbe85
+  data.tar.gz: 1639f625fdedaf8efceb98224e6da870bc10d5d92b387aed79fd90d30a6cb2eece3e033f1d1bb8062ba2b3b071f8e1adb8443bdd3595c26f7e76dc107781d607

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Jonah Burke
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# bing-search
+
+A Ruby client for the [Bing Search API](http://datamarket.azure.com/dataset/bing/search).
+
+## Getting Started
+
+### Installation
+
+```bash
+gem install bing-search
+```
+
+### Signup
+
+Sign up for the [Bing Search API](https://datamarket.azure.com/dataset/bing/search) or the [Web-Only Bing Search API](https://datamarket.azure.com/dataset/bing/searchweb) at the Microsoft Azure Marketplace. Then retrieve your Account Key from the [My Account](https://datamarket.azure.com/account) section of the marketplace and provide it as shown below.
+
+## Basics
+
+To use bing-search, first supply your Account Key:
+
+```ruby
+BingSearch.account_key = 'hzy9+Y6...'
+```
+
+Then, use {BingSearch.web} to search for web pages:
+
+```ruby
+results = BingSearch.web('Dirac')
+```
+
+Or, use the other {BingSearch} class methods to search for images, news, video, related searches, and spelling suggestions:
+
+```ruby
+BingSearch.spelling('Feinman').first.suggestion # => "Feynman"
+```
+
+The type of result depends on the kind of search:
+
+```ruby
+BingSearch.web('Gell-Mann').class # => WebResult
+BingSearch.image('Pauli').class # => ImageResult
+BingSearch.video('von Neumann').class # => VideoResult
+```
+
+And each result type has its own attributes:
+
+```ruby
+web = BingSearch.web('Gell-Mann').first
+web.summary # => "Murray Gell-Mann (born September 15, 1929) is an American physicist ..."
+
+image = BingSearch.image('Pauli').first
+image.media_type # => "image/jpeg"
+
+video = BingSearch.video('von Neumann').first
+video.duration # => 151000
+```
+
+See the documentation of the result types for a full list of the attributes.
+
+## Options
+
+The search methods take options that control the number of results returned;
+
+```ruby
+BingSearch.web('Dyson', limit: 5).count # => 5
+```
+
+the size, orientation, and contents of images;
+
+```ruby
+BingSearch.image 'Tesla', filters: [:large, :wide, :photo, :face]
+```
+
+whether to {BingSearch::HIGHLIGHT_DELIMITER highlight} query terms in the results;
+
+```ruby
+BingSearch.news('Hawking', highlighting: true).first.title # => "How Intel Gave Stephen Hawking a Voice"
+```
+
+and many other aspects of the search. Note that "enumeration" options—those whose values are module-level constants—may be provided as underscored symbols:
+
+```ruby
+# equivalent searches
+BingSearch.news 'Higgs', category: BingSearch::NewsCategory::ScienceAndTechnology
+BingSearch.news 'Higgs', category: :science_and_technology
+```
+
+See {BingSearch::Client} for exhaustive documentation of the options.
+
+## Composite Searches
+
+To retrieve multiple result types at once, use {BingSearch.composite}:
+
+```ruby
+result = BingSearch.composite('Majorana', [:web, :image, :news])
+```
+
+The result is a {BingSearch::CompositeResult} ...
+
+```ruby
+result.class # => BingSearch::CompositeResult
+```
+
+... containing an array for each result type:
+
+```ruby
+result.web.first.class # => BingSearch::WebResult
+result.image.first.class # => BingSearch::ImageResult
+result.news.first.class # => BingSearch::NewsResult
+```
+
+All of the single-type search options are supported in composite searches, though the names may have prefixes to specify the type they pertain to:
+
+```ruby
+BingSearch.composite 'Fermi', [:image, :video], image_filters: [:small], video_filters: [:short]
+```
+
+Composite searches also give you access more data about the search including the total number of results in the Bing index and whether Bing corrected apparent errors in the query text:
+
+```ruby
+result = BingSearch.composite('Feyman', [:web, :image, :news])
+result.web_total # => 2400000
+result.altered_query # => "feynman"
+```
+
+## Web-Only API
+
+To use the less expensive [web-only API](https://datamarket.azure.com/dataset/bing/searchweb), set {BingSearch.web_only}:
+
+```ruby
+BingSearch.web_only = true
+BingSearch.news 'Newton' # => BingSearch::ServiceError
+BingSearch.web 'Newton'
+```
+
+## BingSearch::Client
+
+{BingSearch::Client} is the class underlying the {BingSearch} class methods. You can use it on its own to run multiple searches over a single TCP connection:
+
+```ruby
+BingSearch::Client.open do |client|
+  client.web 'Lee'
+  client.web 'Wu'
+  client.web 'Yang' 
+end
+```
+
+Or to override global settings:
+
+```ruby
+client = BingSearch::Client.new(access_key: 'hzy9+Y6...', web_only: true)
+```
+
+## Tests
+
+To run the tests:
+
+1. Sign up for both the standard and web-only APIs
+2. Set the environment variable BING\_SEARCH\_ACCESS\_KEY to your Access Key
+3. `rake`
+
+## Contributing
+
+Please submit issues and pull requests to [jonahb/bing-search](http://github.com/jonahb/bing-search) on GitHub.
+

data/lib/bing-search.rb

@@ -0,0 +1,93 @@
+%w{
+  client
+  enums
+  errors
+  models
+  version
+}.each do |file|
+  require File.expand_path("../bing-search/#{file}", __FILE__)
+end
+
+module BingSearch
+
+  HIGHLIGHT_DELIMITER = "\u{e001}"
+
+  class << self
+    # An Access Key obtained from the Azure Marketplace. You can set this
+    # attribute once instead of instantiating each {Client} with an Access Key.
+    # @return [String]
+    attr_accessor :access_key
+
+    # Whether to use the less expensive web-only API
+    # @return [Boolean]
+    attr_accessor :web_only
+
+    # Convenience method that creates a {Client} and searches for web pages.
+    # Takes the same arguments as {Client#web}. Set {access_key} before calling.
+    # @return (see Client#web)
+    # @see Client#web
+    #
+    def web(*args)
+      Client.new.web *args
+    end
+
+    # Convenience method that creates a {Client} and searches for images. Takes
+    # the same arguments as {Client#image}. Set {access_key} before calling.
+    # @return (see Client#image)
+    # @see Client#image
+    #
+    def image(*args)
+      Client.new.image *args
+    end
+
+    # Convenience method that creates a {Client} and searches for videos. Takes
+    # the same arguments as {Client#video}. Set {access_key} before calling.
+    # @return (see Client#video)
+    # @see Client#video
+    #
+    def video(*args)
+      Client.new.video *args
+    end
+
+    # Convenience method that creates a {Client} and searches for news. Takes
+    # the same arguments as {Client#news}. Set {access_key} before calling.
+    # @return (see Client#news)
+    # @see Client#news
+    #
+    def news(*args)
+      Client.new.news *args
+    end
+
+    # Convenience method that creates a {Client} and searches for related
+    # queries. Takes the same arguments as {Client#related_search}. Set {access_key}
+    # before calling.
+    # @return (see Client#related_search)
+    # @see Client#related_search
+    #
+    def related_search(*args)
+      Client.new.related_search *args
+    end
+    alias_method :related, :related_search
+
+    # Convenience method that creates a {Client} and corrects spelling in the
+    # query text. Takes the same arguments as {Client#related_search}. Set
+    # {access_key} before calling.
+    # @return (see Client#spelling_suggestions)
+    # @see Client#spelling_suggestions
+    #
+    def spelling_suggestions(*args)
+      Client.new.spelling_suggestions *args
+    end
+    alias_method :spelling, :spelling_suggestions
+
+    # Convenience method that creates a {Client} and searches multiple sources
+    # Takes the same arguments as {Client#related_search}. Set {access_key} before
+    # calling.
+    # @return (see Client#composite)
+    # @see Client#composite
+    #
+    def composite(*args)
+      Client.new.composite *args
+    end
+  end
+end

data/lib/bing-search/client.rb

@@ -0,0 +1,614 @@
+require 'date'
+require 'json'
+require 'net/http'
+require 'uri'
+require 'active_support/core_ext/hash/slice'
+require 'active_support/core_ext/string/inflections'
+require_relative 'errors'
+require_relative 'models'
+require_relative 'enums'
+
+module BingSearch
+  class Client
+    # The Access Key obtained from the Azure Marketplace
+    # @return [String]
+    attr_reader :access_key
+
+    # Whether to use the less expensive web-only API
+    # @return [Boolean]
+    attr_reader :web_only
+
+
+    # @!group Constructors
+
+    # @param [String, nil] access_key
+    #   An Access Key obtained from the Azure Marketplace. If nil,
+    #   {BingSearch.access_key} is assumed.
+    # @param [Boolean, nil] web_only
+    #   Whether to use the less expensive web-only API. If nil,
+    #   {BingSearch.web_only} is assumed.
+    #
+    def initialize(access_key: nil, web_only: nil)
+      @access_key = access_key || BingSearch.access_key
+      @web_only = web_only.nil? ? BingSearch.web_only : web_only
+
+      unless @access_key
+        raise ArgumentError, "Pass an Access Key or set BingSearch.access_key"
+      end
+    end
+
+
+    # @!group Sessions
+
+    # Opens a client and yields it to the given block. Takes the same arguments
+    # as {#initialize}.
+    # @see #initialize
+    # @yieldparam [Client] client
+    # @return [Client]
+    # @see #open
+    #
+    def self.open(*args)
+      raise "Block required" unless block_given?
+      client = new(*args)
+      client.open { yield client }
+      client
+    end
+
+    # 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.
+    #
+    # @yield
+    #   If a block is given, the client is closed when the block returns.
+    # @return [Object, self]
+    #   If a block is given, the return value of the block; otherwise, +self+.
+    # @raise [StandardError]
+    #   The client is already open
+    #
+    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
+
+    # Closes the client. Must be called after {#open} is called without a
+    # block.
+    # @return [self]
+    # @see #open
+    #
+    def close
+      @session.finish if open?
+      @session = nil
+      self
+    end
+
+    # Whether the client is open
+    # @return [Boolean]
+    # @see #open
+    #
+    def open?
+      @session && @session.started?
+    end
+
+
+    # @!group Searching
+
+    # @!macro general
+    #   @param [String] query
+    #     The query text; supports the
+    #     {http://msdn.microsoft.com/en-us/library/ff795667.aspx Bing Query Language}
+    #   @param [Hash<Symbol => Object>] opts
+    #   @option opts [Integer] :limit
+    #     The maximum number of results to return
+    #   @option opts [Integer] :offset
+    #     The zero-based ordinal of the first result to return
+    #   @option opts [Adult, Symbol] :adult
+    #     The level of filtering of sexually explicit content. If omitted, Bing
+    #     uses the default level for the market.
+    #   @option opts [Float] :latitude
+    #     May range from -90 to 90
+    #   @option opts [Float] :longitude
+    #     May range from -180 to 180
+    #   @option opts [String] :market
+    #     A language tag specifying the market in which to search (e.g.
+    #     +en-US+). If omitted, Bing infers the market from IP address, etc.
+    #   @option opts [Boolean] :location_detection (true)
+    #     Whether to infer location from the query text
+    #   @raise [ServiceError]
+    #     The Bing Search service returned an error
+    #   @raise [StandardError]
+    #     Invalid argument, unable to parse Bing response, networking error,
+    #     and other error conditions
+    #   @see http://msdn.microsoft.com/en-us/library/ff795667.aspx Bing Query Language reference
+
+    # Searches for web pages
+    # @!macro general
+    # @option opts [FileType] :file_type
+    #   Type of file to return
+    # @option opts [Boolean] :highlighting (false)
+    #   Whether to surround query terms in {WebResult#description} with the
+    #   delimiter {BingSearch::HIGHLIGHT_DELIMITER}.
+    # @option opts [Boolean] :host_collapsing (true)
+    #   Whether to suppress results from the same 'top-level URL'
+    # @option opts [Boolean] :query_alterations (true)
+    #   Whether to alter the query in case of, e.g., supposed spelling errors
+    # @return [Array<WebResult>]
+    #
+    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
+
+    # Searches for images
+    # @!macro general
+    # @option opts [Integer] :minimum_height
+    #   In pixels; ANDed with other filters
+    # @option opts [Integer] :minimum_width
+    #   In pixels; ANDed with other filters
+    # @option opts [Array<ImageFilter>] :filters
+    #   Multiple filters are ANDed
+    # @return [Array<ImageResult>]
+    #
+    def image(query, opts = {})
+      invoke 'Image',
+        query,
+        opts,
+        param_name_replacements: {filters: 'ImageFilters'},
+        params: {filters: image_filters_from_opts(opts)}
+    end
+
+    # Searches for videos
+    # @!macro general
+    # @option opts [Array<VideoFilter>] :filters
+    #   Multiple filters are ANDed. At most one duration is allowed.
+    # @option opts [VideoSort] :sort
+    # @return [Array<VideoResult>]
+    #
+    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
+
+    # Searches for news
+    # @!macro general
+    # @option opts [Boolean] :highlighting (false)
+    #   Whether to surround query terms in {NewsResult#description} with the
+    #   delimiter {BingSearch::HIGHLIGHT_DELIMITER}.
+    # @option opts [NewsCategory] :category
+    #   Only applies in the en-US market. If no news matches the category, Bing
+    #   returns results from a mix of categories.
+    # @option opts [String] :location_override
+    #   Overrides Bing's location detection. Example: +US.WA+
+    # @option opts [NewsSort] :sort
+    # @return [Array<NewsResult>]
+    #
+    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
+
+    # Searches for related queries
+    # @!macro general
+    # @return [Array<RelatedSearchResult>]
+    #
+    def related_search(query, opts = {})
+      invoke 'RelatedSearch', query, opts
+    end
+    alias_method :related, :related_search
+
+    # Corrects spelling in the query text
+    # @!macro general
+    # @return [Array<SpellingSuggestionsResult>]
+    #
+    def spelling_suggestions(query, opts = {})
+      invoke 'SpellingSuggestions', query, opts
+    end
+    alias_method :spelling, :spelling_suggestions
+
+    # Searches multiple sources. At most 15 news results are returned by
+    # a composite query regardless of the +:limit+ option.
+    # @macro general
+    # @param [Array<Source>] sources
+    #   The sources to search
+    # @option opts [Boolean] :highlighting (false)
+    #   Whether to surround query terms in {NewsResult#description} and
+    #   {WebResult#description} with the delimiter {BingSearch::HIGHLIGHT_DELIMITER}.
+    # @option opts [FileType] :web_file_type
+    #   Type of file to return. Applies to {Source::Web}; also affects
+    #   {Source::Image} and {Source::Video} if {Source::Web} is specified.
+    # @option opts [Boolean] :web_host_collapsing (true)
+    #   Whether to suppress results from the same 'top-level URL.' Applies to {Source::Web}.
+    # @option opts [Boolean] :web_query_alterations (true)
+    #   Whether to alter the query in case of, e.g., supposed spelling errors. Applies to {Source::Web}.
+    # @option opts [Integer] :image_minimum_width
+    #   In pixels; ANDed with other filters. Applies to {Source::Image}.
+    # @option opts [Integer] :image_minimum_height
+    #   In pixels; ANDed with other image filters. Applies to {Source::Image}.
+    # @option opts [Array<ImageFilter>] :image_filters
+    #   Multiple filters are ANDed. Applies to {Source::Image}.
+    # @option opts [Array<VideoFilter>] :video_filters
+    #   Multiple filters are ANDed. At most one duration is allowed. Applies to {Source::Video}.
+    # @option opts [VideoSort] :video_sort
+    #   Applies to {Source::Video}
+    # @option opts [NewsCategory] :news_category
+    #   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}.
+    # @option opts [String] :news_location_override
+    #   Overrides Bing's location detection. Example: +US.WA+. Applies to {Source::News}.
+    # @option opts [NewsSort] :news_sort
+    #   Applies to {Source::News}.
+    #
+    # @return [CompositeSearchResult]
+    #
+    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
+
+    private
+
+    # @param [Hash] opts
+    # @param [#to_s] opt_prefix
+    # return [Array<String>]
+    #
+    def web_search_options_from_opts(opts = {}, opt_prefix = nil)
+      web_search_options = []
+      web_search_options << 'DisableHostCollapsing' if opts["#{opt_prefix}host_collapsing".to_sym] == false
+      web_search_options << 'DisableQueryAlterations' if opts["#{opt_prefix}query_alterations".to_sym] == false
+      web_search_options
+    end
+
+    # @param [Hash] opts
+    # @param [#to_s] opt_prefix
+    # @return [Array<String>]
+    #
+    def image_filters_from_opts(opts = {}, opt_prefix = nil)
+      filters = (opts["#{opt_prefix}filters".to_sym] || []).map { |filter| enum_value(filter, ImageFilter) }
+
+      height = opts["#{opt_prefix}minimum_height".to_sym]
+      width = opts["#{opt_prefix}minimum_width".to_sym]
+      filters << "Size:Width:#{width}" if width
+      filters << "Size:Height:#{height}" if height
+
+      filters
+    end
+
+    # @param [String] operation
+    #   The first segment of the invocation URI path (after the base path),
+    #   e.g. 'Web'
+    # @param [String] query
+    #   The query text
+    # @param [Hash<Symbol => Object>] opts
+    #   The options hash provided by the caller
+    # @param [Array<Symbol>] passthrough_opts
+    #   Keys of the options to copy to the params hash
+    # @param [Hash<Symbol => Module>] enum_opt_to_module
+    #   Maps an enum option key to the module containing the enum's values.
+    #   Used to translate symbols to enum values. E.g. maps +:web_file_type+
+    #   to {FileType}.
+    # @param [Hash<Symbol => Object>] params
+    #   Parameters for the invocation
+    # @return [Object]
+    # @raise [ServiceError]
+    # @raise [RuntimeError]
+    #
+    def invoke(operation, query, opts, passthrough_opts: [], enum_opt_to_module: {}, param_name_replacements: {}, params: {})
+      options = []
+      options << 'DisableLocationDetection' if opts[:location_detection] == false
+      options << 'EnableHighlighting' if opts[:highlighting]
+
+      # Works around an apparent bug where Bing treats offsets 0 and 1 the same
+      offset = opts[:offset] && opts[:offset] + 1
+
+      opts = opts.each_with_object(Hash.new) do |(key, value), hash|
+        module_ = GENERAL_ENUM_OPT_TO_MODULE[key] || enum_opt_to_module[key]
+        hash[key] = module_ ? enum_value(value, module_) : value
+      end
+
+      params = params.
+        merge(opts.slice(*GENERAL_PASSTHROUGH_OPTS, *passthrough_opts)).
+        merge(query: query, offset: offset, options: options, format: :JSON).
+        delete_if { |_, v| v.nil? || (v.is_a?(Array) && v.empty?) }
+
+      params = format_params(replace_param_names(params, param_name_replacements))
+      query = URI.encode_www_form(params)
+      base_path = web_only ? WEB_ONLY_BASE_PATH : BASE_PATH
+
+      response = in_session do |session|
+        request = Net::HTTP::Get.new("#{base_path}/#{operation}?#{query}")
+        request.basic_auth(access_key, access_key)
+        session.request request
+      end
+
+      unless response.is_a?(Net::HTTPOK)
+        raise ServiceError.new(response.code, response.body)
+      end
+
+      raw = JSON.parse(response.body)
+
+      unless raw['d'] && raw['d']['results']
+        raise "Unexpected response format"
+      end
+
+      parse raw['d']['results']
+    end
+
+    # @yield [Net::HTTP]
+    # @return [Net::HTTPResponse]
+    #
+    def in_session
+      if open?
+        yield @session
+      else
+        open { yield @session }
+      end
+    end
+
+    # @param [Object] value
+    # @param [Module] module_
+    # @return [Object]
+    #
+    def enum_value(value, module_)
+      case value
+      when Symbol
+        enum_from_symbol(value, module_)
+      when Array
+        value.collect { |element| enum_value(element, module_) }
+      else
+        value
+      end
+    end
+
+    # @param [Symbol] symbol
+    # @param [Module] module_
+    # @return [Object]
+    # @raise [ArgumentError]
+    #   The module does not contain a constant corresponing to the symbol
+    #
+    def enum_from_symbol(symbol, module_)
+      [symbol.to_s.camelcase, symbol.to_s.upcase].each do |const|
+        return module_.const_get(const) if module_.const_defined?(const)
+      end
+      raise ArgumentError, "#{module_} does not contain a constant corresponding to #{symbol}"
+    end
+
+    # @param [Hash<Symbol => Object>] params
+    # @return [Hash<String => Object]
+    #
+    def replace_param_names(params, replacements)
+      params.each_with_object(Hash.new) do |(key, value), hash|
+        key = replacements[key] || GENERAL_PARAM_NAME_REPLACEMENTS[key] || key.to_s.camelcase
+        hash[key] = value
+      end
+    end
+
+    # @param [Hash] params
+    # @return [Hash]
+    #
+    def format_params(params)
+      params.each_with_object(Hash.new) do |(key, value), hash|
+        hash[key] = format(value)
+      end
+    end
+
+    # @param [Object] value
+    # @return [String]
+    #
+    def format(value)
+      case value
+      when String then format_string(value)
+      when Array then format_array(value)
+      else value
+      end
+    end
+
+    # @param [String] string
+    # @return [String]
+    #
+    def format_string(string)
+      "'#{string}'"
+    end
+
+    # @param [Array] array
+    # @return [String]
+    #
+    def format_array(array)
+      "'#{array.join '+'}'"
+    end
+
+    # @param [Object] raw
+    # @param [Symbol, nil] type
+    # @return [Object]
+    #
+    def parse(raw, type = nil)
+      if type
+        parse_typed raw, type
+      elsif raw.is_a?(Array)
+        raw.collect { |element| parse element }
+      elsif raw_model?(raw)
+        parse_model raw
+      else
+        raw
+      end
+    end
+
+    # @param [Object] raw
+    # @param [Symbol] type
+    # @return [Object, nil]
+    # @raise [ArgumentError]
+    #
+    def parse_typed(raw, type)
+      case type
+      when :datetime
+        raw.empty? ? nil : DateTime.parse(raw)
+      when :integer
+        raw.empty? ? nil : Integer(raw)
+      else
+        raise ArgumentError, "Can't parse value #{raw} of type #{type}"
+      end
+    end
+
+    # @param [Object] raw
+    # @return [Model]
+    #
+    def parse_model(raw)
+      raw_type = raw['__metadata']['type']
+      model = model_class(raw_type).new
+      attr_to_type = RAW_MODEL_TYPE_TO_ATTR_TO_TYPE[raw_type] || {}
+
+      for key, value in raw
+        next if key == '__metadata'
+        attr = key.underscore.to_sym
+        model.set attr, parse(value, attr_to_type[attr])
+      end
+
+      model
+    end
+
+    # @param [Object] raw
+    # @return [Boolean]
+    #
+    def raw_model?(raw)
+      raw.is_a?(Hash) && raw['__metadata'] && raw['__metadata']['type']
+    end
+
+    # @param [String] raw_type
+    # @return [Class]
+    # @raise [ArgumentError]
+    #
+    def model_class(raw_type)
+      unless RAW_MODEL_TYPES.include?(raw_type)
+        raise ArgumentError, "Invalid model type: #{raw_type}"
+      end
+
+      case raw_type
+      when 'Bing.Thumbnail'
+        Image
+      when 'SpellResult'
+        SpellingSuggestionsResult
+      when 'ExpandableSearchResult'
+        CompositeSearchResult
+      else
+        BingSearch.const_get(raw_type)
+      end
+    end
+
+
+    HOST = 'api.datamarket.azure.com'
+    private_constant :HOST
+
+    BASE_PATH = '/Bing/Search'
+    private_constant :BASE_PATH
+
+    WEB_ONLY_BASE_PATH = '/Bing/SearchWeb'
+    private_constant :WEB_ONLY_BASE_PATH
+
+    GENERAL_PASSTHROUGH_OPTS = %i(limit adult latitude longitude market)
+    private_constant :GENERAL_PASSTHROUGH_OPTS
+
+    GENERAL_ENUM_OPT_TO_MODULE = {adult: Adult}
+    private_constant :GENERAL_ENUM_OPT_TO_MODULE
+
+    GENERAL_PARAM_NAME_REPLACEMENTS = {
+      limit: '$top',
+      offset: '$skip',
+      format: '$format',
+    }
+    private_constant :GENERAL_PARAM_NAME_REPLACEMENTS
+
+    RAW_MODEL_TYPES = %w{
+      WebResult
+      ImageResult
+      VideoResult
+      NewsResult
+      RelatedSearchResult
+      SpellResult
+      ExpandableSearchResult
+      Bing.Thumbnail
+    }
+    private_constant :RAW_MODEL_TYPES
+
+    RAW_MODEL_TYPE_TO_ATTR_TO_TYPE = {
+      'ImageResult' => {
+        width: :integer,
+        height: :integer
+      },
+      'NewsResult' => {
+        date: :datetime
+      },
+      'VideoResult' => {
+        run_time: :integer
+      },
+      'ExpandableSearchResult' => {
+        web_total: :integer,
+        web_offset: :integer,
+        image_total: :integer,
+        image_offset: :integer,
+        video_total: :integer,
+        video_offset: :integer,
+        news_total: :integer,
+        news_offset: :integer,
+        spelling_suggestions_total: :integer
+      }
+    }
+    private_constant :RAW_MODEL_TYPE_TO_ATTR_TO_TYPE
+
+  end
+end

data/lib/bing-search/enums.rb

@@ -0,0 +1,78 @@
+module BingSearch
+  module Adult
+    Off = 'Off'
+    Moderate = 'Moderate'
+    Strict = 'Strict'
+  end
+
+  module FileType
+    DOC = 'DOC'
+    DWF = 'DWF'
+    FEED = 'FEED'
+    HTM = 'HTM'
+    HTML = 'HTML'
+    PDF = 'PDF'
+    PPT = 'PPT'
+    RTF = 'RTF'
+    TEXT = 'TEXT'
+    TXT = 'TXT'
+    XLS = 'XLS'
+  end
+
+  module ImageFilter
+    Small = 'Size:Small'
+    Medium = 'Size:Medium'
+    Large = 'Size:Large'
+    Square = 'Aspect:Square'
+    Wide = 'Aspect:Wide'
+    Tall = 'Aspect:Tall'
+    Color = 'Color:Color'
+    Monochrome = 'Color:Monochrome'
+    Photo = 'Style:Photo'
+    Graphics = 'Style:Graphics'
+    Face = 'Face:Face'
+    Portrait = 'Face:Portrait'
+    OtherFace = 'Face:Other'
+  end
+
+  module NewsCategory
+    Business = 'rt_Business'
+    Entertainment = 'rt_Entertainment'
+    Health = 'rt_Health'
+    Politics = 'rt_Politics'
+    Sports = 'rt_Sports'
+    US = 'rt_US'
+    World = 'rt_World'
+    ScienceAndTechnology = 'rt_ScienceAndTechnology'
+  end
+
+  module NewsSort
+    Date = 'Date'
+    Relevance = 'Relevance'
+  end
+
+  module Source
+    Web = 'Web'
+    Image = 'Image'
+    Video = 'Video'
+    News = 'News'
+    SpellingSuggestions = 'Spell'
+    RelatedSearch = 'RelatedSearch'
+  end
+
+  module VideoFilter
+    Short = 'Duration:Short'
+    Medium = 'Duration:Medium'
+    Long = 'Duration:Long'
+    StandardAspect = 'Aspect:Standard'
+    Widescreen = 'Aspect:Widescreen'
+    LowResolution = 'Resolution:Low'
+    MediumResolution = 'Resolution:Medium'
+    HighResolution = 'Resolution:High'
+  end
+
+  module VideoSort
+    Date = 'Date'
+    Relevance = 'Relevance'
+  end
+end

data/lib/bing-search/errors.rb

@@ -0,0 +1,23 @@
+module BingSearch
+
+  class ServiceError < StandardError
+    # The error code returned by Bing
+    # @return [String]
+    attr_reader :code
+
+    # @param [String] code
+    #   The error code returned by Bing
+    # @param [String] message
+    #
+    def initialize(code, message = nil)
+      super(message)
+      @code = code
+    end
+
+    # @return [String]
+    #
+    def to_s
+      "Bing error #{code}: #{super}"
+    end
+  end
+end

data/lib/bing-search/models.rb

@@ -0,0 +1,255 @@
+module BingSearch
+
+  class Model
+    # @param [Hash] attrs
+    def initialize(attrs = {})
+      attrs.each do |k, v|
+        public_send "#{k}=", v
+      end
+    end
+
+    # Sets an attribute via a public instance method on the receiver or its
+    # ancestors up to but not including Object
+    # @param [Symbol] attr
+    # @param value
+    # @return [self]
+    # @raise [ArgumentError]
+    #   No public setter for +attr+ on the receiver or its ancestors up to
+    #   Object
+    #
+    def set(attr, value)
+      setter = "#{attr}=".to_sym
+
+      self.class.attr_methods.include?(setter) ?
+        public_send(setter, value) :
+        raise(ArgumentError, "Can't set attr #{attr} of #{self}")
+    end
+
+    private
+
+    def self.attr_methods
+      @attr_methods ||= model_ancestors.reduce([]) do |memo, class_|
+        memo + class_.public_instance_methods(false)
+      end
+    end
+
+    def self.model_ancestors
+      ancestors.select { |ancestor| ancestor < Model }
+    end
+  end
+
+  class Result < Model
+    # @return [String]
+    #   A universally unique identifier (UUID)
+    attr_accessor :id
+  end
+
+  class WebResult < Result
+    # @return [String]
+    attr_accessor :title
+
+    # The summary displayed below the title in bing.com search results
+    # @return [String]
+    attr_accessor :description
+    alias_method :summary, :description
+
+    # URL to display to the user. Omits the scheme if HTTP.
+    # @return [String]
+    attr_accessor :display_url
+
+    # Full URL of the result, including the scheme.
+    # @return [String]
+    attr_accessor :url
+  end
+
+  class ImageResult < Result
+    # @return [String]
+    attr_accessor :title
+
+    # URL of the image
+    # @return [String]
+    attr_accessor :media_url
+    alias_method :url, :media_url
+
+    # URL of the website that contains the image
+    # @return [String]
+    attr_accessor :source_url
+
+    # URL to display to the user. Omits the scheme if HTTP.
+    # @return [String]
+    attr_accessor :display_url
+
+    # In pixels, if available
+    # @return [Integer, nil]
+    attr_accessor :width
+
+    # In pixels, if available
+    # @return [Integer, nil]
+    attr_accessor :height
+
+    # In bytes, if available
+    # @return [Integer, nil]
+    attr_accessor :file_size
+
+    # {http://en.wikipedia.org/wiki/Internet_media_type Internet media type} (MIME type) of the image, if available
+    # @return [String]
+    attr_accessor :content_type
+    alias_method :media_type, :content_type
+
+    # @return [Image]
+    attr_accessor :thumbnail
+  end
+
+  class VideoResult < Result
+    # @return [String]
+    attr_accessor :title
+
+    # URL of the video, often a web page containing the video
+    # @return [String]
+    attr_accessor :media_url
+    alias_method :url, :media_url
+
+    # URL of a Bing page that displays the video
+    # @return [String]
+    attr_accessor :display_url
+
+    # Duration of the video in milliseconds, if available
+    # @return [Integer, nil]
+    attr_accessor :run_time
+    alias_method :duration, :run_time
+
+    # @return [Image]
+    attr_accessor :thumbnail
+  end
+
+  class NewsResult < Result
+    # @return [String]
+    attr_accessor :title
+    alias_method :headline, :title
+
+    # URL of the article
+    # @return [String]
+    attr_accessor :url
+
+    # Organization responsible for the article
+    # @return [String]
+    attr_accessor :source
+
+    # Sample of the article
+    # @return [String]
+    attr_accessor :description
+
+    # Date on which the article was indexed
+    # @return [Date]
+    attr_accessor :date
+  end
+
+  class RelatedSearchResult < Result
+    # The query text of the related search
+    # @return [String]
+    attr_accessor :title
+    alias_method :query, :title
+
+    # The URL of the Bing results page for the related search
+    # @return [String]
+    attr_accessor :bing_url
+  end
+
+  class SpellingSuggestionsResult < Result
+    # The suggested spelling
+    # @return [String]
+    attr_accessor :value
+    alias_method :suggestion, :value
+  end
+
+  class CompositeSearchResult < Result
+    # @!group Instance Attributes for Results
+
+    # @return [Array<WebResult>]
+    attr_accessor :web
+
+    # @return [Array<ImageResult>]
+    attr_accessor :image
+
+    # @return [Array<VideoResult>]
+    attr_accessor :video
+
+    # @return [Array<NewsResult>]
+    attr_accessor :news
+
+    # @return [Array<RelatedSearchResult>]
+    attr_accessor :related_search
+
+    # @return [Array<SpellingSuggestionsResult>]
+    attr_accessor :spelling_suggestions
+
+    # @!endgroup
+
+    # The number of web results in the Bing index
+    # @return [Integer, nil]
+    attr_accessor :web_total
+
+    # The ordinal of the first web result
+    # @return [Integer, nil]
+    attr_accessor :web_offset
+
+    # The number of image results in the Bing index
+    # @return [Integer, nil]
+    attr_accessor :image_total
+
+    # The ordinal of the first image result
+    # @return [Integer, nil]
+    attr_accessor :image_offset
+
+    # The number of video results in the Bing index
+    # @return [Integer, nil]
+    attr_accessor :video_total
+
+    # The ordinal of the first video result
+    # @return [Integer, nil]
+    attr_accessor :video_offset
+
+    # The number of news results in the Bing index
+    # @return [Integer, nil]
+    attr_accessor :news_total
+
+    # The ordinal of the first news result
+    # @return [Integer, nil]
+    attr_accessor :news_offset
+
+    # The number of spelling suggestions in the Bing index
+    # @return [Integer, nil]
+    attr_accessor :spelling_suggestions_total
+
+    # The query text after spelling errors have been corrected
+    # @return [String]
+    attr_accessor :altered_query
+
+    # Query text that forces the original query, preventing any alterations in {#altered_query}
+    # @return [String]
+    attr_accessor :alteration_override_query
+  end
+
+  class Image < Model
+    # URL of the image
+    # @return [String]
+    attr_accessor :media_url
+    alias_method :url, :media_url
+
+    # {http://en.wikipedia.org/wiki/Internet_media_type Internet media type} (MIME type) of the image, if available
+    # @return [String]
+    attr_accessor :content_type
+
+    # In pixels, if available
+    # @return [Integer, nil]
+    attr_accessor :width
+
+    # In pixels, if available
+    # @return [Integer, nil]
+    attr_accessor :height
+
+    # In bytes, if available
+    # @return [Integer, nil]
+    attr_accessor :file_size
+  end
+end

data/lib/bing-search/version.rb

@@ -0,0 +1,3 @@
+module BingSearch
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: bing-search
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jonah Burke
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+description: 
+email:
+- jonah@jonahb.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/bing-search.rb
+- lib/bing-search/client.rb
+- lib/bing-search/enums.rb
+- lib/bing-search/errors.rb
+- lib/bing-search/models.rb
+- lib/bing-search/version.rb
+homepage: http://github.com/jonahb/bing-search
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A Ruby client for the Bing Search API
+test_files: []
+has_rdoc: