Editing API/Query

<languages/>

<translate>
<!--T:1-->
The <tvar name=1><code>action=query</code></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>

<div style="overflow:auto">

</div>

<translate>
== API documentation == <!--T:17-->
</translate>


<translate>
=== Query modules === <!--T:39-->

<!--T:4-->
The query module has three types of submodules (also called query modules):

<!--T:5-->
*  about the wiki and the logged-in user.</translate>
<translate>
<!--T:6-->
*  of pages, including page revisions and content.</translate>
<translate>
<!--T:7-->
*  of pages that match certain criteria.

== Examples == <!--T:18-->
</translate>


<translate>
=== Example 1: Specifying pages === <!--T:10-->

<!--T:40-->
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:

<!--T:47-->
* By name using the <tvar name=1><code>titles</code></tvar> parameter, e.g. <tvar name=2><code>titles=Foo|Bar|Main_Page</code></tvar>.</translate>
<translate>
<!--T:48-->
* By page ID using the <tvar name=1><code>pageids</code></tvar> parameter, e.g. <tvar name=2><code>pageids=123|456|75915</code></tvar>.</translate>
<translate>
<!--T:49-->
* By revision ID using the <tvar name=1><code>revids</code></tvar> parameter, e.g. <tvar name=2><code>revids=478198|54872|54894545</code></tvar>.</translate> <translate><!--T:50--> Most query modules will convert revision ID to the corresponding page ID.</translate> <translate><!--T:51--> Only <tvar name=1>revisions}}</tvar> actually uses the revision ID itself.</translate>
<translate>
<!--T:52-->
* Using a [[<tvar name=1>#Generators</tvar>|generator]].
</translate>


<translate>
==== GET request ==== <!--T:19-->
</translate>
5487548945
|p3=format=json
|p4=formatversion=2
}}
<translate>
==== Response ==== <!--T:20-->
</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>


<translate>
=== Example 2: Title normalization === <!--T:11-->


<!--T:12-->
Title normalization converts page titles to their canonical form.

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




<translate>
==== GET request ==== <!--T:21-->
</translate>
article_B
| p3=format=json
| p4=formatversion=2
}}
<translate>
==== Response ==== <!--T:22-->
</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>


<translate>
=== Example 3: Missing and invalid titles === <!--T:16-->

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

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

<translate><!--T:92--> 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><!--T:93--> These titles will have a <tvar name=1><code>known</code></tvar> attribute set in the response.</translate>


<translate>
==== GET request ==== <!--T:24-->
</translate>
Main%20PageTalk:
|p3=format=json
|p4=formatversion=2
}}
<translate>
==== Response ==== <!--T:25-->
</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>


<translate>
=== Example 4: Continuing queries=== <!--T:27-->

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


<translate>
==== GET request ==== <!--T:28-->
</translate>

<translate>
==== Response ==== <!--T:29-->
</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>
<!--T:56-->
To get further data, add its values to the original request:
</translate>


<translate>
==== GET request ==== <!--T:94-->
</translate>

}}
<translate>
==== Response ==== <!--T:95-->
</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>


<translate>
=== Example 5: Batchcomplete === <!--T:31-->

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


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

<!--T:59-->
The next continuation will begin returning data for the next set of 3 images.
</translate>


<translate>
==== GET request ==== <!--T:32-->
</translate>


<translate>
===== Response ===== <!--T:33-->
</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>



<translate>
=== Example 6: Generators === <!--T:35-->

<!--T:60-->
Use generators if you want to get data about a set of pages.

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

<!--T:62-->
When using a list module as a generator, you don't need to specify the pages.

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

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

<!--T:68-->
Parameters passed to a generator must be prefixed with a <code>g</code>. For instance, when using <code>generator=backlinks</code>, use <code>gbllimit</code> instead of <code>bllimit</code>.

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


<translate>
==== GET request ==== <!--T:36-->
</translate>
categories
|p6=format=json
|p7=formatversion=2
}}
<translate>
==== Response ==== <!--T:37-->
</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>


<translate>
== Continuing queries == <!--T:97-->
</translate>
<translate><!--T:98--> 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><!--T:99--> In these cases, queries can be continued.</translate>
<translate><!--T:100--> More detailed information on continuing queries can be at <tvar name=1></tvar>.</translate>

<translate>
== Possible warnings == <!--T:65-->
</translate>
{| class="wikitable"
|+
! <translate><!--T:41--> Warning message</translate>
! <translate><!--T:42--> Cause</translate>
|-
| <translate><!--T:70--> No support for special pages has been implemented.</translate>
| <translate><!--T:71--> Thrown if a title in the Special: or Media: namespace is given. The pages in these namespaces cannot be queried.</translate>
|-
| 
| <translate><!--T:72--> Thrown if the <tvar name=1><code>redirect</code></tvar> parameter is used in a query that specifies pages using <tvar name=2><code>revids</code></tvar>.</translate>
|}

