簡介

OpenSearch 是一種以 XML 方式定義搜索的方法，網站依據此規範實作可與其他程式介接等用途。

完整的規範可以在此網站查到，本文以表格的方式整理說明。

命名空間

OpenSearch 1.1 版命名空間為 http://a9.com/-/spec/opensearch/1.1/，目前為 Draft

MIME Type

MIME Type(Content Type 或稱為 Media Type) 為 application/opensearchdescription+xml

結構與定義

<OpenSearchDescription>

<OpenSearchDescription> 為 OpenSearch 的 XML 起始根節點，<OpenSearchDescription> 之中定義了以下 Element

Element必要多筆資料型態說明
<ShortName>OX純文字簡短標題，不可超過 16 個字元
<Description>OX純文字描述，不可超過 1024 個字元
<Url>OO<Url>描述搜索介面或連結
<Contact>XXemail提供者的電子郵件
<Tags>XX純文字搜索內容的關鍵字或分類，使用空白隔開，不可超過 256 個字元
<LongName>XX純文字標題，不可超過 48 個字元
<Image>XO<Image>圖示，應該包含一個 16x16 的 image/x-icon 或 image/vnd.microsoft.icon，以及一個 64x64 的 image/jpeg 或 image/png
<Query>XO<Query>提供一些查詢的資訊，應該包含一個 role=”example”
<Developer>XX純文字文件建立者，不可超過 64 個字元
<Attribution>XX純文字內容擁有者，不可超過 256 個字元
<SyndicationRight>XX純文字定義搜索的權限，只能是以下四種，預設為 open
  • open: 全部允許 (允許搜索，顯示結果給使用者，傳送結果到其他位置)
  • limited: 允許搜索，顯示結果給使用者
  • private: 只允許搜索
  • close: 全部不允許
<AdultContent>XX純文字是否包含成人內容，只有 false、FALSE、0、no 和 NO 的值視為 FALSE，其他視為 TRUE，預設為 false
<Language>XO純文字支援的語系，必須是 RFC5646 或者 * 表示不限制，應該包含一個，預設為 *
<InputEncoding>XO純文字搜索引擎支援的查詢文字之編碼，須符合 XML 1.0 Character Encodings 和 IANA Character Set Assignments 規範，應該包含一個，預設為 UTF-8
<OutputEncoding>XO純文字搜索引擎支援的搜索結果之編碼，須符合 XML 1.0 Character Encodings 和 IANA Character Set Assignments 規範，應該包含一個，預設為 UTF-8

<Url>

<Url> 為描述搜索介面或連結，<Url> 之中定義了以下屬性

Attribute必要說明
templateOURL 樣板，依據 OpenSearch URL template syntax 規則處理
typeOMIME Type
relX資源的關連，可以是以下值：
  • result: 搜索結果 (預設)
  • suggestions: 建議的搜索
  • self: 目前的文件
  • collection: 一些資源
除了上面四種值之外，也可以是 URL；可同時給多個值，使用空白隔開。
indexOffsetX第一筆搜索結果的索引值，預設為 1
pageOffsetX搜索結果的頁數索引值，預設為 1

Element內容為空

<Image>

<Image> 為搜索引擎的圖示，<Image> 之中定義了以下屬性

Attribute必要說明
heightX高度像素
widthX寬度像素
typeXMIME Type

Element內容為空

<Query>

<Query> 為查詢相關的資訊，<Query> 之中定義了以下屬性

Attribute必要說明
roleO表示此 Query 的意義，可以是以下值：
  • request: 目前的查詢
  • example: 範例的查詢
  • related: 相關的查詢
  • correction: 輸入錯誤時，可能更正的查詢
  • subset: 縮小範圍的查詢
  • superset: 擴大範圍的查詢
titleX標題，不可超過 256 個字元
totalResultsX查詢預計的結果筆數
searchTermsX搜索的關鍵字，必須要 URL Encode
countX每頁筆數
startIndexX第一筆搜索結果的索引值，預設為 1
startPageX搜索結果的頁數索引值，預設為 1
languageX支援的語系，必須是 RFC5646 或者 * 表示不限制，應該包含一個，預設為 *
inputEncodingX搜索引擎支援的查詢文字之編碼，須符合 XML 1.0 Character Encodings 和 IANA Character Set Assignments 規範，應該包含一個，預設為 UTF-8
outputEncodingX搜索引擎支援的搜索結果之編碼，須符合 XML 1.0 Character Encodings 和 IANA Character Set Assignments 規範，應該包含一個，預設為 UTF-8

Element內容為空。Query可引用其他命名空間，增加自訂的屬性。

搜索回覆

查詢結果輸出格式為 XML 時 (例如 RSS 或 Atom)，可以使用 OpenSearch 命名空間，包含以下 Element

Element必要多筆資料型態說明
<totalResults>XXInt查詢預計的結果筆數
<startIndex>XXInt第一筆搜索結果的索引值，預設為 1
<itemPerPage>XXInt每頁筆數
<Query>XO<Query>提供一些查詢的資訊，應該包含一個 role=”example”

OpenSearch URL template syntax

URL 樣板語法和 <Query> 有些相關，利用這個範例來解說

1
<Url type="application/rss+xml" xmlns:b="http://example.com/extensions/" template="http://example.com?q={searchTerms}&amp;p={startPage?}&amp;d={b:datetime?}"/>

規則簡易整理如下：

  1. 參數使用大括弧表示。
  2. 必填參數結尾不包含問號，如上例之 {searchTerms}。
  3. 選填參數結尾包含問號，如上例之 {startPage?}。
  4. 可用參數預設有 {searchTerms}、{count}、{startIndex}、{startPage}、{language}、{inputEncoding} 和 {outputEncoding}，其意義與 <Query> 一致。
  5. 可使用其他命名空間，增加自訂屬性，如上例之 {b:datetime}。