API:Categorymembers

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png This page is part of the MediaWiki API documentation.
MediaWiki API

Quick overview:

v · d · e


MediaWiki version: 1.11

List of pages that belong to a given category, ordered by page sort title.

Parameters[edit | edit source]

  • cmtitle: The category to enumerate (required). Must include Category: prefix. Cannot be used together with cmpageid.
  • cmpageid: Page ID of the category to enumerate. Cannot be used together with cmtitle.
  • cmnamespace: Only list pages in these namespaces
  • cmtype: Type of category members to include (page, subcat or file; separate with '|'). Ignored when cmsort=timestamp is set. Default: page|subcat|file
  • cmstart: Start listing at this timestamp. Can only be used with cmsort=timestamp
  • cmend: End listing at this timestamp. Can only be used with cmsort=timestamp
  • cmstarthexsortkey: Start listing at this hexadecimal sortkey. Can only be used with cmsort=sortkey
  • cmendhexsortkey: End listing at this hexadecimal sortkey. Can only be used with cmsort=sortkey
  • cmstartsortkeyprefix: Start listing at this sortkey prefix. Can only be used with cmsort=sortkey. Overrides cmstarthexsortkey
  • cmendsortkeyprefix: End listing before (not at) this sortkey prefix (if this value occurs it will not be included). Can only be used with cmsort=sortkey. Overrides cmendhexsortkey
  • cmsort: Property to sort by
    • sortkey: The article's sort key (default) . The sort key might contain "unprintable" characters such as newlines, NULs, ASCII control characters, and so on. When returned from the API using cmprop=sortkey, the whole sortkey is encoded by converting the UTF-8 to a string of hex digits.
    • timestamp: The time the article was added to the category (or the categorization, i.e. the sortkey, was changed)
  • cmdir: Direction to sort in
    • asc: From A to Z or from 2002 to 2014. Note: cmstart has to be before cmend
    • desc: From Z to A or from 2014 to 2002 Note: cmstart has to be later than cmend
  • cmlimit: Maximum number of pages to list (10 by default, "max" provides all members (up to 500 for normal accounts, 5000 for bot accounts))
  • cmprop: Which properties to get (separate with '|'). Default: ids|title
    • ids: page ID (default)
    • title: page title (default)
    • sortkey: the sortkey used for sorting in the category (hexadecimal string)
    • sortkeyprefix: the sortkey prefix used for sorting in the category (human-readable part of the sortkey)
    • type: type that the page has been categorised as (page, subcat or file) MW 1.18+
    • timestamp: time and date the article was added to the category
  • cmcontinue: Used to continue a previous request. Format of cmcontinue is "type|hexsortkey|pageid". When used to continue query then new cmstarthexsortkey value is value of hexsortkey.
  • cmstartsortkey: DEPRECATED! Like cmstarthexsortkey, but the value is passed as a binary string rather than the hex-encoded value returned from cmprop=sortkey.
  • cmendsortkey: DEPRECATED! Like cmendhexsortkey, but the value is passed as a binary string rather than the hex-encoded value returned from cmprop=sortkey.

Example[edit | edit source]

Standard syntax: list 10 pages in a category (e.g. Category:Physics)

List 20 items in the Category:Physics, it will list its 11 pages, and 9 subcategories

Get the 10 articles most recently added to Category:Physics

Get the 10 subcategories of Category:Wikipedia

Continue the next subcategories (if there's more than 10) in Category:Wikipedia (the "cmcontinue" parameter is from the result above)

If you're using "cmcontinue" parameter for pages, the "cmtype=page" parameter is optional, but for subcategories (or files), the "cmtype=subcat" (or "cmtype=file") is necessary.

Error Codes[edit | edit source]

  • code: cmnotitle
    • info: The cmtitle parameter is required
  • code: cminvalidcategory
    • info: The category name you entered is not valid
  • code: cmbadcontinue
    • info: Invalid continue param. You should pass the original value returned by the previous query

Retrieving via AJAX[edit | edit source]

Below is sample code for retrieving the category list via an Ajax request:

function asyncGetCategoryList( categoryName ) {
    $.ajax({
        url: mw.util.wikiScript( 'api' ),
        data: {
            // For parameter documentation, visit <http://en.wikipedia.org/w/api.php> and then search for "list=categorymembers"
            format: 'json',
            action: 'query',
            list: 'categorymembers',
            cmtitle: 'Category:' + categoryName,
            cmtype: 'subcat',
        },
        dataType: 'json',
        type: 'GET',
        success: function( data ) {
            if ( data && data.query && data.query.categorymembers ) {
                // ... success ...
            } else if ( data && data.error ) {
                // Will this ever happen??
                alert( 'Error: API returned error code "' + data.error.code + '": ' + data.error.info );
            } else {
                alert( 'Error: Unknown result from API.' );
            }
        },
        error: function( xhr ) {
            // ... error ...
        }
    });
}