Ecological Spectral Information System (EcoSIS)
Please create issues for any bugs you find here.
The purpose of this page is to show the EcoSIS API (Application Programming Interface) specification and how it can be used to develop 3rd party applications and tools using EcoSIS. The EcoSIS API is a REST based API with all calls over HTTP.
The EcoSIS API is broken into four parts:
A Sample API call would look like this:
curl https://ecosis.org/api/package/search?text=&filters=[]&start=0&end=6This would return return the first six datasets in ecosis.
There are two root urls for EcoSIS, one for production and one for the developer sandbox:
The EcoSIS API allows you to search and find datasets by filtering datasets based on attribute names as well as free text search. Much like you would while shopping for shoes online, the EcoSIS API allows you to specify attributes you would like spectra to match, say, Category = Dicot or Organization = CSTARS.
The path for the dataset search is /api/package/search.
HTTP requests can provide query parameters, similar to passing inputs to a function. HTTP query paramters start at '?' in the url and are followed by '&' after. Ex: /api/package/search?arg1=value1&arg2=value2. The EcoSIS Dataset Search has the following parameters:
The text parameter is exactly the same as entering text into the search text box at EcoSIS Search. You can enter any free text you wish for this field or you can leave it blank.
The filters parameter is the heart of the EcoSIS API. The filters parameters is also the most complex. At it's core, the filter parameter is a JSON array of objects. These JSON objects can be any MongoDB query. The array of query objects will then be logic and together. Don't worry, you don't need to learn the entire MongoDB query document (though you can if you want), learning the simple attribute match will allow you to make 90% of the queries the EcoSIS Search does. A attribute match object looks like:
[{
Category: "Dicot"
}]Which says, return all datasets where Category matches Dicot. Or to match Category = Dicot AND Organization = CSTARS:
[{
Category: "Dicot"
},{
Organization: "CSTARS"
}]Note: for those new to JSON. {} = object, [] = array. So [{},{},{}] is an array of three empty objects.
Note for implementation. You must escape JSON when you provide it to the url. The url component escaping spec is here and it's complex! Use whatever language you are writing in escape method(s) to do this for you! Here is an example of creating a filter query in JavaScript:
var query = [{
Category: "Dicot"
},{
Organization: "CSTARS"
}];
// turn JavaScript object into JSON string
query = JSON.stringify(query);
// escape for url component
query = encodeURIComponent(query);
var restUrl = 'https://ecosis.org/api/package/search?text=&filter='+query+'&start=0&stop=6';The start index is the offset that should be used for the response result set. A query can match hundreds of items and the size of the HTTP response would be very large and cumbersome if you don't filter it down. So if you just want the first 10 items, you would set start = 0, stop = 10.
The stop index minus the start index tells how many items to return. So if you want items 20 - 30, you would say start = 20, stop = 30.
EcoSIS Dataset Search examples are easy to find. Simply go to EcoSIS Search and perform a query. At the very bottom of the page you will see a 'Rest Link' anchor tag and under it, the actual textual representation of the link (not escaped). You can click the link to see the raw JSON response feed. The EcoSIS API is not just an addition to help third party developers, it powers EcoSIS itself. So anything the search interface is doing, you can do. And many of the API calls used to perform the action (such as search for a dataset) are respresented in the search interface.
The responses for the EcoSIS API will also be JSON. The dataset search response has the following attributes
The items array is an array of dataset search objects. These objects represent a dataset with a sumation of all the spectra within that datasets unique attribute values. What that means, every attribute in the response object (except two) are JSON array's of strings. These strings are all the unique values for that attribute in the dataset. Ex: A dataset has the attribute 'Scientific Name' so the response object would contain the attribute 'Scientific Name' with all the unique values for 'Scientific Name' returned in the response object:
{
...
Scientific Name: [
"Acer rubrum",
"Pinus resinosa",
"Pinus strobus",
"Quercus rubra",
"Abies balsamea",
"Picea rubens",
"Tsuga canadensis"
],
...
}The dataset search object will also contain the following attributes:
Each query returns additional filters in the filters attribute. The filters object are the primary filters used on the left hand side of the EcoSIS Search interface. You can use these filters as suggestions to help further narrow your search.
Once you have found a dataset using the Find Dataset query, you can use the datasets ID (see Dataset Search Response item._id or item.ecosis.package_id paramters) to access a dataset directly. The query only has one parameter: _id.
The Rest path to get a dataset search object is: /api/package/[dataset name or ID here]
curl https://ecosis.org/api/package/[dataset name or ID here]The get dataset response is the same response object returned in the items array of the find query: Dataset Search Response.
You can find and get spectra filtering by metadata attributes including package_id or packege_name
The Rest path for the Get Spectra call is: https://ecosis.org/api/spectra/search/
curl https://ecosis.org/api/spectra/search/[dataset name or ID here]?start=0&stop=2&filters=[Array of filters]The Get Spectra call takes the following paramters
The start index that will be used for response. Required for pagination.
The stop index that will be used for response. Required for pagination.
The filters parameter lets you filter down the result set of spectra you are accessing. The filters parameter is formatted the same and works the same as the Find Dataset Filter Parameter. Only instead of filtering key/value pairs based on attributes in a dataset, you are filtering on individual spectra metadata.
The response object for the Get Spectra query has the following attributes:
Along with the standard _id, ecosis and datapoints parameters, the response object.items sends back all of the metadata included with the spectra.
Format Note. The keys and values of the datapoints are always returned as strings. This is both to improve system performance and work around the complexity of handling floats. It will be up to each client interacting with EcoSIS to decide how it wants to parse and handle floating point values.
Use this query to get the min, max, sum, count, avg, and std deviation for any datasets spectra.
The Rest path for the Get Spectra Stats call is: /api/spectra/stats/[dataset name or ID here]
curl https://ecosis.org/api/spectra/stats/[dataset name or ID here]The Get Spectra Stats call takes the following paramters
The filters parameter lets you filter down the result set to get stats for. The filters parameter is formatted the same and works the same as the Find Dataset Filter Parameter. Only instead of filtering key/value pairs based on attributes in a dataset, you are filtering on individual spectra metadata.
The response object for the Get Spectra Stats query is a javascript object. Each key for the object is a wavelength or datapoint. the value is a javascript object, each having the following attributes:
The spectra will be returned sorted if the dataset maintainer provided a sort parameter.
While the Get Spectra call is useful for inspecting spectra, especially from 3rd party applications, it's not an efficient process to download large amounts of spectra. The Download Spectra calls purpose is to allow the export of a datasets spectra in CSV format.
The Rest path to download spectra is: /api/package/[dataset name or id]/export
The Download Spectra call takes the following parameters
Do you want to include the all of the spectra's metadata in the export. The value should be 'true' or 'false'.
The filters parameter lets you filter down the result set of spectra you are downloading. The filters paramter is formatted the same and works the same as the Find Dataset Filter Parameter. Only instead of filtering key/value pairs based on attributes in a dataset, you are filtering on individual spectra. This allows you do export subsets of the dataset spectra.
curl https://ecosis.org/api/package/[dataset name or ID here]/export&metadata=falseJustin Merz (@jrmerz)