API:Query

From MediaWiki.org

Jump to: navigation, search
This page is part of the MediaWiki API documentation.
Languages Languages: 

English  • Español  • 日本語  • Русский
MediaWiki API


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. Query modules can be combined freely. There are three types of query modules:

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

Contents

[edit] Specifying titles

You can specify titles in the following ways:

  • Using the titles parameter, e.g. titles=Foo|Bar|Main_Page
  • Using the pageids parameter, e.g. pageids=123|456|75915
  • Using the revids parameter, e.g. revids=478198|54872|54894545
    • 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 apihighlimits right, usually bots and sysops).

[edit] 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.

Capitalization, localization, "_" => " ", "Project" => "Wikipedia", ...

api.php ? action=query & titles=Project:articleA|article_B

<api>
  <query>
    <normalized>
      <n from="Project:articleA" to="Wikipedia:ArticleA" />
      <n from="article_B" to="Article B" />
    </normalized>
    <pages>
      <page ns="4" title="Wikipedia:ArticleA" missing="" />
      <page ns="0" title="Article B" missing="" />
    </pages>
  </query>
</api>

[edit] Missing and invalid titles

Titles that don't exist or are invalid still appear in the <pages> section, but they have the missing="" or invalid="" 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.

A missing title, an invalid one and an existing one in JSON

api.php ? action=query & titles=Doesntexist|Main%20Page|Talk: & format=jsonfm

{
        "query": {
                "pages": {
                        "-2": {
                                "ns": 0,
                                "title": "Thisdoesntexist",
                                "missing": ""
                        },
                        "-1": {
                                "title": "Talk:",
                                "invalid": ""
                        },
                        "54": {
                                "pageid": 54,
                                "ns": 0,
                                "title": "Main Page",
                        }
                }
        }
}

[edit] 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 redirects 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).


Using "redirects" parameter. "Main page" is a redirect to "Main Page"

api.php ? action=query & titles=Main%20page & redirects

<api>
  <query>
    <redirects>
      <r from="Main page" to="Main Page" />
    </redirects>
    <pages>
      <page pageid="11105676" ns="0" title="Main Page" />
    </pages>
  </query>
</api>
Same request but without the "redirects" parameter.

api.php ? action=query & titles=Main%20page

<api>
  <query>
    <pages>
      <page pageid="217225" ns="0" title="Main page" />
    </pages>
  </query>
</api>
Without "redirects" you may want to use prop=info to obtain redirect status.

api.php ? action=query & titles=Main%20page & prop=info

<api>
  <query>
    <pages>
      <page pageid="217225" ns="0" title="Main page" touched="2007-06-29T11:22:39Z" lastrevid="78280008" counter="0" length="56" redirect="" />
    </pages>
  </query>
</api>

[edit] Circular redirects

Assume Page1 → Page2 → Page3 → Page1 (circular redirect). Also, in this example a non-normalized name 'page1' is used.

Circular redirect behavior

api.php ? action=query & titles=page1 & redirects

<?xml version="1.0" encoding="utf-8"?>
<api>
  <query>
    <normalized>
      <n from="page1" to="Page1" />
    </normalized>
    <redirects>
      <r from="Page1" to="Page2" />
      <r from="Page2" to="Page3" />
      <r from="Page3" to="Page1" />
    </redirects>
  </query>
</api>

[edit] Limits

See here for more information on limits.

[edit] 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 query-continue value.

Using the query-continue value

api.php ? action=query & list=allcategories & acprefix=List%20of

<?xml version="1.0" encoding="utf-8"?>
<api>
  <query-continue>
    <allcategories acfrom="List of Baptist sub-denominations" />
  </query-continue>
  <query>
    <allcategories>
      <c>List of &quot;M&quot; series military vehicles</c>
      <c>List of Alternative Rock Groups</c>
      <c>List of Alumni of Philippine Science High School</c>
      <c>List of American artists</c>
      <c>List of Anglicans and Episcopalians</c>
      <c>List of Arizona Reptiles</c>
      <c>List of Artists by record label</c>
      <c>List of Australian Anglicans</c>
      <c>List of Bahá'ís</c>
      <c>List of Balliol College people</c>
    </allcategories>
  </query>
</api>

You can now use acfrom=List%20of%20Baptist%20sub-denominations to get the next ten categories.

[edit] Generators

With generators, you can use the output of a list instead of the titles parameter. The output of the list must be a list of pages, whose titles are automatically used instead of the titles, pageids or revids parameter. Other query modules will treat those pages as if they were provided by the user through the titles 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 'g'. For instance, when using generator=backlinks, use gbltitle instead of bltitle.

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 gcmprop will therefore have no effect.

[edit] Using list=allpages as generator

Get links and categories for the first thre pages in the main namespace starting with A

api.php ? action=query & generator=allpages & gaplimit=3 & gapfrom=Ba & prop=links|categories

<?xml version="1.0" encoding="utf-8"?>
<api>
  <query-continue>
    <allpages gapfrom="Ba&#039;ad Sneen (Song)" />
  </query-continue>
  <query>
    <pages>
      <page pageid="98178" ns="0" title="Ba">
        <links>
          <pl ns="0" title="BA" />
          <pl ns="4" title="Wikipedia:Redirect" />
          <pl ns="4" title="Wikipedia:Template messages/Redirect pages" />
          <pl ns="10" title="Template:R from alternative name" />
          <pl ns="10" title="Template:R from alternative spelling" />
          <pl ns="14" title="Category:Redirects from other capitalisations" />
        </links>
        <categories>
          <cl ns="14" title="Category:Redirects from other capitalisations" />
          <cl ns="14" title="Category:Unprintworthy redirects" />
        </categories>
      </page>
      <page pageid="14977970" ns="0" title="Ba&#039;">
        <links>
          <pl ns="0" title="Kirkwall Ba game" />
        </links>
      </page>
      <page pageid="10463369" ns="0" title="Ba&#039;Gamnan">
        <links>
          <pl ns="0" title="Characters of Final Fantasy XII" />
        </links>
      </page>
    </pages>
  </query>
</api>

[edit] 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 redirects parameter is set.

The query will execute the following steps:

  1. Resolve redirects for titles in the titles parameter
  2. For all the titles in the titles 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
Using redirect resolution with generators

api.php ? action=query & generator=links & titles=Title & prop=links & redirects

<?xml version="1.0" encoding="utf-8"?>
<api>
  <query>
    <pages>
      <page pageid="32" ns="0" title="TitleA">
        <links>
          <pl ns="0" title="TitleA1" />
          <pl ns="0" title="TitleA2" />
          <pl ns="0" title="TitleA3" />
        </links>
      </page>
      <page pageid="54" ns="0" title="TitleC">
        <links>
          <pl ns="0" title="TitleC1" />
          <pl ns="0" title="TitleC2" />
        </links>
      </page>
    </pages>
    <redirects>
      <r from="TitleB" to="TitleC" />
    </redirects>
  </query>
</api>

[edit] 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 begining at "Re"
http://en.wikipedia.org/w/api.php?action=query&generator=allpages&gaplimit=2&gapfilterredir=nonredirects&gapfrom=Re&prop=revisions&rvprop=content
Retrieved from "http://www.mediawiki.org/wiki/API:Query"
Personal tools