# 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](https://enterprise.wikimedia.com/docs/snapshot/) | 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](https://enterprise.wikimedia.com/docs/on-demand/) | 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](https://enterprise.wikimedia.com/docs/realtime/) (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](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/token-refresh) endpoint within 24 hours, and use the [Login](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/login) endpoint ideally once every 90 days. More info: [Token lifecycle](https://enterprise.wikimedia.com/docs/authentication/#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](https://enterprise.wikimedia.com/docs/metadata/#endpoints). - Snapshot and Realtime identifiers follow the `_namespace_` recipe: [Identifiers](https://enterprise.wikimedia.com/docs/identifiers/). ## Snapshot API - Follow the [Snapshots Available](https://enterprise.wikimedia.com/docs/api/#tag/snapshots/GET/v2/snapshots), then [Snapshot Info](https://enterprise.wikimedia.com/docs/api/#tag/snapshots/GET/v2/snapshots/{identifier}), then [Snapshot Download](https://enterprise.wikimedia.com/docs/api/#tag/snapshots/GET/v2/snapshots/{identifier}/download) sequence; request [Project Snapshot Headers](https://enterprise.wikimedia.com/docs/api/#tag/snapshots/HEAD/v2/snapshots/{identifier}/download) before every download. If you're on a free account, your [Dashboard](https://dashboard.enterprise.wikimedia.com/dashboard) tracks your monthly limit of snapshot and chunk downloads. [Working with snapshots](https://enterprise.wikimedia.com/docs/snapshot/#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](https://enterprise.wikimedia.com/docs/on-demand/#requesting-exactly-what-you-need). - Use `fields`, `filters`, and `limit` to keep responses small: [Fields, Filters, and Limit](https://enterprise.wikimedia.com/docs/filtering/). ## Realtime API - Open up to 10 parallel connections with the `parts` parameter: [Parallel consumption](https://enterprise.wikimedia.com/docs/realtime/#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](https://enterprise.wikimedia.com/docs/realtime/#reconnecting-to-the-realtime-api). - Check batch availability before downloading: [Retrieving hourly batches](https://enterprise.wikimedia.com/docs/realtime/#retrieving-hourly-batches). ## Credibility Signals - Set thresholds deliberately instead of consuming raw scores: [Recommended starting thresholds](https://enterprise.wikimedia.com/docs/credibility-signals/#recommended-starting-thresholds). - Validate against your own traffic before enforcing: [Evaluating signals against your own traffic](https://enterprise.wikimedia.com/docs/credibility-signals/#evaluating-signals-against-your-own-traffic). - Combine fields rather than trusting one signal: [Combining signals](https://enterprise.wikimedia.com/docs/credibility-signals/#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](https://enterprise.wikimedia.com/docs/credibility-signals/#reading-name-and-is_anonymous-after-temporary-accounts). ## Resolving revision tags `version.tags` returns the [change tags](https://www.mediawiki.org/wiki/Manual: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. ```json ["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](https://www.mediawiki.org/wiki/Manual:Tags#List_of_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](https://www.mediawiki.org/wiki/API:Tags) 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](https://en.wikipedia.org/w/api.php?action=query\&list=tags\&tgprop=displayname%7Cdescription%7Chitcount\&tglimit=500). 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)](https://creativecommons.org/licenses/by/4.0/) or [Creative Commons Attribution-ShareAlike (CC BY-SA)](https://creativecommons.org/licenses/by-sa/4.0/). 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](https://wikimedia-attribution.toolforge.org/#keep-free-knowledge-alive). Figure out how to correctly attribute different parts of Wikimedia projects by [finding the attribution signals that match the source of your data](https://wikimedia-attribution.toolforge.org/attribution-signals/overview.html). ### 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](https://commons.wikimedia.org/wiki/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**](https://commons.wikimedia.org/wiki/File:Baker_Harcourt_1940_2.jpg), by Photography Studio Harcourt, Public Domain, via Wikimedia Commons. For more guidance, follow the [Wikimedia Foundation guide on attributing Creative Commons content](https://upload.wikimedia.org/wikipedia/commons/e/e5/Attributing_Creative_Commons_Content_-_A_guide.pdf). ## See also - [Getting Started](https://enterprise.wikimedia.com/docs/) - signup, tokens, and your first calls. - [API reference](https://enterprise.wikimedia.com/docs/api/) - every endpoint and response field.