Documentation menu

Best Practices

This page covers best practices for using the Wikimedia Enterprise APIs. Following them ensures you make the fewest API calls possible to get the data you need (helpful if you're on a free plan with a monthly request quota), reduces the amount of data you're requesting, preserves bandwidth, and speeds up code execution.

For more guidance on how to use a specific API collection, read its dedicated guide page. The links below go to the guide page for every API collection in the Wikimedia Enterprise API suite.

Choose the right API for the job

Most integrations use endpoints from one or two Wikimedia Enterprise API collections. Use this as a starting point, then follow the task-based guidance below for the one you've picked.

Your use case	API collection	Best practice
Download every article from one or more projects on a regular cadence, for LLM training data, search indexes, mirrors, research, and more.	Snapshot API	Download the monthly bundle (up to daily on paid plans), or retrieve it chunk by chunk for very large projects like English Wikipedia.
Look up a specific article by title in response to a user action. Regularly update your knowledge base with the latest revision of specific high-value articles. For your news bot, fact lookup, product feature, and more.	On-demand API	Call Article Lookup with the article name. Cache the response if you'll hit the same article repeatedly.
Track live edits as they happen, or backfill changes within the last 48 hours.	Realtime API (paid)	Connect to the article stream for live events. Pull hourly batches for backfill or catch-up.

Authentication

Store your access_token and refresh_token securely, use the Refresh endpoint within 24 hours, and use the Login endpoint ideally once every 90 days. More info: Token lifecycle.

Metadata

Call the utility endpoints once, cache the results, and use them in order (codes, languages, projects, namespaces) to find your identifiers: Endpoints.
Snapshot and Realtime identifiers follow the <language><project_code>_namespace_<number> recipe: Identifiers.

Snapshot API

Follow the Snapshots Available, then Snapshot Info, then Snapshot Download sequence; request Project Snapshot Headers before every download. If you're on a free account, your Dashboard tracks your monthly limit of snapshot and chunk downloads. Working with snapshots.
Expect a small amount of duplicate and deleted articles in bundles and chunks; keep the highest version.identifier for duplicates.

On-demand API

Article names are case sensitive, spaces in article names become underscores or percent-encoding in the Article Lookup request, and an unfiltered name query matches across all projects: Requesting exactly what you need.
Use fields, filters, and limit to keep responses small: Fields, Filters, and Limit.

Realtime API

Open up to 10 parallel connections with the parts parameter: Parallel consumption.
Reconnect within the 48-hour replay window using since or since_per_partition, and record event IDs to discard duplicates: Reconnecting to the Realtime API.
Check batch availability before downloading: Retrieving hourly batches.

Credibility Signals

Set thresholds deliberately instead of consuming raw scores: Recommended starting thresholds.
Validate against your own traffic before enforcing: Evaluating signals against your own traffic.
Combine fields rather than trusting one signal: Combining signals.
Do not read a missing version.editor.is_anonymous as "registered editor": temporary accounts made that field always false on nearly every project: Reading name and is_anonymous.

Resolving revision tags

version.tags returns the change tags MediaWiki attached to a revision: a short list of machine-readable strings marking the revision as part of a campaign, made with a particular tool, produced by a project-run initiative, or caught by an abuse filter.

["mobile edit", "mobile app edit", "android app edit"]

The values are strings with no definitions attached, and the set is per project, not global. A handful are core change tags that MediaWiki defines everywhere; the rest are created by each project's community and mean nothing outside it. A list of tags from English Wikipedia can't be applied to other Wikimedia projects, e.g. German Wikisource.

Resolve them against the project instead. MediaWiki's Tags API lists every tag a given wiki uses, with a display name, a description, and how many revisions carry it - this call returns them for English Wikipedia. Fetch it once per project you consume and cache it alongside your metadata lookups, the same way you cache project and language codes. The Tags API hitcount field describes how many revisions carry a specific tag, which can be used to filter out tags that have little to no application.

A revision usually carries several version.tags.

Attributing Wikimedia project content

In general, most content, data, and metadata coming from Wikimedia projects are openly licensed. This doesn't, however, mean any part of Wikimedia projects can be reused without restrictions. The most common licenses used for Wikimedia project data are Creative Commons Attribution (CC BY) or Creative Commons Attribution-ShareAlike (CC BY-SA). These licenses allow you to freely reuse data on the condition that you attribute the data source, among other possible conditions.

Attribution is essential for fair acknowledgment and active awareness of Wikimedia's community-driven content, and it's also a key factor in the continued growth and sustainability of the free knowledge ecosystem. Learn more about the value of attribution.

Figure out how to correctly attribute different parts of Wikimedia projects by finding the attribution signals that match the source of your data.

Attributing images

Images on Wikimedia projects will always clearly have their license stated. Take the main image of the Josephine Baker English Wikipedia article for example: File:Baker_Harcourt_1940_2.jpg. Under "licensing", you'll find the license and its associated publication conditions. This specific image is in the public domain, which means you can reuse it without any restrictions.

To attribute an image correctly and neatly, include the following information: the image Title, the image Author (the creator or provider of the image), the image Source (a URL to the image, and the platform from which you sourced the image), and the image License. For example:

Joséphine Baker in 1940, by Photography Studio Harcourt, Public Domain, via Wikimedia Commons.

For more guidance, follow the Wikimedia Foundation guide on attributing Creative Commons content.