MediaWiki

User:Jeropbrenda/Sandbox/en

< User:Jeropbrenda | Sandbox

Data formats

edit

Input

edit

The Action API takes its input through parameters provided by GET or POST requests. Every module (and every action=query submodule) has its own set of parameters, which are listed in the documentation and in action=help. They can also be retrieved through action=paraminfo.

Encoding

edit

All input should be valid UTF-8, in NFC form. MediaWiki will attempt to automatically convert other formats, which may result in errors.

Multivalue parameters

edit

Some parameters take multiple values, separated by a pipe character (|). For example, if you wished to view information on three users, Alex, Shirayuki, and SamanthaNguyen, for the parameter ususers, you would put color=Alex|Shirayuki|SamanthaNguyen in the query. Whether a parameter accepts multiple values is listed explicitly in action=paraminfo and action=help. The documentation does not distinguish multivalue parameters explicitly, but the descriptions for these parameters are usually along the lines of "A list of ..." or "A pipe-separated list of ...".

If you need to submit a list of values where some of the values contain a pipe character (which should be rare - most multivalue parameters are lists of page titles or usernames, neither of which can contain pipes), you can use the unit separator character instead: ususers=<US>A|ex<US>Shirayuk|<US>Samantha|Nguyen (where <US> stands for U+001F) will submit the three values A|ex, Shirayuk| and Samantha|Nguyen. (Note that there is an extra <US> at the beginning. This is mandatory to avoid ambiguity around submitting a single value containing a pipe.)

Boolean values

edit

Boolean parameters work like HTML checkboxes: if the parameter is specified in the HTTP request, regardless of value, it is considered true. For a false value, omit the parameter entirely. The best way to specify a true parameter in an HTTP request is to use someParam=; the trailing = ensures the browser or HTTP library does not discard the "empty" someParam.

Timestamps

edit

Parameters that take timestamp values accept multiple timestamp formats:

In the output, timestamps are always in ISO 8601 format.

Output

edit

MediaWiki API has historically supported a number of different formats, but this has significantly complicated further development.

We would like to standardize on just one JSON format.

For now, MediaWiki discourages, but still supports two additional generic output formats (XML and PHP).

You should always specify the format with the input (request) parameter format and a lowercase value.

Feed modules like Feed Recent Changes override the standard output format, instead using RSS or Atom, as specified by their feedformat parameter.

In those cases, the format specified in the format parameter is only used if there's an error.

All formats other than JSON are deprecated.

XML and PHP are still supported, but all others have been removed in either MediaWiki 1.26 or 1.27; see the table below. All new API users should use JSON.

Clients written in PHP should avoid using the PHP format because it is fundamentally insecure.

It is maintained for now only due to its popularity.


Unless specified, all modules allow data output in all generic formats.

To simplify debugging, all generic formats have "pretty-print in HTML" alternatives with an fm suffix.


The default format changed in MediaWiki 1.25 to jsonfm; it was xmlfm in earlier MediaWiki releases.


Note that while the pretty-print formats are all indented and separate syntactic elements with newlines, the non-pretty formats don't do this.

Format Description
json JSON format (always use this one)
none Always return a blank response 1.21+
Deprecated, but still operational
php serialized PHP format
xml XML format
Formats removed in MediaWiki 1.26
wddx WDDX format
dump PHP var_dump() format
Formats removed in MediaWiki 1.27
txt PHP print_r() format
dbg PHP var_export() format
yaml YAML format

There are many conversion libraries and online converters to convert JSON responses to other formats—for example, JSON-CSV converts to Comma-Separated Values

JSON parameters

edit

format=json and jsonfm accept the following additional parameters:

  • callback: If specified, wraps the output into a given function call. For safety, all user-specific data will be restricted.
  • utf8: If specified, encodes most (but not all) non-ASCII characters as UTF-8 instead of replacing them with hexadecimal escape sequences.
  • formatversion Specify formatversion=2 for to get json (and php) format responses in a cleaner format. This also encodes most non-ASCII characters as UTF-8. MW 1.25+

Callback restrictions

edit

