API:Random

This page is part of the MediaWiki Action API documentation.

MediaWiki version:

≥ 1.12

GET request to view a list of random pages.

This module can be used as a generator .

API documentation

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

list=random (rn)

(main | query | random)

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

Get a set of random pages.

Pages are listed in a fixed sequence, only the starting point is random. This means that if, for example, Main Page is the first random page in the list, List of fictional monkeys will always be second, List of people on stamps of Vanuatu third, etc.

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

Specific parameters:

Other general parameters are available.

rnnamespace: Return pages in these namespaces only.; 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 *.
rnfilterredir: How to filter for redirects.; One of the following values: all, nonredirects, redirects; Default: nonredirects
rnredirect: Deprecated.; Use rnfilterredir=redirects instead.; Type: boolean (details)
rnlimit: Limit how many random pages will be returned.; Type: integer or max; The value must be between 1 and 500.; Default: 1
rncontinue: When more results are available, use this to continue. More detailed information on how to continue queries can be found on mediawiki.org.

Examples:

Return two random pages from the main namespace.: api.php?action=query&list=random&rnnamespace=0&rnlimit=2 [open in sandbox]
Return page info about two random pages from the main namespace.: api.php?action=query&generator=random&grnnamespace=0&grnlimit=2&prop=info [open in sandbox]

Example

GET request

List 5 random pages

api.php?action=query&format=json&list=random&rnlimit=5 [try in ApiSandbox]

Response

{

"batchcomplete": "",
    "continue": {
        "rncontinue": "0.559881820010|0.559881954661|47659388|0",
        "continue": "-||"
    },
    "query": {
        "random": [
            {
                "id": 32381675,
                "ns": 0,
                "title": "Mallabhum Institute of Technology"
            },
            {
                "id": 25126452,
                "ns": 3,
                "title": "User talk:96.232.132.176"
            },
            {
                "id": 1440028,
                "ns": 0,
                "title": "Hyundai Epsilon engine"
            },
            {
                "id": 35446805,
                "ns": 15,
                "title": "Category talk:Ukrainian card games"
            },
            {
                "id": 12613,
                "ns": 0,
                "title": "Grue"
            }
        ]
    }
}

Sample code

Python

#!/usr/bin/python3

"""
    get_random.py

    MediaWiki API Demos
    Demo of `Random` module: Get request to list 5 random pages.

    MIT License
"""

import requests

S = requests.Session()

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

PARAMS = {
    "action": "query",
    "format": "json",
    "list": "random",
    "rnlimit": "5"
}

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

RANDOMS = DATA["query"]["random"]

for r in RANDOMS:
    print(r["title"])

PHP

<?php
/*
    get_random.php

    MediaWiki API Demos
    Demo of `Random` module: Get request to list 5 random pages.

    MIT License
*/

$endPoint = "https://en.wikipedia.org/w/api.php";
$params = [
    "action" => "query",
    "format" => "json",
    "list" => "random",
    "rnlimit" => "5"
];

$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"]["random"] as $k => $v ) {
    echo( $v["title"] . "\n" );
}

JavaScript

/*
    get_random.js

    MediaWiki API Demos
    Demo of `Random` module: Get request to list 5 random pages.

    MIT License
*/

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

var params = {
    action: "query",
    format: "json",
    list: "random",
    rnlimit: "5"
};

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 randoms = response.query.random;
        for (var r in randoms) {
            console.log(randoms[r].title);
        }
    })
    .catch(function(error){console.log(error);});

MediaWiki JS

/*
	get_random.js

	MediaWiki API Demos
	Demo of `Random` module: Get request to list 5 random pages.

	MIT License
*/

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

api.get( params ).done( function ( data ) {
	var randoms = data.query.random,
		r;
	for ( r in randoms ) {
		console.log( randoms[ r ].title );
	}
} );

Parameter history

v1.26: Previous limit of 10/20 on rnlimit was increased to standard 500/5000 limits.
v1.26: Deprecated rnredirect
v1.26: Introduced rnfilterredir
v1.14: Introduced rnredirect

Additional notes

Unlike most modules in the Action API , the default number of pages returned is 1, not 10.
Pages are returned in a fixed sequence; only the starting point is actually random.
The default behavior is to pick pages from across the entire wiki, including talk pages, user pages, and so on. If you are looking for similar functionality as Special:Random, i.e. pick random articles, restrict rnnamespace to 0.
If the number of pages is fewer than rnlimit, the request will simply return all available pages. It will not repeat pages to pad out the response up to the limit.