Using the Planet OS REST API with Javascript

One of our goals at Planet OS is to provide consistent and easy access to environmental data that’s scattered around the web in various formats. Before working at Planet OS I had never heard of OPeNDAP, even though it’s a well known standard, especially in the oceanographic community.

I’m a datavis designer and product developer working in Javascript, so I prefer data as json from a simple REST API, regardless of the original format that data is in. And that’s exactly what Planet OS provides, hiding the complexity of scientific protocols and file types and delivering the json I need. If you’re curious about how to use the Planet OS API and Javascript in your own applications, here are some tips to get you started.

We initially launched data.planetos.com with three datasests, and we’re working to steadily increase this number by adding new datasets to our catalog each month. One of our first supported datasets is NOAA WaveWatch III. You can try to get the data from NOAA’s http repository, or you can use Planet OS instead.

Viewing the data access options on Planet OS does require an account, but you can create a new account for free… I’ll wait.

Once you’ve logged in, the WaveWatch III dataset page provides an example point query that includes your unique API key. Clicking on this sample query will open it in a new page, allowing you to review the json response. We’ll have a sandbox allowing you to explore the API very soon, but let’s see how it’s already easy to use the API with Javascript.

Data Access

The dataset access we provide consists of two parts: a THREDDS server and a point data API. Here’s a definition of the THREDDS server from the official website.

The THREDDS Data Server (TDS) is a web server that provides metadata and data access for scientific datasets, using OPeNDAP, OGC WMS and WCS, HTTP, and other remote data access protocols.

Here’s how to use it. From this Wavewatch dataset page, just above the point query example, you can click on “Planet OS Thredds Data Server” to navigate the data file hierarchy until you land on an OPeNDAP Dataset Access Form, at a URL that will look like this:

http://thredds.planetos.com/thredds/dodsC/dpipe/rel_0_6x11_dataset/transform/scheme=/ftp/authority=/ftp.ncep.noaa.gov/path=/pub/data/nccf/com/gfs/prod/gfs.2016032912/gfs.t12z.sfluxgrbf00.grib2/chunk=/1/0/preview.html

From there, you can replace .html by .das or .dds, to get some useful metadata. We are also computing some nice downsampled preview data for you. You can get it by using the .dods extension. The file will be huge if you don’t filter it. From the .html page, you can check the variables and filters you want and then get the Data URL from the form field, which will look like:

http://thredds.planetos.com/thredds/dodsC/dpipe/rel_0_6x11_dataset/fetch/scheme=/ftp/authority=/ftpprd.ncep.noaa.gov/path=/pub/data/nccf/com/wave/prod/multi_1.20160327/nww3.t06z.grib.grib2/0/file?ordered_sequence_of_data[0:1:0]

Be aware that the .dods data preview file is a binary file, so you will have to parse it. Fortunately there’s a pretty good OPeNDAP parser for javascript called jsdap.js. It was abandoned for a while, but a guy named Brandon Nielson recently took over and did an amazing job of upgrading it. We are trying to contribute to this excellent fork as much as we can and we invite others to contribute as well. Using jsdap to load and parse the .dods file is as simple as this:

jsdap.loadData(dataPreviewDodsURL, function(parsedData){       
    console.log(parsedData);
});

Point API

While many within the scientific community may be comfortable with THREDDS and OPeNDAP, it’s not the friendliest interface for newcomers. As an alternative, Planet OS also provides a RESTful point API that you can use to get the data for multiple variables at a single coordinate. You can have a look at the documentation, but there’s an easier way to try it. Just go back to the dataset details page, like this one for WaveWatch III. Once logged in, you will see an example point query with your API key already included. Just click on the link to get some data back.

Javascript Wrappers

To make it even easier, we made a Backbone wrapper. From this simple wrapper, you can query metadata, data preview and point data. You simply populate a query model, then it will fetch and parse the data in the related data collection, and you just have to listen to it in your view.

// Query
var dataQueryModel = new DataQueryModel();
// Collection, where the data will be
var dataCollection = new DataCollection({
 queryModel: dataQueryModel
});
// A Backbone view that listens to teh collection loading
var variableListView = new VariableListView({
 el: ‘.variable-container’,
 dataCollection: dataCollection
});
// Populating the query model will trigger the query
dataQueryModel.set({
 baseURL: ‘http://api.planetos.com/v1/datasets/',
 datasetName: ‘noaa_gfs_global_sflux_0.12d’,
 lon: 0,
 lat: 0,
 apiKey: ‘ADD_YOUR_API_KEY_HERE’,
 isVerbose: false,
 count: 10
});

I invite you to take a look at this point API demo to see how the wrapper can be used. The source code is available here.

And if that’s not enough, here’s still another way to try it in your own code. Go to this Blockbuilder live code, grab your API key from your account settings, place it in the query URL and have fun! Just a reminder that a Planet OS account is required to access the API, but you can quickly create one for free!

That’s it! We are working on examples for other programming languages and encourage the community to contribute their own. Be on the lookout for additional iPython Notebooks and a nice Node.js wrapper coming soon. Stay tuned!

Christophe
Data Visualization Engineer
Planet OS