API:Categorymembers

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png This page is part of the MediaWiki API documentation.
Language: English
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
  • cmstartsortkey: Start listing at this hexadecimal sortkey. Can only be used with cmsort=sortkey
  • cmendsortkey: 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 cmstartsortkey
  • 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 cmendsortkey
  • cmsort: Property to sort by
    • sortkey: The article's sort key (default)
    • 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 cmstartsortkey value is decoded value of hexsortkey.

Example[edit | edit source]

Get the 10 articles most recently added to Category:Physics

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 ...
        }
    });
}