API:Categories

This page is part of the MediaWiki Action API documentation.

MediaWiki version:

≥ 1.11

GET request to view categories associated with a page or pages.

This module can be used as a generator .

API documentation

The following documentation is the output of Special:ApiHelp/query+categories, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org).

prop=categories (cl)

(main | query | categories)

This module requires read rights.
This module can be used as a generator.
Source: MediaWiki
License: GPL-2.0-or-later

List all categories the pages belong to.

https://www.mediawiki.org/wiki/Special:MyLanguage/API:Categories

Specific parameters:

Other general parameters are available.

clprop

Which additional properties to get for each category:

sortkey: Adds the sortkey (hexadecimal string) and sortkey prefix (human-readable part) for the category.
timestamp: Adds timestamp of when the category was added.
hidden: Tags categories that are hidden with __HIDDENCAT__.

Values (separate with | or alternative): hidden, sortkey, timestamp

clshow

Which kind of categories to show.

Values (separate with | or alternative): !hidden, hidden

cllimit

How many categories to return.

Type: integer or max

The value must be between 1 and 500.

Default: 10

clcontinue

When more results are available, use this to continue. More detailed information on how to continue queries can be found on mediawiki.org.

clcategories

Only list these categories. Useful for checking whether a certain page is in a certain category.

Separate values with | or alternative.

Maximum number of values is 50 (500 for clients that are allowed higher limits).

cldir

The direction in which to list.

One of the following values: ascending, descending

Default: ascending

Examples:

Get a list of categories the page Albert Einstein belongs to.: api.php?action=query&prop=categories&titles=Albert%20Einstein [open in sandbox]
Get information about all categories used in the page Albert Einstein.: api.php?action=query&generator=categories&titles=Albert%20Einstein&prop=info [open in sandbox]

Example

GET request

GET request to view categories on a page.

api.php?action=query&format=json&titles=Janelle%20Monáe&prop=categories [try in ApiSandbox]

Response

{
    "continue": {
        "clcontinue": "13828397|Afrofuturists",
        "continue": "||"
    },
    "query": {
        "pages": {
            "13828397": {
                "pageid": 13828397,
                "ns": 0,
                "title": "Janelle Mon\u00e1e",
                "categories": [
                    {
                        "ns": 14,
                        "title": "Category:1985 births"
                    },
                    {
                        "ns": 14,
                        "title": "Category:21st-century American actresses"
                    },
                    {
                        "ns": 14,
                        "title": "Category:21st-century American singers"
                    },
                    ...
                ]
            }
        }
    }
}

Sample code

Python

#!/usr/bin/python3

"""
    get_categories.py

    MediaWiki API Demos
    Demo of `Categories` module: Get categories associated with a page.

    MIT License
"""

import requests

S = requests.Session()

URL = "https://en.wikipedia.org/w/api.php"

PARAMS = {
    "action": "query",
    "format": "json",
    "prop": "categories",
    "titles": "Janelle Monáe"
}

R = S.get(url=URL, params=PARAMS)
DATA = R.json()

PAGES = DATA["query"]["pages"]

for k, v in PAGES.items():
    for cat in v['categories']:
        print(cat["title"])

PHP

<?php
/*
    get_categories.php

    MediaWiki API Demos
    Demo of `Categories` module: Get categories associated with a page.

    MIT License
*/

$endPoint = "https://en.wikipedia.org/w/api.php";
$params = [
    "action" => "query",
    "format" => "json",
    "prop" => "categories",
    "titles" => "Janelle Monáe"
];

$url = $endPoint . "?" . http_build_query( $params );

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
$output = curl_exec( $ch );
curl_close( $ch );

$result = json_decode( $output, true );

foreach( $result["query"]["pages"] as $k => $v ) {
    foreach( $v["categories"] as $k => $v ) {
        echo( $v["title"] . "\n" );
    }
}

JavaScript

/*
    get_categories.js

    MediaWiki API Demos
    Demo of `Categories` module: Get categories associated with a page.

    MIT License
*/

var url = "https://en.wikipedia.org/w/api.php"; 

var params = {
    action: "query",
    format: "json",
    prop: "categories",
    titles: "Janelle Monáe"
};

url = url + "?origin=*";
Object.keys(params).forEach(function(key){url += "&" + key + "=" + params[key];});

fetch(url)
    .then(function(response){return response.json();})
    .then(function(response) {
        var pages = response.query.pages;
        for (var p in pages) {
            for (var cat of pages[p].categories) {
                console.log(cat.title);
            }
        }
    })
    .catch(function(error){console.log(error);});

MediaWiki JS

/*
	get_categories.js

	MediaWiki API Demos
	Demo of `Categories` module: Get categories associated with a page.

	MIT License
*/

var params = {
		action: 'query',
		format: 'json',
		prop: 'categories',
		titles: 'Janelle Monáe'
	},
	api = new mw.Api();

api.get( params ).done( function ( data ) {
	var pages = data.query.pages,
		p;
	for ( p in pages ) {
		pages[ p ].categories.forEach( function ( cat ) {
			console.log( cat.title );
		} );
	}
} );

Possible errors


Code	Info
clshow	Incorrect parameter - mutually exclusive values may not be supplied.

Parameter history

v1.20: Introduced cldir
v1.16: Introduced clprop=hidden
v1.15: Introduced clcategories
v1.14: Introduced clshow
v1.13: Introduced clcontinue, cllimit, clprop=timestamp