IFCB web services API

Overview

IFCB web services provide access to IFCB data, imagery, and metadata in various raw and standard formats. You can use these web services to access IFCB data from anywhere, and discover what data is in an IFCB time series.

All IFCB API URLs are prefixed with a namespace URL that identifies the time series being accessed. For example, the MVCO time series is at this URL prefix:

http://ifcb-data.whoi.edu/mvco
IFCB data is partitioned into sample bins which typically represent about 20 minutes worth of imaging flow cytometry on a single seawater sample. The data in each sample bin is organized into targets, and some of the targets have associated image data.

Each bin has a URL. Bin URLs are available from the feed API described below. A bin URL begins with the namespace URL, followed by a code identifying the bin.

Feed API

Feeds of most recent data are available in standard formats. The following URLs return a list of the most recent bins up to the current time:
namespace/feed.rss
namespace/feed.html
namespace/feed.atom
namespace/feed.json
To constrain the feed to an earlier date, use this variant:
namespace/api/feed/date/date/format/format
Where "date" is an ISO8601 compliant timestamp (e.g., 2007-04-05) and "format" is one of rss, html, atom, and json.

To list all sample bins in a date range, use this variant

namespace/api/feed/start/date/end/date/format/format

Sample bin API

Raw data is available for each sample bin at the following endpoints:
bin URL.hdr
bin URL.adc
bin URL.roi
These URLs return raw IFCB data. It is not in any standard format, although ADC data is in CSV syntax.

XML, RDF, JSON, and CSV variants are available by using the appropriate prefixes:

bin URL.xml
bin URL.rdf
bin URL.csv
bin URL.json
These variants provide metadata from the sample bin's header file as well as a list of target URLs, which can be used with the target API.
RAW DATA CONTAINS "EXTRA" TARGETS: Raw IFCB data for a sample bin almost always contains more targets than will appear in metadata returned from the XML, RDF, CSV and JSON URLs. This is for two reasons:
  1. Some targets in an ADC file have no image associated with them. In the ADC file these will have a (width,height) of (0,0). These targets are skipped for URLs other than bin URL.adc.
  2. In early IFCB models, some pairs of images associated with the same trigger overlap. In this case the web services will return a composited target at the URL of the first target of the pair, and will report that the second target of the pair does not exist.

A ZIP endpoint returns image data along with metadata, in zip format. Note that this is a CPU-intensive call that can take as long as 30 seconds to complete for a large sample bin.

bin URL.zip
To see an interactive web page summarizing the sample bin, use this URL:
bin URL.html

Target API

Once a target URL is in hand, metadata about it can be fetched in a variety of standard formats:
target URL.xml
target URL.rdf
target URL.json
Images can be fetched using image extensions;
target URL.png
target URL.tiff
target URL.jpg
target URL.gif
target URL.bmp
The PNG and TIFF variants are guaranteed to contain the exact data in the image. Other formats may be lossy. In particular do not use the JPG variant if you intend to perform any automated analysis of the images.
IMAGE DIMENSIONS ARE ROTATED: The image dimensions given in image metadata are 90 degrees rotated from the coordinate systems of the images returned by the image endpoints. So the field called "width" in target metadata corresponds to the height of the image returned from the target image URLs, and the field called "height" corresponds to the width of the image returned from the target image URLs.
To see an interactive web page summarizing the sample bin, use this URL:
target URL.html

Product API: Sample Bins

In addition to instrument data and images, image processing, features, and classification results are also available. To fetch a ZIP file containing all "blobs" (bitmap masks separating the target from the background) for a given bin, use one of these URL variants:
bin URL_blob.zip
namespace/api/blob/pid/bin URL.zip
Note that in the second variant you should put the entire bin URL after /pid/. The URL should look like this:
http://ifcb-data.whoi.edu/mvco/api/blob/pid/http://ifcb-data.whoi.edu/mvco/IFCB1_2009_208_123123.zip
Instead of this:
http://ifcb-data.whoi.edu/mvco/api/blob/pid/IFCB1_2009_208_123123.zip
Features (scalar metrics computed from images and metadata prior to classification) are available in CSV format using one of these URL variants:
bin URL_features.csv
namespace/api/features/pid/bin URL.csv
And classification results are available using one of these URL variants:
bin URL_class_scores.csv
namespace/api/class_scores/pid/bin URL.csv
Note that products are not available unless the processing that produces them has completed.

Product API: Targets

Blob images are available per-target. Use one of these URL variants:
target URL_blob.extension
namespace/api/blob/pid/target URL.extension
Where extension is a valid image type extension such as "png". A simple visualization that shows the outline of the blob overlaid on the target image is available at:
target URL_blob_outline.extension
Note that blob outlining requires some image processing on the server side.