Wikibase/API

MediaWiki-versie:

≥ 1.9

Wat is de Wikibase API?

Wikibase biedt een algemeen mechanisme om statements op te slaan als gestructureerde data. De statements voor productie-items op de server wikidata.org. Lees Wikidata:Glossary voor meer informatie over Wikibase en andere concepten.

Een statement

De Wikibase API is voor het opvragen, toevoegen, verwijderen en bewerken van informatie op Wikidata of een andere Wikibase instantie.

Het wordt verkregen met een aantal extensies voor MediaWiki API-modules. Om de API Wikibase te gebruiken moet u dus redelijk bekend zijn met de MediaWiki Action API: o.a. acties en opvragingen, als ook de generieke parameters zoals curtimestamp en requestid.

Hoe de Wikibase API te gebruiken?

Stuur verzoeken naar de API via HTTP, gelijk als bij de MediaWiki Action API. In deze tutorial staat hoe de MediaWiki Action API te gebruiken is.

Formaat verzoeken

Het eindpunt voor de API is https://wikidata.org/w/api.php.

Voeg in de query string de parameter action toe, die geeft de API aan welke actie er uitgevoerd moet worden. Voorbeeld: met action=wbgetentities wordt aangegeven dat de API de gegevens voor de Wikibase entiteiten moet ophalen. Voor 'meta' en 'property' submodules, gebruik dan action=query&meta=yourmodule resp. action=query&prop=modulename.

Enkele parameters zijn bijna altijd beschikbaar. 'Plural forms' worden gebruikt in gevallen waar een parameter meerdere waarden kan hebben. De parameters zijn:

• id/ids: Identificeert een of meer specifieke entiteiten, meestal een item. De meervoudsvorm wordt gebruikt in wbgetentities. Lijsten van id's moeten gescheiden worden met een "|"
• site ∩ title/sites ∩ titles: Identificeert een of meer items. De meervoudsvorm wordt gebruikt in wbgetentities. De meervoudsvorm mag niet tegelijk worden gebruikt bij sites en titles.
• language/languages: De parameter 'language' filtert 'labels' en 'descriptions' in een actie 'get' of geeft een specifieke taal aan voor een groep acties.
• format: De mogelijke waarden zijn json, jsonfm (bij het debuggen), xml en xmlfm (bij het debuggen).
• summary: Voegt een gebruiker gespecificeerde samenvatting toe naast de door het systeem genereerde samenvatting.
• token: Een versleutelde tekst (encryptie) die bij de aanvraag moet worden meegegeven.
• baserevid: Het ID van de laatste bekende revisie die moet worden verwerkt zodat de server conflicterende bewerkingen kan herkennen.

Een eenvoudige query

GET request

Haal het item voor de pagina "Berlin" op uit de Engelse Wikipedia.

api.php?action=wbgetentities&sites=enwiki&titles=Berlin&props=descriptions&languages=en&format=json [probeer het in de ApiSandbox]

Uitleg van de delen van de URL:

• http://www.wikidata.org/w/api.php is het 'main endpoint', het uitvoerende programma.
• action=wbgetentities geeft aan dat de API de gegevens voor de Wikibase entiteiten moet ophalen.
• sites=enwiki geeft aan dat de gegevens uit de Engelse Wikipedia moeten komen.
• titles=Berlin is de titel van de pagina waar de gegevens staan.
• props=descriptions geeft de attributen (properties) van de entiteiten aan die opgehaald moeten worden, in dit geval de beschrijvingen (descriptions) van de entiteiten.
• languages=en geeft aan dat de resultaten gefilterd moeten worden op de taal Engels.
• format=json geeft het uitvoerformaat aan, in dit geval het aanbevolen formaat JSON.

Antwoord

{
    "entities": {
        "Q64": {
            "type": "item",
            "id": "Q64",
            "descriptions": {
                "en": {
                    "language": "en",
                    "value": "capital and largest city of Germany"
                }
            }
        }
    },
    "success": 1
}

Het antwoord zal doorgaans bevatten:

• Een key success met een boolean waarde, die als integer gebruikt kan worden als het verzoek gelukt is. Als de integer nul is, dan kunnen de aanvullende waarden verkeerd zijn.
• Een error key met een object van twee of drie keys, code, info en *, als de aanvraag mislukt is.
• Informatie over de actie. De informatie wordt op het hoogste niveau doorgegeven of onder item als het een of meerdere items zijn. Bij meerdere items heeft elk item een eigen ID.

Lege objecten worden als JSON arrays teruggeven, dus niet als objecten, lege parameters verwijderen de actuele waarde van het item.

API documentatie en Wikibase modules

Documentatie die uit de broncode van de Action API wordt gegenereerd (inclusief Wikibase 'wb' API modules): wikidata.org/w/api.php

Meta submodules

• wikibase: Get information about the Wikibase client and the associated Wikibase repository.
• wbcontentlanguages: Returns information about the content languages Wikibase accepts in different contexts.

