API/Query

<translate> The <tvar name=1>action=query</tvar> module allows you to fetch information about a wiki and the data stored in it, such as the wikitext of a particular page, the links and categories of a set of pages, or the token you need to . </translate>

API documentation[edit]

</translate>

Query modules[edit]

The query module has three types of submodules (also called query modules):

about the wiki and the logged-in user.</translate>

of pages, including page revisions and content.</translate>

of pages that match certain criteria.

Examples[edit]

</translate>

Example 1: Specifying pages[edit]

Unlike meta and list query modules, all property query modules work on a set of pages that can be specified in one of the following ways:

By name using the <tvar name=1>titles</tvar> parameter, e.g. <tvar name=2>titles=Foo|Bar|Main_Page</tvar>.</translate>

By page ID using the <tvar name=1>pageids</tvar> parameter, e.g. <tvar name=2>pageids=123|456|75915</tvar>.</translate>

By revision ID using the <tvar name=1>revids</tvar> parameter, e.g. <tvar name=2>revids=478198|54872|54894545</tvar>.</translate> <translate> Most query modules will convert revision ID to the corresponding page ID.</translate> <translate> Only <tvar name=1>revisions}}</tvar> actually uses the revision ID itself.</translate>

Using a [[<tvar name=1>#Generators</tvar>|generator]].

</translate>

GET request[edit]

</translate> 5487548945 |p3=format=json |p4=formatversion=2 }} <translate>

Response[edit]

</translate> <syntaxhighlight lang="json"> {

   "batchcomplete": true,
   "query": {
       "pages": [
           {
               "pageid": 1130,
               "ns": 0,
               "title": "Avicenna"
           },
           {
               "pageid": 17412,
               "ns": 0,
               "title": "Klein bottle"
           },
           {
               "pageid": 33642,
               "ns": 0,
               "title": "Warrant"
           }
       ]
   }

} </syntaxhighlight>

Example 2: Title normalization[edit]

Title normalization converts page titles to their canonical form.

This means capitalizing the first character, replacing underscores with spaces, and changing namespace to the localized form defined for that wiki. </translate>

GET request[edit]

</translate> article_B | p3=format=json | p4=formatversion=2 }} <translate>

Response[edit]

</translate> <syntaxhighlight lang="json"> {

   "batchcomplete": true,
   "query": {
       "normalized": [
           {
               "fromencoded": false,
               "from": "Project:articleA",
               "to": "Wikipedia:ArticleA"
           },
           {
               "fromencoded": false,
               "from": "article_B",
               "to": "Article B"
           }
       ],
       "pages": [
           {
               "ns": 0,
               "title": "Article B",
               "missing": true
           },
           {
               "ns": 4,
               "title": "Wikipedia:ArticleA",
               "missing": true
           }
       ]
   }

} </syntaxhighlight>

Example 3: Missing and invalid titles[edit]

Titles that don't exist or are invalid will have a <tvar name=1>missing</tvar> or <tvar name=2>invalid</tvar> attribute set in the response.

In output formats that support numeric array keys, missing and invalid titles will have negative page IDs. </translate>

<translate> In some cases, a title can be viewed by a user but cannot be accessed by the API, such as pages that mirror content from another wiki.</translate> <translate> These titles will have a <tvar name=1>known</tvar> attribute set in the response.</translate>

GET request[edit]

</translate> Main%20PageTalk: |p3=format=json |p4=formatversion=2 }} <translate>

Response[edit]

</translate> <syntaxhighlight lang="json"> {

   "batchcomplete": true,
   "query": {
       "pages": [
           {
               "ns": 0,
               "title": "Doesntexist",
               "missing": true
           },
           {
               "title": "Talk:",
               "invalidreason": "The requested page title is empty or contains only the name of a namespace.",
               "invalid": true
           },
           {
               "pageid": 15580374,
               "ns": 0,
               "title": "Main Page"
           }
       ]
   }

} </syntaxhighlight>

