An example of how to write web queries to AntWeb

ant_web_example.R

# We'll use the httr library to make web calls
library(httr) 
library(rjson) # to parse the json
library(plyr) # to convert lists to data.frames
library(assertthat) # To make assertions for right inputs
# If you don't have these packages run:
# install.packages(c("httr", "plyr", "rjson", "assertthat"))


example_url <- "http://www.antweb.org/api/?genus=acanthognathus&species=brevicornis"
# Make a web call
call <- GET(example_url)
# Retrive the data as text since it's already in JSON
data <- fromJSON(content(call, "text"))
# Now coerce the list to a data.frame
data_df <- ldply(data, function(x){ 
	df <- data.frame(t(unlist(x)))
	# There is one field which is a big dump of field names. So I just remove it here
	df$other <- NULL
	df
})

data_df # This is the final outcome from the call that a  user can use downstream.

> data_df
           code                           taxon_name subgenus
1 casent0280684 myrmicinaeacanthognathus brevicornis         
2 casent0637708 myrmicinaeacanthognathus brevicornis         
       tribe speciesgroup  subfamily          genus
1   dacetini              myrmicinae acanthognathus
2 dacetonini              myrmicinae acanthognathus
      species type subspecies  country adm2          adm1
1 brevicornis                 Colombia                   
2 brevicornis                     Peru      Madre de Dios
                  localityname localitycode collectioncode
1 Las Naranjas near Josc Maria   Josc Maria      ANTC19540
2    Tambopata Research Center    JTL060117  TRC-S06-R1C04
  biogeographicregion       last_modified
1           Neotropic 2014-01-30 13:48:18
2           Neotropic 2014-01-22 09:42:56
                   habitat  method             ownedby
1                                  BMNH, London, U. K.
2 Mixed terra firme forest winkler                    
  collectedby  caste access_group locatedat determinedby
1  D. Jackson     1w            1      BMNH             
2   D. Feener worker            2      JTLC   J. Longino
     medium access_login latlonmaxerror          microhabitat
1       pin           23                                     
2 dry mount            2           100m ex sifted leaf litter
  elevationmaxerror localitynotes dnaextractionnotes
1                                                   
2                                                   
   specimennotes             created     family
1 BMNH(E)1017559 2014-01-30 13:48:18 formicidae
2                2014-01-22 09:42:56 formicidae
  collectionnotes datecollectedstart datecollectedstartstr
1                         1977-08-08            8 Aug 1977
2                         2001-11-01            1 Nov 2001
  datecollectedendstr datedeterminedstr kingdom_name
1                                           animalia
2                           12 Sep 2013     animalia
  phylum_name class_name  order_name image_count
1  arthropoda    insecta hymenoptera           5
2  arthropoda    insecta hymenoptera           0
  decimal_latitude decimal_longitude elevation datedetermined
1             <NA>              <NA>      <NA>           <NA>
2        -13.14142           -69.623       252     2013-09-12

# Writing this as a function. Here we input both the genus and species as arguments, make sure they are characters
# Then make a call, check that we got a valid response, and format the results back to a data.frame that R can understand.



aw_specimen <- function(genus = NULL, species = NULL) {

	# These assertions make sure we are not passing NULLs to either argument
	assert_that(is.character(genus))
	assert_that(is.character(species))
	base_url <- "http://www.antweb.org/api/"
	# Format the input arguments as a list
	args <- compact(as.list(c(genus = genus, species = species)))
	# Pass that to the API
	results <- GET(base_url, query = args)
	# This checks to make sure we didn't hit a 404 or other unwanted http response codes
	stop_for_status(results)
	# Now get the JSON data
	data <- fromJSON(content(results, "text"))
	# Format to a clean data.frame
	data_df <- ldply(data, function(x){ 
	df <- data.frame(t(unlist(x)))
	df$other <- NULL
	df
})
	data_df # Return that out of the functionu
}

data <- aw_specimen(genus = "acanthognathus", species = "brevicornis")

# We can similarly do this for other types of calls to AntWeb