YANAPI

DESCRIPTION

YANAPI is an API for Yahoo! Answers web services. It has been developed in Ruby.

YANAPI provides a flexible interface to the Yahoo! Answers search services. As of this writing it is the most complete library for accessing Yahoo! Answers compared to other libraries on RubyGems.

It supports four search types:

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:

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 and the RDoc documentation in this library.

Exception Hierarchy

While using YANAPI you can face three kinds of errors:

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.