Example 4: Continuing queries[edit]

When all the data is not returned in the response of a query, there will be a <tvar name=1>continue</tvar> attribute to indicate that there is more data. </translate>

GET request[edit]

</translate>

Response[edit]

</translate> <syntaxhighlight lang="json"> {

   "continue": {
       "accontinue": "List_of_largest_companies_in_Sri_Lanka",
       "continue": "-||"
   },
   "query": {
       "allcategories": [
           {
               "category": "List of BioWare characters"
           },
           {
               "category": "List of Harlequin Romance novels"
           },
           {
               "category": "List of MPs elected in UK elections templates"
           },
           {
               "category": "List of Metamorphoses characters"
           },
           {
               "category": "List of Rockstar Games characters"
           },
           {
               "category": "List of Star Trek awards and nominations"
           },
           {
               "category": "List of Swedish films of the 2020s"
           },
           {
               "category": "List of association football clubs in the Republic of Ireland templates"
           },
           {
               "category": "List of awards and nominations received by Aleksej Pechkuroy"
           },
           {
               "category": "List of cabinet templates"
           }
       ]
   }

} </syntaxhighlight>

<translate> To get further data, add its values to the original request: </translate>

GET request[edit]

</translate>

}} <translate>

Response[edit]

</translate> <syntaxhighlight lang="json"> {

   "batchcomplete": true,
   "query": {
       "allcategories": [
           {
               "category": "List of largest companies in Sri Lanka"
           },
           {
               "category": "List of longest beaches of the world"
           },
           {
               "category": "List of ministers by ministry of Bangladesh"
           },
           {
               "category": "List of people from Palm Beach, Florida"
           },
           {
               "category": "List of video game characters"
           }
       ]
   }

} </syntaxhighlight>

Example 5: Batchcomplete[edit]

The API returns a <tvar name=1>batchcomplete</tvar> element to indicate that all data for the current batch of items has been returned. </translate>

<translate> In the response of the sample query below, <tvar name=1>batchcomplete</tvar> has been included to indicate that all the data for each of the three images has been returned.

The next continuation will begin returning data for the next set of 3 images. </translate>

GET request[edit]

</translate>

Response[edit]

</translate> <syntaxhighlight lang="json"> {

 "batchcomplete": true,
 "continue": {
   "aicontinue": "20020822143445|Do_You_Want_to_Know_a_Secret_(Beatles_song_-_sample).ogg",
   "continue": "-||"
 },
 "query": {
   "allimages": [
     {
       "name": "Simon_and_Garfunkel_-_Mrs_Robinson.ogg",
       "timestamp": "2002-08-04T19:55:17Z",
       "url": "https://upload.wikimedia.org/wikipedia/en/6/64/Simon_and_Garfunkel_-_Mrs_Robinson.ogg",
       "descriptionurl": "https://en.wikipedia.org/wiki/File:Simon_and_Garfunkel_-_Mrs_Robinson.ogg",
       "descriptionshorturl": "https://en.wikipedia.org/w/index.php?curid=67723",
       "ns": 6,
       "title": "File:Simon and Garfunkel - Mrs Robinson.ogg"
     },
     {
       "name": "Simon_and_Garfunkel_-_Scarborough_Fair.ogg",
       "timestamp": "2002-08-04T20:01:36Z",
       "url": "https://upload.wikimedia.org/wikipedia/en/c/c1/Simon_and_Garfunkel_-_Scarborough_Fair.ogg",
       "descriptionurl": "https://en.wikipedia.org/wiki/File:Simon_and_Garfunkel_-_Scarborough_Fair.ogg",
       "descriptionshorturl": "https://en.wikipedia.org/w/index.php?curid=67779",
       "ns": 6,
       "title": "File:Simon and Garfunkel - Scarborough Fair.ogg"
     },
     {
       "name": "Beatles_please_me.ogg",
       "timestamp": "2002-08-22T14:34:00Z",
       "url": "https://upload.wikimedia.org/wikipedia/en/e/ee/Beatles_please_me.ogg",
       "descriptionurl": "https://en.wikipedia.org/wiki/File:Beatles_please_me.ogg",
       "descriptionshorturl": "https://en.wikipedia.org/w/index.php?curid=74826",
       "ns": 6,
       "title": "File:Beatles please me.ogg"
     }
   ]
 }

} </syntaxhighlight>

