API:Watchlist

MediaWiki version:
1.9

GET request to list pages on the current user's watchlist that were changed within the given time period, ordered by time of the last change of the watched page.

This module can be used as a generator .

API documentation edit


list=watchlist (wl)

(main | query | watchlist)
  • This module requires read rights.
  • This module can be used as a generator.
  • Source: MediaWiki
  • License: GPL-2.0-or-later

Get recent changes to pages in the current user's watchlist.

Specific parameters:
Other general parameters are available.
wlallrev

Include multiple revisions of the same page within given timeframe.

Type: boolean (details)
wlstart

The timestamp to start enumerating from.

Type: timestamp (allowed formats)
wlend

The timestamp to end enumerating.

Type: timestamp (allowed formats)
wlnamespace

Filter changes to only the given namespaces.

Values (separate with | or alternative): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 90, 91, 92, 93, 100, 101, 102, 103, 104, 105, 106, 107, 486, 487, 710, 711, 828, 829, 1198, 1199, 2600, 5500, 5501
To specify all values, use *.
wluser

Only list changes by this user.

Type: user, by any of username, IP, Temporary user, interwiki name (e.g. "prefix>ExampleName") and user ID (e.g. "#12345")
wlexcludeuser

Don't list changes by this user.

Type: user, by any of username, IP, Temporary user, interwiki name (e.g. "prefix>ExampleName") and user ID (e.g. "#12345")
wldir

In which direction to enumerate:

newer
List oldest first. Note: wlstart has to be before wlend.
older
List newest first (default). Note: wlstart has to be later than wlend.
One of the following values: newer, older
Default: older
wllimit

How many total results to return per request.

Type: integer or max
The value must be between 1 and 500.
Default: 10
wlprop

Which additional properties to get:

ids
Adds revision IDs and page IDs.
title
Adds title of the page.
flags
Adds flags for the edit.
user
Adds the user who made the edit. If the user has been revision deleted, a userhidden property will be returned.
userid
Adds user ID of whoever made the edit. If the user has been revision deleted, a userhidden property will be returned.
comment
Adds comment of the edit. If the comment has been revision deleted, a commenthidden property will be returned.
parsedcomment
Adds parsed comment of the edit. If the comment has been revision deleted, a commenthidden property will be returned.
timestamp
Adds timestamp of the edit.
patrol
Tags edits that are patrolled.
sizes
Adds the old and new lengths of the page.
notificationtimestamp
Adds timestamp of when the user was last notified about the edit.
loginfo
Adds log information where appropriate.
tags
Lists tags for the entry.
expiry
Adds the expiry time.
Values (separate with | or alternative): comment, expiry, flags, ids, loginfo, notificationtimestamp, parsedcomment, patrol, sizes, tags, timestamp, title, user, userid
Default: ids|title|flags
wlshow

Show only items that meet these criteria. For example, to see only minor edits done by logged-in users, set wlshow=minor|!anon.

Values (separate with | or alternative): !anon, !autopatrolled, !bot, !minor, !patrolled, !unread, anon, autopatrolled, bot, minor, patrolled, unread
wltype

Which types of changes to show:

edit
Regular page edits.
new
Page creations.
log
Log entries.
external
External changes.
categorize
Category membership changes.
Values (separate with | or alternative): categorize, edit, external, log, new
Default: edit|new|log|categorize
wlowner

Used along with wltoken to access a different user's watchlist.

Type: user, by username
wltoken

A security token (available in the user's preferences) to allow access to another user's watchlist.

wlcontinue

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

Examples:
List the top revision for recently changed pages on the current user's watchlist.
api.php?action=query&list=watchlist [open in sandbox]
Fetch additional information about the top revision for recently changed pages on the current user's watchlist.
api.php?action=query&list=watchlist&wlprop=ids|title|timestamp|user|comment [open in sandbox]
Fetch additional information about the top revision for recently changed pages on the current user's watchlist, including when temporarily watched items will expire.
api.php?action=query&list=watchlist&wlprop=ids|title|timestamp|user|comment|expiry [open in sandbox]
Fetch information about all recent changes to pages on the current user's watchlist.
api.php?action=query&list=watchlist&wlallrev=&wlprop=ids|title|timestamp|user|comment [open in sandbox]
Fetch page info for recently changed pages on the current user's watchlist.
api.php?action=query&generator=watchlist&prop=info [open in sandbox]
Fetch revision info for recent changes to pages on the current user's watchlist.
api.php?action=query&generator=watchlist&gwlallrev=&prop=revisions&rvprop=timestamp|user [open in sandbox]
List the top revision for recently changed pages on the watchlist of user Example.
api.php?action=query&list=watchlist&wlowner=Example&wltoken=123ABC [open in sandbox]

Example edit

GET request edit

Get the currently logged-in user's watchlist.


Response edit

{
  "batchcomplete": "",
  "query": {
    "watchlist": [
      {
        "ns": 1,
        "old_revid": 898447862,
        "pageid": 5858,
        "revid": 898447924,
        "title": "Talk:Software",
        "type": "edit"
      },
      {
        "ns": 0,
        "old_revid": 896386764,
        "pageid": 18934886,
        "revid": 897854521,
        "title": "Proprietary software",
        "type": "edit"
      },
      {
        "minor": "",
        "ns": 0,
        "old_revid": 894771707,
        "pageid": 1721496,
        "revid": 897348916,
        "title": "Free and open-source software",
        "type": "edit"
      }
    ]
  }
}

Sample code edit

Python edit

#!/usr/bin/python3

"""
    get_watchlist.py

    MediaWiki API Demos
    Demo of `Watchlist` module: Get the currently logged-in user's watchlist.

    MIT License
"""

import requests

S = requests.Session()

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

# Step 1: Retrieve a login token
PARAMS_1 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"
}

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

