maxlath
wikibase-sdk
JS utils functions to query a Wikibase instance and simplify its results
This package was primarily developed as wikidata-sdk but has now being generalized to support any Wikibase instance, wikidata.org among others, and was thus renamed wikibase-sdk.
This project received a Wikimedia Project Grant.
Summary
Changelog
See CHANGELOG.md for version info
Dependencies
NodeJS >= v12.0.0 or not too outdated web browsers (see Object.fromEntries browser compatibility table)
For older JS runtimes, you can use ES5 bundles from wikibase-sdk <= v8.
Install
as an ES module
Install via npm to be able to use the import the module.
npm install wikibase-sdkThen in your javascript:
import { WBK } from 'wikibase-sdk'
const wbk = WBK({
instance: 'https://my-wikibase-instan.se',
sparqlEndpoint: 'https://query.my-wikibase-instan.se/sparql' // Required to use `sparqlQuery` and `getReverseClaims` functions, optional otherwise
})The wdk object of previous versions of this documentation - from the time this module was bound to wikidata.org only - thus corresponds to the following:
import { WBK } from 'wikibase-sdk'
const wdk = WBK({
instance: 'https://www.wikidata.org',
sparqlEndpoint: 'https://query.wikidata.org/sparql'
})For convenience, and for the sake of retro-compatibility, that same wdk object can be obtain directly from the wikibase-sdk/wikidata.org package:
import wdk from 'wikibase-sdk/wikidata.org'By default wikibase-sdk assumes that your Wikibase instance has $wgScriptPath set to /w, but if that's not the case, you can set it by passing a wgScriptPath parameter:
import { WBK } from 'wikibase-sdk'
const wbk = WBK({
instance: 'https://my-wikibase-instan.se',
wgScriptPath: '/some_custom_script_path'
})as an CommonJS module
Importing with CommonJS require is not supported anymore in version >= v9.0.0, but can still be done by installing an older version:
npm install wikibase-sdk@v8See the corresponding version documentation
download pre-bundled files
Pre-bundled files is not supported anymore in version >= v9.0.0, but can still be done by pre-bundled files from older versions:
wget https://raw.githubusercontent.com/maxlath/wikibase-sdk/v8.1.1/dist/wikibase-sdk.js
wget https://raw.githubusercontent.com/maxlath/wikibase-sdk/v8.1.1/dist/wikidata-sdk.js
wget https://raw.githubusercontent.com/maxlath/wikibase-sdk/v8.1.1/dist/wikibase-sdk.min.js
wget https://raw.githubusercontent.com/maxlath/wikibase-sdk/v8.1.1/dist/wikidata-sdk.min.jsSee the corresponding version documentation
Features
Wikibase API
A set of functions to make read queries to a Wikibase instance API (see Wikidata API documentation). For write operations, see wikibase-edit.
Wikibase Query
There are additional functions for Wikibase instances that have a SPARQL Query Service (such as Wikidata Query for wikidata.org). SPARQL can be a weird thing at first, but the Wikidata team and community really puts lots of efforts to make things easy with a super rich Wikidata Query Help page, an awesome tool to test you queries and visualize the result, and lots of examples!
- Get JSON from a SPARQL query
- Simplify results
- Pre-baked queries
General helpers
Contributing
Context
This library had for primary purpose to serve the needs of the inventaire project but extending its capabilities to other needs it totally possible: feel welcome to post your suggestions as issues or pull requests!
Design constraints
wikibase-sdkshould stay "small" and dependency-free, so that a web application can include it in its bundle without paying a too high cost for it. A consequence is that the lib generates URLs where other libs would integrate doing the request and parsing it's response. But that actually feels quite right to do this way: simply generating the URLs let's users free to handle requests as they like (with callbacks, promises, async/await, custom request agent, whatever!)- Therefore, it should focus on providing basic, general helper functions most application working with a Wikibase instance would need.
- Write operations should go into wikibase-edit as it involves working with Wikibase credentials/tokens.
- General command-line interface tools should go to wikibase-cli, very specific ones —
wikibase-dump-filterand alikes — should get their own modules.
See Also
- wikibase-edit: Edit a Wikibase instance from NodeJS
- wikibase-cli: The command-line interface to Wikibase instances
- wikibase-dump-filter: Filter and format a newline-delimited JSON stream of Wikibase entities
- wikidata-taxonomy: Command-line tool to extract taxonomies from Wikidata
- Other Wikidata external tools
You may also like
Do you know Inventaire? It's a web app to share books with your friends, built on top of Wikidata! And its libre software too.