Example 6: Generators[edit]

Use generators if you want to get data about a set of pages.

For example, to get data about pages in a certain category, instead of querying <tvar name=1>list=categorymembers</tvar> and then querying again with <tvar name=2>pageids</tvar> set to all the returned pages, combine the two API calls into one by using <tvar name=3>generator=categorymembers</tvar>.

When using a list module as a generator, you don't need to specify the pages.

However, for a property module, you should [[<tvar name=1>#Specifying pages</tvar>|specify the pages]] which the generator will work on.

For example, to load all pages that are linked to from the main page, use <tvar name=1>generator=links&titles=Main%20Page</tvar>.

Parameters passed to a generator must be prefixed with a g. For instance, when using generator=backlinks, use gbllimit instead of bllimit.

The sample query below gets links and categories for the first three pages in the main namespace starting with "Ba". </translate>

GET request[edit]

</translate> categories |p6=format=json |p7=formatversion=2 }} <translate>

Response[edit]

</translate> <syntaxhighlight lang="json"> {

    "continue": {
        "plcontinue": "14977970|0|Kirkwall_Ba_game",
        "continue": "||categories"
    },
    "query": {
        "pages": [
            {
                "pageid": 98178,
                "ns": 0,
                "title": "Ba",
                "links": [
                    {
                        "ns": 0,
                        "title": "BA"
                    },
                    {
                        "ns": 4,
                        "title": "Wikipedia:Mainspace"
                    },
                    {
                        "ns": 4,
                        "title": "Wikipedia:Naming conventions (capitalization)"
                    },
                    {
                        "ns": 4,
                        "title": "Wikipedia:Protection policy"
                    },
                    {
                        "ns": 4,
                        "title": "Wikipedia:Redirect"
                    },
                    {
                        "ns": 10,
                        "title": "Template:R from miscapitalisation"
                    },
                    {
                        "ns": 10,
                        "title": "Template:R from modification"
                    },
                    {
                        "ns": 10,
                        "title": "Template:R to disambiguation page"
                    },
                    {
                        "ns": 14,
                        "title": "Category:Redirects from ambiguous terms"
                    },
                    {
                        "ns": 14,
                        "title": "Category:Redirects from other capitalisations"
                    }
                ],
                "categories": [
                    {
                        "ns": 14,
                        "title": "Category:Redirects from ambiguous terms"
                    },
                    {
                        "ns": 14,
                        "title": "Category:Redirects from other capitalisations"
                    },
                    {
                        "ns": 14,
                        "title": "Category:Unprintworthy redirects"
                    }
                ]
            },
            {
                "pageid": 14977970,
                "ns": 0,
                "title": "Ba'"
            },
            {
                "pageid": 33351890,
                "ns": 0,
                "title": "Ba'Al Shem Tov"
            }
        ]
    }

} </syntaxhighlight>

Continuing queries[edit]

