The API search function

1. Requirements
2. Architecture Overview
3. Configuring gcloud
4. Getting started
   1. Grabbing the code
   2. Launching the development server

Introduction

The search function of the VertNet API provides a simple way to access VertNet data programmatically. With appropriate API requests, you can easily automate searching for and retrieving custom data sets from VertNet.

The base URL for API search requests is http://api.vertnet-portal.appspot.com/api/search?q=query_object, where query_object is a JSON object specifying the request parameters. Request objects can include the following properties:

• q: query string
  
• l: maximum number of records to return per query. Performance depends heavily on this value as described in Stucky 2013. Optimum and default value is 400. (OPTIONAL)
  
• c: search cursor for paging over multiple results (OPTIONAL)
  

Search requests to the API return a JSON response object that includes the following properties:

• recs: a list of records including Darwin Core fields, data set metadata fields, and VertNet-specific index fields
  
• cursor: cursor string to use if there are more records to page over
  
• api_version: the version of the API source code used in the request
  
• query_version: the version of the query source code (search.py) used in the request
  
• limit: the maximum number of records to return in a response
  
• request_date: the UTC datetime when the request was submitted
  
• request_origin: the latitude,longitude of the source of the request
  
• response_records: the total number of records in the current response
  
• matching_records: the total number of records that match the query
  

As a simple example, the following request searches for Noturus placidus (the threatened Neosho madtom catfish):

http://api.vertnet-portal.appspot.com/api/search?q={"q":"noturus placidus"}

This document discusses each possible property of the search request object ("q", "l", and "c") in detail, beginning with the query string.

Search query strings

The search query is specified as the value of the "q" property of the JSON API request object (e.g., "noturus placidus" in the example above). A search query is just a string that contains at most 2000 Unicode characters. Searches are case insensitive in terms of the content they match, but the boolean operators AND, OR, and NOT (discussed below) must be written in upper case and the term names must be in all lower case (e.g. "basisofrecord"). Looking for punctuated content is a little tricky. You have to enclose the exact string you are looking for in escaped quotes, for example, the following API search looks for any records that contain the exact string urn:occurrence:Arctos:CUMV:Amph:10008:2243441:

http://api.vertnet-portal.appspot.com/api/search?q={"q":"iptrecordid:\"urn:occurrence:Arctos:CUMV:Amph:10008:2243441\""}

Queries can be used for global full text search, field k