wikibase-sdk
Version:
utils functions to query a Wikibase instance and simplify its results
163 lines (129 loc) • 9.09 kB
Markdown
# 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/ -->
<a href="https://wikidata.org"><img src="https://raw.githubusercontent.com/maxlath/wikibase-sdk/main/assets/wikidata.jpg" alt="wikidata"></a>
</div>
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/wikibase-sdk)
[](http://nodejs.org)
[](https://npm-stat.com/charts.html?package=wikibase-sdk)
[](http://standardjs.com/)
[](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
[](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)