Neotoma Developer Center

Remote programmatic access to the Neotoma Database

User Tools

Site Tools


Using the API

This page provides tips for using the API and understanding its general structure and conventions.

API Versions

To accommodate future development, the Neotoma API is versioned. As noted below, every call to the API must include the version in the URL. API changes will not be frequent. When a new version is released, the previous version will be maintained until the next new version is made available.

Current API version: v1

Calling a Resource

All resources are called via HTTP GET requests in the following format:

api.neotomadb.org/v<APIVersion>/<webServiceName>/<resourceName>?<parameterName1>=<value>&<parameterName2>=<value>...

Alternatively, specifying a known record id in the URL, as indicated below, will return results for that resource.

api.neotomadb.org/v<APIVersion>/<webServiceName>/<resourceName>/<recordID>

Request Parameters

Resources support a variety of parameters that may be specified in the call to filter the results to a subset of resource records. Almost all parameters are optional. If no parameters are provided, all records for a resource are returned. When using parameters:

  • Specify parameters in the request query string (i.e. after the ?)
  • Set the value of a parameter name with =
  • Separate multiple parameter name-value pairs with &
  • Separate multiple parameter values with a comma
  • Do not quote parameter names or values
  • Spaces in values are allowed
  • Some parameters support wildcards (see below)

Substring Searches in Parameters

Spaces and the * wildcard are supported in search strings. Spaces are useful for separating whole words and word components. For example, taxa search results for “*pinus” include alpinus, carpinus, lupinus, etc. Searching instead for “* pinus” will narrow the results to just the word pinus. The following table illustrates several ways that the * wildcard can be used to more finely control how your search string is matched.

Desired ResultExample
contains sitename=*cotton*
begins with sitename=Cotton*
ends with sitename=*Lake
is exactly sitename=Cottonwood Lake

Response Formats

By default, responses are encoded in Javascript Object Notation (JSON). Specify the format parameter to change responses to “xml” or “pretty” JSON (i.e. human readable). For example, return the AgeTypes table as XML:

http://api.neotomadb.org/v1/dbtables/AgeTypes?format=xml

Response Structure

Server errors excluded (e.g. HTTP 404), all JSON-formatted responses are structured as a single JSON object with two name:value pairs. The first pair handles request status and the second handles either data, or a status message. The name of the first pair is always “success;” it returns 1 if true, and 0 if false (error). If a request is successful, the second pair name is “data” and its value is an array of data objects. Otherwise, if a request fails, the second pair name is “message” and its value is a string containing a description of the error.

XML-formatted responses are structured equivalently using nodes/tags instead of JSON objects; the root tag is <Results>.

{
    "success":1,
    "data":[{dataObject1},{dataObject2}...{dataObjectN}]
}

<Results>
  <success>0</success>
  <message>error message string</message>
</Results>

JSONP

The API supports JSONP. To get a JSONP response, include a parameter named “callback” in the request and set the value to the name of your function. Example:

http://api.neotomadb.org/v1/dbtables/contacts/1?callback=myFunctionName

Searches Involving Ages

In the Neotoma database, sample ages are measured in several different time scales, and samples associated with more than one chronology have multiple ages. To enable query and comparison across these collective data, it was necessary to resolve all sample ages to a single calendar-year time-scale. Therefore, when ages are specified in calls to resources such as Datasets and SampleData, the API employs methods to determine the best available default chronology to use and, if necessary, converts sample ages in uncalibrated radiocarbon years to calendar years using a conversion table based on the INTCAL04 calibration curve (Reimer et al. 2004). For more information, please see the Neotoma Database Manual.


Page Tools