API:Opensearch

From MediaWiki.org
Jump to: navigation, search
Language: English  • 日本語 • polski
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page

MediaWiki action API

v · d · e


This API is provided by MediaWiki core starting with MediaWiki version 1.25 (gerrit:171573). Prior to MediaWiki 1.25, you needed to install the OpenSearch extension.

Page name searches are case-sensitive. If $wgCapitalLinks is true (this is the default), the first letter is case-insensitive. If the TitleKey extension is enabled, page name searches are entirely case-insensitive.

Parameters[edit]

  • search: Search string.
  • namespace: Namespaces to search. (Default: 0)
  • limit: Maximum number of results to return. (Note: prior to MW 1.28, this value was capped at 100, regardless of user permissions.) No more than 500 (5000 for bots) allowed. (Default: 10)
  • profile: Search profile to use. Possible values: strict, normal, fuzzy, classic. (Default: fuzzy) 1.28+
    • strict: Strict profile with few punctuation characters removed but diacritics and stress marks are kept.
    • normal: Few punctuation characters, some diacritics and stopwords removed.
    • fuzzy: Similar to normal with typo correction (two typos supported).
    • classic: Classic prefix, few punctuation characters and some diacritics removed.
  • suggest: Do nothing if $wgEnableOpenSearchSuggest is false.
  • redirects: How to handle redirects. Possible values: return, resolve. (Default: return when format=json/jsonfm; resolve otherwise.)
    • return: Return the redirect itself.
    • resolve: Return the target page. May return fewer than limit results.
  • format: The format of the output. Possible values: json, jsonfm, xml, xmlfm. (Default: json)
  • warningsaserror: If warnings are raised with format=json, return an API error instead of ignoring them.

Examples[edit]

The opensearch API module handles formats differently. It only recognizes XML and JSON (and their *fm formatted versions); every other valid format parameter results in JSON. The JSON format returns an array containing the search query and an array of result titles.

Example of API response in jsonfm format

If the wiki loads the OpenSearchXml extension or is running MediaWiki version 1.25 or greater, which merged this extension into core, then the XML format returns an OpenSearch XML document with titles and URLs. Furthermore:

  • If the wiki loads the TextExtracts extension and configures $wgExtractsExtendOpenSearchXml true, then each Item in the XML format may include a <Description> tag with a text extract from the article.
  • Likewise, if the wiki loads the PageImages extension and configures $wgPageImagesExpandOpenSearchXml true, then each Item in the XML format may include an <Image> tag with a thumbnail image from the article.

Example API response in xmlfm format

action=opensearch

(main | opensearch)
  • This module requires read rights.
  • Source: MediaWiki
  • License: GPL-2.0+

Search the wiki using the OpenSearch protocol.

Parameters:
search

Search string.

This parameter is required.
namespace

Namespaces to search.

Values (separate with | or alternative): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 90, 91, 92, 93, 100, 101, 102, 103, 104, 105, 106, 107, 486, 487, 828, 829, 1198, 1199, 2300, 2301, 2302, 2303, 2600
To specify all values, use *.
Default: 0
limit

Maximum number of results to return.

No more than 500 (5,000 for bots) allowed.
Type: integer or max
Default: 10
profile

Search profile to use.

strict
Strict profile with few punctuation characters removed but diacritics and stress marks are kept.
normal
Few punctuation characters, some diacritics and stopwords removed.
normal-subphrases
Few punctuation characters, some diacritics and stopwords removed. It will match also subphrases (can be subphrases or subpages depending on internal wiki configuration).
fuzzy
Similar to normal with typo correction (two typos supported).
fuzzy-subphrases
Similar to normal with typo correction (two typos supported). It will match also subphrases (can be subphrases or subpages depending on internal wiki configuration).
classic
Classic prefix, few punctuation characters and some diacritics removed.
One of the following values: strict, normal, normal-subphrases, fuzzy, fuzzy-subphrases, classic
Default: fuzzy
suggest

Do nothing if $wgEnableOpenSearchSuggest is false.

Type: boolean (details)
redirects

How to handle redirects:

return
Return the redirect itself.
resolve
Return the target page. May return fewer than limit results.

For historical reasons, the default is "return" for format=json and "resolve" for other formats.

One of the following values: return, resolve
format

The format of the output.

One of the following values: json, jsonfm, xml, xmlfm
Default: json
warningsaserror

If warnings are raised with format=json, return an API error instead of ignoring them.

Type: boolean (details)
Example:
Find pages beginning with Te.
api.php?action=opensearch&search=Te [open in sandbox]

See also[edit]