Skip to content

Home

Jump to bottom
Joanne Koch edited this page Aug 14, 2025 · 26 revisions

Welcome to the nes-lter-api-2 wiki!

What does "REST API" mean?

A REST API provides a set of consistent URLs that, when fetched, return data in machine-readable form that may be used by application code.

Overview

The REST API provides a set of URLs from which your code can directly access conveniently-formatted NES-LTER datasets. To do this, construct a URL according to the instructions below, and use one of the provided code snippets to fetch the data. Please obtain the url_prefix from your System Administrator. This url_prefix will be referenced in all the urls below.

A list of all Vessels and all Cruises is provided, in addition to individual Vessel and Cruise information.

Several data types are currently provided per cruise:

  • CTD casts and metadata related to them
  • Underway data
  • Station metadata
  • Event logs
  • Nutrients
  • Chlorophyll
  • HPLC

In addition to fetching the data directly into your code, you can access the URL with your browser and download the data. The downloaded file will have a filename that distinguishes it from other similar files.

The NinjaAPI is web-based UI for interacting with your API endpoints. It allows you to test GET and POST requests directly from the browser. The NinjaAPI interactive API document contains all the working URLs for the API. To access the interactive API docs, type url_prefix/api/docs# in your browser address bar.

When you request data from a URL, there are two reasons why you might get a 404 "not found" response. One is if your URL is not correctly formatted according to the REST URL syntax; the other is that the requested data are not available.

You can view the README for each data type to learn more about what data are available.

URL syntax

URLs begin with a standard URL prefix followed by a data type indicator followed by the cruise ID followed by the cast number (/api/ctd/cast/get/{cruise_name}/{cast_number}). For example, to fetch CTD cast 8 from en608, use the following URL:

[url_prefix/api/ctd/cast/get/en608/8]

Example URLs for all data types are given below.

Vessel and Cruise URLs

Provides a list of Vessels

[url_prefix/api/ctd/vessels/get/all]

Provides data specific to an individual Vessel such as designation and name (/api/ctd/vessels/get/{vessel_name}):

[url_prefix/api/ctd/vessels/get/endeavor]

Provides a list of Cruises

[url_prefix/api/ctd/cruises/get/all]

Provides data specific to an individual Cruise such as Cruise name, Vessel name and Cruise start and end dates (/api/ctd/cruises/get/{cruise_name}).

[url_prefix/api/ctd/cruises/get/en608]

CTD URLs

CTD metadata provides a list of casts for a given cruise along with metadata about each cast (e.g., time, lat/lon, nearest station)(/api/ctd/metadata/{cruise_name}). For example:

[url_prefix/api/ctd/metadata/en608]

CTD bottle data provides a list of niskins along with data from the CTD as it has been provided by the SeaBird CTD processing software (/api/ctd/bottles/{cruise_name}). For example:

[url_prefix/api/ctd/bottles/en608]

Please note that column headers for CTD bottle data and profiles are described in the SeaBird Data Processing Software Manual, Appendix VI: Output Variable Names, e.g., pp. 161 - 174 at this link.

CTD bottle summary data provides a concise summary of when and where each bottle was fired (/api/ctd/bottle_summary/{cruise_name}). For example:

[url_prefix/api/ctd/bottle_summary/en608]

A list of CTD cast numbers for Cruise en617 (/api/ctd/casts/get/{cruise_name}):

[url_prefix/api/ctd/casts/get/en617]

CTD profiles for each cast for a specific Cruise are available(/api/ctd/niskins/get/all/{cruise_name}/{cast_number}):

[url_prefix/api/ctd/cast/get/en617/12]

Display Cruise Track on a geographic map. The Cruise Track is shown along with selectable Cast locations for the Cruise. Click on the Cast icons to display the Cast details and view the CTD Profile plot graph.

[url_prefix/api/cruise/ar70b/track]

image

Underway URL pattern

Underway 1-minute data is provided per-cruise (/api/underway/get/{cruise_name}):

[url_prefix/api/underway/get/ar31a]

Returns column headers for the Underway 1-minute data above (/api/underway/get_column_headers/{cruise_name})

[url_prefix/api/underway/get_column_headers/ar31a]

Searches 1-minute Underway data and returns a list of cruises having Underway data between a start and end date (/api/underway/find/{start_timestamp}/{end_timestamp})

[url_prefix/api/underway/find/2021-10-07/2022-10-07]

Station metadata URL pattern