</translate> <translate> Queries will often have more results available than are just shown in the original query.</translate> (Often this is because a query's result has been reached.) <translate> In these cases, queries can be continued.</translate> <translate> More detailed information on continuing queries can be at <tvar name=1></tvar>.</translate>

Possible warnings[edit]

</translate>


<translate> Warning message</translate>	<translate> Cause</translate>
<translate> No support for special pages has been implemented.</translate>	<translate> Thrown if a title in the Special: or Media: namespace is given. The pages in these namespaces cannot be queried.</translate>
	<translate> Thrown if the <tvar name=1>`redirect`</tvar> parameter is used in a query that specifies pages using <tvar name=2>`revids`</tvar>.</translate>

Parameter history[edit]

</translate>

v1.34: <translate> Introduced <tvar name=1>exportschema</tvar></translate>
v1.24: <translate> Introduced <tvar name=1>rawcontinue</tvar></translate> <translate> (note: [[<tvar name=1>Special:MyLanguage/API:Raw query continue</tvar>|raw continuation]] was the default behavior until v1.26)</translate>
v1.21: <translate> Introduced <tvar name=1>continue</tvar></translate>

Additional notes[edit]

</translate>

<translate> Specifying titles through <tvar name=1>titles</tvar> or <tvar name=2>pageids</tvar> is limited to 50 titles per query, or 500 for those with the <tvar name=3>apihighlimits</tvar> right.</translate>
<translate> Use multiple query modules together to get what you need in one request, e.g. <tvar name=1>prop=info|revisions&list=backlinks|embeddedin|allimages&meta=userinfo</tvar>.</translate>
<translate> Generators always pass page titles to the query module.</translate> <translate> Unlike lists (which may include additional data by default), generators should not output any information themselves, unless when explicitly requested via the generator module's query parameters.</translate>

Resolving redirects[edit]

</translate> <translate> Redirects can be resolved automatically, so that the target of a redirect is returned instead of the given title.</translate> <translate> When present, they will always contain <tvar name=1>from</tvar> and <tvar name=2>to</tvar> attributes and may contain a <tvar name=3>tofragment</tvar> attribute for those redirects that point to specific sections.</translate>

<translate> Both normalization and redirection may take place.</translate> <translate> In the case of multiple redirects, all redirects will be resolved, and in case of a circular redirect, there might not be a page in the 'pages' section (see [[<tvar name=1>#circular_redirects</tvar>|an example request]]).</translate> <translate> Redirect resolution cannot be used in combination with the <tvar name=1>revids=</tvar> parameter or with a generator generating revids; doing that will produce a [[<tvar name=2>#Possible warnings</tvar>|warning]] and will not resolve redirects for the specified revids.</translate>

<translate> The examples below show how the <tvar name=1>redirects</tvar> parameter works. </translate>

Template:ApiEx Template:ApiEx Template:ApiEx Template:ApiEx <translate> Here is a case of a circular redirect: <tvar name=1>Page1 → Page2 → Page3 → Page1</tvar>.</translate> <translate> Also, in this example a non-normalized name <tvar name=1>'page1'</tvar> is used.</translate> |p1=action=query |p2=titles=page1 |p3=redirects |p4=format=json |p5=formatversion=2 |result=<syntaxhighlight lang="json"> {

   "batchcomplete": true,
   "query": {
       "normalized": [
           {
               "fromencoded": false,
               "from": "page1",
               "to": "Page1"
           }
       ],
       "redirects": [
           {
               "from": "Page1",
               "to": "Page2"
           },
           {
               "from": "Page2",
               "to": "Page3"
           },
           {
               "from": "Page3",
               "to": "Page1"
           }
       ],
       "pages": [
           {
               "ns": 0,
               "title": "Page1",
               "missing": true
           }
       ]
   }

} </syntaxhighlight>}}

API documentation[edit]

Query modules[edit]

Examples[edit]

Example 1: Specifying pages[edit]

GET request[edit]

Response[edit]

Example 2: Title normalization[edit]

GET request[edit]

Response[edit]

Example 3: Missing and invalid titles[edit]

GET request[edit]

Response[edit]

Example 4: Continuing queries[edit]

GET request[edit]

Response[edit]

GET request[edit]

Response[edit]

Example 5: Batchcomplete[edit]

GET request[edit]

Response[edit]

Example 6: Generators[edit]

GET request[edit]

Response[edit]

Continuing queries[edit]

Possible warnings[edit]

Parameter history[edit]

Additional notes[edit]

Resolving redirects[edit]

See also[edit]