[med-svn] [r-cran-wikidatar] 01/02: New upstream version 1.4.0
Andreas Tille
tille at debian.org
Mon Oct 2 13:10:53 UTC 2017
This is an automated email from the git hooks/post-receive script.
tille pushed a commit to branch master
in repository r-cran-wikidatar.
commit 9d0cd5b102b62ce9e38421e550407a60279cc818
Author: Andreas Tille <tille at debian.org>
Date: Mon Oct 2 15:10:28 2017 +0200
New upstream version 1.4.0
---
DESCRIPTION | 21 ++++
LICENSE | 2 +
MD5 | 29 +++++
NAMESPACE | 19 +++
NEWS | 33 +++++
R/WikidataR.R | 15 +++
R/geo.R | 182 +++++++++++++++++++++++++++
R/gets.R | 127 +++++++++++++++++++
R/prints.R | 125 +++++++++++++++++++
R/utils.R | 90 ++++++++++++++
README.md | 38 ++++++
build/vignette.rds | Bin 0 -> 211 bytes
inst/doc/Introduction.R | 36 ++++++
inst/doc/Introduction.Rmd | 82 ++++++++++++
inst/doc/Introduction.html | 290 +++++++++++++++++++++++++++++++++++++++++++
man/WikidataR.Rd | 18 +++
man/extract_claims.Rd | 33 +++++
man/find_item.Rd | 41 ++++++
man/get_geo_box.Rd | 58 +++++++++
man/get_geo_entity.Rd | 58 +++++++++
man/get_item.Rd | 42 +++++++
man/get_random.Rd | 39 ++++++
man/print.find_item.Rd | 16 +++
man/print.find_property.Rd | 16 +++
man/print.wikidata.Rd | 19 +++
tests/testthat.R | 4 +
tests/testthat/test_geo.R | 48 +++++++
tests/testthat/test_gets.R | 30 +++++
tests/testthat/test_search.R | 17 +++
vignettes/Introduction.Rmd | 82 ++++++++++++
30 files changed, 1610 insertions(+)
diff --git a/DESCRIPTION b/DESCRIPTION
new file mode 100644
index 0000000..c0657f9
--- /dev/null
+++ b/DESCRIPTION
@@ -0,0 +1,21 @@
+Package: WikidataR
+Type: Package
+Title: API Client Library for 'Wikidata'
+Version: 1.4.0
+Date: 2017-09-21
+Author: Oliver Keyes [aut, cre], Serena Signorelli [aut, cre],
+ Christian Graul [ctb], Mikhail Popov [ctb]
+Maintainer: Oliver Keyes <ironholds at gmail.com>
+Description: An API client for the Wikidata <http://wikidata.org/> store of
+ semantic data.
+BugReports: https://github.com/Ironholds/WikidataR/issues
+URL: https://github.com/Ironholds/WikidataR/issues
+License: MIT + file LICENSE
+Imports: httr, jsonlite, WikipediR (>= 1.4.0), utils
+Suggests: testthat, knitr, pageviews
+VignetteBuilder: knitr
+RoxygenNote: 6.0.1
+NeedsCompilation: no
+Packaged: 2017-09-22 02:22:59 UTC; ironholds
+Repository: CRAN
+Date/Publication: 2017-09-22 05:43:08 UTC
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..ebbb227
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,2 @@
+YEAR: 2014
+COPYRIGHT HOLDER: Oliver Keyes
\ No newline at end of file
diff --git a/MD5 b/MD5
new file mode 100644
index 0000000..3fd3d6c
--- /dev/null
+++ b/MD5
@@ -0,0 +1,29 @@
+eb02df461c648d4da3f983afc54503d5 *DESCRIPTION
+1d9678dbfe1732b5d2c521e07b2ceef0 *LICENSE
+8f5819571233c6d8d08d23f9bfc9979b *NAMESPACE
+2776dd31c6533290c7fd2cd414a2b4bf *NEWS
+e6967d650ab6b6462db1793f0fe5a46b *R/WikidataR.R
+5ad80eca5081277b549234400a2dd7a3 *R/geo.R
+4229fe3d75d444beb2fa00ae2bdcdba6 *R/gets.R
+e588e32737791defc6f982114f39d75c *R/prints.R
+c16306d76abfe6d0e78dd62bf77173c7 *R/utils.R
+6095c718be80727c886cff790734e9b5 *README.md
+a1d7177a65e4773e0c7fae2ccb9d143d *build/vignette.rds
+43cc957bbe79bc0b25b62be190705064 *inst/doc/Introduction.R
+5ab492a540df058a91940716bf3e9c4f *inst/doc/Introduction.Rmd
+3e88344829cf501478fb9e8c841a18b5 *inst/doc/Introduction.html
+dea44cd789a89155878f75eb0c430541 *man/WikidataR.Rd
+ca32f05afde2f042aa5ce7c799d63976 *man/extract_claims.Rd
+d6439bd1505303b2c069a9ec5a482346 *man/find_item.Rd
+6486678f64813a107103352d076f2ed3 *man/get_geo_box.Rd
+3d485c862e1ab25782c98cf2d2e8c009 *man/get_geo_entity.Rd
+d44df4503eefe77a44f15be028f977b7 *man/get_item.Rd
+9a902a02739165e2a862571144e74ebd *man/get_random.Rd
+aa48f8096742e46ef2f78f0ec960b039 *man/print.find_item.Rd
+5f88c4bb32c2b352ff1cab1f9124a982 *man/print.find_property.Rd
+294468449f0be62ebd8443bd10e926be *man/print.wikidata.Rd
+ced86f667bcd51239f1c0d5d5c1a492b *tests/testthat.R
+8f0a71f6693281b0d26afe5532158157 *tests/testthat/test_geo.R
+2986dd17d5e90976391d811f9bb3bb1c *tests/testthat/test_gets.R
+38bd7da6e5db4b243603b6d0d53e8cdd *tests/testthat/test_search.R
+5ab492a540df058a91940716bf3e9c4f *vignettes/Introduction.Rmd
diff --git a/NAMESPACE b/NAMESPACE
new file mode 100644
index 0000000..a40769d
--- /dev/null
+++ b/NAMESPACE
@@ -0,0 +1,19 @@
+# Generated by roxygen2: do not edit by hand
+
+S3method(print,find_item)
+S3method(print,find_property)
+S3method(print,wikidata)
+export(extract_claims)
+export(find_item)
+export(find_property)
+export(get_geo_box)
+export(get_geo_entity)
+export(get_item)
+export(get_property)
+export(get_random_item)
+export(get_random_property)
+importFrom(WikipediR,page_content)
+importFrom(WikipediR,query)
+importFrom(WikipediR,random_page)
+importFrom(httr,user_agent)
+importFrom(jsonlite,fromJSON)
diff --git a/NEWS b/NEWS
new file mode 100644
index 0000000..84e9813
--- /dev/null
+++ b/NEWS
@@ -0,0 +1,33 @@
+1.4.0
+=================================================
+* extract_claims() allows you to, well, extract claims.
+* SPARQL syntax bug with some geo queries now fixed (thanks to Mikhail Popov)
+
+1.3.0
+=================================================
+* get_* functions are now vectorised
+
+1.2.0
+=================================================
+* geographic data for entities that exist relative to other Wikidata items can now be retrieved
+with get_geo_entity and get_geo_box, courtesy of excellent Serena Signorelli's excellent
+QueryWikidataR package.
+
+* A bug in printing returned objects is now fixed.
+
+1.1.0
+=================================================
+* You can now retrieve multiple random properties or items with get_random_item and get_random_property
+
+1.0.1
+=================================================
+* Various documentation and metadata improvements.
+
+1.0.0
+=================================================
+* Fix a bug in get_* functions due to a parameter name mismatch
+* Print methods added by Christian Graul
+
+0.5.0
+=================================================
+* This is the initial release! See the explanatory vignettes.
diff --git a/R/WikidataR.R b/R/WikidataR.R
new file mode 100644
index 0000000..9614e67
--- /dev/null
+++ b/R/WikidataR.R
@@ -0,0 +1,15 @@
+#' @title API client library for Wikidata
+#' @description This package serves as an API client for \href{Wikidata}{https://www.wikidata.org}.
+#' See the accompanying vignette for more details.
+#'
+#' @name WikidataR
+#' @docType package
+#'@seealso \code{\link{get_random}} for selecting a random item or property,
+#'\code{\link{get_item}} for a /specific/ item or property, or \code{\link{find_item}}
+#'for using search functionality to pull out item or property IDs where the descriptions
+#'or aliases match a particular search term.
+#' @importFrom WikipediR page_content random_page query
+#' @importFrom httr user_agent
+#' @importFrom jsonlite fromJSON
+#' @aliases WikidataR WikidataR-package
+NULL
\ No newline at end of file
diff --git a/R/geo.R b/R/geo.R
new file mode 100644
index 0000000..37efdff
--- /dev/null
+++ b/R/geo.R
@@ -0,0 +1,182 @@
+clean_geo <- function(results){
+ do.call("rbind", lapply(results, function(item){
+ point <- unlist(strsplit(gsub(x = item$coord$value, pattern = "(Point\\(|\\))", replacement = ""),
+ " "))
+ wd_id <- gsub(x = item$item$value, pattern = "http://www.wikidata.org/entity/",
+ replacement = "", fixed = TRUE)
+ return(data.frame(item = wd_id,
+ name = ifelse(item$name$value == wd_id, NA, item$name$value),
+ latitutde = as.numeric(point[1]),
+ longitude = as.numeric(point[2]),
+ stringsAsFactors = FALSE))
+
+ }))
+}
+
+#'@title Retrieve geographic information from Wikidata
+#'@description \code{get_geo_entity} retrieves the item ID, latitude
+#'and longitude of any object with geographic data associated with \emph{another}
+#'object with geographic data (example: all the locations around/near/associated with
+#'a city).
+#'
+#'@param entity a Wikidata item (\code{Q...}) or series of items, to check
+#'for associated geo-tagged items.
+#'
+#'@param language the two-letter language code to use for the name
+#'of the item. "en" by default, because we're imperialist
+#'anglocentric westerners.
+#'
+#'@param radius optionally, a radius (in kilometers) around \code{entity}
+#'to restrict the search to.
+#'
+#'@param ... further arguments to pass to httr's GET.
+#'
+#'@return a data.frame of 5 columns:
+#'\itemize{
+#' \item{item}{ the Wikidata identifier of each object associated with
+#' \code{entity}.}
+#' \item{name}{ the name of the item, if available, in the requested language. If it
+#' is not available, \code{NA} will be returned instead.}
+#' \item{latitude}{ the latitude of \code{item}}
+#' \item{longitude}{ the longitude of \code{item}}
+#' \item{entity}{ the entity the item is associated with (necessary for multi-entity
+#' queries).}
+#'}
+#'
+#'@examples
+#'# All entities
+#'sf_locations <- get_geo_entity("Q62")
+#'
+#'# Entities with French, rather than English, names
+#'sf_locations <- get_geo_entity("Q62", language = "fr")
+#'
+#'# Entities within 1km
+#'sf_close_locations <- get_geo_entity("Q62", radius = 1)
+#'
+#'# Multiple entities
+#'multi_entity <- get_geo_entity(entity = c("Q62", "Q64"))
+#'
+#'@seealso \code{\link{get_geo_box}} for using a bounding box
+#'rather than an unrestricted search or simple radius.
+#'
+#'@export
+get_geo_entity <- function(entity, language = "en", radius = NULL, ...){
+
+ entity <- check_input(entity, "Q")
+
+ if(is.null(radius)){
+ query <- paste0("SELECT DISTINCT ?item ?name ?coord ?propertyLabel WHERE {
+ ?item wdt:P131* wd:", entity, ". ?item wdt:P625 ?coord .
+ SERVICE wikibase:label {
+ bd:serviceParam wikibase:language \"", language, "\" .
+ ?item rdfs:label ?name
+ }
+ }
+ ORDER BY ASC (?name)")
+ } else {
+ query <- paste0("SELECT ?item ?name ?coord
+ WHERE {
+ wd:", entity, " wdt:P625 ?mainLoc .
+ SERVICE wikibase:around {
+ ?item wdt:P625 ?coord .
+ bd:serviceParam wikibase:center ?mainLoc .
+ bd:serviceParam wikibase:radius \"", radius,
+ "\" .
+ }
+ SERVICE wikibase:label {
+ bd:serviceParam wikibase:language \"", language, "\" .
+ ?item rdfs:label ?name
+ }
+ } ORDER BY ASC (?name)")
+ }
+
+ if(length(query) > 1){
+ return(do.call("rbind", mapply(function(query, entity, ...){
+ output <- clean_geo(sparql_query(query, ...)$results$bindings)
+ output$entity <- entity
+ return(output)
+ }, query = query, entity = entity, ..., SIMPLIFY = FALSE)))
+ }
+ output <- clean_geo(sparql_query(query)$results$bindings)
+ output$entity <- entity
+ return(output)
+}
+
+#'@title Get geographic entities based on a bounding box
+#'@description \code{get_geo_box} retrieves all geographic entities in
+#'Wikidata that fall between a bounding box between two existing items
+#'with geographic attributes (usually cities).
+#'
+#'@param first_city_code a Wikidata item, or series of items, to use for
+#'one corner of the bounding box.
+#'
+#'@param first_corner the direction of \code{first_city_code} relative
+#'to \code{city} (eg "NorthWest", "SouthEast").
+#'
+#'@param second_city_code a Wikidata item, or series of items, to use for
+#'one corner of the bounding box.
+#'
+#'@param second_corner the direction of \code{second_city_code} relative
+#'to \code{city} (eg "NorthWest", "SouthEast").
+#'
+#'@param language the two-letter language code to use for the name
+#'of the item. "en" by default.
+#'
+#'@param ... further arguments to pass to httr's GET.
+#'
+#'@return a data.frame of 5 columns:
+#'\itemize{
+#' \item{item}{ the Wikidata identifier of each object associated with
+#' \code{entity}.}
+#' \item{name}{ the name of the item, if available, in the requested language. If it
+#' is not available, \code{NA} will be returned instead.}
+#' \item{latitude}{ the latitude of \code{item}}
+#' \item{longitude}{ the longitude of \code{item}}
+#' \item{entity}{ the entity the item is associated with (necessary for multi-entity
+#' queries).}
+#'}
+#'
+#'@examples
+#'# Simple bounding box
+#'bruges_box <- WikidataR:::get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")
+#'
+#'# Custom language
+#'bruges_box_fr <- WikidataR:::get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
+#' language = "fr")
+#'
+#'@seealso \code{\link{get_geo_entity}} for using an unrestricted search or simple radius,
+#'rather than a bounding box.
+#'
+#'@export
+get_geo_box <- function(first_city_code, first_corner, second_city_code, second_corner,
+ language = "en", ...){
+
+ # Input checks
+ first_city_code <- check_input(first_city_code, "Q")
+ second_city_code <- check_input(second_city_code, "Q")
+
+ # Construct query
+ query <- paste0("SELECT ?item ?name ?coord WHERE {
+ wd:", first_city_code, " wdt:P625 ?Firstloc .
+ wd:", second_city_code, " wdt:P625 ?Secondloc .
+ SERVICE wikibase:box {
+ ?item wdt:P625 ?coord .
+ bd:serviceParam wikibase:corner", first_corner, " ?Firstloc .
+ bd:serviceParam wikibase:corner", second_corner, " ?Secondloc .
+ }
+ SERVICE wikibase:label {
+ bd:serviceParam wikibase:language \"", language, "\" .
+ ?item rdfs:label ?name
+ }
+ }ORDER BY ASC (?name)")
+
+ # Vectorise if necessary, or not if not!
+ if(length(query) > 1){
+ return(do.call("rbind", mapply(function(query, ...){
+ output <- clean_geo(sparql_query(query, ...)$results$bindings)
+ return(output)
+ }, query = query, ..., SIMPLIFY = FALSE)))
+ }
+ output <- clean_geo(sparql_query(query)$results$bindings)
+ return(output)
+}
\ No newline at end of file
diff --git a/R/gets.R b/R/gets.R
new file mode 100644
index 0000000..2a9c5ce
--- /dev/null
+++ b/R/gets.R
@@ -0,0 +1,127 @@
+#'@title Retrieve specific Wikidata items or properties
+#'@description \code{get_item} and \code{get_property} allow you to retrieve the data associated
+#'with individual Wikidata items and properties, respectively. As with
+#'other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
+#'to manipulate and see the underlying structure of the data.
+#'
+#'@param id the ID number(s) of the item or property you're looking for. This can be in
+#'various formats; either a numeric value ("200"), the full name ("Q200") or
+#'even with an included namespace ("Property:P10") - the function will format
+#'it appropriately. This function is vectorised and will happily accept
+#'multiple IDs.
+#'
+#'@param ... further arguments to pass to httr's GET.
+#'
+#'@seealso \code{\link{get_random}} for selecting a random item or property,
+#'or \code{\link{find_item}} for using search functionality to pull out
+#'item or property IDs where the descriptions or aliases match a particular
+#'search term.
+#'
+#'@examples
+#'
+#'#Retrieve a specific item
+#'adams_metadata <- get_item("42")
+#'
+#'#Retrieve a specific property
+#'object_is_child <- get_property("P40")
+#'
+#'@aliases get_item get_property
+#'@rdname get_item
+#'@export
+get_item <- function(id, ...){
+ id <- check_input(id, "Q")
+ output <- (lapply(id, wd_query, ...))
+ class(output) <- "wikidata"
+ return(output)
+}
+
+#'@rdname get_item
+#'@export
+get_property <- function(id, ...){
+ has_grep <- grepl("^P(?!r)",id, perl = TRUE)
+ id[has_grep] <- paste0("Property:", id[has_grep])
+ id <- check_input(id, "Property:P")
+
+ output <- (lapply(id, wd_query, ...))
+ class(output) <- "wikidata"
+ return(output)
+}
+
+#'@title Retrieve randomly-selected Wikidata items or properties
+#'@description \code{get_random_item} and \code{get_random_property} allow you to retrieve the data
+#'associated with randomly-selected Wikidata items and properties, respectively. As with
+#'other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
+#'to manipulate and see the underlying structure of the data.
+#'
+#'@param limit how many random items to return. 1 by default, but can be higher.
+#'
+#'@param ... arguments to pass to httr's GET.
+#'
+#'@seealso \code{\link{get_item}} for selecting a specific item or property,
+#'or \code{\link{find_item}} for using search functionality to pull out
+#'item or property IDs where the descriptions or aliases match a particular
+#'search term.
+#'
+#'@examples
+#'
+#'#Random item
+#'random_item <- get_random_item()
+#'
+#'#Random property
+#'random_property <- get_random_property()
+#'
+#'@aliases get_random get_random_item get_random_property
+#'@rdname get_random
+#'@export
+get_random_item <- function(limit = 1, ...){
+ return(wd_rand_query(ns = 0, limit = limit, ...))
+}
+
+#'@rdname get_random
+#'@export
+get_random_property <- function(limit = 1, ...){
+ return(wd_rand_query(ns = 120, limit = limit, ...))
+}
+
+#'@title Search for Wikidata items or properties that match a search term
+#'@description \code{find_item} and \code{find_property} allow you to retrieve a set
+#'of Wikidata items or properties where the aliase or descriptions match a particular
+#'search term. As with other \code{WikidataR} code, custom print methods are available;
+#'use \code{\link{str}} to manipulate and see the underlying structure of the data.
+#'
+#'@param search_term a term to search for.
+#'
+#'@param language the language to return the labels and descriptions in; this should
+#'consist of an ISO language code. Set to "en" by default.
+#'
+#'@param limit the number of results to return; set to 10 by default.
+#'
+#'@param ... further arguments to pass to httr's GET.
+#'
+#'@seealso \code{\link{get_random}} for selecting a random item or property,
+#'or \code{\link{get_item}} for selecting a specific item or property.
+#'
+#'@examples
+#'
+#'#Check for entries relating to Douglas Adams in some way
+#'adams_items <- find_item("Douglas Adams")
+#'
+#'#Check for properties involving the peerage
+#'peerage_props <- find_property("peerage")
+#'
+#'@aliases find_item find_property
+#'@rdname find_item
+#'@export
+find_item <- function(search_term, language = "en", limit = 10, ...){
+ res <- searcher(search_term, language, limit, "item")
+ class(res) <- "find_item"
+ return(res)
+}
+
+#'@rdname find_item
+#'@export
+find_property <- function(search_term, language = "en", limit = 10){
+ res <- searcher(search_term, language, limit, "property")
+ class(res) <- "find_property"
+ return(res)
+}
diff --git a/R/prints.R b/R/prints.R
new file mode 100644
index 0000000..261287d
--- /dev/null
+++ b/R/prints.R
@@ -0,0 +1,125 @@
+#'@title Print method for find_item
+#'
+#'@description print found items.
+#'
+#'@param x find_item object with search results
+#'@param \dots Arguments to be passed to methods
+#'
+#'@method print find_item
+#'@export
+print.find_item <- function(x, ...) {
+ cat("\n\tWikidata item search\n\n")
+
+ # number of results
+ num_results <- length(x)
+ cat("Number of results:\t", num_results, "\n\n")
+
+ # results
+ if(num_results > 0) {
+ cat("Results:\n")
+ for(i in 1:num_results) {
+ if(is.null(x[[i]]$description)){
+ desc <- "\n"
+ }
+ else {
+ desc <- paste("-", x[[i]]$description, "\n")
+ }
+ cat(i, "\t", x[[i]]$label, paste0("(", x[[i]]$id, ")"), desc)
+ }
+ }
+}
+
+#'@title Print method for find_property
+#'
+#'@description print found properties.
+#'
+#'@param x find_property object with search results
+#'@param \dots Arguments to be passed to methods
+#'
+#'@method print find_property
+#'@export
+print.find_property <- function(x, ...) {
+ cat("\n\tWikidata property search\n\n")
+
+ # number of results
+ num_results <- length(x)
+ cat("Number of results:\t", num_results, "\n\n")
+
+ # results
+ if(num_results > 0) {
+ cat("Results:\n")
+ for(i in seq_len(num_results)) {
+ if(is.null(x[[i]]$description)){
+ desc <- "\n"
+ }
+ else {
+ desc <- paste("-", x[[i]]$description, "\n")
+ }
+ cat(i, "\t", x[[i]]$label, paste0("(", x[[i]]$id, ")"), desc)
+ }
+ }
+}
+
+wd_print_base <- function(x, ...){
+
+ cat("\n\tWikidata", x$type, x$id, "\n\n")
+
+ # labels
+ num.labels <- length(x$labels)
+ if(num.labels>0) {
+ lbl <- x$labels[[1]]$value
+ if(num.labels==1) cat("Label:\t\t", lbl, "\n")
+ else {
+ if(!is.null(x$labels$en)) lbl <- x$labels$en$value
+ cat("Label:\t\t", lbl, paste0("\t[", num.labels-1, " other languages available]\n"))
+ }
+ }
+
+ # aliases
+ num_aliases <- length(x$aliases)
+ if(num_aliases > 0) {
+ al <- unique(unlist(lapply(x$aliases, function(xl){return(xl$value)})))
+ cat("Aliases:\t", paste(al, collapse = ", "), "\n")
+ }
+
+ # descriptions
+ num_desc <- length(x$descriptions)
+ if(num_desc > 0) {
+ desc <- x$descriptions[[1]]$value
+ if(num_desc == 1){
+ cat("Description:", desc, "\n")
+ }
+ else {
+ if(!is.null(x$descriptions$en)){
+ desc <- x$descriptions$en$value
+ }
+ cat("Description:", desc, paste0("\t[", (num_desc - 1), " other languages available]\n"))
+ }
+ }
+
+ # num claims
+ num_claims <- length(x$claims)
+ if(num_claims > 0){
+ cat("Claims:\t\t", num_claims, "\n")
+ }
+
+ # num sitelinks
+ num_links <- length(x$sitelinks)
+ if(num_links > 0){
+ cat("Sitelinks:\t", num_links, "\n")
+ }
+}
+
+#'@title Print method for Wikidata objects
+#'
+#'@description print found objects generally.
+#'
+#'@param x wikidata object from get_item, get_random_item, get_property or get_random_property
+#'@param \dots Arguments to be passed to methods
+#'@seealso get_item, get_random_item, get_property or get_random_property
+#'@method print wikidata
+#'@export
+print.wikidata <- function(x, ...){
+ lapply(x, wd_print_base, ...)
+ return(invisible())
+}
\ No newline at end of file
diff --git a/R/utils.R b/R/utils.R
new file mode 100644
index 0000000..ffde3cc
--- /dev/null
+++ b/R/utils.R
@@ -0,0 +1,90 @@
+#Generic queryin' function for direct Wikidata calls. Wraps around WikipediR::page_content.
+wd_query <- function(title, ...){
+ result <- WikipediR::page_content(domain = "wikidata.org", page_name = title, as_wikitext = TRUE,
+ httr::user_agent("WikidataR - https://github.com/Ironholds/WikidataR"),
+ ...)
+ output <- jsonlite::fromJSON(result$parse$wikitext[[1]])
+ return(output)
+}
+
+#Query for a random item in "namespace" (ns). Essentially a wrapper around WikipediR::random_page.
+wd_rand_query <- function(ns, limit, ...){
+ result <- WikipediR::random_page(domain = "wikidata.org", as_wikitext = TRUE, namespaces = ns,
+ httr::user_agent("WikidataR - https://github.com/Ironholds/WikidataR"),
+ limit = limit, ...)
+ output <- lapply(result, function(x){jsonlite::fromJSON(x$wikitext[[1]])})
+ class(output) <- "wikidata"
+ return(output)
+
+}
+
+#Generic input checker. Needs additional stuff for property-based querying
+#because namespaces are weird, yo.
+check_input <- function(input, substitution){
+ in_fit <- grepl("^\\d+$",input)
+ if(any(in_fit)){
+ input[in_fit] <- paste0(substitution, input[in_fit])
+ }
+ return(input)
+}
+
+#Generic, direct access to Wikidata's search functionality.
+searcher <- function(search_term, language, limit, type, ...){
+ result <- WikipediR::query(url = "https://www.wikidata.org/w/api.php", out_class = "list", clean_response = FALSE,
+ query_param = list(
+ action = "wbsearchentities",
+ type = type,
+ language = language,
+ limit = limit,
+ search = search_term
+ ),
+ ...)
+ result <- result$search
+ return(result)
+}
+
+sparql_query <- function(params, ...){
+ result <- httr::GET("https://query.wikidata.org/bigdata/namespace/wdq/sparql",
+ query = list(query = params),
+ httr::user_agent("WikidataR - https://github.com/Ironholds/WikidataR"),
+ ...)
+ httr::stop_for_status(result)
+ return(httr::content(result, as = "parsed", type = "application/json"))
+}
+
+#'@title Extract Claims from Returned Item Data
+#'@description extract claim information from data returned using
+#'\code{\link{get_item}}.
+#'
+#'@param items a list of one or more Wikidata items returned with
+#'\code{\link{get_item}}.
+#'
+#'@param claims a vector of claims (in the form "P321", "P12") to look for
+#'and extract.
+#'
+#'@return a list containing one sub-list for each entry in \code{items},
+#'and (below that) the found data for each claim. In the event a claim
+#'cannot be found for an item, an \code{NA} will be returned
+#'instead.
+#'
+#'@examples
+#'# Get item data
+#'adams_data <- get_item("42")
+#'
+#'# Get claim data
+#'claims <- extract_claims(adams_data, "P31")
+#'
+#'@export
+extract_claims <- function(items, claims){
+ output <- lapply(items, function(x, claims){
+ return(lapply(claims, function(claim, obj){
+ which_match <- which(names(obj$claims) == claim)
+ if(!length(which_match)){
+ return(NA)
+ }
+ return(obj$claims[[which_match[1]]])
+ }, obj = x))
+ }, claims = claims)
+
+ return(output)
+}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e38a002
--- /dev/null
+++ b/README.md
@@ -0,0 +1,38 @@
+WikidataR
+=========
+
+An R API wrapper for the Wikidata store of semantic data.
+
+__Author:__ Oliver Keyes, Serena Signorelli & Christian Graul<br/>
+__License:__ [MIT](http://opensource.org/licenses/MIT)<br/>
+__Status:__ Stable
+
+[](https://travis-ci.org/Ironholds/WikidataR)
+
+Description
+======
+WikidataR is a wrapper around the Wikidata API. It is written in and for R, and was inspired by Christian Graul's
+[rwikidata](https://github.com/chgrl/rwikidata) project. For details on how to best use it, see the [explanatory
+vignette](https://CRAN.R-project.org/package=WikidataR/vignettes/Introduction.html).
+
+Please note that this project is released with a
+[Contributor Code of Conduct](https://github.com/Ironholds/WikidataR/blob/master/CONDUCT.md).
+By participating in this project you agree to abide by its terms.
+
+Installation
+======
+
+For the most recent CRAN version:
+
+ install.packages("WikidataR")
+
+For the development version:
+
+ library(devtools)
+ devtools::install_github("ironholds/WikidataR")
+
+Dependencies
+======
+* R. Doy.
+* [httr](https://cran.r-project.org/package=httr) and its dependencies.
+* [WikipediR](https://cran.r-project.org/package=WikipediR)
diff --git a/build/vignette.rds b/build/vignette.rds
new file mode 100644
index 0000000..ca9dd2f
Binary files /dev/null and b/build/vignette.rds differ
diff --git a/inst/doc/Introduction.R b/inst/doc/Introduction.R
new file mode 100644
index 0000000..652eec9
--- /dev/null
+++ b/inst/doc/Introduction.R
@@ -0,0 +1,36 @@
+## ---- eval=FALSE---------------------------------------------------------
+# #Retrieve an item
+# item <- get_item(id = 1)
+#
+# #Get information about the property of the first claim it has.
+# first_claim <- get_property(id = names(item$claims)[1])
+# #Do we succeed? Dewey!
+
+## ---- eval=FALSE---------------------------------------------------------
+# #Retrieve a random item
+# rand_item <- get_random_item()
+#
+# #Retrieve a random property
+# rand_prop <- get_random_property()
+
+## ---- eval=FALSE---------------------------------------------------------
+# #Retrieve 42 random items
+# rand_item <- get_random_item(limit = 42)
+#
+# #Retrieve 42 random properties
+# rand_prop <- get_random_property(limit = 42)
+
+## ---- eval=FALSE---------------------------------------------------------
+# #Find item - find defaults to "en" as a language.
+# aarons <- find_item("Aaron Halfaker")
+#
+# #Find a property - also defaults to "en"
+# first_names <- find_property("first name")
+
+## ---- eval=FALSE---------------------------------------------------------
+# #Find item.
+# all_aarons <- find_item("Aaron Halfaker")
+#
+# #Grab the ID code for the first entry and retrieve the associated item data.
+# first_aaron <- get_item(all_aarons[[1]]$id)
+
diff --git a/inst/doc/Introduction.Rmd b/inst/doc/Introduction.Rmd
new file mode 100644
index 0000000..e22aae2
--- /dev/null
+++ b/inst/doc/Introduction.Rmd
@@ -0,0 +1,82 @@
+<!--
+%\VignetteEngine{knitr::knitr}
+%\VignetteIndexEntry{Introduction to WikidataR}
+-->
+
+# WikidataR: the API client library for Wikidata
+Wikidata is a wonderful and irreplaceable resource for linked data, containing information on pretty much any subject. If there's a Wikipedia article on it, there's almost certainly a Wikidata item for it.
+
+<code>WikidataR</code> - following the naming scheme of [WikipediR](https://github.com/Ironholds/WikipediR#thanks-and-misc) - is an API client library for Wikidata, written in and accessible from R.
+
+## Items and properties
+The two basic component pieces of Wikidata are "items" and "properties". An "item" is a thing - a concept, object or
+topic that exists in the real world, such as "Rush". These items each have statements associated with them - for
+example, "Rush is an instance of: Rock Band". In that statement, "Rock Band" is a property: a class or trait
+that items can hold. Wikidata items are organised as descriptors of the item, in various languages, and references to the properties that that item holds.
+
+## Retrieving specific items or properties
+Items and properties are both identified by numeric IDs, prefaced with "Q" in the case of items,
+and "P" in the case of properties. WikipediR can be used to retrieve items or properties with specific
+ID numbers, using the <code>get\_item</code> and <code>get\_property</code> functions:
+
+```{r, eval=FALSE}
+#Retrieve an item
+item <- get_item(id = 1)
+
+#Get information about the property of the first claim it has.
+first_claim <- get_property(id = names(item$claims)[1])
+#Do we succeed? Dewey!
+```
+
+These functions are capable of accepting various forms for the ID, including (as examples), "Q100" or "100"
+for items, and "Property:P100", "P100" or "100" for properties. They're also vectorised - pass them as many IDs as you want!
+
+## Retrieving randomly-selected items or properties
+As well as retrieving specific items or properties, Wikidata's API also allows for the retrieval of *random*
+elements. With WikidataR, this can be achieved through:
+
+```{r, eval=FALSE}
+#Retrieve a random item
+rand_item <- get_random_item()
+
+#Retrieve a random property
+rand_prop <- get_random_property()
+```
+
+These also allow you to retrieve *sets* of random elements - not just one at a time, but say, 50 at a time - by including the "limit" argument:
+
+```{r, eval=FALSE}
+#Retrieve 42 random items
+rand_item <- get_random_item(limit = 42)
+
+#Retrieve 42 random properties
+rand_prop <- get_random_property(limit = 42)
+```
+
+## Search
+Wikidata's search functionality can also be used, either to find items or to find properties. All you need is
+a search string (which is run over the names and descriptions of items or properties) and a language code
+(since Wikidata's descriptions can be in many languages):
+
+```{r, eval=FALSE}
+#Find item - find defaults to "en" as a language.
+aarons <- find_item("Aaron Halfaker")
+
+#Find a property - also defaults to "en"
+first_names <- find_property("first name")
+```
+
+The resulting search entries have the ID as a key, making it trivial to then retrieve the full corresponding
+items or properties:
+
+```{r, eval=FALSE}
+#Find item.
+all_aarons <- find_item("Aaron Halfaker")
+
+#Grab the ID code for the first entry and retrieve the associated item data.
+first_aaron <- get_item(all_aarons[[1]]$id)
+```
+
+## Other and future functionality
+If you have ideas for other types of useful Wikidata access, the best approach
+is to either [request it](https://github.com/Ironholds/WikidataR/issues) or [add it](https://github.com/Ironholds/WikidataR/pulls)!
diff --git a/inst/doc/Introduction.html b/inst/doc/Introduction.html
new file mode 100644
index 0000000..9bdad3a
--- /dev/null
+++ b/inst/doc/Introduction.html
@@ -0,0 +1,290 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+
+<title>WikidataR: the API client library for Wikidata</title>
+
+<script type="text/javascript">
+window.onload = function() {
+ var imgs = document.getElementsByTagName('img'), i, img;
+ for (i = 0; i < imgs.length; i++) {
+ img = imgs[i];
+ // center an image if it is the only element of its parent
+ if (img.parentElement.childElementCount === 1)
+ img.parentElement.style.textAlign = 'center';
+ }
+};
+</script>
+
+<!-- Styles for R syntax highlighter -->
+<style type="text/css">
+ pre .operator,
+ pre .paren {
+ color: rgb(104, 118, 135)
+ }
+
+ pre .literal {
+ color: #990073
+ }
+
+ pre .number {
+ color: #099;
+ }
+
+ pre .comment {
+ color: #998;
+ font-style: italic
+ }
+
+ pre .keyword {
+ color: #900;
+ font-weight: bold
+ }
+
+ pre .identifier {
+ color: rgb(0, 0, 0);
+ }
+
+ pre .string {
+ color: #d14;
+ }
+</style>
+
+<!-- R syntax highlighter -->
+<script type="text/javascript">
+var hljs=new function(){function m(p){return p.replace(/&/gm,"&").replace(/</gm,"<")}function f(r,q,p){return RegExp(q,"m"+(r.cI?"i":"")+(p?"g":""))}function b(r){for(var p=0;p<r.childNodes.length;p++){var q=r.childNodes[p];if(q.nodeName=="CODE"){return q}if(!(q.nodeType==3&&q.nodeValue.match(/\s+/))){break}}}function h(t,s){var p="";for(var r=0;r<t.childNodes.length;r++){if(t.childNodes[r].nodeType==3){var q=t.childNodes[r].nodeValue;if(s){q=q.replace(/\n/g,"")}p+=q}else{if(t.chi [...]
+hljs.initHighlightingOnLoad();
+</script>
+
+
+
+<style type="text/css">
+body, td {
+ font-family: sans-serif;
+ background-color: white;
+ font-size: 13px;
+}
+
+body {
+ max-width: 800px;
+ margin: auto;
+ padding: 1em;
+ line-height: 20px;
+}
+
+tt, code, pre {
+ font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', 'Lucida Console', Consolas, Monaco, monospace;
+}
+
+h1 {
+ font-size:2.2em;
+}
+
+h2 {
+ font-size:1.8em;
+}
+
+h3 {
+ font-size:1.4em;
+}
+
+h4 {
+ font-size:1.0em;
+}
+
+h5 {
+ font-size:0.9em;
+}
+
+h6 {
+ font-size:0.8em;
+}
+
+a:visited {
+ color: rgb(50%, 0%, 50%);
+}
+
+pre, img {
+ max-width: 100%;
+}
+pre {
+ overflow-x: auto;
+}
+pre code {
+ display: block; padding: 0.5em;
+}
+
+code {
+ font-size: 92%;
+ border: 1px solid #ccc;
+}
+
+code[class] {
+ background-color: #F8F8F8;
+}
+
+table, td, th {
+ border: none;
+}
+
+blockquote {
+ color:#666666;
+ margin:0;
+ padding-left: 1em;
+ border-left: 0.5em #EEE solid;
+}
+
+hr {
+ height: 0px;
+ border-bottom: none;
+ border-top-width: thin;
+ border-top-style: dotted;
+ border-top-color: #999999;
+}
+
+ at media print {
+ * {
+ background: transparent !important;
+ color: black !important;
+ filter:none !important;
+ -ms-filter: none !important;
+ }
+
+ body {
+ font-size:12pt;
+ max-width:100%;
+ }
+
+ a, a:visited {
+ text-decoration: underline;
+ }
+
+ hr {
+ visibility: hidden;
+ page-break-before: always;
+ }
+
+ pre, blockquote {
+ padding-right: 1em;
+ page-break-inside: avoid;
+ }
+
+ tr, img {
+ page-break-inside: avoid;
+ }
+
+ img {
+ max-width: 100% !important;
+ }
+
+ @page :left {
+ margin: 15mm 20mm 15mm 10mm;
+ }
+
+ @page :right {
+ margin: 15mm 10mm 15mm 20mm;
+ }
+
+ p, h2, h3 {
+ orphans: 3; widows: 3;
+ }
+
+ h2, h3 {
+ page-break-after: avoid;
+ }
+}
+</style>
+
+
+
+</head>
+
+<body>
+<!--
+%\VignetteEngine{knitr::knitr}
+%\VignetteIndexEntry{Introduction to WikidataR}
+-->
+
+<h1>WikidataR: the API client library for Wikidata</h1>
+
+<p>Wikidata is a wonderful and irreplaceable resource for linked data, containing information on pretty much any subject. If there's a Wikipedia article on it, there's almost certainly a Wikidata item for it.</p>
+
+<p><code>WikidataR</code> - following the naming scheme of <a href="https://github.com/Ironholds/WikipediR#thanks-and-misc">WikipediR</a> - is an API client library for Wikidata, written in and accessible from R.</p>
+
+<h2>Items and properties</h2>
+
+<p>The two basic component pieces of Wikidata are “items” and “properties”. An “item” is a thing - a concept, object or
+topic that exists in the real world, such as “Rush”. These items each have statements associated with them - for
+example, “Rush is an instance of: Rock Band”. In that statement, “Rock Band” is a property: a class or trait
+that items can hold. Wikidata items are organised as descriptors of the item, in various languages, and references to the properties that that item holds.</p>
+
+<h2>Retrieving specific items or properties</h2>
+
+<p>Items and properties are both identified by numeric IDs, prefaced with “Q” in the case of items,
+and “P” in the case of properties. WikipediR can be used to retrieve items or properties with specific
+ID numbers, using the <code>get_item</code> and <code>get_property</code> functions:</p>
+
+<pre><code class="r">#Retrieve an item
+item <- get_item(id = 1)
+
+#Get information about the property of the first claim it has.
+first_claim <- get_property(id = names(item$claims)[1])
+#Do we succeed? Dewey!
+</code></pre>
+
+<p>These functions are capable of accepting various forms for the ID, including (as examples), “Q100” or “100”
+for items, and “Property:P100”, “P100” or “100” for properties. They're also vectorised - pass them as many IDs as you want!</p>
+
+<h2>Retrieving randomly-selected items or properties</h2>
+
+<p>As well as retrieving specific items or properties, Wikidata's API also allows for the retrieval of <em>random</em>
+elements. With WikidataR, this can be achieved through:</p>
+
+<pre><code class="r">#Retrieve a random item
+rand_item <- get_random_item()
+
+#Retrieve a random property
+rand_prop <- get_random_property()
+</code></pre>
+
+<p>These also allow you to retrieve <em>sets</em> of random elements - not just one at a time, but say, 50 at a time - by including the “limit” argument:</p>
+
+<pre><code class="r">#Retrieve 42 random items
+rand_item <- get_random_item(limit = 42)
+
+#Retrieve 42 random properties
+rand_prop <- get_random_property(limit = 42)
+</code></pre>
+
+<h2>Search</h2>
+
+<p>Wikidata's search functionality can also be used, either to find items or to find properties. All you need is
+a search string (which is run over the names and descriptions of items or properties) and a language code
+(since Wikidata's descriptions can be in many languages):</p>
+
+<pre><code class="r">#Find item - find defaults to "en" as a language.
+aarons <- find_item("Aaron Halfaker")
+
+#Find a property - also defaults to "en"
+first_names <- find_property("first name")
+</code></pre>
+
+<p>The resulting search entries have the ID as a key, making it trivial to then retrieve the full corresponding
+items or properties:</p>
+
+<pre><code class="r">#Find item.
+all_aarons <- find_item("Aaron Halfaker")
+
+#Grab the ID code for the first entry and retrieve the associated item data.
+first_aaron <- get_item(all_aarons[[1]]$id)
+</code></pre>
+
+<h2>Other and future functionality</h2>
+
+<p>If you have ideas for other types of useful Wikidata access, the best approach
+is to either <a href="https://github.com/Ironholds/WikidataR/issues">request it</a> or <a href="https://github.com/Ironholds/WikidataR/pulls">add it</a>!</p>
+
+</body>
+
+</html>
diff --git a/man/WikidataR.Rd b/man/WikidataR.Rd
new file mode 100644
index 0000000..2ea9768
--- /dev/null
+++ b/man/WikidataR.Rd
@@ -0,0 +1,18 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/WikidataR.R
+\docType{package}
+\name{WikidataR}
+\alias{WikidataR}
+\alias{WikidataR-package}
+\alias{WikidataR-package}
+\title{API client library for Wikidata}
+\description{
+This package serves as an API client for \href{Wikidata}{https://www.wikidata.org}.
+See the accompanying vignette for more details.
+}
+\seealso{
+\code{\link{get_random}} for selecting a random item or property,
+\code{\link{get_item}} for a /specific/ item or property, or \code{\link{find_item}}
+for using search functionality to pull out item or property IDs where the descriptions
+or aliases match a particular search term.
+}
diff --git a/man/extract_claims.Rd b/man/extract_claims.Rd
new file mode 100644
index 0000000..7f32f98
--- /dev/null
+++ b/man/extract_claims.Rd
@@ -0,0 +1,33 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utils.R
+\name{extract_claims}
+\alias{extract_claims}
+\title{Extract Claims from Returned Item Data}
+\usage{
+extract_claims(items, claims)
+}
+\arguments{
+\item{items}{a list of one or more Wikidata items returned with
+\code{\link{get_item}}.}
+
+\item{claims}{a vector of claims (in the form "P321", "P12") to look for
+and extract.}
+}
+\value{
+a list containing one sub-list for each entry in \code{items},
+and (below that) the found data for each claim. In the event a claim
+cannot be found for an item, an \code{NA} will be returned
+instead.
+}
+\description{
+extract claim information from data returned using
+\code{\link{get_item}}.
+}
+\examples{
+# Get item data
+adams_data <- get_item("42")
+
+# Get claim data
+claims <- extract_claims(adams_data, "P31")
+
+}
diff --git a/man/find_item.Rd b/man/find_item.Rd
new file mode 100644
index 0000000..d2af2bd
--- /dev/null
+++ b/man/find_item.Rd
@@ -0,0 +1,41 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/gets.R
+\name{find_item}
+\alias{find_item}
+\alias{find_property}
+\alias{find_property}
+\title{Search for Wikidata items or properties that match a search term}
+\usage{
+find_item(search_term, language = "en", limit = 10, ...)
+
+find_property(search_term, language = "en", limit = 10)
+}
+\arguments{
+\item{search_term}{a term to search for.}
+
+\item{language}{the language to return the labels and descriptions in; this should
+consist of an ISO language code. Set to "en" by default.}
+
+\item{limit}{the number of results to return; set to 10 by default.}
+
+\item{...}{further arguments to pass to httr's GET.}
+}
+\description{
+\code{find_item} and \code{find_property} allow you to retrieve a set
+of Wikidata items or properties where the aliase or descriptions match a particular
+search term. As with other \code{WikidataR} code, custom print methods are available;
+use \code{\link{str}} to manipulate and see the underlying structure of the data.
+}
+\examples{
+
+#Check for entries relating to Douglas Adams in some way
+adams_items <- find_item("Douglas Adams")
+
+#Check for properties involving the peerage
+peerage_props <- find_property("peerage")
+
+}
+\seealso{
+\code{\link{get_random}} for selecting a random item or property,
+or \code{\link{get_item}} for selecting a specific item or property.
+}
diff --git a/man/get_geo_box.Rd b/man/get_geo_box.Rd
new file mode 100644
index 0000000..899c005
--- /dev/null
+++ b/man/get_geo_box.Rd
@@ -0,0 +1,58 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/geo.R
+\name{get_geo_box}
+\alias{get_geo_box}
+\title{Get geographic entities based on a bounding box}
+\usage{
+get_geo_box(first_city_code, first_corner, second_city_code, second_corner,
+ language = "en", ...)
+}
+\arguments{
+\item{first_city_code}{a Wikidata item, or series of items, to use for
+one corner of the bounding box.}
+
+\item{first_corner}{the direction of \code{first_city_code} relative
+to \code{city} (eg "NorthWest", "SouthEast").}
+
+\item{second_city_code}{a Wikidata item, or series of items, to use for
+one corner of the bounding box.}
+
+\item{second_corner}{the direction of \code{second_city_code} relative
+to \code{city} (eg "NorthWest", "SouthEast").}
+
+\item{language}{the two-letter language code to use for the name
+of the item. "en" by default.}
+
+\item{...}{further arguments to pass to httr's GET.}
+}
+\value{
+a data.frame of 5 columns:
+\itemize{
+ \item{item}{ the Wikidata identifier of each object associated with
+ \code{entity}.}
+ \item{name}{ the name of the item, if available, in the requested language. If it
+ is not available, \code{NA} will be returned instead.}
+ \item{latitude}{ the latitude of \code{item}}
+ \item{longitude}{ the longitude of \code{item}}
+ \item{entity}{ the entity the item is associated with (necessary for multi-entity
+ queries).}
+}
+}
+\description{
+\code{get_geo_box} retrieves all geographic entities in
+Wikidata that fall between a bounding box between two existing items
+with geographic attributes (usually cities).
+}
+\examples{
+# Simple bounding box
+bruges_box <- WikidataR:::get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")
+
+# Custom language
+bruges_box_fr <- WikidataR:::get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
+ language = "fr")
+
+}
+\seealso{
+\code{\link{get_geo_entity}} for using an unrestricted search or simple radius,
+rather than a bounding box.
+}
diff --git a/man/get_geo_entity.Rd b/man/get_geo_entity.Rd
new file mode 100644
index 0000000..ccec09e
--- /dev/null
+++ b/man/get_geo_entity.Rd
@@ -0,0 +1,58 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/geo.R
+\name{get_geo_entity}
+\alias{get_geo_entity}
+\title{Retrieve geographic information from Wikidata}
+\usage{
+get_geo_entity(entity, language = "en", radius = NULL, ...)
+}
+\arguments{
+\item{entity}{a Wikidata item (\code{Q...}) or series of items, to check
+for associated geo-tagged items.}
+
+\item{language}{the two-letter language code to use for the name
+of the item. "en" by default, because we're imperialist
+anglocentric westerners.}
+
+\item{radius}{optionally, a radius (in kilometers) around \code{entity}
+to restrict the search to.}
+
+\item{...}{further arguments to pass to httr's GET.}
+}
+\value{
+a data.frame of 5 columns:
+\itemize{
+ \item{item}{ the Wikidata identifier of each object associated with
+ \code{entity}.}
+ \item{name}{ the name of the item, if available, in the requested language. If it
+ is not available, \code{NA} will be returned instead.}
+ \item{latitude}{ the latitude of \code{item}}
+ \item{longitude}{ the longitude of \code{item}}
+ \item{entity}{ the entity the item is associated with (necessary for multi-entity
+ queries).}
+}
+}
+\description{
+\code{get_geo_entity} retrieves the item ID, latitude
+and longitude of any object with geographic data associated with \emph{another}
+object with geographic data (example: all the locations around/near/associated with
+a city).
+}
+\examples{
+# All entities
+sf_locations <- get_geo_entity("Q62")
+
+# Entities with French, rather than English, names
+sf_locations <- get_geo_entity("Q62", language = "fr")
+
+# Entities within 1km
+sf_close_locations <- get_geo_entity("Q62", radius = 1)
+
+# Multiple entities
+multi_entity <- get_geo_entity(entity = c("Q62", "Q64"))
+
+}
+\seealso{
+\code{\link{get_geo_box}} for using a bounding box
+rather than an unrestricted search or simple radius.
+}
diff --git a/man/get_item.Rd b/man/get_item.Rd
new file mode 100644
index 0000000..830d4f5
--- /dev/null
+++ b/man/get_item.Rd
@@ -0,0 +1,42 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/gets.R
+\name{get_item}
+\alias{get_item}
+\alias{get_property}
+\alias{get_property}
+\title{Retrieve specific Wikidata items or properties}
+\usage{
+get_item(id, ...)
+
+get_property(id, ...)
+}
+\arguments{
+\item{id}{the ID number(s) of the item or property you're looking for. This can be in
+various formats; either a numeric value ("200"), the full name ("Q200") or
+even with an included namespace ("Property:P10") - the function will format
+it appropriately. This function is vectorised and will happily accept
+multiple IDs.}
+
+\item{...}{further arguments to pass to httr's GET.}
+}
+\description{
+\code{get_item} and \code{get_property} allow you to retrieve the data associated
+with individual Wikidata items and properties, respectively. As with
+other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
+to manipulate and see the underlying structure of the data.
+}
+\examples{
+
+#Retrieve a specific item
+adams_metadata <- get_item("42")
+
+#Retrieve a specific property
+object_is_child <- get_property("P40")
+
+}
+\seealso{
+\code{\link{get_random}} for selecting a random item or property,
+or \code{\link{find_item}} for using search functionality to pull out
+item or property IDs where the descriptions or aliases match a particular
+search term.
+}
diff --git a/man/get_random.Rd b/man/get_random.Rd
new file mode 100644
index 0000000..7edfaf1
--- /dev/null
+++ b/man/get_random.Rd
@@ -0,0 +1,39 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/gets.R
+\name{get_random_item}
+\alias{get_random_item}
+\alias{get_random}
+\alias{get_random_property}
+\alias{get_random_property}
+\title{Retrieve randomly-selected Wikidata items or properties}
+\usage{
+get_random_item(limit = 1, ...)
+
+get_random_property(limit = 1, ...)
+}
+\arguments{
+\item{limit}{how many random items to return. 1 by default, but can be higher.}
+
+\item{...}{arguments to pass to httr's GET.}
+}
+\description{
+\code{get_random_item} and \code{get_random_property} allow you to retrieve the data
+associated with randomly-selected Wikidata items and properties, respectively. As with
+other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
+to manipulate and see the underlying structure of the data.
+}
+\examples{
+
+#Random item
+random_item <- get_random_item()
+
+#Random property
+random_property <- get_random_property()
+
+}
+\seealso{
+\code{\link{get_item}} for selecting a specific item or property,
+or \code{\link{find_item}} for using search functionality to pull out
+item or property IDs where the descriptions or aliases match a particular
+search term.
+}
diff --git a/man/print.find_item.Rd b/man/print.find_item.Rd
new file mode 100644
index 0000000..0bfbccc
--- /dev/null
+++ b/man/print.find_item.Rd
@@ -0,0 +1,16 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/prints.R
+\name{print.find_item}
+\alias{print.find_item}
+\title{Print method for find_item}
+\usage{
+\method{print}{find_item}(x, ...)
+}
+\arguments{
+\item{x}{find_item object with search results}
+
+\item{\dots}{Arguments to be passed to methods}
+}
+\description{
+print found items.
+}
diff --git a/man/print.find_property.Rd b/man/print.find_property.Rd
new file mode 100644
index 0000000..a7f4e4f
--- /dev/null
+++ b/man/print.find_property.Rd
@@ -0,0 +1,16 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/prints.R
+\name{print.find_property}
+\alias{print.find_property}
+\title{Print method for find_property}
+\usage{
+\method{print}{find_property}(x, ...)
+}
+\arguments{
+\item{x}{find_property object with search results}
+
+\item{\dots}{Arguments to be passed to methods}
+}
+\description{
+print found properties.
+}
diff --git a/man/print.wikidata.Rd b/man/print.wikidata.Rd
new file mode 100644
index 0000000..8e3b076
--- /dev/null
+++ b/man/print.wikidata.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/prints.R
+\name{print.wikidata}
+\alias{print.wikidata}
+\title{Print method for Wikidata objects}
+\usage{
+\method{print}{wikidata}(x, ...)
+}
+\arguments{
+\item{x}{wikidata object from get_item, get_random_item, get_property or get_random_property}
+
+\item{\dots}{Arguments to be passed to methods}
+}
+\description{
+print found objects generally.
+}
+\seealso{
+get_item, get_random_item, get_property or get_random_property
+}
diff --git a/tests/testthat.R b/tests/testthat.R
new file mode 100644
index 0000000..34fbd73
--- /dev/null
+++ b/tests/testthat.R
@@ -0,0 +1,4 @@
+library(testthat)
+library(WikidataR)
+
+test_check("WikidataR")
diff --git a/tests/testthat/test_geo.R b/tests/testthat/test_geo.R
new file mode 100644
index 0000000..ac7e88b
--- /dev/null
+++ b/tests/testthat/test_geo.R
@@ -0,0 +1,48 @@
+testthat::context("Geographic queries")
+
+testthat::test_that("Simple entity-based geo lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude", "entity")
+ sf_locations <- get_geo_entity("Q62")
+ testthat::expect_true(is.data.frame(sf_locations))
+ testthat::expect_true(all(field_names == names(sf_locations)))
+ testthat::expect_true(unique(sf_locations$entity) == "Q62")
+})
+
+testthat::test_that("Language-variant entity-based geo lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude", "entity")
+ sf_locations <- get_geo_entity("Q62", language = "fr")
+ testthat::expect_true(is.data.frame(sf_locations))
+ testthat::expect_true(all(field_names == names(sf_locations)))
+ testthat::expect_true(unique(sf_locations$entity) == "Q62")
+})
+
+testthat::test_that("Radius restricted entity-based geo lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude", "entity")
+ sf_locations <- get_geo_entity("Q62", radius = 1)
+ testthat::expect_true(is.data.frame(sf_locations))
+ testthat::expect_true(all(field_names == names(sf_locations)))
+ testthat::expect_true(unique(sf_locations$entity) == "Q62")
+})
+
+testthat::test_that("multi-entity geo lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude", "entity")
+ sf_locations <- get_geo_entity(c("Q62", "Q64"), radius = 1)
+ testthat::expect_true(is.data.frame(sf_locations))
+ testthat::expect_true(all(field_names == names(sf_locations)))
+ testthat::expect_equal(length(unique(sf_locations$entity)), 2)
+})
+
+testthat::test_that("Simple bounding lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude")
+ bruges_box <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")
+ testthat::expect_true(is.data.frame(bruges_box))
+ testthat::expect_true(all(field_names == names(bruges_box)))
+})
+
+testthat::test_that("Language-variant bounding lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude")
+ bruges_box <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
+ language = "fr")
+ testthat::expect_true(is.data.frame(bruges_box))
+ testthat::expect_true(all(field_names == names(bruges_box)))
+})
\ No newline at end of file
diff --git a/tests/testthat/test_gets.R b/tests/testthat/test_gets.R
new file mode 100644
index 0000000..2164d4b
--- /dev/null
+++ b/tests/testthat/test_gets.R
@@ -0,0 +1,30 @@
+context("Direct Wikidata get functions")
+
+test_that("A specific item can be retrieved with an entire item code", {
+ expect_true({get_item("Q100");TRUE})
+})
+
+test_that("A specific item can be retrieved with a partial entire item code", {
+ expect_true({get_item("100");TRUE})
+})
+
+test_that("A specific property can be retrieved with an entire prop code + namespace", {
+ expect_true({get_property("Property:P10");TRUE})
+})
+
+test_that("A specific property can be retrieved with an entire prop code + namespace", {
+ expect_true({get_property("P10");TRUE})
+})
+
+
+test_that("A specific property can be retrieved with a partial prop code", {
+ expect_true({get_property("10");TRUE})
+})
+
+test_that("A randomly-selected item can be retrieved",{
+ expect_true({get_random_item();TRUE})
+})
+
+test_that("A randomly-selected property can be retriveed",{
+ expect_true({get_random_property();TRUE})
+})
\ No newline at end of file
diff --git a/tests/testthat/test_search.R b/tests/testthat/test_search.R
new file mode 100644
index 0000000..3588f82
--- /dev/null
+++ b/tests/testthat/test_search.R
@@ -0,0 +1,17 @@
+context("Search functions")
+
+test_that("English-language search works",{
+ expect_true({find_item("Wonder Girls", "en");TRUE})
+})
+
+test_that("Non-English-language search works",{
+ expect_true({find_item("Wonder Girls", "es");TRUE})
+})
+
+test_that("Search with limit modding works",{
+ expect_that(length(find_item("Wonder Girls", "en", 3)), equals(3))
+})
+
+test_that("Property search works",{
+ expect_true({find_property("Music", "en");TRUE})
+})
\ No newline at end of file
diff --git a/vignettes/Introduction.Rmd b/vignettes/Introduction.Rmd
new file mode 100644
index 0000000..e22aae2
--- /dev/null
+++ b/vignettes/Introduction.Rmd
@@ -0,0 +1,82 @@
+<!--
+%\VignetteEngine{knitr::knitr}
+%\VignetteIndexEntry{Introduction to WikidataR}
+-->
+
+# WikidataR: the API client library for Wikidata
+Wikidata is a wonderful and irreplaceable resource for linked data, containing information on pretty much any subject. If there's a Wikipedia article on it, there's almost certainly a Wikidata item for it.
+
+<code>WikidataR</code> - following the naming scheme of [WikipediR](https://github.com/Ironholds/WikipediR#thanks-and-misc) - is an API client library for Wikidata, written in and accessible from R.
+
+## Items and properties
+The two basic component pieces of Wikidata are "items" and "properties". An "item" is a thing - a concept, object or
+topic that exists in the real world, such as "Rush". These items each have statements associated with them - for
+example, "Rush is an instance of: Rock Band". In that statement, "Rock Band" is a property: a class or trait
+that items can hold. Wikidata items are organised as descriptors of the item, in various languages, and references to the properties that that item holds.
+
+## Retrieving specific items or properties
+Items and properties are both identified by numeric IDs, prefaced with "Q" in the case of items,
+and "P" in the case of properties. WikipediR can be used to retrieve items or properties with specific
+ID numbers, using the <code>get\_item</code> and <code>get\_property</code> functions:
+
+```{r, eval=FALSE}
+#Retrieve an item
+item <- get_item(id = 1)
+
+#Get information about the property of the first claim it has.
+first_claim <- get_property(id = names(item$claims)[1])
+#Do we succeed? Dewey!
+```
+
+These functions are capable of accepting various forms for the ID, including (as examples), "Q100" or "100"
+for items, and "Property:P100", "P100" or "100" for properties. They're also vectorised - pass them as many IDs as you want!
+
+## Retrieving randomly-selected items or properties
+As well as retrieving specific items or properties, Wikidata's API also allows for the retrieval of *random*
+elements. With WikidataR, this can be achieved through:
+
+```{r, eval=FALSE}
+#Retrieve a random item
+rand_item <- get_random_item()
+
+#Retrieve a random property
+rand_prop <- get_random_property()
+```
+
+These also allow you to retrieve *sets* of random elements - not just one at a time, but say, 50 at a time - by including the "limit" argument:
+
+```{r, eval=FALSE}
+#Retrieve 42 random items
+rand_item <- get_random_item(limit = 42)
+
+#Retrieve 42 random properties
+rand_prop <- get_random_property(limit = 42)
+```
+
+## Search
+Wikidata's search functionality can also be used, either to find items or to find properties. All you need is
+a search string (which is run over the names and descriptions of items or properties) and a language code
+(since Wikidata's descriptions can be in many languages):
+
+```{r, eval=FALSE}
+#Find item - find defaults to "en" as a language.
+aarons <- find_item("Aaron Halfaker")
+
+#Find a property - also defaults to "en"
+first_names <- find_property("first name")
+```
+
+The resulting search entries have the ID as a key, making it trivial to then retrieve the full corresponding
+items or properties:
+
+```{r, eval=FALSE}
+#Find item.
+all_aarons <- find_item("Aaron Halfaker")
+
+#Grab the ID code for the first entry and retrieve the associated item data.
+first_aaron <- get_item(all_aarons[[1]]$id)
+```
+
+## Other and future functionality
+If you have ideas for other types of useful Wikidata access, the best approach
+is to either [request it](https://github.com/Ironholds/WikidataR/issues) or [add it](https://github.com/Ironholds/WikidataR/pulls)!
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/r-cran-wikidatar.git
More information about the debian-med-commit
mailing list