Station metadata briefly describes each station along with pertinent information like lat/lon. Use the following URL pattern (/api/stations/file):

[url_prefix/api/stations/file]

Note that some stations have moved their locations during the life time of the project.

Add a Nearest Station using the following URL specifying the lat, lon, and timestamp.

[url_prefix/api/stations/add_nearest] **

** This POST endpoint can only be called from your code and not the browser address bar.

Event log URLs

Event logs are available per-cruise. The event logs are corrected to align with the other products, including correction of timestamps and positions (/api/events/get/{cruise_name}).

For example:

[url_prefix/api/events/get/en627]

Search the event log for a cruise containing one or more of the following: instrument, action, station, cast, comment:

[url_prefix/api/events/filter/en627/] **

** This POST endpoint can only be called from your code and not the browser address bar.

Get a history of manual changes made to the event log (/api/events/history/{cruise_name}):

[url_prefix/api/events/history/en627/]

Nutrients, Chlorophyll, and HPLC URLs

Nutrients, Cholorphyll, and HPLC data are available per cruise. Nutrient and Cholorphyll data have a single "all" endpoint available to access all the available cruise data in a single file.

For example:

[url_prefix/api/nut/en644.csv] (/api/nut/{cruise_name})

[url_prefix/api/nut/all] (/api/nut/all)

[url_prefix/api/chl/en644.csv] (/api/chl/{cruise_name})

[url_prefix/api/chl/all] (/api/chl/all)

[url_prefix/api/hplc/en617.csv] (/api/hplc/{cruise_name})

Code snippets

The following code snippets show how to read NES-LTER data into your preferred language using the REST API. To use each example, change the URL to the URL for whichever dataset you want.

If the URL pattern is incorrect or no data is available, the server will respond with HTTP 404, "not found".

MATLAB

To read data from one of these URLs from MATLAB, use the following two lines of code. The timeout of 30 seconds can be changed to according to your requirements.

myreadtable = @(filename)readtable(filename,'Delimiter',',');
options = weboptions('ContentType', 'table', 'Timeout', 30,'ContentReader',myreadtable);
mytable = webread(`url_prefix`/api/ctd/cast/get/en608/7', options);

The result is a MATLAB table.

Note that MATLAB's default timeout is 5s and sometimes the API does not return quickly enough, hence the Timeout setting in weboptions.

Python

Use Pandas read_csv:

import pandas as pd

pd.read_csv(`url_prefix`api/ctd/cast/get/en608/7')

R

In R, use read.csv:

read.csv(`url_prefix`/api/ctd/cast/get/en608/7')

Julia

In Julia use the HTTP, CSV, and DataFrames packages:

using HTTP
using CSV
using DataFrames

DataFrame!(CSV.File(HTTP.get(`url_prefix`/api/ctd/cast/get/en608/7').body))

Parsing dates and times

When possible, dates and times are provided in ISO 8601 format in the UTC timezone. Using those fields typically requires additional parsing, and default rules for parsing dates and times in tools such as Excel and MATLAB will often fail or produce unexpected results because of limitations of those tools. For some datatypes, date and/or time are provided in separate columns in various other formats (e.g., seconds since the beginning of a CTD cast).

Here are some code snippets for parsing ISO 8601 formatted timestamps:

MATLAB

iso8601format = 'yyyy-mm-dd hh:MM:ss'
mydatenum = datenum('2019-02-22 12:34:56+00:00', iso8601format)

Python

Use Pandas to_datetime:

import pandas as pd

mydatetime = pd.to_datetime('2019-02-22 12:34:56+00:00', utc=True)

R

mydatetime <- as.POSIXlt("2019-02-22 12:34:56+00:00", tz="UTC")

or

iso8601format <- "%Y-%m-%d %H:%M:%S"
mydatetime <- strptime("2019-02-22 12:34:56+00:00", iso8601format, tz="UTC")

Excel

The following formula will convert an ISO 8601 timestamp to an Excel timestamp value, see this answer for details.

=DATEVALUE(MID(A2,1,10))+TIMEVALUE(MID(A2,12,8))

For developers

REST endpoints respond with JSON if no extension is specified or if the extension provided is "json". The JSON format is the one provided by Pandas to_json.

Some JSON-only endpoints are/will be included. For example this endpoint returns a list of CTD cast numbers for en608:

[url_prefix/api/ctd/casts/get/en608]

And this endpoint returns a list of cruises:

[url_prefix/api/ctd/cruises/get/en608]

Clone this wiki locally