Installation and Usage

1. Installation

pip install wikibase-api

2. Usage

To access the API, simply create an instance of the Wikibase class:

from wikibase_api import Wikibase

wb = Wikibase()

Note

The Wikibase instance which is accessed by default is Wikidata. To use another instance, e.g. a local one for testing, set the api_url parameter accordingly. You can find a guide on how to set up your own instance locally using Docker under Local Wikibase Instance.

3. Queries

You can query a Wikibase instance (e.g. Wikidata) by simply creating an object of the Wikibase class and calling a query function. For example, you ask for all information about an item:

from wikibase_api import Wikibase

wb = Wikibase()
r = wb.entity.get("Q1")
print(r)

Output:

{
  "entities": {
    "Q1": {
      # ...
    }
  },
  "success": 1,
}

4. Edits

You can also make edits using the Wikibase API, e.g. create an empty item:

r = wb.entity.add("item")
print(r)

Output:

{
  "entity": {
    "labels": {},
    "descriptions": {},
    "aliases": {},
    "sitelinks": {},
    "claims": {},
    "id": "Q1",
    "type": "item",
    "lastrevid": 1234
  },
  "success": 1
}

For a list of all available API functions, have a look at the API Reference.

Note

If you plan to make edits on Wikidata, it’s a good idea to test them on the sandbox item.

Before being able to make requests, you need to authenticate yourself to the API. You have two options:

OAuth is the recommended method as it is more secure than logging in with username and password. However, setting up OAuth is more complicated and requires you to apply for credentials.

a) OAuth

To be able to use OAuth, you need to obtain credentials for an owner-only consumer. This information can be obtained at Special:OAuthConsumerRegistration/propose (i.e. https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration/propose for Wikimedia or http://localhost:8181/wiki/Special:OAuthConsumerRegistration/propose on a local instance):

  1. Log in using your username and password

  2. Fill in the registration form:

    • Application name and description
    • Tick “This consumer is for use only by <username>”
    • Select the grants you need, e.g. “High-volume editing”, “Edit existing pages”, “Create, edit, and move pages”, and “Delete pages, revisions, and log entries”
  3. Click the “Propose consumer” button at the bottom of the page

  4. Write down your OAuth consumer information

Now, you can create an instance of the Wikibase class using your newly obtained OAuth credentials:

from wikibase_api import Wikibase

oauth_credentials = {
    "consumer_key": "...",
    "consumer_secret": "...",
    "access_token": "...",
    "access_secret": "...",
}

wb = Wikibase(oauth_credentials=oauth_credentials)

Note

Some additional steps are required when using OAuth on a local Wikibase instance (see oauth_on_local_wikibase_instance).

b) User Login

Bot passwords allow users to access the API without providing their account’s main login credentials. You can generate a bot password under Special:BotPasswords (i.e. https://www.wikidata.org/wiki/Special:BotPasswords on Wikidata or http://localhost:8181/wiki/Special:BotPasswords on a local instance):

  1. Log in using your username and password

  2. Fill in the registration form:

    • Choose a bot name (this will be a suffix to your username)
    • Select the grants you need, e.g. “High-volume editing”, “Edit existing pages”, “Create, edit, and move pages”, and “Delete pages, revisions, and log entries”
  3. Click the “Create” button at the bottom of the page

  4. Write down your bot username and password

Now, you can create an instance of the Wikibase class using your newly obtained bot credentials:

from wikibase_api import Wikibase

login_credentials = {
    "bot_username": "...",
    "bot_password": "...",
}

wb = Wikibase(login_credentials=login_credentials)