SAGOOLトップ

SAGOOLについて

WEB API NEW!
   ・SAGOOL AJAX API
   ・SAGOOL API
   ・WACAAL API
   ・ガイドライン

ヘルプ

利用規約

プライバシーポリシー

人材募集

お問い合わせ

SAGOOL 検索 API

 

SAGOOL APIを利用してアプリケーションを開発

好きな開発言語から、SAGOOL APIを利用して、オモロ検索エンジンSAGOOLの検索結果を利用することができます。

SAGOOL APIは OpenSearch 1.0 規格に基づいて利用できます。OpenSearch は RSS2.0 を拡張したXML形式で検索結果を返します。SAGOOL APIは OpenSearch に対応しているので、OpenSearch が提案しているインタフェースでその操作を行うことができます。

SAGOOL APIの OpenSearch Description Document は http://sagool.jp/openapi より取得することができます。

SAGOOL API では OpenSearch で規定されているパラメータ以外のパラメータも利用できます。

SAGOOL APIご利用の際には、次の点にご注意ください。
  1. SAGOOL APIはベータバージョンです。利用状況により、サービスの仕様変更、あるいはサービスを停止する可能性があります。
  2. SAGOOL APIの利用状況把握のため、クエリパラメータにSAGOOL API を利用するWEBアプリケーションのURLを指定してください。
  3. SAGOOL APIを利用するアプリケーションは、見やすい位置に「SAGOOL」へのリンクとロゴを表示してください。詳細はこちらをご覧ください。
  4. SAGOOL APIの利用はリクエスト元のIP毎に制限が設けられています。現状では 1IP あたり 24時間に 5千回が上限となっています。

利用のガイドライン

 
ガイドラインに同意いただけない場合は、SAGOOL APIを使用するライセンスは許諾されません。

API利用のガイドライン

URLの構築

 
SAGOOL API は、次のパスにGETリクエストを投げ、XMLを取得します。

http://sagool.jp/openapi?

このあとには、実際のクエリーパラメータが続きます。パラメータは「引数=値」の形式をとります。引数と値はURLエンコードします。複数パラメータは'&'で区切ります。

■パラメータ解説
パラメータ名形式説明デフォルト
query文字列検索クエリです。150文字以内の文字列を指定します。UTF-8をURLエンコードしてください。詳しくはSAGOOLのヘルプをご確認ください。なし
start数値 0～100結果を返すときの最初の位置を返します。0から始まります（1を指定すると最初の結果を得ることができません）0
engineweb,movie「オモロ検索(web)」か「動画をSAGOOL(movie)」かを指定します。
また、動画検索のAPIはサグールテレビのAPIもご利用になることができます。 APIのご利用方法についてはこちらをご覧ください。		web
langja,all「日本語のみから検索(ja)」か「日本語以外からも検索(all)」かを指定します。ja
hitsPerPage数値 1～20一度の検索で返す結果数の最大値を指定します。10
clientUrlURL文字列SAGOOL API を利用するWEBアプリケーションのURLを指定します。UTF-8をURLエンコードしてください。必ず指定してください。WEBアプリケーション以外（ウェジット等）の場合は、配布ページのURLを指定します。WEB上に配布ページがない場合は個別に相談してください。なし
user文字列 (200文字以内)実際に検索を行ったユーザーを識別する文字列を入れてください。ユーザーIDやセッションID、IPとUSER-AGENT、などのMD5ハッシュ値など。なし
query が未指定の場合、OpenSearch Description Documentを返します。

clientUrl が未指定の場合はエラーを返します。clientUrlは他のAPIにおけるAPI-KEYのようなものとお考えください。弊社でAPIの利用状況を把握し、サービス改善の指針とするために使用します。API利用者が事前に申請する必要はありません。利用状況によっては一部の形式のURLが利用できなくなる可能性があります。

以下は 'enjoy' という語をウェブから検索する場合の例です。

http://sagool.jp/openapi?query=enjoy&clientUrl=http%3A%2F%2Fsagool.jp%2F&user=3835006176c32c20570684f5a851cf8b

レスポンス

 
SAGOOL API は、正常なリクエストに対して、OpenSearch1.0 に基づき次のようなXMLを返します。
■XMLタグ解説    
フィールドデータタイプ説明
rss 全体を囲むタグです
   channel文字列 
      title文字列全体のタイトル
      description文字列全体の解説
      linkURLSAGOOLへのリンク
      opensearch:totalResults数値クエリに対する全体の検索結果件数（注１）
      opensearch:startIndex数値実際に返す検索結果の最初の表示順位（一番目が0）
      opensearch:itemParPage数値実際に返す検索結果のitem数
      item 検索結果一件につき一つのItemタグで囲まれます
         titleHTMLエンコードされた文字列対象ページのタイトルを、検索クエリに一致した部分を太字にしたもの
         descriptionHTMLエンコードされた文字列対象ページ内の検索クエリに一致した部分を太字にしたもの
         linkURL対象ページのURL
         enclosure動画等が見つかった場合に追加されます。
URL属性に動画等のURLが記述されています。length、mime等は設定されていません。

opensearch:totalResults は more の値にかかわらず SAGOOL全体のヒットした結果数を返します。more=0 のクエリでは、同一ドメインにつき 2件までしか結果として返しませんので、totalResults の件数と実際に返せるアイテム数がずれる可能性があります。「次のページ」ボタンの実装を確実にしたい場合は、「取得する結果」を、実際に取得する数より一つ多く（たとえば1ページに10件表示する場合は11件を）取得し、11件目が存在するか否かで「次へ」ボタンの表示／非表示を決定する、等の工夫をする必要があります。

HTMLエンコードされた文字列 は、 & などは &amp; に、され、「太字」部分は<b>タグで囲まれています。プレーンテキストとしてXMLを見た場合、item/titel 要素等の中では、&は &amp;amp; と２重にHTMLエンコードされているように見えます。

エラーについて

 
SAGOOL APIでは次の場合にHTTPヘッダでエラーを返します。

HTTPコード説明
400clientUrl が不正、あるいは制限された clientUrl の場合
403利用制限を超えた使用の場合

動画検索について

 
動画検索では、 サグールテレビのAPIもご利用になることができます。
APIのご利用方法についてはこちらをご覧ください。

お問い合わせ

 

WEB APIに対する要望や質問は、SAGOOL 運営事務局にお寄せください。

SAGOOLのAPIを利用することによって、ガイドラインの内容に同意いただいたものとみなします。本ガイドラインに同意いただけない場合は、SAGOOLのAPIを使用するライセンスは許諾されません。