guile-wikidata
==============

This package provides wikidata-query functions to query and print
data the public wikidata APIs at wikidata.org from Guile Scheme.

It is inspired by guile-sparql, python-wikidata_guessing and python-Wikidata.

It currently has the following dependencies besides guile:

* guile-json
* guix 0.15 or later
 * (guix import json) 2 procedures in for alist functionality and
   (guix import utils) and (guix http-client) for fetching from
   servers with error reporting.
   
(NOTE: We should really factor out a lot of the generic code in guix in
external libraries to keep libraries like this one light-weight.)

## Use as module

It is exported as "wikidata". It can be imported with:

```
(use-modules (wikidata apis)) ; for search and claims APIs
```
And:
```
(use-modules (wikidata sparql)) ; for support for SPARQL queries
```

The first enables you to get all the information in any Q-article in
Wikidata. 

The second one is very powerful and enables you e.g. to construct a
query to get a list of all free software (Q341) in Wikidata. This
could then e.g. be automatically correlated with package data in guix
adding a field with the Q-id to the relevant package.

## Example usage

### Show

To search for paris and get the first 15 results with sv labels
and descriptions, do:

```
(search "paris" #:limit 15 #:language 'sv)
```

#### Notes:

Fallback language is 'en and output is currently limited to Qid,
label, description (Use the medium level procedures to get other
data). No more than 50 (500 for bots) results are allowed. 

There is a bug in the API so only english results are returned at the
time of this writing (dec 2018).

#### Example output:

First 15:       Label & Description
Q90:    Paris: capital and largest city of Fr...
Q167646:        Paris: son of Priam, king of Troy
Q830149:        Paris: county seat of Lamar County, T...
Q3181341:       Paris: county seat of Bourbon County,...
Q162121:        Paris: genus of plants
Q576584:        Paris: city in Illinois
Q1018504:       Paris: city in Tennessee, United Stat...
Q984459:        Paris: city in Idaho
Q79917: Paris: city in Arkansas
Q160946:        Paris, Texas: 1984 film by Wim Wenders
Q934294:        Paris: town in Maine, USA
Q18331346:      Paris: family name
Q960025:        Paris: city in Missouri
Q1158980:       Paris: male given name
Q366081:        Paris Bordone: Italian artist


### Medium level-example: extract-search

To search on wikidata and get back an alist with the 10 first results
with each element being an alist of label, desc, qid, do this:

```
(extract-search "Guix")
```

#### Example output:

scheme@(guile-user) [2]> (load "wikidata.scm")
scheme@(guile-user) [2]> ,use(wikidata)
scheme@(guile-user) [2]> (extract-result "Guix")
$1 = ((("label" . "GNU Guix") ("description" . "a purely functional
package manager for the GNU system") ("id" . "Q18968627")) (("label"
. "Guixe\
rs") ("description" . #f) ("id" . "Q1905661")) (("label" . "Guixi")
("description" . "county-level city") ("id" . "Q1335331")) (("label"
. "Guixi\
ng Qiu") ("description" . #f) ("id" . "Q39066155")) (("label"
. "GuixSD") ("description" . "distribution of the GNU system via the
Guix package m\
anager, project maintained by the GNU Project") ("id" . "Q19597382"))
(("label" . "Guixi Railway Station") ("description" . "railway station
in G\
uixi, Yingtan") ("id" . "Q24835612")) (("label" . "Guixi Subdistrict")
("description" . "subdistrict in Wuhou, Chengdu") ("id"
. "Q11111703")) ((\
"label" . "Guixiang") ("description" . "military general, father of
Longyu") ("id" . "Q8172534")) (("label" . "Guixia Zhao")
("description" . #f)\
 ("id" . "Q56528602")) (("label" . "Guixue Wang") ("description" . #f)
 ("id" . "Q45902385")))

You could then map over this list and get the label and description or
author(s) from Wikidata via queries to the wbgetentity API. See the
source for procedures.