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.
See CHANGELOG.md for version info
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 via npm to be able to use the import
the module.
npm install wikibase-sdk
Then 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'
})
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@v8
See the corresponding version documentation
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.js
See the corresponding version documentation
A set of functions to make read queries to a Wikibase instance API (see Wikidata API documentation). For write operations, see wikibase-edit.
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
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-sdk
should 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-filter
and alikes — should get their own modules.
- 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
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.