npm package: @larsgw/wikibase-sdk
Description: utils functions to query a Wikibase instance and simplify its results
Author: maxlath
Latest version: 10.2.1

# wikibase-sdk

JS utils functions to query a [Wikibase](http://wikiba.se) 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](https://www.wikidata.org) among others, and was thus renamed `wikibase-sdk`.

This project received a [Wikimedia Project Grant](https://meta.wikimedia.org/wiki/Grants:Project/WikidataJS).

<div align="center">
  <a href="https://wikiba.se"><img height="150" src="https://raw.githubusercontent.com/maxlath/wikibase-sdk/main/assets/wikibase.png" alt="wikibase"></a>
  <!-- yeay hacky margin \o/ -->
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  <a href="https://wikidata.org"><img src="https://raw.githubusercontent.com/maxlath/wikibase-sdk/main/assets/wikidata.jpg" alt="wikidata"></a>
</div>

[![License](https://img.shields.io/npm/l/wikibase-sdk)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/wikibase-sdk)](https://www.npmjs.com/package/wikibase-sdk)
[![Required Node.js version](https://img.shields.io/node/v/wikibase-sdk)](http://nodejs.org)
[![npm downloads](https://img.shields.io/npm/dw/wikibase-sdk)](https://npm-stat.com/charts.html?package=wikibase-sdk)
[![code style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)
[![type definitions](https://img.shields.io/npm/types/wikibase-sdk)](https://www.typescriptlang.org/)

## Summary

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Changelog](#changelog)
- [Dependencies](#dependencies)
- [Install](#install)
  - [as an ES module](#as-an-es-module)
  - [as an CommonJS module](#as-an-commonjs-module)
  - [download pre-bundled files](#download-pre-bundled-files)
- [Features](#features)
  - [Wikibase API](#wikibase-api)
  - [Wikibase Query](#wikibase-query)
  - [General helpers](#general-helpers)
- [Contributing](#contributing)
- [See Also](#see-also)
- [You may also like](#you-may-also-like)
- [License](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version info

## Dependencies
NodeJS `>= v12.0.0` or not too outdated web browsers (see [`Object.fromEntries` browser compatibility table](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries))
For older JS runtimes, you can use [ES5 bundles from `wikibase-sdk <= v8`](https://github.com/maxlath/wikibase-sdk/tree/v8.1.1#download-pre-bundled-files).

## Install
### as an ES module
Install via npm to be able to use the `import` the module.
```sh
npm install wikibase-sdk
```

Then in your javascript:
```js
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:
```js
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:
```js
import wdk from 'wikibase-sdk/wikidata.org'
```

By default `wikibase-sdk` assumes that your Wikibase instance has [`$wgScriptPath`](https://www.mediawiki.org/wiki/Manual:$wgScriptPath) set to `/w`, but if that's not the case, you can set it by passing a `wgScriptPath` parameter:
```js
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:
```sh
npm install wikibase-sdk@v8
```

See the [corresponding version documentation](https://github.com/maxlath/wikibase-sdk/tree/v8.1.1#as-a-module)

### 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:
```sh
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](https://github.com/maxlath/wikibase-sdk/tree/v8.1.1#download-pre-bundled-files)

## Features
### Wikibase API
A set of functions to make **read** queries to a Wikibase instance API (see [Wikidata API documentation](https://www.wikidata.org/w/api.php)).
For **write** operations, see [wikibase-edit](http://github.com/maxlath/wikibase-edit).

* **[Search entities](docs/search_entities.md)**
* **[Get entities](docs/get_entities.md)**
  * [By ids](docs/get_entities.md#by-ids)
  * [By id and revision](docs/get_entities.md#by-id-and-revision)
  * [By Wikipedia titles](docs/get_entities.md#by-wikipedia-titles)
  * [By other Wikimedia projects titles](docs/get_entities.md#by-other-wikimedia-projects-titles)
* **[Simplify entities data](docs/simplify_entities_data.md)**
* **[Get revisions](docs/get_revisions.md)**

### Wikibase Query
There are additional functions for Wikibase instances that have a [SPARQL](https://en.wikipedia.org/wiki/SPARQL) Query Service (such as [Wikidata Query](http://query.wikidata.org/) 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](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/Wikidata_Query_Help) page, [an awesome tool to test you queries and visualize the result](https://query.wikidata.org/), and [lots of examples](https://www.wikidata.org/wiki/Special:MyLanguage/Wikidata:SPARQL_query_service/queries/examples)!

* **[Get JSON from a SPARQL query](docs/sparql_query.md)**
* **[Simplify results](docs/simplify_sparql_results.md)**
* **Pre-baked queries**
  * [Get entities reverse claims](docs/get_entities_reverse_claims.md)

### General helpers
  * **[Work with ids](docs/general_helpers.md#work-with-ids)**
  * **[Sitelink helper](docs/general_helpers.md#sitelink-helpers)**
  * **[Wikibase Time converters](docs/general_helpers.md#wikibase-time-converters)**

## Contributing
**Context**

This library had for primary purpose to serve the needs of the [inventaire](https://github.com/inventaire/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](https://github.com/maxlath/wikibase-edit) as it involves working with Wikibase credentials/tokens.
* General command-line interface tools should go to [wikibase-cli](https://github.com/maxlath/wikibase-cli), very specific ones — [`wikibase-dump-filter` and alikes](#see-also) — should get their own modules.

## See Also
* [wikibase-edit](https://github.com/maxlath/wikibase-edit): Edit a Wikibase instance from NodeJS
* [wikibase-cli](https://github.com/maxlath/wikibase-cli): The command-line interface to Wikibase instances
* [wikibase-dump-filter](https://npmjs.com/package/wikibase-dump-filter): Filter and format a newline-delimited JSON stream of Wikibase entities
* [wikidata-taxonomy](https://github.com/nichtich/wikidata-taxonomy): Command-line tool to extract taxonomies from Wikidata
* [Other Wikidata external tools](https://www.wikidata.org/wiki/Wikidata:Tools/External_tools)

## You may also like

[![inventaire banner](https://inventaire.io/public/images/inventaire-brittanystevens-13947832357-CC-BY-lighter-blue-4-banner-500px.png)](https://inventaire.io)

Do you know [Inventaire](https://inventaire.io/)? It's a web app to share books with your friends, built on top of Wikidata! And its [libre software](http://github.com/inventaire/inventaire) too.

## License
[MIT](LICENSE.md)