Property submodules

• pageterms: Get the Wikidata terms (typically labels, descriptions and aliases) associated with a page via a sitelink.
• wbentityusage: Returns all entity IDs used in the given pages.

API modules

• wbgetentities: Haalt gegevens op van meerdere Wikibase-entiteiten.
• wbavailablebadges: Vraagt beschikbare badge-items op.
• wbcreateclaim: Maakt Wikibase-verklaringen aan.
• wbcreateredirect: Maakt Entiteit-doorverwijzingen aan.
• wbeditentity: Maakt een enkele nieuwe Wikibase-entiteit aan en werkt het bij met geserialiseerde informatie.
• wbformatvalue: Formatteert DataValues.
• wbgetclaims: Haalt Wikibase-claims op.
• wblinktitles: Koppelt twee pagina's op twee verschillende wiki's aan elkaar door middel van een Wikibase-item.
• wbmergeitems: Voegt meerdere items samen.
• wbparsevalue: Verwerkt waarden met een ValueParser (waardeverwerker).
• wbremoveclaims: Wikibase-claims verwijderen.
• wbremovequalifiers: Een kwalificatie van een claim verwijderen.
• wbremovereferences: Verwijdert één of meerdere bronnen van de dezelfde verklaring.
• wbsearchentities: Searches for entities using labels and aliases.
• wbsetaliases: Aliassen voor een Wikibase-entiteit instellen.
• wbsetclaim: Maakt een complete verklaring aan of werkt deze bij
• wbsetclaimvalue: Stelt de waarde van een Wikibase-verklaring in.
• wbsetdescription: Stelt een beschrijving in voor een enkele Wikibase-entiteit.
• wbsetlabel: Stelt een label in voor een enkele Wikibase-entiteit.
• wbsetqualifier: Maakt een kwalificatie aan of stelt de waarde in van een reeds bestaande.
• wbsetreference: Maakt een bron aan of stelt de waarde in van een reeds bestaande.
• wbsetsitelink: Koppelt een pagina op een wiki aan een Wikibase-item, of verwijdert een dergelijke reeds gemaakte koppeling.
• wbsgetsuggestions: API module for getting suggestions of additional properties to add to a Wikibase entity. The API module is primarily intended for use by the suggester widget when users are editing Wikibase entities.
• wbcheckconstraints: Voert een beperkingen controle uit op de gewenste entiteit en toont het resultaat.
• wbcheckconstraintparameters: Checks the constraint parameters of constraint statements.

Mogelijke fouten

Om eventuele fouten te vinden, gebruik de module action=paraminfo&modules=modulename. Het foutformaat komt overeen met dat van de MediaWiki Action API. Legacy formaat fouten en waarschuwingen.

Alle foutteksten van de Wikibase modules dienen internationaal (i18n) en lokaal gemaakt (l10n) te worden. De taal van de ingelogde gebruiker is de standaardtaal bij foutteksten, dit kan aangepast worden (override) door uselang=languageCode toe te voegen aan de URL query string.

Fouttype	Code	Info
An internationalized error message that isn't localized.	no-such-item	<wikibase-api-no-such-item>
A correctly localized error message.	no-such-item	There are no such item to be found
A localized variant.(Norwegian)	no-such-item	Det finnes ingen slik item

Aanvullende opmerkingen

• Veel Wikimedia wiki's gebruiken de extensie Wikibase Client. Hiermee kunnen API clients op die wiki de wikibase meta submodule gebruiken om de URL's van de volledige Wikibase repo te bepalen, en de pageterms property submodule gebruiken voor het verkrijgen van Wikidata informatie over pagina's op de lokale wiki.
• Op de Wikibase kunnen de Gregoriaanse kalender (d:Q1985727) en de Juliaanse kalender (d:Q1985786) worden gebruikt.
• De API gebruikt de revisie-ID's om conflicterende bewerkingen te herkennen. Als er zo'n 'edit collision is, dan moet bij de aanvraag een nieuwere revisie aanvragen. Dit gaat dan over het verzoeken van wbgetentities voor het gevraagde item, en dan het opslaan (en gebruiken) van de bijbehorende revisie.
• Op elke MediaWiki installatie kan Wikibase worden uitgevoerd. Op het Wikimedia cluster zullen de meeste wiki's niet alle extensies van Wikibase gebruiken. Wikimedia Commons heeft een eigen Wikibase voor de eigenschappen van de bestanden op Commons.
• Test de waarde van info niet op een bepaalde fout, gebruik de waarde code, deze waarde wordt niet vertaald.

Zie ook

• API:Hoofdpagina - De verkorte instructie voor de MediaWiki Action API.
• API:FAQ/nl - Veel gestelde vragen over de MediaWiki Action API.
• API:Tutorial - Een tutorial over hoe de MediaWiki Action API gebruikt moet worden.
• Download Wikidata database dumps in JSON (aanbevolen), XML en RDF formaten.