yanapi

= YANAPI

• {RubyGems}[http://rubygems.org/gems/yanapi]
• {Bug Tracker}[https://github.com/arbox/yanapi/issues]
• {YANAPI Project Page}[http://yanapi.rubyforge.org/]
• Developers {Homepage}[http://www.bu.chsta.be]

== DESCRIPTION

YANAPI is an API for Yahoo! Answers web services. It has been developed in {Ruby}[http://www.ruby-lang.org].

YANAPI provides a flexible interface to the {Yahoo! Answers}[http://answers.yahoo.com/] search services. As for this writing it is the most complete library for accessing {Yahoo! Answers}[http://answers.yahoo.com/] compared to other libraries on {RubyGems}[http://rubygems.org/].

It supports four search types:

• {key word search}[http://developer.yahoo.com/answers/V1/questionSearch.html];
• {search based on the category name or the category ID }[http://developer.yahoo.com/answers/V1/getByCategory.html];
• {search for a precise question ID }[http://developer.yahoo.com/answers/V1/getQuestion.html];
• {search for a questions posted by a user with an ID }[http://developer.yahoo.com/answers/V1/getByUser.html].

See CHANGELOG for features which are planned for future releases.

It is possible to restrict key word based search through a category.

Question Search and User Search cannot be extended by key words or category IDs.

YANAPI tries to be as flexible as possible. It restricts unallowed parameter combinations and forces using mandatory ones. But it doesn't care about defaults. For example, as for this writing the default output value is an xml based format. If it changes in the future, the user will be responsible to choose the format. No defaults are hardcoded in YANAPI.

YANAPI provides the minimal acceptable query.

== INSTALLATION To install YANAPI ussue the following command: $ gem install yanapi

You might want to install versions prior to +0.3.1+, if you are bound on the old one dimensional parameter hash: $ gem install yanapi -v 0.1.1

If you want to do a system wide installation, do this as root (possibly using +sudo+).

Alternatively use your Gemfile for dependency management. == SYNOPSIS

YANAPI requires a parameter hash with two dimensions:

• the key +:method+ points to one of possible search methods ('questionSearch', 'getByCategory', 'getByUser', 'getQuestion');
• the key +:query_params+ points to a parameter hash, the names of the parameters and their values correspond to the semantics given on {the official page}[http://developer.yahoo.com/answers/];
• values in +:query_params+ may be +String+, +Fixnum+ or +Array+, the latter provides the opportunity for multiple values which is possible and sometimes reasonable for such keys as +:region+, +:category_id+ or +:category_name+.

A small example shall demostrate the usage: require 'yanapi' params = { :method => 'questionSearch', :query_params => { :appid => 'YahooDemo', :query => 'Haus', :search_in => 'question', :type => 'resolved', :results => 2, :output => 'xml', :region => ['us', 'de'] } } api = YANAPI::API.new(params) api.get # => String

For details on particular keys and defaults see {the official description}[http://developer.yahoo.com/answers/] and the RDoc documentation in this library.

=== Exception Hierarchy While using YANAPI you can face three kinds of errors:

• YANAPI::UserError;
• YANAPI::ExternalError;
• YANAPI::ContentError.

The errors here are presented in the order they may occur during YANAPI's work.

First YANAPI checks the user input and throws a YANAPI::UserError.

Then it fetches a response from a remote server, it can result in a YANAPI::ExternalError.

If the response contains no 200 OK code or the response body cannot be parsed, the library throws a YANAPI::ContentError.

See the RDoc documentation on semantics of these errors.

All of them are subcalsses of YANAPI::Error which is in turn a subclass of the standard +RuntimeError+.

If you want to intercept any and every exception thrown by YANAPI simply rescue YANAPI::Error.

=== Parameter Semantics YANAPI accepts following keys and values (given default values if appropriate): { :query_params => { :appid => 'YahooDemo', # It is required, register your own ID. :callback => 'str', # Only in combination with <:output => 'json'>. :category_id => '123456', # See below. :category_name => 'Wohnen', # See below. :date_range => 'all', # '7'|'7-30'|'30-60'|'60-90'|'more90' :filter => 'question', # 'best_answer' :output => 'xml', # 'json'|'php'|'rss' :query => 'Haus AND Grund', :question_id => '123456', :region => 'us', # 'de'|'uk'|'ca'|'au'|'in'|'es'|'br'| # 'ar'|'mx'|'e1'|'it'|'fr'|'sg' :results => 10, # 0..50 (0 returns the default value) :search_in => "all", # "question" | "best_answer" :sort => 'relevance', # 'date_desc'| 'date_asc' :start => 0, # Now <= 1000, otherwise you'll get an empty response. :type => 'all', # 'resolved'|'open'|'undecided' :user_id => '123456' }, :method => 'questionSearch', # 'getByUser'|'getByCategory'|'getQuestion' }

== SEARCH STRATEGIES This section will describe possible applications of YANAPI.

=== Boolean Search

== CHANGELOG See CHANGELOG.

== CAUTION This library is work in process! Though the interface is mostly complete, you might face some not implemented features.

Please contact me with your suggestions, bug reports and feature requests.

== LICENSE

YANAPI is a copyrighted software by Andrei Beliankou, 2011.

You may use, redistribute and change it under the terms provided in the LICENSE file.