When using JSON in callback mode, a number of things are disabled for security:

  • Tokens cannot be obtained (so state-changing actions aren't possible)
  • The client is treated as an anonymous user (i.e. not logged in) for all purposes, even after logging in through action=login
    • This means that things that require additional rights, such as rcprop=patrolled, won't work unless anonymous users are allowed to use them

Examples

edit
JSON
api.php?action=query&titles=Albert%20Einstein&prop=info&format=jsonfm [try in ApiSandbox]
Result
{
    "query": {
        "pages": {
            "736": {
                "pageid": 736,
                "ns": 0,
                "title": "Albert Einstein",
                "touched": "2007-07-06T04:37:30Z",
                "lastrevid": 142335140,
                "counter": 4698,
                "length": 86906
            }
        }
    }
}

it may be useful to add the '&indexpageids' parameter, to parse the json if the pageid ("736") is not known before the result.

JSON utf8 content on a French page, remove the utf8= parameter to see the difference
api.php?action=query&titles=Façade&prop=revisions&rvprop=content&format=jsonfm&utf8= [try in ApiSandbox]
XML
api.php?action=query&titles=Albert%20Einstein&prop=info&format=xmlfm [try in ApiSandbox]
Result
<?xml version="1.0" encoding="utf-8"?>
<api>
  <query>
    <pages>
      <page pageid="736" ns="0" title="Albert Einstein" touched="2007-07-06T04:37:30Z" lastrevid="142335140" counter="4698" length="86906" />
    </pages>
  </query>
</api>
PHP (serialized format, with line breaks added for readability. Use PHP's unserialize() function to recover data.)
api.php?action=query&titles=Albert%20Einstein&prop=info&format=php [try in ApiSandbox]
Result
a:1:{s:5:"query";a:1:{s:5:"pages";a:1:{i:736;a:7:{s:6:"pageid";i:736;s:2:"ns";i:0;s:5:"title";s:15:"Albert Einstein";
s:7:"touched";s:20:"2007-07-06T04:37:30Z";s:9:"lastrevid";i:142335140;s:7:"counter";i:4698;s:6:"length";i:86906;}}}}
PHP (var_export format)
api.php?action=query&titles=Albert%20Einstein&prop=info&format=dbg [try in ApiSandbox]
Result
array (
  'query' => 
  array (
    'pages' => 
    array (
      736 => 
      array (
        'pageid' => 736,
        'ns' => 0,
        'title' => 'Albert Einstein',
        'touched' => '2008-10-11T20:27:04Z',
        'lastrevid' => 244636163,
        'counter' => 4698,
        'length' => 89641,
      ),
    ),
  ),
)


Langlinks

edit
MediaWiki version:
≥ 1.11

GET Request to list all language links from the provided pages to other languages.

API documentation

edit
(main | query | langlinks)

Returns all interlanguage links from the given pages.

Specific parameters:
Other general parameters are available.
llprop

Which additional properties to get for each interlanguage link:

url
Adds the full URL.
langname
Adds the localised language name (best effort). Use llinlanguagecode to control the language.
autonym
Adds the native language name.
Values (separate with | or alternative): autonym, langname, url
lllang

Only return language links with this language code.

lltitle

Link to search for. Must be used with lllang.

lldir

The direction in which to list.

One of the following values: ascending, descending
Default: ascending
llinlanguagecode

Language code for localised language names.

Default: en
lllimit

How many langlinks to return.

Type: integer or max
The value must be between 1 and 500.
Default: 10
llcontinue

When more results are available, use this to continue. More detailed information on how to continue queries can be found on mediawiki.org.

llurl
Deprecated.

Whether to get the full URL (cannot be used with llprop).

Type: boolean (details)
Example:
Get interlanguage links from the page MediaWiki.
api.php?action=query&prop=langlinks&titles=MediaWiki&redirects= [open in sandbox]


Example

edit

GET Request

edit

Get a list of first 20 language links Main Page has with localised language name.

api.php?action=query&titles=Main%20Page&prop=langlinks&lllimit=20&llprop=langname [try in ApiSandbox]

Response

edit 
{
  "query": {
        "pages": {
            "15580374": {
                "pageid": 15580374,
                "ns": 0,
                "title": "Main Page",
                "langlinks": [
                    {
                        "lang": "ar",
                        "langname": "Arabic",
                        "*": ""
                    },
                    {
                        "lang": "bg",
                        "langname": "Bulgarian",
                        "*": ""
                    },
                    {
                        "lang": "bs",
                        "langname": "Bosnian",
                        "*": ""
                    },
                    {
                        "lang": "ca",
                        "langname": "Catalan",
                        "*": ""
                    },
                    {
                        "lang": "cs",
                        "langname": "Czech",
                        "*": ""
                    },
                    {
                        "lang": "da",
                        "langname": "Danish",
                        "*": ""
                    },
                    {
                        "lang": "de",
                        "langname": "German",
                        "*": ""
                    },
                    {
                        "lang": "el",
                        "langname": "Greek",
                        "*": ""
                    },
                    {
                        "lang": "eo",
                        "langname": "Esperanto",
                        "*": ""
                    },
                    {
                        "lang": "es",
                        "langname": "Spanish",
                        "*": ""
                    }
                ]
            }
        }
    }
}

Sample code

edit

get_langlinks.py 

#!/usr/bin/python3

"""
    get_langlinks.py

    MediaWiki Action API Code Samples
    Demo of `Langlinks` module: Demo to gets a list of first 20 language links from the provided pages to other languages.

    MIT License
"""

import requests

S = requests.Session()

URL = "https://en.wikipedia.org/w/api.php"

#list of first 20 language links with the localised language name.

PARAMS = {
    "llprop" : "langname",
    "format" : "json",
    "lllimit": "20",
    "prop"   : "langlinks",
    "titles" : "Main Page",
    "action" : "query"
}

R = S.get(url=URL, params=PARAMS)
DATA = R.json()

print(DATA)

Possible errors

edit
Code Info
invalidparammix The title parameter may only be used with lang.

See also

edit
Retrieved from "https://www.mediawiki.org/w/index.php?title=User:Jeropbrenda/Sandbox/en&oldid=4084463"