API:Categorymembers

This page is part of the MediaWiki API documentation.

Language:	English

MediaWiki API

Quick overview:

• Quick start guide
• FAQ
  • Etiquette and usage limits
• Tutorial
• Formats
• Error reporting
• Restricting usage
• Cross-site requests
• Authentication
  • Login
  • Logout
  • Account creation
• Queries
  • Meta information
  • Properties
  • Lists
• Search suggestions
• Expanding templates and rendering
• Purging pages' caches
• Parameter information
• Changing wiki content
  • Create and edit pages
  • Move pages
  • Rollback
  • Delete pages
  • Restore deleted revisions
  • (Un)protect pages
  • (Un)block users
  • (Un)watch pages
  • Send email
  • Patrol changes
  • Import pages
  • Change user group membership
  • Upload files
  • User options
• Watchlist feed
• Wikidata
• Extensions
• Using the API in MediaWiki and extensions
• Miscellaneous
• Implementation
• Client code

MediaWiki version:

1.11

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

Parameters

• 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 2013. Note: cmstart has to be before cmend
  • desc: From Z to A or from 2013 to 2002 Note: cmstart has to be later than cmend
• cmlimit: Maximum amount 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

Get the 10 articles most recently added to Category:Physics

api.php?action=query&list=categorymembers&cmtitle=Category:Physics&cmsort=timestamp&cmdir=desc

Error Codes

• 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

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