API:Opensearch

From MediaWiki.org
Jump to: navigation, search
Language:Project:Language policy English  • 日本語 • polski
This page is part of the MediaWiki action API documentation.


MediaWiki action API

v · d · e
Opensearch
Get pages whose name matches a given string. When limit is reached, results are ordered by number of incoming links.
This module cannot be used as a GeneratorAPI:generator.
Prefix none
Required rights none
Post only? No
Generated help Current
Version added
≥ 1.25

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

api.php?action=opensearch&search=api&limit=10&namespace=0&format=jsonfm [try in ApiSandbox]
Result 
[
	"api",
	[
		"API",
		"Apiales",
		"Apiaceae",
		"Apia",
		"Apicomplexa",
		"Apicomplexa lifecycle stages",
		"Apidae",
		"APIA Leichhardt Tigers",
		"Apical membrane",
		"Apical consonant"
	]
]

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

api.php?action=opensearch&search=api&limit=2&namespace=0&format=xmlfm [try in ApiSandbox]
Result 
<?xml version="1.0"?>
<SearchSuggestion version="2.0" xmlns="http://opensearch.org/searchsuggest2">
  <Query xml:space="preserve">api</Query>
  <Section>
    <Item>
      <Text xml:space="preserve">Application programming interface</Text>
      <Url xml:space="preserve">https://en.wikipedia.org/wiki/Application_programming_interface</Url>
      <Description xml:space="preserve">In computer programming, an application programming interface (API) is a set of routines, protocols, and tools for building software applications.</Description>
    </Item>
    <Item>
      <Text xml:space="preserve">Apia</Text>
      <Url xml:space="preserve">https://en.wikipedia.org/wiki/Apia</Url>
      <Description xml:space="preserve">Apia is the capital and the largest city of Samoa. From 1900 to 1919, it was the capital of the German Samoa.</Description>
      <Image source="https://upload.wikimedia.org/wikipedia/commons/thumb/b/b2/Samoa_-_Apia_Govt_buildings.jpg/50px-Samoa_-_Apia_Govt_buildings.jpg" width="50" height="38" />
    </Item>
  </Section>
</SearchSuggestion>



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, 5500, 5501
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).
fast-fuzzy
Experimental fuzzy profile (may be removed at any time)
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, fast-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]

Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Opensearch&oldid=2381927"