Wikibase/API

General introduction
The Wikibase API is provided by a set of extensions that implement MediaWiki API modules.

So to use it you should have basic familiarity with the MediaWiki action API: actions, queries, etc., and conversely all your experience with generic parameters such as  and , etc. applies to the Wikibase API.

Changes to the Wikibase API are subject to the Stable Interface Policy.

Wikibase and Wikidata
Wikibase provides a general mechanism to store statements as structured data. Any MediaWiki installation can run it.

(See d>d:Wikidata:Glossary|wikidata:Glossary for explanations of these terms.)

On the Wikimedia cluster, most wikis do not run the full set of Wikibase extensions.

The statements about items live on the server.

Since this includes statements about the millions of items in Wikipedias, it's a fantastic resource to query!

(Wikimedia Commons has its own Wikibase for properties of the files on Commons.)

The extensions implement the   submodules and the API modules
 * pageterms query property submodule
 * wikibase query meta submodule
 * wbcontentlanguages query meta submodule - (docs)
 * wbavailablebadges
 * wbcreateclaim
 * wbcreateredirect
 * wbeditentity
 * wbformatvalue
 * wbgetclaims
 * wbgetentities
 * wblinktitles
 * wbmergeitems
 * wbparsevalue
 * wbremoveclaims
 * wbremovequalifiers
 * wbremovereferences
 * wbsearchentities
 * wbsetaliases
 * wbsetclaim
 * wbsetclaimvalue
 * wbsetdescription
 * wbsetlabel
 * wbsetqualifier
 * wbsetreference
 * wbsetsitelink
 * wbsgetsuggestions

To generate API documentation for just one of these modules, append   to Special:ApiHelp; for example visit wd>wikidata:Special:ApiHelp/wbgetentities|Special:ApiHelp/wbgetentities.