<translate>
== Parameter history == <!--T:43-->
</translate>
* v1.34: <translate><!--T:96--> Introduced <tvar name=1><code>exportschema</code></tvar></translate>
* v1.24: <translate><!--T:67--> Introduced <tvar name=1><code>rawcontinue</code></tvar></translate> <translate><!--T:76--> (note: [[<tvar name=1>Special:MyLanguage/API:Raw query continue</tvar>|raw continuation]] was the default behavior until v1.26)</translate>
* v1.21: <translate><!--T:66--> Introduced <tvar name=1><code>continue</code></tvar></translate>

<translate>
== Additional notes == <!--T:44-->
</translate>
* <translate><!--T:73--> Specifying titles through <tvar name=1><code>titles</code></tvar> or <tvar name=2><code>pageids</code></tvar> is limited to 50 titles per query, or 500 for those with the <tvar name=3><code>apihighlimits</code></tvar> right.</translate>
* <translate><!--T:8--> Use multiple query modules together to get what you need in one request, e.g. <tvar name=1><code>prop=info|revisions&list=backlinks|embeddedin|allimages&meta=userinfo</code></tvar>.</translate>
* <translate><!--T:101--> Generators always pass page titles to the query module.</translate> <translate><!--T:102--> 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>

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

<translate><!--T:80--> Both normalization and redirection may take place.</translate>
<translate><!--T:81--> 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><!--T:82--> Redirect resolution cannot be used in combination with the <tvar name=1><code>revids=</code></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>
<!--T:83-->
The examples below show how the <tvar name=1><code>redirects</code></tvar> parameter works.
</translate>

{{ApiEx
| desc=<translate><!--T:84--> Using "<tvar name=1>redirects</tvar>" parameter.</translate> <translate><!--T:85--> "<tvar name=1>Main page</tvar>" is a redirect to "<tvar name=2>Main Page</tvar>"</translate>
| p1=action=query
| p2=titles=Main%20page
| p3=redirects
| p4=format=json
| p5=formatversion=2
| result=<syntaxhighlight lang="json">
{
    "batchcomplete": true,
    "query": {
        "redirects": [
            {
                "from": "Main page",
                "to": "Main Page"
            }
        ],
        "pages": [
            {
                "pageid": 15580374,
                "ns": 0,
                "title": "Main Page"
            }
        ]
    }
}
</syntaxhighlight>
}}
{{ApiEx
| desc=<translate><!--T:86--> Same request but without the "<tvar name=1>redirects</tvar>" parameter.</translate>
| p1=action=query
| p2=titles=Main%20page
| p3=format=json
| p4=formatversion=2
| result=<syntaxhighlight lang="json">
{
    "batchcomplete": true,
    "query": {
        "pages": [
            {
                "pageid": 217225,
                "ns": 0,
                "title": "Main page"
            }
        ]
    }
}
</syntaxhighlight>
}}
{{ApiEx
| desc=<translate><!--T:87--> Without "<tvar name=1>redirects</tvar>" you may want to use <tvar name=2>prop=info</tvar> to obtain redirect status.</translate>
| p1=action=query
| p2=titles=Main%20page
| p3=prop=info
| p4=formatversion=2
| result=<syntaxhighlight lang="json">
{
    "batchcomplete": true,
    "query": {
        "pages": [
            {
                "pageid": 217225,
                "ns": 0,
                "title": "Main page",
                "contentmodel": "wikitext",
                "pagelanguage": "en",
                "pagelanguagehtmlcode": "en",
                "pagelanguagedir": "ltr",
                "touched": "2017-12-17T02:02:05Z",
                "lastrevid": 777924062,
                "length": 170,
                "redirect": true
            }
        ]
    }
}
</syntaxhighlight>
}}
{{ApiEx
| desc=<translate><!--T:88--> Request with a section link.</translate> <translate><!--T:89--> "<tvar name=1>Wikipedia:!--</tvar>" is a redirect to "<tvar name=2>Wikipedia:Manual of Style#Invisible comments</tvar>"</translate>
| p1=action=query
| p2=titles=Wikipedia:!--
| p3=redirects
| p4=format=json
| p5=formatversion=2
| result=<syntaxhighlight lang="json">
{
    "batchcomplete": true,
    "query": {
        "redirects": [
            {
                "from": "Wikipedia:!--",
                "to": "Wikipedia:Manual of Style",
                "tofragment": "Invisible comments"
            }
        ],
        "pages": [
            {
                "pageid": 33697,
                "ns": 4,
                "title": "Wikipedia:Manual of Style"
            }
        ]
    }
}
</syntaxhighlight>
}}
<translate><!--T:90--> Here is a case of a circular redirect: <tvar name=1>Page1 &rarr; Page2 &rarr; Page3 &rarr; Page1</tvar>.</translate> <translate><!--T:91--> 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>}}

<translate>

== See also == <!--T:45-->
</translate>
*  - <translate><!--T:46--> The quick start guide.</translate>
*  - <translate><!--T:75--> Contains information on how to use the <tvar name=1><code>rawcontinue</code></tvar> parameter.</translate>

----
''Sample content adapted from [[mediawikiwiki:API:Query]] on mediawiki.org, licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC BY-SA 4.0].''