API:Opensearch
| MediaWiki version: | 1.9 |
 |
This page is part of the MediaWiki action API documentation. |
MediaWiki action API
- Introduction and quick start
- FAQ
- Tutorial
- Formats
- Error reporting
- Restricting usage
- Cross-site requests
- Authentication
- Queries
- Searching (by title, content, coordinates...)
- Parsing wikitext and expanding templates
- Purging pages' caches
- Parameter information
- Changing wiki content
- Watchlist feed
- Wikidata
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
- Asserting
| Opensearch | |
|---|---|
| Get pages whose name matches a given string. When limit is reached, results are ordered by number of incoming links. | |
| Prefix | |
| Required rights | read |
| Post only? | No |
| Generated help | Current |
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.
Module documentation[edit | edit source]
|
The following documentation is the output of Special:ApiHelp/opensearch, generated from opensearch's source code. |
action=opensearch
- This module requires read rights.
- Source: MediaWiki
- License: GPL-2.0+
Search the wiki using the OpenSearch protocol.
- search
-
Search string.
- limit
-
Maximum number of results to return.
- No more than 100 (100 for bots) allowed.
- Type: integer or max
- Default: 10
- namespace
-
Namespaces to search.
- Values (separate with |): 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, 484, 485, 486, 487, 828, 829, 1198, 1199, 2300, 2301, 2302, 2303, 2600
- Default: 0
- 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)
- Find pages beginning with Te.
- api.php?action=opensearch&search=Te
Note on case sensitivity[edit | edit source]
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.
Result format[edit | edit source]
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
| 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
$wgExtractsExtendOpenSearchXmltrue, 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
$wgPageImagesExpandOpenSearchXmltrue, 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
| 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>
|
See also[edit | edit source]
- API:Search
- Extension:OpenSearchXml (merged into core in MediaWiki 1.25) provides search plugin autodetection for browsers
