Wikidata query service/User Manual/MWAPI

From MediaWiki.org
Jump to: navigation, search

Mediawiki API Query Service[edit]

Mediawiki API Service allows to call out to Mediawiki API from SPARQL, and receive the results from inside the SPARQL query.

Service[edit]

The query is initiated by SERVICE with URL wikibase:mwapi.

Input[edit]

Query inputs are specified as service parameters, in clause looking like:

      bd:serviceParam mwapi:language "en" .

This defines parameter "language" in the query.

There are two special parameters, api and endpoint, which are always required and identify the endpoint host (wiki) and the specific API used. The API endpoints are pre-defined in configuration, see below. Currently, only pre-configured endpoints are allowed.

Example:

      bd:serviceParam wikibase:api "EntitySearch" .
      bd:serviceParam wikibase:endpoint "www.wikidata.org" .

The rest of the parameters use predicate starting with mwapi: and the name is the name of the parameter in the query, e.g. mwapi:srsearch. The value is the value that will be used in the query, it can be a constant or a variable. If the variable is not bound when the query is run, the parameter is skipped or, if it is required, as defined by the configuration, an error happens.

It is permissible to add input parameters not specified in the configuration, they will be passed to the service query. Please refer to the API documentation for the lists of parameters each service has.

Currently supported endpoints are: *.wikipedia.org, commons.wikimedia.org, www.mediawiki.org, www.wikidata.org, test.wikidata.org. If any other wikis need to be supported, please leave a comment to the developers and we will enable them.

Output[edit]

Mediawiki API services are asked to return the results in XML, from which they are extracted to output parameters using XPath. There are two ways to specify output parameters: by referring to the configured parameter and by specifying XPath directly.

The configured output parameter would be used like this:

      ?title wikibase:apiOutput mwapi:title .

This results in variable ?title bound to the XPath result defined by "title" output variable.

The direct XPath expression is used like this:

    ?ns wikibase:apiOutput "@ns" .

In this case, the object of the triple is an XPath string and not mwapi: URI.

In both cases, XPath is evaluated relative to item path, specified in service configuration. There's no difference in XPath evaluation for both forms.

The predicates that can be used are wikibase:apiOutput, wikibase:apiOutputItem and wikibase:apiOutputURI. The first form results in a string taken literally, the second interprets the string as Item ID and constructs full item URI and the third interprets the string as an URI and constructs an URI value.

Supported services[edit]

Currently the following services are supported:

Service Inputs Outputs Description
Generator generator, prop, pprop title, item, pageid, lastrevid, timestamp Call any generator API. Use "generator" parameter to specify, and specific generator parameters to further amend the search (see the example below).
Categories titles,cllimit category, title Get a list of categories on the page.
Search srsearch,srwhat,srlimit title Full-text search in wiki.
EntitySearch search,language,type,limit item,label Wikibase entity search, by title.

Required parameters are in bold. Please refer to the service documentation (linked in Service column) for the meaning of input parameters.

The full list of services can be seen in the production config file.

Configuration[edit]

The service is configured by a JSON file listing particular API configurations and a list of endpoints. Please see the example configuration.

On the top level, there is a list of endpoint hostnames under "endpoints" and API configs under "services", with the keys being service names for use with wikibase:api.

Only endpoints listed in endpoints are allowed. The list can also contain prefixes - i.e. .wikipedia.org allows any hostname that ends with .wikipedia.org.

Individual service configuration[edit]

The service configuration has two required elements - params for input parameters and output for output parameters. All the rest are currently ignored by the code, but @note and @docs are used to store description and link to documentation about particular API. It is safe to assume that config entries starting with @ will be always ignored by the code.

Input[edit]

Input parameters are keyed by parameter name, and the value can be either constant - in which case the parameter is fixed, always present and its value can not be changed, or object, which contains description of variable parameter.

Variable parameter is bound by the query template or variable. The configuration specifies its type, which is currently ignored but may be enforced later. The configuration can also specify the default, which will be used in case the parameter is not specified or not bound. If the default is "",the parameter will be omitted in case it is not specified or not bound. If no default is specified, the parameter is treated as required and omitting it will result in an error.

Output[edit]

Output is defined by items , which specifies the XPath for extracting specific result elements for the query, and set of output variables under vars. Each key in vars is variable name (to be used with wikibase:apiOutput) and the value is XPath to this particular value, calculated relative to the items path. Note that it is possible to also specify absolute paths for specific variables, but in that case you will get copies of that value for each result set.

Examples[edit]

Find all entities with labels "cheese" and get their types[edit]
SELECT * WHERE {
  SERVICE wikibase:mwapi {
      bd:serviceParam wikibase:api "EntitySearch" .
      bd:serviceParam wikibase:endpoint "www.wikidata.org" .
      bd:serviceParam mwapi:search "cheese" .
      bd:serviceParam mwapi:language "en" .
      ?item wikibase:apiOutputItem mwapi:item .
  }
  ?item (wdt:P279|wdt:P31) ?type
}

Try it!

Find articles in Wikipedia[edit]
SELECT * WHERE {
  SERVICE wikibase:mwapi {
      bd:serviceParam wikibase:api "Search" .
      bd:serviceParam wikibase:endpoint "en.wikipedia.org" .
      bd:serviceParam mwapi:srsearch "cheese" .
      ?title wikibase:apiOutput mwapi:title .
  }
}

Try it!

Find subcategories[edit]
SELECT * WHERE {
  wd:Q27119725 wdt:P910 ?category .
  ?link schema:about ?category; schema:isPartOf <https://en.wikipedia.org/>; schema:name ?title .
  SERVICE wikibase:mwapi {
	 bd:serviceParam wikibase:api "Generator" .
     bd:serviceParam wikibase:endpoint "en.wikipedia.org" .
     bd:serviceParam mwapi:gcmtitle ?title .
     bd:serviceParam mwapi:generator "categorymembers" .
     bd:serviceParam mwapi:gcmprop "ids|title|type" .
     bd:serviceParam mwapi:gcmlimit "max" .
    # out
    ?subcat wikibase:apiOutput mwapi:title  .
    ?ns wikibase:apiOutput "@ns" .
    ?item wikibase:apiOutputItem mwapi:item .
  }
}

Try it!