Wikimedia Pageviews & Analytics Scraper

Query the Wikimedia Analytics API (AQS) — the official, keyless analytics service for every Wikimedia project. No login, no API key; pageview and analytics data is CC0.

• Article pageviews — daily / monthly views for any article, split by access method (desktop / mobile) and agent (user / spider / automated)
• Project pageviews — whole-project totals over time, down to hourly; windows before 2015-07-01 auto-route to legacy pagecounts (back to 2007)
• Top articles — the up-to-1000 most-viewed articles for a day or a month, ranked
• Top by country — which countries send a project the most traffic (privacy-bucketed by Wikimedia)
• Unique devices — Wikimedia's estimated unique-device counts per project
• Media file requests — request counts for Commons / upload.wikimedia.org files, per file or aggregated by referer / media type
• Wiki activity — edits, active editors, new pages and new registered users per project over time

Record type	One per	Carries
SEARCH_SUMMARY	work unit (article / date / month / file / metric) or the whole run	rowsReturned, requestsMade, date range, totals, truncated, note
PAGEVIEWS	timestamp bucket	project, article (or project total), access, agent, granularity, timestamp, views, articleUrl
TOP_ARTICLE	ranked article	project, access, date, period, rank, article, views
COUNTRY	country	project, month, rank, country, viewsRange (bucket), viewsCeil
UNIQUE_DEVICES	timestamp bucket	project, accessSite, devices, offset, underestimate
MEDIA_REQUESTS	timestamp bucket	subMode, fileName, filePath, referer, mediaType, requests
WIKI_ACTIVITY	timestamp bucket	project, metric, editorType, pageType, value
ERROR	bad input / unrecoverable fetch	_error + _errorDetail

Every data row keeps the verbatim upstream item in raw (turn off with slimOutput). Timestamps are normalised to a UTC ISO string — YYYY-MM-DD for daily/monthly, …T HH:00:00+00:00 for hourly.

Modes & inputs

Mode	Needs	Notes
article-pageviews	articles, date range	granularity daily or monthly (hourly is a 400)
project-pageviews	date range	granularity also hourly; project may be all-projects; pre-2015 → legacy
top-articles	dates (YYYY/MM/DD or YYYY/MM)	up to 1000 ranked; not all-projects; defaults to last month
top-by-country	months (YYYY/MM)	views are privacy buckets, never exact; not all-projects
unique-devices	date range	accessSite = all-sites / desktop-site / mobile-site
media-requests	files (per-file) or just filters (aggregate)	File:Name.jpg is resolved to its hashed upload path
wiki-activity	activityMetrics	edits, editors, new-pages, registered-users

Things the AQS will mislead you about

Each is measured, and each has a scenario in tests/smoke/wikimedia-pageviews-scraper_traps.sh (14/14 passing).

One 404 body means four different things. An unknown project, a title that has never been viewed, a future date range and a range that is simply too recent for the data to have landed all return the same {"detail": "…we either do not have data…"}. This Actor treats that as a SEARCH_SUMMARY with rowsReturned: 0 and a note, never an error. (A different 404, {"detail": "invalid route"}, means a real path bug and is surfaced.)

Article titles are case-sensitive. berlin returns nothing; Berlin returns data. Spaces and underscores are interchangeable; / in a title (AC/DC) is handled for you.

top-by-country never gives an exact number. viewsRange is a bucket string like "1000000000-9999999999"; viewsCeil is its upper bound. Wikimedia buckets these for reader privacy.

top-articles and top-by-country reject all-projects. Only project-pageviews accepts it.

Two response shapes. Pageviews / unique-devices / media-requests return a flat items list. Edit metrics nest the series one level deeper under results with ISO timestamps — normalised to the same row shape here.

A bad enum value or start > end is an honest HTTP 400. Bad enums are caught client-side (with the valid set in the message) before a request is spent; start > end is passed through as bad_request.

Notes on cost

One request per article / per date / per month / per file / per metric; a single request for project-pageviews and unique-devices (two when the window straddles 2015-07-01). A multi-year daily series comes back in one request. No proxy needed — the AQS has no anti-bot layer.