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:
- Authentication using OAuth
- Authentication with a user account
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):
Log in using your username and password
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”
Click the “Propose consumer” button at the bottom of the page
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):
Log in using your username and password
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”
Click the “Create” button at the bottom of the page
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)