API:Presenting Wikidata knowledge

This page shows how to retrieve and present relevant information from Wikidata by associating it with entities in your application.

You can use Wikidata items and properties to provide language-independent information about entities (real-world things) in your application&mdash;events, places, people, works of art, concepts, etc. This is more direct and consistent than presenting descriptions and snippets from Wikipedia articles about these things, as API:Page info in search results explains.

Example


Inventaire lets you create an inventory of your books and share with others. It displays certain properties from Wikidata about books, such as P407 "original language of work" and P50 "author". To do so, it uses Wikidata's 'Q' IDs internally to identify books. For example, its URL https://inventaire.io/entity/wd:Q180736 shows certain properties from the Wikidata entity http://www.wikidata.org/entity/Q180736 (the book "Les Misérables"). The Wikidata glossary explains entities and properties in more detail.

Recipe

 * 1) Find existing wiki pages in the domain of your application, e.g. creative works, places, events, people, species.
 * 2) View the Wikidata information for those pages, and choose interesting properties.
 * 3) Associate Wikidata entity IDs with entities in your application.
 * 4) Display their Wikidata information in the user's language.
 * 5) Use the Wikidata "sitelinks" information about the item to provide links to the full Wikipedia article about the entity in the user's language.

Getting Wikidata entity IDs
To get an article's entity ID in Wikidata, you can use the following methods:


 * Copy the link "Wikidata item" ('wikibase-dataitem' message key) in the sidebar in most skins. It ends with 'Q' NNNN '.
 * Access the  variable in client-side JavaScript with.
 * Use the API to query the page for the page property.

Choosing properties
If you view https://www.wikidata.org/wiki/Q180736, you can see the following properties:


 * Some localized information:
 * "label"
 * "description"
 * "aliases" (displayed as "Also known as")
 * Many "Statements" about the item that give values for its properties such as "author" and "publication date"
 * Many "sitelinks" for the item, providing the titles of pages about the item in various Wikipedias and other Wikimedia projects

upright=2.0|right|This diagram of a Wikidata item shows you the most important terms in Wikidata.

Clicking the title of a statement takes you to a page about that property. For example, the "author" property is Property:P50. Property pages in turn have labels, descriptions, aliases, and further statements, much like the Wikidata pages for real-world items.

The set of properties in Wikidata is steadily growing. Not all items in Wikidata have properties, and not all property values have been translated into all languages. For example, Victor Hugo's occupation as an "author" has been translated into nearly all languages, but lesser known occupations may have fewer translations. You need to consider how to fall back to an available language if a property or value isn't translated into a language you are supporting, and you shouldn't build your application around a property that only appears in a few statements. The API performs language fallback for you if possible. (Of course you can help by contributing missing statements and translations to Wikidata.)

Querying Wikibase
The extensions Wikibase Repository and Wikibase Client power Wikidata, together with related components. Most Wikimedia sites run Wikibase Client (check with Special:Version), while only wikidata.org itself runs Wikibase Repository. Wikidata Repository implements several modules for MediaWiki's Action API, all prefixed with. The main API module in Wikibase Repository is. (See its generated API help). This returns the dataset Wikidata has about items (QNNNNN entities) or properties.

Retrieving and displaying Wikidata information
Say you have associated Wikidata entity IDs with your application's entities, and you want to display the following information:


 * the label and description of the item
 * author (property P50)
 * publication date property P577)
 * genre (property P136)
 * a link to the Wikipedia article for more information

can return the same information that you see on an item's Wikidata page: labels, descriptions, aliases, "claims" (like statements), and sitelinks. Let's ask for this information about Les Misérables in a less popular language, Azerbaijani, to see how  and   work.


 * You can give  page titles on a wiki; but in this scenario, we provide it with the entity   of the Wikidata items for entities in our application.
 * You can specify the  you want for the information, and it will only return the description, labels, and aliases in that language (if they are available).
 * You can also specify  so that values and properties without a translation in your requested languages fall back to some value.
 * has no means to specify which properties you want, instead you request all claims about the entity. So in this scenario, we request.
 * You can specify a  for the wiki site links you want. In this scenario we only want the Wikipedia page (if any) on the wiki for the same language.

From the response, you can see the following information:


 * The label for Les Misérables is available in Azerbaijani ("Səfillər").
 * The description  falls back to the English description.
 * There is a wiki page for it on Azerbaijani Wikipedia: az:Səfillər (roman).

Choosing sitelinks
The generated API help for  includes all the possible values for   and. (Wikimedia encompasses a lot of wikis!) Visit Special:SiteMatrix for a table listing Wikimedia wikis. The wiki names are pretty standardized except for some edge cases, so it's safe to assume that wiki names from that table that exist and are not struck out (meaning closed) in. If you want to, for example, ask for links to Wikiquote sites that may not exist yet, your code can also query the API module  (documentation) and look through its response to dynamically build a list of relevant sites for.

Parsing claims
The claims that give properties values are unavoidably complex: there can be more than one and they may disagree, they differ in, they are (ideally) backed up by references, they may be qualified (for example the date range in which a claim applies).

As a result, for each property value you want, you must walk through an array of claims for it. In this example, for "author" and "genre" of Les Misérables, you would expect the value of a statement about them to be another item in Wikidata (rather than a simple number or date). To get the IDs for the genre (P136), we are looking for the following property (in the syntax for JSON elements used by jq): In pseudocode, you would locate  in the JSON response, then for each element in the array, you would check that its   exists and its value is "item", then you can safely access the. The result is a set of numbers of items, in this case 8261 and 192239.

You then need to request the labels of items Q8261 and Q192239 in the user's language, making a similar  request but only requesting. For performance, you should batch up all these follow-on queries and build a local cache of item labels, so that you don't repeatedly query the Wikidata API to find that Q8261 is a "novel" ("Roman" in Azerbaijani).

Getting the publication date (P577) is a little simpler since the value of a statement about it is a simple date rather than another item: In pseudocode, you would locate  in the JSON response, then for each element in the array, you would check that its   exists and its   is , then you can use its. The result is a set of times, in this case one value: "+1862-01-01T00:00:00Z". A time value's format resembles ISO 8601; the Wikibase DataModel gives the details, including  which in this case is 9, indicating this publication date is 1862.

action=wbgetclaims for claims alone
If you want only the claims of an item ( ' ), you can instead invoke the API module. It returns similar information.

Alternatives
You can associate an entity in your application with a page in a particular language's Wikipedia. Then as Page info in search results shows, you can query for and display useful information from that article such as a lead image thumbnail, opening text, and description (, |pageimages|pageterms&format=jsonfm&exsentences=2&exintro=&piprop=thumbnail&wbptterms=description&titles=Les%20Misérables&formatversion=2 try it for Les Misérables). A downside of this is page titles change so you may have to deal with redirects. Another downside is that it's not multilingual: you have to know the page's title in other wikis (for example, the article in Greek Wikipedia about Les Misérables is Οι Άθλιοι), or track down a "sitelink" to the page in another language. Hence that article talks about page info in the context of search&mdash;if your user is searching for articles from a wiki, you know the language and wiki to query.