🌎 Java Wiki Api

Java Wiki Api is a comprehensive tool for flexible creation of detailed queries to the Wikipedia online encyclopedia. It uses declarative approach and provides built-in types for results.

Installation

This library is available on maven central. The latest version is always shown in the releases page.

The build requires JDK 17 or later.

Maven

<dependency>
    <groupId>io.github.masterflomaster1</groupId>
    <artifactId>java-wiki-api</artifactId>
    <version>0.11.0</version>
</dependency>

Gradle

dependencies {
    implementation("io.github.masterflomaster1:java-wiki-api:0.11.0")
}

Usage

This section explains the basic principles of working with the MediaWiki API, commonly used in Wikipedia and other MediaWiki-based projects. The API allows you to retrieve and manipulate wiki data by sending requests with specific parameters like action, prop, list, and meta.

WikiApi api = new WikiApi();

var a = new WikiApiRequest.Builder()
        .action(new QueryAction.Builder().build())
        .build();

Response r = api.execute(a);

1. Action

The action parameter defines what action the API should perform. Supported actions:

Name	Description
antispoof	Check a username against AntiSpoof's normalisation checks
block	Block a user
centralauthtoken	Fetch a centralauthtoken for making an authenticated request to an attached wiki
checktoken	Check the validity of a token
compare	Get the difference between two pages
createaccount	Create a new user account
delete	Delete a page
emailuser	Email a user
languagesearch	Search for language names in any script
opensearch	Search the wiki using the OpenSearch protocol
parse	Parses content and returns parser output
query	Fetch data from and about MediaWiki
review	Review a revision by approving or de-approving it
shortenurl	Shorten a long URL into a shorter one
sitematrix	Get Wikimedia sites list
spamblacklist	Validate one or more URLs against the spam block list
thank	Send a thank-you notification to an editor
titleblacklist	Validate a page title, filename, or username against the TitleBlacklist
torblock	Check if an IP address is blocked as a Tor exit node
validatepassword	Validate a password against the wiki's password policies
watch	Add or remove pages from the current user's watchlist

Example:

var a = new WikiApiRequest.Builder()
        .action(new QueryAction.Builder().build())
        .build();

2. Properties

When using query action, the prop parameter specifies which properties of pages or objects you want to retrieve. This includes page content, contributors, templates, and more. Supported props:

Name	Description
categories	List all categories the pages belong to
categoryinfo	Returns information about the given categories
contributors	Get the list of logged-in contributors and the count of anonymous contributors to a page
extlinks	Returns all external URLs (not interwikis) from the given pages
fileusage	Find all pages that use the given files
globalusage	Returns global image usage for a certain image
imageinfo	Returns file information and upload history
images	Returns all files contained on the given pages
info	Get basic page information
isreviewed	Determine if a page is marked as reviewed
linkshere	Find all pages that link to the given pages
links	Returns all links from the given pages
pageviews	Shows per-page pageview data
redirects	Returns all redirects to the given pages
revisions	Get revision information
templates	Returns all pages transcluded on the given pages
transcodestatus	Get transcode status for a given file page
videoinfo	Extends imageinfo to include video source (derivatives) information

Example:

Returns all files contained on the wikipedia page about Java

var a = new WikiApiRequest.Builder()
        .action(new QueryAction.Builder()
                .prop(Set.of(new ImagesProp.Builder().build()))
                .titles(Set.of("Java (programming language)"))
                .build()
        )
        .build();

3. Lists

The list parameter is used to retrieve lists of various objects, such as pages, categories, users, or links. Supported lists:

Name	Description
allcategories	Enumerate all categories
allfileusages	List all file usages, including non-existing
allimages	Enumerate all images sequentially
alllinks	Enumerate all links that point to a given namespace
allpages	Enumerate all pages sequentially in a given namespace
allusers	Enumerate all registered users
backlinks	Find all pages that link to the given page
betafeatures	List all BetaFeatures
blocks	List all blocked users and IP addresses
categorymembers	List all pages in a given category
exturlusage	Enumerate pages that contain a given URL
filearchive	Enumerate all deleted files sequentially
imageusage	Find all pages that use the given image title
prefixsearch	Perform a prefix search for page titles
projects	List all the projects
protectedtitles	List all titles protected from creation
random	Get a set of random pages
recentchanges	Enumerate recent changes
tags	List change tags
usercontribs	Get all edits by a user
users	Get information about a list of users

Example:

List recent changes.

var a = new WikiApiRequest.Builder()
        .action(new QueryAction.Builder()
                .list(Set.of(new RecentChangesList.Builder().build()))
                .build()
        )
        .build();

4. Meta

The meta parameter is used to retrieve general information about the wiki, users, or statistics. Supported meta:

Name	Description
globaluserinfo	Show information about a global user
languageinfo	Return information about available languages
siteinfo	Return general information about the site
siteviews	Shows sitewide pageview data
tokens	Gets tokens for data-modifying actions
userinfo	Get information about the current user

Example:

Show sitewide pageview totals.

var a = new WikiApiRequest.Builder()
        .action(new QueryAction.Builder()
                .meta(Set.of(
                        new SiteViewsMeta.Builder()
                                .pvIsMetric(SiteViewsMeta.PvIsMetric.UNIQUES)
                                .build()
                ))
                .build()
        )
        .build();

