MediaWiki API client written in node.js
- At minimum Node.js at the maintenance version
npm install nodemw
Or Download the latest stable version via GitHub.
git clone https://github.com/macbre/nodemw.git
- HTTP requests are stored in the queue and performed in parallel with limited number of "threads" (i.e. there's no risk of flooding the server)
- articles creation / edit / move / delete
- file uploads (using given content or via provided URL)
- Special:Log processing
- listing articles in categories
- and much more
- getting claims from WikiData
- Over 10k edits on Poznań Wiki as Pyrabot - scripts repository
An example script can be found in /examples
directory.
cd examples
node pagesInCategory.js
You can enter debug mode by setting DEBUG
enviromental variable:
DEBUG=1 node examples/pagesInCategory.js
You can enter dry-run mode (all "write" operations like edits and uploads will be disabled) by setting DRY_RUN
environmental variable (or dryRun
entry in the config):
DRY_RUN=1 node examples/pagesInCategory.js
npm test
var bot = require("nodemw");
// pass configuration object
var client = new bot({
protocol: "https", // Wikipedia now enforces HTTPS
server: "en.wikipedia.org", // host name of MediaWiki-powered site
path: "/w", // path to api.php script
debug: false, // is more verbose when set to true
});
client.getArticle("foo", function (err, data) {
// error handling
if (err) {
console.error(err);
return;
}
// ...
});
nodemw can use config files as well as objects directly provided to bot
object constructor.
// read config from external file
var client = new bot("config.js");
Config file is a JSON-encoded object with the following fields (see /examples/config-DIST.js
file):
{
"protocol": "https", // default to 'http'
"server": "en.wikipedia.org", // host name of MediaWiki-powered site
"path": "/w", // path to api.php script
"debug": false, // is more verbose when set to true
"username": "foo", // account to be used when logIn is called (optional)
"password": "bar", // password to be used when logIn is called (optional)
"domain" : "auth.bar.net", // domain to be used when logIn is called (optional)
"userAgent": "Custom UA", // define custom bot's user agent
"concurrency": 5 // how many API requests can be run in parallel (defaults to 3)
}
nodemw allows you make direct calls to MediaWiki API (example querying Semantic MediaWiki API):
var bot = require("nodemw"),
client = new bot({
server: "semantic-mediawiki.org",
path: "/w",
}),
params = {
action: "ask",
query:
"[[Modification date::+]]|?Modification date|sort=Modification date|order=desc",
};
client.api.call(
params /* api.php parameters */,
function (
err /* Error instance or null */,
info /* processed query result */,
next /* more results? */,
data /* raw data */,
) {
console.log(data && data.query && data.query.results);
},
);
The last parameter of each function in nodemw API is a callback which will be fired when the requested action is done.
Callbacks use node.js style - err
is always passed as the first argument.
Log-in using given credentials - read more
Gets the list of all categories on a wiki
Gets the list of all pages from the main namespace (excludes redirects) - read more
Gets the list of pages in a given category - read more
Gets the list of pages in a given namespace - read more
Gets the list of pages by a given prefix - read more
Gets the list of pages that transclude the given pages - read more
Gets article content and redirect info - read more
Gets all revisions of a given article - read more
Gets all categories a given article is in - read more
Gets all info of a given article - read more
Creates / edits an article (and mark the edit as minor if minor is set to true) - read more
Adds given content to the end of the page - read more
Adds given content to the beginning of the page - read more
Add a Flow topic - read more
Deletes an article - read more
Purge a given list of articles (titles or page IDs can be provided) - read more
By providing
Category:Foo
astitles
argument you can purge all pages in a given category (available since MW 1.21)
Protect a page (A title or page ID can be provided) - read more
The protections
value is an Array of protection information in the format:
{
action: string,
level?: string = 'all',
expiry?: string | number = 'never'
}
Calls to the Protect endpoint are not additive. Each call must include a list of all intended protections, including any already in place. Each call will replace all existing protections.
Send an email to an user - read more
Returns token required for a number of MediaWiki API operations - read more / for MW 1.24+
Gets information about current bot's user (including rights and rate limits) - read more
Gets information about a specific user (including rights, current block, groups) - read more
Gets information about specific users (including rights, current block, groups) - read more
Create account using given credentials - read more
Moves (aka renames) given article - read more
Gets list of all images on a wiki
Gets list of all articles using given image
Get list of all images that are used on a given page - read more
Gets metadata (including uploader, size, dimensions and EXIF data) of given image
Get entries form Special:Log - read more
Returns XML with preprocessed wikitext - read more
Returns parsed wikitext - read more
Makes a GET request to provided resource and returns its content.
Returns entries from recent changes (starting from a given point)
Returns site information entries - read more
Returns site statistics (number of articles, edits etc) - read more
Returns the version of MediaWiki given site uses - read more
Returns entries from QueryPage-based special pages
Uploads a given raw content as a File:[filename] - read more
Uploads a given external resource as a File:[filename]
Uploads a given video as a File:[filename] (Wikia-specific API)
Gets a value of a given template parameter from article's preparsed content (see expandTemplates)
Gets all external links used in article
Gets all articles that links to given article
Performs a search
Gets config entry value (returns def
value if not found)
Sets config entry value
Returns a diff colored using ANSI colors (powered by diff)
Wikia-specific bot methods
They're grouped in
bot.wikia
"namespace".
Get wiki-specific settings (like ThemeDesigner colors and hubs).
Get information (avatar, number of edits) about a given user
Get information (avatar, number of edits) about a given set of users (by their IDs)
This API is Promise-based, use await
keyword.
Examples:
const wikidata = require("nodemw/lib/wikidata");
const client = new wikidata();
// Where is Saksun, Faroe Islands located?
const geo = await client.getEntityClaim(
"Q928875" /* Saksun */,
"P625" /* place location */,
);
// will give you the geolocation of the place
expect(geo[0].mainsnak.datavalue.value).toMatchObject({
latitude: 62.248888888889,
longitude: -7.1758333333333,
});
// When was Albert Einstein born?
const res = await client.getArticleClaims("Albert Einstein");
const dateOfBirth = res.P569[0].mainsnak.datavalue.value;
expect(dateOfBirth.time).toMatch(/1879-03-14/);
const dateOfDeath = res.P570[0].mainsnak.datavalue.value;
expect(dateOfDeath.time).toMatch(/1955-04-18/);
// interwiki links for a given artlice
const links = await client.getArticleSitelinks("Albert Einstein");
console.log(links.enwiki); // {site: "enwiki", title: "Albert Einstein", badges: ["Q17437798"]}