LOGIN_TOKEN = DATA['query']['tokens']['logintoken']

# Step 2: Send a post request to log in. For this login
# method, Obtain bot credentials by visiting
# https://en.wikipedia.org/wiki/Special:BotPasswords/
# See https://www.mediawiki.org/wiki/API:Login for more
# information on log in methods.
PARAMS_2 = {
    "action": "login",
    "lgname": "username",
    "lgpassword": "password",
    "format": "json",
    "lgtoken": LOGIN_TOKEN
}

R = S.post(URL, data=PARAMS_2)

# Step 3: While logged in, get the watchlist
PARAMS_3 = {
    "action": "query",
    "list": "watchlist",
    "format": "json"
}

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

print(DATA)

PHP edit

<?php

/*
    get_watchlist.php

	MediaWiki API Demos
	Demo of `Watchlist` module: Get the currently logged-in user's watchlist.
    MIT license
*/

$endPoint = "https://test.wikipedia.org/w/api.php";

$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
watchlist(); // Step 3

// Step 1: GET request to fetch login token
function getLoginToken() {
	global $endPoint;

	$params1 = [
		"action" => "query",
		"meta" => "tokens",
		"type" => "login",
		"format" => "json"
	];

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

	$ch = curl_init( $url );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

	$result = json_decode( $output, true );
	return $result["query"]["tokens"]["logintoken"];
}

// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
	global $endPoint;

	$params2 = [
		"action" => "login",
		"lgname" => "bot_user_name",
		"lgpassword" => "bot_password",
		"lgtoken" => $logintoken,
		"format" => "json"
	];

	$ch = curl_init();

	curl_setopt( $ch, CURLOPT_URL, $endPoint );
	curl_setopt( $ch, CURLOPT_POST, true );
	curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );
}

// Step 3: POST request to get the watchlist
function watchlist() {
	global $endPoint;

	$params4 = [
		"action" => "query",
		"list" => "watchlist",
		"format" => "json"
	];

	$ch = curl_init();

	curl_setopt( $ch, CURLOPT_URL, $endPoint );
	curl_setopt( $ch, CURLOPT_POST, true );
	curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params4 ) );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

	$result = json_decode( $output, true );

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

JavaScript edit

/*  
    get_watchlist.js

    MediaWiki API Demos
	Demo of `Watchlist` module: Get the currently logged-in user's watchlist.

    MIT license
*/

var request = require('request').defaults({jar: true}),
    url = "https://test.wikipedia.org/w/api.php";

// Step 1: GET request to fetch login token
function getLoginToken() {
    var params_0 = {
        action: "query",
        meta: "tokens",
        type: "login",
        format: "json"
    };

    request.get({ url: url, qs: params_0 }, function (error, res, body) {
        if (error) {
            return;
        }
        var data = JSON.parse(body);
        loginRequest(data.query.tokens.logintoken);
    });
}

// Step 2: POST request to log in. 
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest(login_token) {
    var params_1 = {
        action: "login",
        lgname: "bot_username",
        lgpassword: "bot_password",
        lgtoken: login_token,
        format: "json"
    };

    request.post({ url: url, form: params_1 }, function (error, res, body) {
        if (error) {
            return;
        }
        get_watchlist();
    });
}

// Step 3: POST request to get the watchlist
function get_watchlist() {
    var params_3 = {
        action: "query",
        list: "watchlist",
        format: "json"
    };

    request.post({ url: url, form: params_3 }, function (error, res, body) {
        if (error) {
            return;
        }
        console.log(body);
    });
}

// Start From Step 1
getLoginToken();

MediaWiki JS edit

/*
	get_watchlist.js

	MediaWiki API Demos
	Demo of `Watchlist` module: Get the currently logged-in user's watchlist.

	MIT License
*/

var params = {
		action: 'query',
		list: 'watchlist',
		format: 'json'
	},
	api = new mw.Api();

api.get( params ).done( function ( data ) {
	console.log( data );
} );

Possible errors edit

Code Info
wlnotloggedin You must be logged-in to have a watchlist
wlpatrol patrol property is not available
wlshow Incorrect parameter - mutually exclusive values may not be supplied.

Parameter history edit

  • v1.24: Introduced unread, !unread
  • v1.23: Introduced wlcontinue
  • v1.22: Introduced wltype
  • v1.18: Introduced loginfo
  • v1.17: Introduced userid
  • v1.16: Introduced wluser, wlexcludeuser, parsedcomment, notificationtimestamp, wlowner, wltoken
  • v1.14: Introduced patrolled, !patrolled
  • v1.12: Introduced wlshow
  • v1.11: Introduced ids, title, flags, sizes

Additional Notes edit

  • This module should not be confused with API:Watchlistraw , which lists all the pages on the logged in user's watchlist, regardless of whether they were recently changed or not.

See also edit