API:Watchlist

From MediaWiki.org
Jump to navigation Jump to search

Other languages:
Bahasa Indonesia • ‎English • ‎polski • ‎русский • ‎中文 • ‎日本語
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.

Parameters:
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, 828, 829, 1198, 1199, 2300, 2301, 2302, 2303, 2600, 5500, 5501
To specify all values, use *.
wluser

Only list changes by this user.

Type: user name
wlexcludeuser

Don't list changes by this user.

Type: user name
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.

No more than 500 (5,000 for bots) allowed.
Type: integer or max
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.
userid
Adds user ID of whoever made the edit.
comment
Adds comment of the edit.
parsedcomment
Adds parsed comment of the edit.
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.
Values (separate with | or alternative): ids, title, flags, user, userid, comment, parsedcomment, timestamp, patrol, sizes, notificationtimestamp, loginfo, tags
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): minor, !minor, bot, !bot, anon, !anon, patrolled, !patrolled, autopatrolled, !autopatrolled, unread, !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): edit, new, log, external, categorize
Default: edit|new|log|categorize
wlowner

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

Type: user name
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.

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 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]

  • API:Watchlistraw - Get all the pages on the logged in user's watchlist, regardless of whether they were recently changed or not.
  • API:Watchlist feed - Get the RSS feed of a user's watchlist.