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.

This project received a Wikimedia Project Grant.

         

• wikibase-sdk download stats
• wikidata-sdk download stats

Summary

• Changelog
• Dependencies
• Install
  • as a module
  • download pre-bundled files
• Features
  • Wikibase API
  • Wikibase Query
  • General helpers
• Contributing
• See Also
• You may also like
• License

Changelog

See CHANGELOG.md for version info

Dependencies

This module uses JavaScript ES6, which means NodeJS >= v6.4.0 or not too outdated web browsers.

For older version, you can use ES5 bundles.

Install

as a module

Install via npm to be able to use the module with require (CommonJS) or import (ES6 Modules)

npm install wikibase-sdk

Then in your javascript:

const WBK = require('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:

const WBK = require('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 wikidata-sdk package:

// After having run `npm install wikidata-sdk`
const wdk = require('wikidata-sdk')

and instance-independant helper functions are directly available from the module root:

const { simplify, parse, isEntityId, isPropertyId, ... } = require('wikibase-sdk')

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:

const wbk = require('wikibase-sdk')({
  instance: 'https://my-wikibase-instan.se',
  wgScriptPath: '/some_custom_script_path'
})

download pre-bundled files

If you just want to import the lib from an HTML file and don't have a setup that can import with CommonJS or ES6 Modules, you can simply download those pre-bundled files:

wget https://raw.githubusercontent.com/maxlath/wikibase-sdk/dist/dist/wikibase-sdk.js
wget https://raw.githubusercontent.com/maxlath/wikibase-sdk/dist/dist/wikidata-sdk.js
wget https://raw.githubusercontent.com/maxlath/wikibase-sdk/dist/dist/wikibase-sdk.min.js
wget https://raw.githubusercontent.com/maxlath/wikibase-sdk/dist/dist/wikidata-sdk.min.js

then you can import it in your html:

<script src="/path/to/wikibase-sdk.js"></script>
<script>console.log('can access WBK', WBK)</script>
<script src="/path/to/wikidata-sdk.js"></script>
<script>console.log('can access wdk, the wikidata.org bound product of WBK', wdk)</script>

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.

• Search entities
• Get entities
  • By ids
  • By id and revision
  • By Wikipedia titles
  • By other Wikimedia projects titles
• Simplify entities data
• Get revisions

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
  • Get entities reverse claims

General helpers

• Work with ids
• Sitelink helper
• Wikibase Time converters

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-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, 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 — wikidata-filter, import-wikidata-dump-to-couchdb, and 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-subset-search-engine: Tools to setup an ElasticSearch instance fed with subsets of Wikidata
• wikidata-taxonomy: Command-line tool to extract taxonomies from Wikidata
• import-wikidata-dump-to-couchdb: Import a subset or a full Wikidata dump into a CouchDB database
• 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.

License

MIT