API:Watchlistraw

This page is part of the MediaWiki Action API documentation.

MediaWiki version:

≥ 1.14

GET request to list all the pages on the logged in user's watchlist, regardless of whether they were recently changed or not.

This module can be used as a generator.

API documentation

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

list=watchlistraw (wr)

(main | query | watchlistraw)

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

Get all pages on the current user's watchlist.

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

Specific parameters:

Other general parameters are available.

wrcontinue

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

wrnamespace

Only list pages in 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 *.

wrlimit

How many total results to return per request.

Type: integer or max

The value must be between 1 and 500.

Default: 10

wrprop

Which additional properties to get:

changed: Adds timestamp of when the user was last notified about the edit.

Values (separate with | or alternative): changed

wrshow

Only list items that meet these criteria.

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

wrowner

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

Type: user, by username

wrtoken

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

wrdir

The direction in which to list.

One of the following values: ascending, descending

Default: ascending

wrfromtitle

Title (with namespace prefix) to begin enumerating from.

wrtotitle

Title (with namespace prefix) to stop enumerating at.

Examples:

List pages on the current user's watchlist.: api.php?action=query&list=watchlistraw [open in sandbox]
Fetch page info for pages on the current user's watchlist.: api.php?action=query&generator=watchlistraw&gwrshow=changed&prop=info [open in sandbox]

Example

GET request

Get three pages on the logged-in user's watchlist from the main namespace.

api.php?action=query&format=json&list=watchlistraw&wrnamespace=0&wrlimit=3 [try in ApiSandbox]

Response

{
  "batchcomplete": "",
  "continue": {
    "continue": "-||",
    "wrcontinue": "0|Software"
  },
  "watchlistraw": [
    {
      "ns": 0,
      "title": "Free and open-source software"
    },
    {
      "ns": 0,
      "title": "Free software"
    },
    {
      "ns": 0,
      "title": "Proprietary software"
    }
  ]
}

Sample code

Python

#!/usr/bin/python3

"""
    get_watchlistraw.py

    MediaWiki API Demos
    Demo of `Watchlistraw` module: Get three pages on the logged-in user's
    watchlist from the main namespace.

    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": "watchlistraw",
    "format": "json",
    "wrnamespace": "0",
    "wrlimit": "3"
}

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

print(DATA)

PHP

<?php

/*
    get_watchlistraw.php

    MediaWiki API Demos
    Demo of `Watchlistraw` module: Get three pages on the logged-in user's
	watchlist from the main namespace.
	
    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: GET request to get the watchlist
function watchlist() {
	global $endPoint;

	$params3 = [
		"action" => "query",
		"list" => "watchlistraw",
		"wrnamespace" => "0",
		"wrlimit" => "3",
		"format" => "json"
	];

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

	$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 );

	echo ( $output );
}

JavaScript

/*  
    get_watchlistraw.js

    MediaWiki API Demos
	Demo of `Watchlistraw` module: Get three pages on the logged-in user's
	watchlist from the main namespace.

    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_watchlistraw();
    });
}

// Step 3: POST request to get the watchlist
function get_watchlistraw() {
    var params_3 = {
        action: "query",
        list: "watchlistraw",
        wrnamespace: "0",
		wrlimit: "3",
        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

/*
	get_watchlistraw.js

	MediaWiki API Demos
	Demo of `Watchlistraw` module: Get three pages on the logged-in user's
    watchlist from the main namespace.

	MIT License
*/

var params = {
		action: 'query',
		list: 'watchlistraw',
		wrnamespace: '0',
		wrlimit: '3',
		format: 'json'
	},
	api = new mw.Api();

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

Possible errors

Code	Info
bad_wlowner	Specified user does not exist.
bad_wltoken	Incorrect watchlist token provided. Please set a correct token in Special:Preferences.
notloggedin	You must be logged-in to have a watchlist.
show	Incorrect parameter - mutually exclusive values may not be supplied.

Parameter history

v1.20: Introduced wrdir
v1.17: Introduced wrowner, wrtoken

Additional notes

This module should not be confused with API:Watchlist , which returns 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.
The results of this query module are returned as part of the api node, not the query node.

v t e Watchlists
API modules	Watch Watchlist Watchlistraw Watchlist feed
Configuration settings	$wgEnotifWatchlist $wgRCShowWatchingUsers $wgRCWatchCategoryMembership $wgReadOnlyWatchedItemStore $wgShowUpdatedMarker $wgStructuredChangeFiltersLiveUpdatePollingRate $wgUnwatchedPageSecret $wgUnwatchedPageThreshold $wgWatchersMaxAge $wgWatchlistExpiry $wgWatchlistExpiryMaxDuration $wgWatchlistPurgeRate
Database tables	watchlist watchlist_expiry
Help pages	Watchlist Watchlist expiry Watching pages
Hooks	ApiQueryWatchlistExtractOutputData ApiQueryWatchlistPrepareWatchedItemQueryServiceOptions BeforeResetNotificationTimestamp ChangesListSpecialPageQuery ChangesListSpecialPageStructuredFilters SendWatchlistEmailNotification SpecialWatchlistGetNonRevisionTypes WatchArticle WatchArticleComplete WatchlistEditorBeforeFormRender WatchlistEditorBuildRemoveLine WatchedItemQueryServiceExtensions UnwatchArticle UnwatchArticleComplete
Jobs	ClearUserWatchlistJob ClearWatchlistNotificationsJob WatchlistExpiryJob
Maintenance scripts	cleanupWatchlist.php purgeExpiredWatchlistItems.php
Special pages	Special:Watchlist Special:EditWatchlist