To generate API documentation for multiple modules on one page, pass module names separated by   as the   parameter to  ; for example, [http://www.wikidata.org/w/api.php?action=help&modules=query+pageterms|query+wikibase|wbavailablebadges|wbcreateclaim|wbcreateredirect|wbeditentity|wbformatvalue|wbgetclaims|wbgetentities|wblinktitles|wbmergeitems|wbparsevalue|wbremoveclaims|wbremovequalifiers|wbremovereferences|wbsearchentities|wbsetaliases|wbsetclaim|wbsetclaimvalue|wbsetdescription|wbsetlabel|wbsetqualifier|wbsetreference|wbsetsitelink|wbsgetsuggestions this URL] generates the documentation for all the modules listed above.

Wikibase clients
Many Wikimedia wikis run the ext>Extension:Wikibase Client</>|Wikibase Client extension. This lets API clients on them
 * query the <tvar|wb> </> meta submodule to determine URLs for the full Wikibase repo see its API help
 * query the <tvar|prop> </> property submodule to get some Wikidata information about pages on the local wiki

Post vs. get

 * Requests that change content should use a token>#Token</>|token.
 * Requests should use <tvar|p1>HTTP POST</> or <tvar|get>GET</> requests according to api module. Modules that change content use <tvar|p2>POST</>. Use <tvar|p3>POST</> to avoid problem with non-behaving proxies.
 * Clients should be aware of and handle errors from the API.

Module parameters
There are some parameters that are nearly always available. Plural forms are used in those cases where a parameter can take several values.
 * id | ids : Identifies a specific entity or entities, most typical an item. Plural form is used in wbgetentities. Lists of ids should be separated by <tvar|pipe> </>.
 * site ∩ title | sites ∩ titles : Identifies a single item or multiple items. Plural form is used in wbgetentities. Only one of sites and titles can have multiple values at the same time.
 * language | languages : The language is used as a filter mechanism to filter labels and descriptions in get actions or to identify a specific language for set actions.
 * format : Should always be set to json (or jsonfm for debugging), or xml (or xmlfm for debugging), no other form is supported.
 * summary : Adds a user specified summary in addition to the system generated one.
 * token : An encrypted string the requester must pass on shall the request be fulfilled.
 * baserevid : An id for the last known revision that must be passed on so the server can detect edit collisions.

Normally the return value either has a <tvar|key1> </> key with a boolean cast as an integer or an <tvar|key2> </> key with an object of two, optionally three, keys <tvar|key4> </>, <tvar|key5> </> and <tvar|key6> </>. The last one is additional information. Information about the action is either passed on the top level or under item if it is one single item or items if it is several. If it is several items, each is found under a key with its own item id. See succ>#Success</>|Success and err>#Errors</>|Errors paragraphs.


 * Note that empty objects are returned as json arrays and not as objects.
 * Note that empty parameters removes the actual entry from the item.

wbgetentities
Please see the live docs and try the examples in the API Sandbox.

wbeditentity
live docs


 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title is a pair that identifies a single existing item, if the item does not exist an error is returned.
 * data
 * clear is a marker to clear out the complete item and start from scratch.
 * new


 * Examples


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request

or


 * Result


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request

or


 * Result

wbsetlabel
Module to set a label for a single Wikibase entity. See live docs.


 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title is a pair that identifies a single existing item, if the item does not exist an error is returned.
 * language is the language for the label. The language must be a valid identifier.
 * value is the value of the label

Set the label of the item "Q42" to the English language string "Wikimedia":

Set the label of the item with sitelink "enwiki → Earth" to the English language string "Planet Earth"

wbsetdescription
Module to set a description for a single Wikibase entity. See live docs.


 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title is a pair that identifies a single existing item, if the item does not exist an error is returned.
 * language is the language for the description. The language must be a valid identifier.
 * value is the value of the description.


 * Set the string "An encyclopedia that everyone can edit" for page with id "Q42" as a description in English language:
 * Set the string "An encyclopedia that everyone can edit" as a description in English language for page with a sitelink to enwiki:Wikipedia:

wbsetaliases
Module to set, add and remove aliases from items. Aliases are alternate names for the items, that can be queried and used for lookup. See live docs. setAliases( ( id XOR ( site, title ) ) OR baserevid, ( add OR remove ) XOR set, *summary )
 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title is a pair that identifies a single existing item, if the item does not exist an error is returned.
 * set contains a list of strings that will be used as the new list of aliases. The values are normalized before they are used.
 * add contains a list of additional strings that will be used as aliases. The values are normalized before they are used.
 * remove contains a list of strings that will be removed from the the list of aliases. The values are normalized before they are used.
 * language


 * Examples


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result

wbsetsitelink
Module to define new links to pages at external client sites. During processing of requests the module will query the external site to verify the existence of the page and to acquire the canonical form of the prefix and the pagename. linkSite( ( id XOR ( site, title ) ) OR baserevid, linksite, linktitle, *summary )
 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title is a pair that identifies a single existing item, if the item does not exist an error is returned.
 * linksite is the site id for a client site that will be the target of the new link. The site will be queried during the call.
 * linktitle is the title of the page at the client site that will be the target of the new link. The site will be queried during the call.
 * badges is the list of badges linked to the given sitelink.


 * Examples


 * Request
 * Result


 * Request
 * Result

wbgetclaims
Please see the live docs and try the examples in the API Sandbox.

wbcreateclaim

 * entity is the id of the entity you are adding the claim to.
 * snaktype (value, novalue, somevalue)
 * property is the id of the snaks property.
 * value of snak when creating a claim with a snak that has a value.
 * Examples


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Note: value parameters "globe" and "precision" are optional. Default for "globe" is "http://www.wikidata.org/entity/Q2" (earth).


 * Request
 * Result


 * Request
 * Result

wbsetclaim
Module for creating or updating an entire Claim.


 * claim a claim in json form
 * index


 * Example


 * Request
 * Result

wbsetclaimvalue
Module for setting the value of a Wikibase claim.


 * claim a GUID identifying the claim. Required.
 * snaktype (value, novalue, somevalue).
 * value of snak when setting a claim with a snak that has a value in JSON format.


 * Example


 * Request
 * Result

wbremoveclaims
Module for removing Wikibase claims.


 * claim a GUID identifying the claim.


 * Example


 * Request
 * Result

wbsetqualifier
Module for creating a qualifier or setting the value of an existing one.


 * claim a GUID identifying the claim. Required.
 * property Id of the snaks property
 * value Object value in JSON format.
 * snaktype
 * snakhash


 * Examples

In this example, p4 is a string property
 * Request
 * Result


 * Request
 * Result


 * Request
 * Result

wbremovequalifiers
Module for removing a qualifier from a claim.


 * claim a GUID identifying the claim. Required.
 * qualifiers a hash of the qualifier that should be removed.


 * Examples


 * Request
 * Result

wbsetreference
Module for creating a reference or setting the value of an existing one.


 * statement a GUID identifying the statement. Required.
 * snaks
 * snaks-order
 * reference a hash of the reference that should be updated.
 * index


 * Examples


 * Request
 * Result


 * Request
 * Result

wbremovereferences
Module for removing one or more references of the same statement.


 * statement a GUID identifying the statement. Required.
 * references a hash of the reference that should be updated.


 * Example


 * Request
 * Result

wbsearchentities
Module to search for entities.


 * <tvar|search>search</> is the text string to search for
 * <tvar|lang>language</> is the language to search in
 * <tvar|type>type</> is the type of entities to return
 * <tvar|limit>limit</> is the maximum number of results to return (default 7)
 * <tvar|continue>continue</> offset to continue the query from a previous search


 * Examples


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result

wblinktitles
Module to associate two articles on two different wikis with a Wikibase item.


 * <tvar|to>tosite ∩ totitle</> is pair that identifies first sitelink
 * <tvar|from>fromsite ∩ fromtitle</> is pair that identifies second sitelink


 * Examples


 * Request
 * Result

wbmergeitems
Module to merge two Wikibase items.
 * <tvar|fromid>fromid</> is the numeric identifier for the item to merge from
 * <tvar|toid>toid</> is the numeric identifier for the item to merge to
 * <tvar|ignore>ignoreconflicts</> Array of elements of the item to ignore conflicts for, can only contain values of "label" and or "description" and or "sitelink"


 * Examples


 * Request
 * Result

wbparsevalue
Module to parse strings using a backend ValueParser.


 * parser
 * values
 * options


 * Examples


 * Request
 * Result

wbformatvalue
Module for formatting DataValues.
 * generate: The desired output format to generate. One of the following values:,  ,  . Default:.
 * datavalue: The data to format. This has to be the JSON serialization of a DataValue object. This parameter is required.
 * datatype: The value's data type. This is distinct from the value's type. One of the following values:,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,.
 * property: This can (and should) be used instead of datatype to indicate the property ID for this value. For instance, in the case of an external-id with a formatter URL, the value will be formatted with the appropriate link.
 * options: This takes a JSON object containing various options to customize the rendering. The lang field can always be supplied, with a Wikimedia language code (for instance to determine how month names will be rendered for dates). The list of options supported by each datatype is not centralized yet but can be guessed from here: https://github.com/search?utf8=%E2%9C%93&q=%22OPT%22+user%3Awmde+user%3ADataValues+extension%3Aphp&type=Code


 * Examples


 * Request
 * Result

wbentityusage
Module as a prop in <tvar|code> </> to add entity usage data to the result.
 * Examples


 * Request
 * Result

wbcheckconstraints
Module to check constraints for given entities or claims.


 * <tvar|id>id</> Entity ID(s) of entities (items, properties, …) that you want to check. All statements of the entities will be checked. Can be combined with <tvar|claimed>claimid</> to check some individual statements of other entities.
 * <tvar|claimed>claimid</> Statement ID(s) of individual statements that you want to check. Can be combined with <tvar|id>id</>, but the statements listed here need not belong to the IDs listed there.
 * <tvar|constraintid>constraintid</> If specified, only check these constraints (otherwise: all of them). The ID of a constraint is the statement ID of the corresponding statement on the property where the constraint is defined.
 * <tvar|status>status</> Only return check results with these statuses. Only requests that limit the statuses to  benefit from caching. (This is also the default value.)

The output format of the wbcheckconstraints action is based on the wb-json>Wikibase/DataModel/JSON</>|Wikibase JSON format, but in every place where the Wikibase JSON format can contain a snak, the wbcheckconstraints response instead contains an object with members <tvar|hash1> </> and <tvar|rep> </>. <tvar|hash2> </> is the hash of the corresponding snak, and <tvar|rep> </> is a list of the individual constraint reports for that snak.

Embedded in the output structure are individual constraint report results, which are objects with the following members:
 * : The main status of the result. The main statuses are <tvar|1> </>, <tvar|2> </>, and <tvar|3> </> (violation of non-mandatory constraint). Other statuses include <tvar|4> </> (entity is an exception to the constraint), <tvar|5> </> (unimplemented or unknown constraint), <tvar|6> </> (parameters of the constraint definition are broken), and <tvar|7> </> (constraint check skipped on deprecated statement). While the API is still evolving, other statuses may be added without prior notice.
 * : The property ID of the property of the snak being checked, which is also the property on which the constraint is defined.
 * : An object with the following members:
 * : The ID of the constraint, which is the statement ID of the constraint statement that defines the constraint.
 * : The constraint type, which is an item ID.
 * : The label of the item with the ID given in, in the user's language.
 * : A link to a help page for the constraint type.


 * : A human-readable message explaining the result (mainly in case of a violation), in HTML format.
 * : The statement ID being checked, if the result belongs to the main snak of a statement. This member is absent on check results for qualifiers, references, and any other snaks that aren't main snaks of saved statements.
 * : If this optional member is present and contains a truthy value, the result was cached. The value may be an object with a <tvar|max> </> member, which indicates how outdated the value might be, in seconds.
 * Examples


 * Request
 * Result

Time

 * Calendar model
 * <tvar|d1>Q1985727</> - Gregorian calendar
 * <tvar|d2>Q1985786</> - Julian calendar

Token
An Edit token is required to make edits. This token can be obtained through query&meta=tokens, or by the deprecated <tvar|1></>.

See also <tvar|1></>.

Revision
The API uses revision ids for edit collision detection. If the revision id is known from an previous reply, page load or similar, then pass on the revision to the edit. Without the revision id it is not possible to detect edit collisions in a reliable way. If there is an edit collision the requester must acquire a newer revision id to be able to continue. This typically involves requesting wbgetentities for the item in question, and then storing (and using) the revision from the entry.

Errors
Possible errors for all modules can be found at <tvar|api-help> </>, for example [<tvar|url>http://www.wikidata.org/w/api.php?action=paraminfo&modules=wbeditentity</> wbeditentity]

"Expected" errors will have a standardized form:
 * example :

The <tvar|servedby>servedby</> is given unconditionally for <tvar|err1>error</> messages, but could be missing for some less than fatal errors. In some cases <tvar|err2>error</> messages can be appended to a <tvar|succ>success</> and be called <tvar|warn>warning(s)</>.

All error messages from the Wikibase modules should be internationalized (i18n) and localized (l10n), but note that error messages from the base API system may not be localized. The user language for the logged in user (usually the same as in the web interface) will be the default for error messages. You can override this by supplying <tvar|lc> </> in the URL query string

Do not test the <tvar|info>info</> value for a particular error, instead use the <tvar|code>code</> value as this will remain independent of localization.

An internationalized error message that isn't localized as it should will have additional angle brackets. With correctly localized error message the angle brackets will go away and the info string will print out in clear text. Assuming the user is logged in and use English language it will print as something like the following. Switching to Norwegian in the prefs>Special:Preferences</> or by appending  it will change the text of the info string to a localized variant, while the code string remains constant. A lot of error messages are not properly localized.
 * example :

Success
'' Can be removed since all normal calls will return data of some kind, unless there is an error condition. ''

If a success is achieved it will have the following form when the

The interpretation of the value for success can be dependent on the actual parameters in the call, but usually it is a boolean that is type casted to an integer.

Its meaning is that every previous tests evaluated to true.

If the number is 0 (zero) any additional values might be wrong.

There might be additional values in the structure after a successful call.