README.md

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
• Dependencies
• Install
  • as an ES module
  • as an CommonJS 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

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-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'
})

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@v8

See 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.js

See 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.

• 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, 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.

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.

License

MIT