WD-watch

Wikidata monitoring tool for tracking edits on watched items and generating HTML reports.

Repository: https://github.com/OSC-JYU/wd-watch

User-Agent

Wikidata requires a user-agent with contact info. Set it in config.json:

"user_agent": "WD-Watch/2.0 (https://github.com/OSC-JYU/wd-watch; CONTACT_EMAIL_HERE)"

Running (NodeJS)

git clone https://github.com/OSC-JYU/wd-watch.git
cd wd-watch
npm install
npm start

Default server port is 8200.

Running (Docker)

make build
make start

Reports are exported to the public/reports directory.

Converting Legacy Data

If you still have an old database (data/watchlist.db), convert it to the current schema:

npm run convert:v1-to-v2 -- --dry-run
npm run convert:v1-to-v2

Options:

• --source <file> defaults to data/watchlist.db
• --target <file> defaults to data/watchlist_v2.db
• --runs <file> defaults to data/runs_v2.db
• --dry-run prints what would be converted without writing
• --force overwrites existing rows with the same QID

Usage

Status:

curl http://localhost:8200/api/status

Add one item:

curl -XPOST 'http://localhost:8200/api/watchlist/Q42?wdset=Dougs'

SPARQL import:

curl -G -XPOST 'http://localhost:8200/api/watchlist/query' \
  --header "Accept: application/json" \
  --data-urlencode wdset="Klimt" \
  --data-urlencode query="
SELECT ?item ?itemLabel
WHERE
{
  ?item wdt:P31 wd:Q3305213 .
  ?item wdt:P170 wd:Q34661 .
  SERVICE wikibase:label { bd:serviceParam wikibase:language \"fi,en\". }
}
limit 10
"

Note: always include LIMIT in SPARQL imports. Large unbounded queries may take a long time. If an item already exists in watchlist, import now counts it as skipped_existing (same set) or skipped_other_set (already tracked in another set) instead of flooding failure output.

Create report:

curl -XPOST 'http://localhost:8200/api/watchlist/report?wdset=Klimt'

By default, reports use email-safe template (optimized for email clients). Use template=web for the richer browser layout:

curl -XPOST 'http://localhost:8200/api/watchlist/report?wdset=Klimt&template=web'

Create report for a fixed lookback period (overrides saved last run):

curl -XPOST 'http://localhost:8200/api/watchlist/report?wdset=Klimt&days=21'

Report files are written to public/reports/ and listed at:

curl 'http://localhost:8200/reports'

Email Reports

Set MAILER and MAILER_PORT, then:

curl -XPOST 'http://localhost:8200/api/watchlist/report?wdset=Klimt&mail=somebody@somewhere.com'

API Summary

• GET /api/status
• GET /api/watchlist/sets
• GET /api/watchlist?wdset=<set>
• GET /api/watchlist/{qid}
• POST /api/watchlist/{qid}?wdset=<set>
• POST /api/watchlist/query?wdset=<set>&query=<sparql>
• DELETE /api/watchlist/{qid}
• DELETE /api/watchlist/sets?wdset=<set>
• POST /api/watchlist/report?wdset=<set>[&template=<email-safe|web>][&days=<1..3650>][&mail=<email>]
• GET /reports