API:Users

This page is part of the MediaWiki Action API documentation.

MediaWiki version:

≥ 1.12

GET request to view information about a list of users.

API documentation

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

list=users (us)

(main | query | users)

This module requires read rights.
Source: MediaWiki
License: GPL-2.0-or-later

Get information about a list of users.

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

Specific parameters:

Other general parameters are available.

usprop

Which pieces of information to include:

blockinfo: Tags if the user is blocked, by whom, and for what reason.
groups: Lists all the groups each user belongs to.
groupmemberships: Lists groups that each user has been explicitly assigned to, including the expiry date of each group membership.
implicitgroups: Lists all the groups a user is automatically a member of.
rights: Lists all the rights each user has.
editcount: Adds the user's edit count.
registration: Adds the user's registration timestamp.
emailable: Tags if the user can and wants to receive email through Special:Emailuser.
gender: Tags the gender of the user. Returns "male", "female", or "unknown".
centralids: Adds the central IDs and attachment status for the user.
cancreate: Indicates whether an account for valid but unregistered usernames can be created. To check whether the current user can perform the account creation, use action=query&meta=userinfo&uiprop=cancreateaccount.

Values (separate with | or alternative): blockinfo, cancreate, centralids, editcount, emailable, gender, groupmemberships, groups, implicitgroups, registration, rights

usattachedwiki

With usprop=centralids, indicate whether the user is attached with the wiki identified by this ID.

ususers

A list of users to obtain information for.

Separate values with | or alternative.

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

ususerids

A list of user IDs to obtain information for.

Type: list of integers

Separate values with | or alternative.

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

Example:

Return information for user Example.: api.php?action=query&list=users&ususers=Example&usprop=groups|editcount|gender [open in sandbox]

Example

GET request

Get a list of the specified users -- each item in the list contains information specified by the usprop parameter

Response

{
    "batchcomplete": "",
    "query": {
        "users": [
            {
                "name": "1.2.3.4",
                "invalid": ""
            },
            {
                "userid": 4587601,
                "name": "Catrope",
                "editcount": 359,
                "registration": "2007-06-07T16:36:03Z",
                "groups": [
                    "*",
                    "user",
                    "autoconfirmed"
                ],
                "emailable": "",
                "gender": "male"
            },
            {
                "name": "Vandal01",
                "missing": ""
            },
            {
                "userid": 2793024,
                "name": "Bob",
                "editcount": 4542,
                "registration": "2006-11-18T21:55:03Z",
                "groups": [
                    "extendedconfirmed",
                    "reviewer",
                    "*",
                    "user",
                    "autoconfirmed"
                ],
                "emailable": "",
                "gender": "male"
            }
        ]
    }
}

Sample code

Python

#!/usr/bin/python3

"""
    get_users.py

    MediaWiki API Demos
    Demo of `Users` module: Get information about several users:
    [[1.2.3.4]], [[Catrope]], [[Vandal01]], and [[Bob]]

    MIT License
"""

import requests

S = requests.Session()

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

PARAMS = {
    "action": "query",
    "format": "json",
    "list": "users",
    "ususers": "Catrope|Bob",
    "usprop": "blockinfo|groups|editcount|registration|emailable|gender"
}

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

USERS = DATA["query"]["users"]

for u in USERS:
    print(str(u["name"]) + " has " + str(u["editcount"]) + " edits.")

PHP

<?php
/*
    get_users.php

    MediaWiki API Demos
    Demo of `Users` module: Get information about several users: [[1.2.3.4]], [[Catrope]], [[Vandal01]], and [[Bob]]

    MIT License
*/

$endPoint = "https://en.wikipedia.org/w/api.php";
$params = [
    "action" => "query",
    "list" => "users",
    "ususers" => "Catrope|Bob",
    "usprop" => "blockinfo|groups|editcount|registration|emailable|gender",
    "format" => "json"
];

$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"]["users"] as $user ){
    echo( $user["name"] . " has " . $user["editcount"] . " edits." . "\n" );
}

JavaScript

/*
    get_users.js

    MediaWiki API Demos
    Demo of `Users` module: Get information about several users: [[1.2.3.4]], [[Catrope]], [[Vandal01]], and [[Bob]]

    MIT License
*/

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

var params = {
    action: "query",
    list: "users",
    ususers: "Catrope|Bob",
    usprop: "blockinfo|groups|editcount|registration|emailable|gender",
    format: "json"
};

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 users = response.query.users;
        for (var u in users) {
            console.log(users[u].name + " has " + users[u].editcount + " edits.");
        }
    })
    .catch(function(error){console.log(error);});

MediaWiki JS

/*
	get_users.js

	MediaWiki API Demos
	Demo of `Users` module: Get information about several users: [[1.2.3.4]], [[Catrope]], [[Vandal01]], and [[Bob]]

	MIT License
*/

var params = {
		action: 'query',
		list: 'users',
		ususers: 'Catrope|Bob',
		usprop: 'blockinfo|groups|editcount|registration|emailable|gender',
		format: 'json'
	},
	api = new mw.Api();

api.get( params ).done( function ( data ) {
	var users = data.query.users,
		u;
	for ( u in users ) {
		console.log( users[ u ].name + " has " + users[ u ].editcount + " edits.");
	}
} );

Parameter history

v1.29: Introduced ususerids, userrights
v1.24: Deprecated ustoken
v1.18: Introduced implicitgroups
v1.17: Introduced rights
v1.16: Introduced ususerids, gender
v1.14: Introduced emailable
v1.13: Introduced registration