Contributing

Feel free to open an issue if you've found a bug or want to raise a question, or discuss a possible feature. Any help is appreciated :)

More Examples

• Actions

  • antispoof
    • Check username "Foo" against AntiSpoof
  • block
    • Block IP address 192.0.2.5 for three days with a reason
    • Block user Vandal indefinitely with a reason, and prevent new account creation and email sending
  • centralauthtoken
    • Fetch a centralauthtoken
  • checktoken
    • Test the validity of a csrf token
  • compare
    • Create a diff between revision 1246320177 and 1242717618
  • delete
    • Delete Main Page
    • Delete Main Page with the reason Preparing for move
  • emailuser
    • Send an email to the user WikiSysop with the text Content
  • languagesearch
    • Search for "Te"
    • Search for "ഫി"
    • Search for "ഫി", allowing one typo
  • opensearch
    • Find pages beginning with Te
  • parse
    • Parse a page
    • Parse wikitext
    • Parse wikitext, specifying the page title
  • query
    • Fetch site info and revisions of Main Page
  • review
    • Approve revision 12345 with comment "Ok"
  • shortenurl
    • Get the short URL for https://en.wikipedia.org/wiki/Arctica
    • Get a QR code for https://en.wikipedia.org/wiki/Arctica
  • sitematrix
    • Show the site matrix
  • spamblacklist
    • Check two URLs against the block list
  • thank
    • Send thanks for revision ID 456, with the source being a diff page
  • titleblacklist
    • Check whether Foo is blacklisted
    • Check whether Bar is blacklisted for editing
  • torblock
    • Check if the IP address 192.0.2.18 is blocked as a Tor exit node
  • validatepassword
    • Validate the password foobar for the current user
    • Validate the password qwerty for creating user Example
  • watch
    • Watch the page Main Page
    • Watch the pages Main Page, Foo, and Bar for one month
    • Unwatch the page Main Page

• List

  • allcategories
    • List categories with information on the number of pages in each
  • allfileusages
    • List file titles, including missing ones, with page IDs they are from, starting at B
    • List unique file titles
  • allimages
    • Show a list of files starting at the letter B
    • Show a list of recently uploaded files, similar to Special:NewFiles
  • alllinks
    • List linked titles, including missing ones, with page IDs they are from, starting at B
  • allpages
    • Show a list of pages starting at the letter B
  • allusers
    • List users starting at Y
  • backlinks
    • Show links to Main Page
  • betafeatures
    • Get all available beta features and show how many users have enabled them
  • blocks
    • List blocks
  • categorymembers
    • Get first 10 pages in Category:Physics
  • exturlusage
    • Show pages linking to https://www.mediawiki.org
  • filearchive
    • Show a list of all deleted files
  • imageusage
    • Show pages using File:Albert Einstein Head.jpg
  • prefixsearch
    • Search for page titles beginning with meaning
  • projects
    • Get a list of all the projects and subprojects
  • protectedtitles
    • List protected titles
  • random
    • Return two random pages from the main namespace
  • recentchanges
    • List recent changes
  • tags
    • List available tags
  • usercontribs
    • Show contributions of user Example
  • users
    • Return information for user Example

• Meta

  • globaluserinfo
    • Get information about the current global user
    • Get information about global user Example
  • languageinfo
    • Get the language codes of all supported languages
    • Get the autonyms and German names of all supported languages
    • Get the fallback languages and variants of Occitan
    • Get the BCP-47 language code and direction of all supported languages
  • siteinfo
    • Fetch site information.
  • siteviews
    • Show sitewide pageview totals
    • Show sitewide unique visitor totals
  • tokens
    • Retrieve a csrf token (the default)
    • Retrieve a watch token and a patrol token
  • userinfo
    • Get information about the current user
    • Get additional information about the current user

• Prop

  • categories
    • Get a list of categories the page Albert Einstein belongs to
  • categoryinfo
    • Get information about Category:Foo and Category:Bar
  • contributors
    • Show contributors to the page Main Page
  • extlinks
    • Get a list of external links on the page Main Page
  • fileusage
    • Get a list of pages using File:Example.jpg
  • globalusage
    • Get usage of File:Example.jpg
  • imageinfo
    • Fetch information about the current version of File:Albert Einstein Head.jpg
    • Fetch information about versions of File:Test.jpg from 2008 and later
  • images
    • Get a list of files used on the page Main Page
  • info
    • Get information about the page Main Page
  • isreviewed
    • Determine if Main Page is marked as reviewed
  • linkshere
    • Get a list of pages linking to the Main Page
  • links
    • Get links from the page Main Page
    • Get links from the page Main Page in the User and Template namespaces
  • pageviews
    • Show pageview statistics for the main page
  • redirects
    • Get a list of redirects to the Main Page
  • revisions
    • Get data with content for the last revision of titles API and Main Page
    • Get last 5 revisions of the Main Page
    • Get first 5 revisions of the Main Page
  • templates
    • Get the templates used on the page Main Page
    • Get pages in the User and Template namespaces that are transcluded on the page Main Page
  • transcodestatus
    • Get transcode status for File:Clip.webm
  • videoinfo
    • Fetch information about File:Folgers.ogv

Please refer to the Wikipedia API Sandbox for in-depth exploration.