API:Query

The action=query module allows for retrieving all sorts of data, and is loosely based on the now obsolete Query API. action=query is also used to retrieve tokens needed for editing and the like.

The query module has many submodules (called query modules), each with a different function. There are three types of query modules:
 * Meta information about the wiki and the logged-in user
 * Properties of pages
 * Lists of pages that match certain criteria

Query modules can be combined freely, so you can use e.g.  to call six modules in one request.

Apart from query modules, action=query also has some features of its own.

Sample query
Before we get into the nitty-gritty, here's a useful sample query that simply gets the content of a page:

api.php?action=query&prop=revisions&rvprop=content&format=xml&titles=Main%20Page

This means fetch (action=query) the content (rvprop=content) of the most recent revision of Main Page (title=Main%20Page) in XML format (format=xml).

Specifying titles
You can specify titles in the following ways:
 * Using the  parameter, e.g.
 * Using the  parameter, e.g.
 * Using the  parameter, e.g.
 * Most query modules will use the page the revision ID belongs to. Only prop=revisions actually uses the revision ID itself
 * Using a generator

Specifying titles through the query string is limited to 51 titles per query (or 501 for those with the  right, usually bots and sysops).

Title normalization
Title normalization converts page titles to their canonical form. This means capitalizing the first character, replacing underscores with spaces, etc. Title normalization is done automatically, regardless of which query modules are used.

Missing and invalid titles
Titles that don't exist or are invalid still appear in the  section, but they have the   or   attribute set. In output formats that support numeric array keys (such as JSON and PHP serialized), missing and invalid titles will have unique, negative page IDs. Query modules will just ignore missing or invalid titles, as they can't do anything useful with them.

Titles in the Special: and Media: namespaces
Currently, titles in the Special: and Media: namespaces cannot be queried. If any such titles are found in the  parameter or passed to a module by a generator, a warning will be issued.

Resolving redirects
Redirects can be resolved automatically, so that the target of redirect is returned instead of the given title. The example below isn't really useful because it doesn't use any query modules, but shows how the  parameter works. Both normalization and redirection may take place. In case of double redirects, all redirects will be resolved, and in case of a circular redirect, there might not be a page in the 'pages' section (see also below). Redirect resolution cannot be used in combination with the  parameter or with a generator generating revids; doing that will produce a warning and will not resolve redirects for the specified revids.

Circular redirects
Assume Page1 &rarr; Page2 &rarr; Page3 &rarr; Page1 (circular redirect). Also, in this example a non-normalized name 'page1' is used.

Limits
See here for more information on limits.

Continuing queries
Very often, you will not get all the data you want in one request. To continue the request, you can use the provided  value.

You can now use  to get the next ten categories.

When using a generator, you might get two  values, one for the generator and one for the 'regular' module. In this case you need to continue the 'regular' module first (with the old value of generator-continue) until it runs out, then continue the generator. You should not set both  parameters together.

Getting a list of page IDs
With the  parameter, you'll get a list of all page IDs listed in the   element. This is particularly useful for formats like JSON in which the pages array has numeric indexes.

Exporting pages
You can export pages through the API with the  parameter. If the  parameter is set, an XML dump of all pages in the   element will be added to the result. The  parameter gives only a result, when used with specifyed titles (Generator, titles, pageids or revid). Note that the XML dump will be wrapped in the requested format; if that format is XML, characters like &lt; and &gt; will be encoded as entities (&amp;lt; and &amp;gt;) If the  parameter is also set, only the XML dump (not wrapped in an API result) will be returned.

See also: Importing pages

Generators
With generators, you can use the output of a list instead of the  parameter. The output of the list must be a list of pages, whose titles are automatically used instead of the,   or   parameter. Other query modules will treat those pages as if they were provided by the user through the  parameter. Only one generator is allowed. List modules that don't list pages, can't be used as a generator. Some prop modules can also be used as a generator.

Parameters passed to a generator must be prefixed with a. For instance, when using, use   instead of.

It should also be noted that generators only pass page titles to the 'real' query, and can't output any information themselves. Setting parameters like  will therefore have no effect.

Generators and redirects
Here, we use prop=links as a generator. This query will get all the links from all the pages that are linked from Title. For this example, assume that Title has links to TitleA and TitleB. TitleB is a redirect to TitleC. TitleA links to TitleA1, TitleA2, TitleA3; and TitleC links to TitleC1 and TitleC2. Redirect are solved because the  parameter is set.

The query will execute the following steps:
 * 1) Resolve redirects for titles in the   parameter
 * 2) For all the titles in the   parameter, get the list of pages they link to
 * 3) Resolve redirects in that list
 * 4) Run the prop=links query on that list of titles

More generator examples

 * Show info about 4 pages starting at the letter "T"
 * http://en.wikipedia.org/w/api.php?action=query&generator=allpages&gaplimit=4&gapfrom=T&prop=info


 * Show content of first 2 non-redirect pages beginning at "Re"
 * http://en.wikipedia.org/w/api.php?action=query&generator=allpages&gaplimit=2&gapfilterredir=nonredirects&gapfrom=Re&prop=revisions&rvprop=content

Possible warnings

 * No support for special pages has been implemented
 * Thrown if a title in the Special: or Media: namespace is given
 * Redirect resolution cannot be used together with the revids= parameter. Any redirects the revids= point to have not been resolved.
 * Note that this can also be caused by a generator that generates revids