Planet OS Product Guide

This guide provides an overview of the key features and concepts of Planet OS.

Datasets

Planet OS maintains a curated catalog of public and commercial datasets. For each of the datasets in our catalog, Planet OS provides a detailed summary page that contains key metadata attributes and a downsampled dataset preview.

Summary

The summary section provides key metadata attributes for the dataset. Each of these attributes is explained in further detail below.

Publisher: The party from whom the dataset was acquired.
Source: The specific method of production of the original data. If the product was model-generated, source should name the model and its version. If the dataset is observational, source should characterize the empirical method (e.g. surface observation, radiosonde, etc.).
Abstract: A short, descriptive summary of the dataset.
Refreshed: The time at which Planet OS last acquired new data from the dataset publisher.
Update Frequency: The frequency at which data is updated at its origin (e.g. hourly, daily, monthly).
Product Type: The general method by which data is produced (e.g. observed, modeled, hindcast, reanalysis).
Feature Type: Scientific feature type or CDM data type (e.g. GRID, RADIAL, SWATH, IMAGE, ANY_POINT, POINT, PROFILE, SECTION, STATION, STATION_PROFILE, TRAJECTORY).
Spatial Reference System: The spatial reference system used by the dataset (e.g. WGS84).
Temporal Resolution: The temporal resolution of the data in time units or free text.
Spatial Resolution: The spatial resolution of the data in meters, decimal degrees or free text.

Extent

The extent section describes the spatial and temporal extent of the dataset. The minimum and maximum latitude and longitude are expressed as decimal degrees. For datasets with a vertical extent, this information is also included.

The start and end date of the available data are provided as well. Datasets that are actively producing new data are denoted as "Ongoing".

Variables

The variables section includes information about all dataset variables, including the variable name, long name, and unit. The total number of variables is shown in parenteses immediately after the section title.

At the right of the section header is the vocabulary used for the variables. Typically this is a CF (Climate and Forecast) convention, and includes the specific version of the vocabulary is also included when available.

When performing API queries, the variable name shown in this section may be used to request specific variables.

Dimensions

The dimensions of the dataset are displayed separately in this section. Typically this includes dimensions such as time, reference time, latitude and longitude.

License

When provided by the publisher, the dataset's license is included here for reference.

Data Access

Planet OS provides a variety of interfaces for accessing data. Details regarding the available data access methods and protocols, as well as rate and volume limiting are discussed below.

REST API

Planet OS provides a RESTful API for programmatically accessing data at specific locations. Documentation and resources for this API are included below.

Limits

Data access is limited by both call rate and transfer volume per user. For details on individual plans, see our pricing page.

Free accounts are limited to 100 REST API calls per day and 5 GB of data transfer per month.

If your workflow or application requires access that exceeds these limits, please contact datahub@intertrust.com.

REST API (v1)

The Planet OS REST API can be used to integrate disparate spatiotemporal datasets into data-driven applications and workflows. The API provides programmatic access to data at a specific location and delivers JSON responses.

Authentication

Each Planet OS user is granted a unique API key that is used to authenticate API calls. All API endpoints require this key be passed as a query parameter to authenticate the request. Your key may be viewed on the Account Settings screen and is provided below if you're currently logged in.

Your API Key is: Create an account to receive an API Key

Example of an Authenticated HTTP Request

GET http://api.planetos.com/v1/datasets?apikey={apikey}

Search & Discovery Endpoints

Dataset Search

Search and filter datasets index by keyword and facet. Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/search/text?q=temperature&apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/search/text"

querystring = {
  "apikey":"{apikey}",
  "q": "temperature"
}

response = requests.request("GET", url, params=querystring)

# response.text is raw output
result = response.json()  # turn JSON into python data structure
print result

var request = require("request");
// npm install request

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/search/text',
  qs: { apikey: '{apikey}', q: 'temperature' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  // console.log(body);
  var result = JSON.parse(body)
  console.log(result)
});

apikey = '{apikey}'
api_root_url = 'http://api.planetos.com/v1/'

all_variables_url = sprintf('%ssearch/text', api_root_url)
list_of_variables = webread(all_variables_url, 'apikey', apikey, 'q', 'temperature')
disp(list_of_variables)

The above command returns JSON structured like this (sample):

{
  "count": 10,
  "isError": false,
  "searchedPolygons": [],
  "results": [
    {
      "key": "nasa_ghrsst_global_daily",
      "title": "GHRSST Level 4 G1SST Global Foundation Sea Surface Temperature Analysis",
      "summary": "A Group for High Resolution Sea Surface Temperature (GHRSST) …",
      "UpdateFrequency": "1 day",
      "timeCoverage": [{
        "timeFrom": "2016-10-01T00:00:00+0000",
        "timeTo": "2016-10-31T00:00:00+0000"
      }],
      "TemporalResolution": "1 day",
      "ProductType": "Analysis",
      "SpatialResolution": "0.009 degrees",
      "FeatureType": "GRID",
      "snippets": [],
      "geoCoverage": [
        {
          "type": "MultiPolygon",
          "coordinates": [[[[-179.9, 80.5], [-179.9, -80.5], [179.9, -80.5], [179.9, 80.5], [-179.9, 80.5] ] ] ]
        }
      ]
    }
  ]
}

Filter dataset index by specified criteria. It supports free text search as well as predefined facets, like a variable, time range, spatial and temporal resolution, publisher, dataset type (time-series, grid), data product type (forecast, observation, model, etc.)

HTTP REQUEST

GET http://api.planetos.com/v1/search/text?q=temperature&apikey={apikey}

variable	Filter by variable key WIND_SPEED
variable.standard_name	Matches on the standard name of any variable in the dataset. Standard names are from the NetCDF-CF standard name table. To search for multiple standard names, they should be comma-separated. Quoted expressions will be treated as a single standard name. E.g., `variable.standard_name=time,"air temperature"` will match datasets that contain variables with standard names matching `time` or `air temperature`. Partial matching is supported via usage of `` wildcard. E.g., `variable.standard_name="wind"` will match datasets containing variables with standard names containing `wind`. wind*
variable_partial	Partial variable key match wind
after	Time range start 2016-10-01
before	Time range end 2016-11-10
product_type	Type of data rroduct MODEL \| OBSERVATION \| FORECAST
feature_type	Data type GRID \| TIMESERIES
publisher	Data publisher COPERNICUS

RESPONSE

The response includes a count of matches, a list of matched datasets (results) with dataset IDs (key) and a set of metadata attributes.

Request a list of all facets available in the system. Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/browse/open/variables?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/browse/open/variables"

querystring = {"apikey":"{apikey}"}

response = requests.request("GET", url, params=querystring)

# response.text is raw output
result = response.json()  # turn JSON into python data structure
print result

var request = require("request");
// npm install request

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/browse/open/variables',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  // console.log(body);
  var result = JSON.parse(body)
  console.log(result)
});

apikey = '{apikey}'
api_root_url = 'http://api.planetos.com/v1/'

all_variables_url = sprintf('%sbrowse/open/variables', api_root_url)
list_of_variables = webread(all_variables_url, 'apikey', apikey)
disp(list_of_variables)

The above command returns JSON structured like this (sample):

[
  ["WNDGUST10M", "10m wind gust"],
  ["WIND_SPEED", "10m wind speed"],
  ["ATMP", "ATMOSPHERIC_PRESSURE"],
  ["DEWPT_TEMPERATURE", "Dew Point Temperature"],
  ["DEWPOINT_TEMPERATURE_HYBRID", "Dewpoint temperature @ Hybrid level"],
  ["NITRATE", "Nitrate_Concentration"],
  ["WATER_V", "Northward Water Velocity"],
  ["WATER_U", "Eastward Water Velocity"],
  ["UV-B_DOWNWARD_SOLAR_FLUX_SURFACE_12_HOUR_AVERAGE", "UV-B Downward Solar Flux (12_Hour Average) @ Ground or water surface"],
  ["WATER_TEMP", "Water Temperature"]
]

Dataset search is enhanced with additional faced-based filtering. To take advantage of it, please use these API endpoints which list all possible facet values.

Table of matching search parameters.

HTTP REQUEST

GET http://api.planetos.com/v1/browse/open/variables?apikey={apikey}

GET http://api.planetos.com/v1/browse/open/filters/SpatialResolution?apikey={apikey}

GET http://api.planetos.com/v1/browse/open/filters/TemporalResolution?apikey={apikey}

GET http://api.planetos.com/v1/browse/open/filters/ProductType?apikey={apikey}

GET http://api.planetos.com/v1/browse/open/filters/FeatureType?apikey={apikey}

GET http://api.planetos.com/v1/browse/open/filters/Publisher?apikey={apikey}

RESPONSE

A list of facets key value tuple pairs. The key is for making API queries, while value might be used as a human-friendly facet representation for UIs, data visualizations, etc.

Dataset Endpoints

/datasets

Request a list of all dataset IDs available in the system. Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/datasets?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets"

querystring = {"apikey":"{apikey}"}

response = requests.request("GET", url, params=querystring)

# response.text is raw output
result = response.json()  # turn JSON into python data structure
print result

var request = require("request");
// npm install request

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  // console.log(body);
  var result = JSON.parse(body)
  console.log(result)
});

apikey = '{apikey}'
api_root_url = 'http://api.planetos.com/v1/'

dataset_meta_url = sprintf('%sdatasets', api_root_url)
list_of_ds_ids = webread(dataset_meta_url, 'apikey', apikey)
disp(list_of_ds_ids)

The above command returns JSON structured like this:

[
  "nasa_grctellus_ocean",
  "nasa_gldas_lwc_monthly",
  "noaa_ndbc_swden_stations",
  "myocean_sst_europe_daily",
  "nasa_ghrsst_global_daily",
  "noaa_ww3_ak",
  "noaa_nam_hawaii",
  "nasa_3imerghhl",
  "socib_forecast_western_mediterranean_daily",
  "metoffice_glosea5_global_daily",
  "nasa_3imerghhe",
  "noaa_ndbc_adcp_station",
  "rss_ccmp_winds_v2",
  "cmems_gwind",
  "noaa_ww3_nah",
  "noaa_nam_ca",
  "nasa_grctellus_land",
  "noaa_etopo_global_1arcmin",
  "noaa_icoads_enhanced_1d_day",
  "myocean_sst_baltic_daily",
  "noaa_gfs_global_sflux_0.12d",
  "noaa_blended_sea_winds_6hr_global_0.25d",
  "noaa_ww3_global_1.25x1d",
  "noaa_ww3_wc",
  "noaa_ww3_ao",
  "noaa_nam_prico",
  "noaa-ncep_gefs",
  "noaa_ww3_nph",
  "noaa_ndbc_stdmet_stations",
  "bom_access-g_global_40km",
  "noaa_nam_alaska",
  "noaa_nam_north_pacific",
  "copernicus_biogeo_baltic_hourly",
  "noaa_nam_awips_phys",
  "nasa_oscar_global_5day",
  "copernicus_goba_global_weekly",
  "noaa_ww3_at",
  "nasa_3imerghh",
  "pacioos_swan_oahu",
  "noaa_ww3_hurricane_ep",
  "noaa_ww3_hurricane_at",
  "noaa_ndbc_cwind_stations",
  "noaa_ww3_ep",
  "noaa_ww3_hurricane_ak",
  "noaa_ww3_hurricane_wc",
  "hycom_glbu0.08_91.2_global_0.08d",
  "noaa_nam_awips_12"
]

Get list of all dataset IDs.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets?apikey={apikey}

RESPONSE

A flat list where each item is a plain text dataset ID.

/datasets/{id}

Request metadata for the hycom_glbu0.08_91.2_global_0.08d dataset. Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/datasets/hycom_glbu0.08_91.2_global_0.08d?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets/hycom_glbu0.08_91.2_global_0.08d"

querystring = {"apikey":"{apikey}"}

response = requests.request("GET", url, params=querystring)

# response.text is raw output
result = response.json()  # turn JSON into python data structure
print result['Title']

var request = require("request");
// npm install request

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/hycom_glbu0.08_91.2_global_0.08d',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  // console.log(body);
  var result = JSON.parse(body)
  console.log(result.Title)
});

apikey = '{apikey}'
dataset_id = 'hycom_glbu0.08_91.2_global_0.08d'
api_root_url = 'http://api.planetos.com/v1/'

dataset_meta_url = sprintf('%sdatasets/%s', api_root_url, dataset_id)
metadata = webread(dataset_meta_url, 'apikey', apikey)
disp(metadata.Title)

The above command returns JSON structured like this:

{
  "Title":"HYCOM (Hybrid Coordinate Ocean Model) global ocean forecast",
  "Source":"Operational ocean model output",
  "Publisher":"HYCOM consortium",
  "Institution":"HYCOM consortium",
  "Abstract":"The HYCOM consortium is a multi-institutional effort [...]",
  "UpdateFrequency":"24 h",
  "FeatureType":"climatologyMeteorologyAtmosphere",
  "ProductType":"Forecast",
  "Refreshed":"2016-04-18T12:43:13",
  "TemporalResolution":"3 hours",
  "SpatialResolution":"1/12 degrees",
  "SpatialExtent":{
    "type":"MultiPolygon",
    "coordinates":[[[[-0.5, 85.5 ], [-0.5, 80.5 ], [-1.5, 80.5 ], "..." ] ] ] },
  "SpatialExtentText":null,
  "SpatialReferenceSystem":"WGS84",
  "VerticalExtent":"40 levels from surface to 5000 m below the surface",
  "TemporalExtentStart":"",
  "TemporalExtentEnd":"Ongoing",
  "Licence":"Open data",
  "LicenceType":"open",
  "DistributionFormat":"thredds, ftp",
  "OnlineResource":[ "http://hycom.org/" ],
  "DataVendorKey":null,
  "Variables":[
    {
      "name":"time",
      "longName":"Valid Time",
      "standardName":null,
      "unit":"microseconds since 1970-01-01 00:00:00",
      "isData":false,
      "isCoord":true,
      "isInfo":false
    },
    {
      "name":"lat",
      "longName":"Latitude",
      "standardName":"latitude",
      "unit":"degrees_north",
      "isData":false,
      "isCoord":true,
      "isInfo":false
    },
    {
      "name":"lon",
      "longName":"Longitude",
      "standardName":"longitude",
      "unit":"degrees_east",
      "isData":false,
      "isCoord":true,
      "isInfo":false
    },
    {
      "name":"salinity",
      "longName":"Salinity",
      "standardName":"sea_water_salinity",
      "unit":"psu",
      "isData":true,
      "isCoord":false,
      "isInfo":false
    }
  ]
}

Get dataset metadata.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}?apikey={apikey}

RESPONSE

Title: The title or name of the dataset.

Abstract: A short summary of the dataset.

Publisher: The party from whom the dataset was acquired.

Institution: The party who created the dataset.

Source: The method of production of the original data. If it was model-generated, source should name the model and its version, as specifically as could be useful. If it is observational, source should characterize it (e.g., 'surface observation' or 'radiosonde').

ProductType: Method how data is being produced — observed, modeled, hindcast, reanalysis, etc. More generic than the "Source"

Refreshed: Indicate the timestamp at which point system last acquired new data from the publisher

DistributionFormat: Available distribution formats as free text

FeatureType: Scientific feature type or CDM data type (e.g. GRID, RADIAL, SWATH, IMAGE, ANY_POINT, POINT, PROFILE, SECTION, STATION, STATION_PROFILE, TRAJECTORY)

License: Original data access/use license

LicenseType: Original data access/use license type — one of (commercial, open) string

OnlineResource: Available distribution URLs for original data

SpatialExtent: Extent, polygon or multipolygon in GeoJSON notation

SpatialExtentText: Free text description of spatial coverage

SpatialReferenceSystem: WGS84 or similar

SpatialResolution: Spatial resolution of gridded data in meters, decimal degrees or free text

SpatialResolutionVertical: Vertical resolution of gridded data in meters, decimal degrees or free text

TemporalExtentStart: Temporal extent start time in ISO8601 text format

TemporalResolution: Temporal resolution of gridded data in time units or free text

TemporalextentEnd: Temporalextent end time in ISO8601 text format OR 'ongoing'

UpdateFrequency: How frequently is data updated at its origin. Mostly for regularly updating automatic data

Variables: List of variables

VerticalExtent: Vertical extent description as text

/datasets/{id}/point

Request values from the noaa_ww3_global_1.25x1d dataset at a specific point coordinate. Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/point?lon=-50.5&lat=49.5&apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/point"

querystring = {"lon":"-50","lat":"50","apikey":"{apikey}"}

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/point',
  qs: { lon: '-50', lat: '50', apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

apikey = '{apikey}'
dataset_id = 'noaa_ww3_global_1.25x1d'
api_root_url = 'http://api.planetos.com/v1/'

dataset_point_url = sprintf('%sdatasets/%s/point', api_root_url, dataset_id)
rest_data = webread(dataset_point_url, 'apikey', apikey, 'lon', -50, 'lat', 50)

The above command returns JSON structured like this:

{
  "stats": {
    "offset": 0,
    "count": 1
  },
  "entries": [{
    "context": "reftime_time_lat_lon",
    "axes": {
      "reftime": "2016-04-24T12:00:00",
      "time": "2016-04-24T12:00:00",
      "longitude": -49.99999999999997,
      "latitude": 50.0
    },
    "data": {
      "Wind_speed_surface": 4.409999847412109,
      "Wind_direction_from_which_blowing_surface": 171.86000061035156,
      "v-component_of_wind_surface": 4.360000133514404,
      "u-component_of_wind_surface": -0.6200000047683716,
      "Direction_of_wind_waves_surface": 98.7699966430664,
      "Primary_wave_mean_period_surface": 10.760000228881836,
      "Primary_wave_direction_surface": 94.48999786376953,
      "Significant_height_of_wind_waves_surface": null,
      "Mean_period_of_wind_waves_surface": 9.59000015258789,
      "Secondary_wave_mean_period_surface": null,
      "Significant_height_of_combined_wind_waves_and_swell_surface": 2.1500000953674316,
      "Secondary_wave_direction_surface": null
    }
  }, {
    "context": "reftime_time_lat_lon_ordered_sequence_of_data",
    "axes": {
      "latitude": 50.0,
      "reftime": "2016-04-24T12:00:00",
      "longitude": -49.99999999999997,
      "time": "2016-04-24T12:00:00",
      "iter_ordered_sequence_of_data": 0.0
    },
    "data": {
      "Direction_of_swell_waves_ordered_sequence_of_data": 148.16000366210938,
      "Mean_period_of_swell_waves_ordered_sequence_of_data": 9.539999961853027,
      "Significant_height_of_swell_waves_ordered_sequence_of_data": 0.9599999785423279
    }
  }]
}

Provides values for the specified dataset at a given point of interest. Points are expressed using longitude and latitude coordinates in decimal degrees.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}/point?lon={longitude}&lat={latitude}apikey={apikey}

HTTP QUERY PARAMETERS

lat required	Latitude in decimal degrees. North latitude is positive. 37.383252
lon required	Longitude in decimal degrees. East longitude is positive. -122.005152
z optional first	Altitude/depth axis. Is not defined by specific unit, instead allows to select "first", "last" or "all" altitude/depth data "layers" (all, first, last)
var optional	Name of the specific variable obtained via metadata query. water_temp
csv optional	Format the response as comma separated values (CSV). true
buffer optional 0	Search bounding box in decimal degrees. Data with coordinates within this buffer will be returned. 1.0
context optional	If multiple axes contexts are provided for a dataset, use context to limit which are returned. Multiple contexts can be passed using comma separation. All available contexts are returned by default. More details are in the Contexts API. main
count optional 1	The total number of results (data samples) to return. Single sample is identified by unique LonLat coordinate and timestamp. Variables from a single sample can be split into contexts. 100
offset optional 0	Offset the returned results by a specific count. 100
start optional	Sets a lower time boundary for dataset values. Return values at or after this timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. 2016-04-05T14:30:00Z
end optional	Sets an upper time boundary for dataset values. Return values at or before this timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. 2016-04-11T15:30:00Z
time_order optional asc	Orders samples in the API output by "time" dimension. desc
nearest optional true	If true, return data only from the point nearest the requested latitude and longitude. By default, this value is true and the nearest point is returned, however if a buffer value is passed, nearest will default to false. false
reftime_end optional	Return values at or before this reference timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. 2016-04-11T15:30:00Z
reftime_recent optional true	If true, returns the full forecast duration using values from the latest available reference time (e.g. most recent). If a partial forecast exists due to processing delays, values from the previous reference time are also included. If either reftime_start or reftime_end values are passed, reftime_recent will default to false. false
reftime_start optional	Return values at or after this reference timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. 2016-04-05T14:30Z
meta optional false	If true, display global metadata. true
entry_meta optional false	If true, display entry metadata. true
entry_lineage optional false	If true, display entry lineage. true
verbose optional false	If true, display all available metadata. true

RESPONSE

Response format is documented in a separate section — Data Values Output Format.

/datasets/{id}/area

Request values from the noaa_ww3_global_1.25x1d dataset at a specific point coordinate. Make sure to replace {apikey} with your own API key:

curl -g --request GET \
  --url 'http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/area?polygon=[[-94,26],[-94,23],[-96,23],[-96,26],[-94,26]]&apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/area"

querystring = {"polygon": "[[-94,26],[-94,23],[-96,23],[-96,26],[-94,26]]","apikey":"{apikey}"}

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/area',
  qs: { polygon: '[[-94,26],[-94,23],[-96,23],[-96,26],[-94,26]]', apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

apikey = '{apikey}'
dataset_id = 'noaa_ww3_global_1.25x1d'
api_root_url = 'http://api.planetos.com/v1/'

dataset_point_url = sprintf('%sdatasets/%s/area', api_root_url, dataset_id)
rest_data = webread(dataset_point_url, 'apikey', apikey, 'polygon', '[[-94,26],[-94,23],[-96,23],[-96,26],[-94,26]]')

The above command returns JSON structured like this:

{
  "stats": {
    "offset": 0,
    "count": 1
  },
  "entries": [{
    "context": "reftime_time_lat_lon",
    "axes": {
      "reftime": "2016-04-24T12:00:00",
      "time": "2016-04-24T12:00:00",
      "longitude": -49.99999999999997,
      "latitude": 50.0
    },
    "data": {
      "Wind_speed_surface": 4.409999847412109,
      "Wind_direction_from_which_blowing_surface": 171.86000061035156,
      "v-component_of_wind_surface": 4.360000133514404,
      "u-component_of_wind_surface": -0.6200000047683716,
      "Direction_of_wind_waves_surface": 98.7699966430664,
      "Primary_wave_mean_period_surface": 10.760000228881836,
      "Primary_wave_direction_surface": 94.48999786376953,
      "Significant_height_of_wind_waves_surface": null,
      "Mean_period_of_wind_waves_surface": 9.59000015258789,
      "Secondary_wave_mean_period_surface": null,
      "Significant_height_of_combined_wind_waves_and_swell_surface": 2.1500000953674316,
      "Secondary_wave_direction_surface": null
    }
  }, {
    "context": "reftime_time_lat_lon_ordered_sequence_of_data",
    "axes": {
      "latitude": 50.0,
      "reftime": "2016-04-24T12:00:00",
      "longitude": -49.99999999999997,
      "time": "2016-04-24T12:00:00",
      "iter_ordered_sequence_of_data": 0.0
    },
    "data": {
      "Direction_of_swell_waves_ordered_sequence_of_data": 148.16000366210938,
      "Mean_period_of_swell_waves_ordered_sequence_of_data": 9.539999961853027,
      "Significant_height_of_swell_waves_ordered_sequence_of_data": 0.9599999785423279
    }
  }]
}

Provides values for the specified dataset at a given area of interest. Area-based query output is a grid of Points which are expressed using longitude and latitude coordinates in decimal degrees.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}/area?polygon={polygon}&apikey={apikey}

HTTP QUERY PARAMETERS

Query parameters of /area endpoint are the same as for /point endpoint, except the lon and lat coordinates. Instead, /area uses polygon parameter.

polygon

required

Polygon defined by the list of Longitude-Latitude pairs.

[[-94,26],[-94,23],[-96,23],[-96,26],[-94,26]]

RESPONSE

Response format is documented in a separate section — Data Values Output Format.

/datasets/{id}/area (β)

Example API output with location-based grouping

{
  "data": {
    "Temperature_height_above_ground": [
      [271.0320129394531, 271.0119934082031, 270.97601318359375, 268.4639892578125],
      [271.7619934082031, 271.7699890136719, 271.7980041503906, 271.85400390625],
      [271.0320129394531, 271.0119934082031, 270.97601318359375, 268.4639892578125]
    ]
  },
  "indexAxes": [
    ["latitude", [57.1, 57.2, 57.3]],
    ["longitude", [22.0, 22.1, 22.2, 22.3]]
  ]
}

Example code showing how dimensions from the data and indexAxes attributes align

n = 0 # first row
# number of rows of values in data array should be the same as the number of values in the first "index axis"
len(sample['data']['Temperature_height_above_ground']) == len(sample['indexAxes'][0][1])
# number of values in row #n should be the same as the number of values in the second "index axis"
len(sample['data']['Temperature_height_above_ground'][n]) == len(sample['indexAxes'][1][1])

var n = 0 // first row
// number of rows of values in data array should be the same as the number of values in the first "index axis"
sample['data']['Temperature_height_above_ground'].length == sample['indexAxes'][0][1].length
// number of values in row #n should be the same as the number of values in the second "index axis"
sample['data']['Temperature_height_above_ground'][n].length == sample['indexAxes'][1][1].length

An experimental feature of /area API endpoint.

Allows to retrieve all values from the provided polygon and a single timestamp in one request without pagination.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}/area?polygon={polygon}&apikey={apikey}&grouping=location

HTTP QUERY PARAMETERS

A new experimental area-specific query parameter grouping renders the output of the single API sample as an array of arrays covering the whole dimension like LonLat.

The output of location-based grouping has additional attribute — indexAxes. It contains a list of tuples (pairs) of dimension name and dimension coordinates values.

grouping

optional, experimental

Group data values into a single sample using provided dimension. The only supported dimension, for now, is "location."


                      location

/datasets/{id}/stations

Request stations within the noaa_ndbc_stdmet_stations dataset. Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/datasets/noaa_ndbc_stdmet_stations/stations?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets/noaa_ndbc_stdmet_stations/stations"

querystring = {"apikey":"{apikey}"}

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/noaa_ndbc_stdmet_stations/stations',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "station": {
    "45017": {
      "TemporalExtentStart": "2011-08-08T21:00:00",
      "TemporalExtentEnd": "2011-09-05T02:00:00",
      "SpatialExtent": {
        "type": "Point",
        "coordinates": [-88.0, 42.0]
      }
    },
    "46252": {
      "TemporalExtentStart": "2014-10-01T20:35:00",
      "TemporalExtentEnd": "2015-12-03T17:05:00",
      "SpatialExtent": {
        "type": "Point",
        "coordinates": [-119.0, 34.0]
      }
    },
    "42390": {
      "TemporalExtentStart": "2012-10-01T00:30:00",
      "TemporalExtentEnd": "2016-06-20T22:30:00",
      "SpatialExtent": {
        "type": "Point",
        "coordinates": [-95.0, 26.0]
      }
    },
    "keca2": {
      "TemporalExtentStart": "2009-05-06T19:12:00",
      "TemporalExtentEnd": "2016-06-20T23:12:00",
      "SpatialExtent": {
        "type": "Point",
        "coordinates": [-132.0, 55.0]
      }
    },
    "bltm2": {
      "TemporalExtentStart": "2005-01-07T01:48:00",
      "TemporalExtentEnd": "2016-06-20T18:54:00",
      "SpatialExtent": {
        "type": "Point",
        "coordinates": [-77.0, 39.0]
      }
    }
  }
}

Get the list of stations within a dataset. Note that not all datasets contain stations.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}/stations?apikey={apikey}

RESPONSE

A JSON object where every key inside station structure is station identifier.

Station attributes like TemporalExtentStart, TemporalExtentEnd, SpatialExtent indicating spatial and temporal bounds of time-series data originated from the station.

/datasets/{id}/stations/{station_id}

Request values from station keca2 within the noaa_ndbc_stdmet_stations dataset. Make sure to replace {apikey} with your own API key:

export STATION_ID=keca2
curl --request GET \
  --url http://api.planetos.com/v1/datasets/noaa_ndbc_stdmet_stations/stations/$STATION_ID?apikey={apikey}

import requests
station_id = 'keca2'

url = "http://api.planetos.com/v1/datasets/noaa_ndbc_stdmet_stations/stations/%s" % (station_id)

querystring = {"apikey":"{apikey}"}

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");
var station_id = 'keca2';

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/noaa_ndbc_stdmet_stations/stations/' + station_id,
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "stats": {
    "offset": 0,
    "count": 1
  },
  "entries": [{
    "context": "time_latitude_longitude",
    "classifiers": {
      "station": "keca2"
    },
    "axes": {
      "time": "2014-01-01T00:00:00",
      "longitude": -131.625,
      "latitude": 55.33100128173828
    },
    "data": {
      "wave_height": null,
      "sea_surface_temperature": 6.599999904632568,
      "gust": 4.400000095367432,
      "wind_spd": 2.0,
      "water_level": null,
      "dewpt_temperature": null,
      "air_temperature": 7.199999809265137,
      "air_pressure": 1020.2999877929688,
      "wind_dir": 112.0,
      "average_wpd": null,
      "visibility": null,
      "dominant_wpd": null,
      "mean_wave_dir": null
    }
  }]
}

Get values for a station. Note that not all datasets contain stations.

HTTP Request

GET http://api.planetos.com/v1/datasets/{id}/stations/{station_id}?apikey={apikey}

HTTP Query Parameters

Accepts the same query parameters as the /point endpoint.

Response

Response format is similar to the /point endpoint.

/datasets/{id}/contexts

Request contexts of variables from noaa_ww3_global_1.25x1d dataset. Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/contexts?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/contexts"

querystring = {"apikey":"{apikey}"}

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/noaa_ww3_global_1.25x1d/contexts',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "contexts": [
    {
      "attributes": [],
      "contextKey": "reftime_time_lat_lon",
      "datasetKey": "noaa_ww3_global_1.25x1d",
      "dimensionKeys": [ "lat", "lon", "time" ],
      "referenceSystem": {
        "categoricalAxes": [],
        "numericalAxes": [],
        "scopes": [
          {
            "scopeSpecification": {
              "scopeModifiers": [],
              "scopeVariables": [ "reftime" ]
            },
            "scopeType": "reference_time"
          },
          {
            "scopeSpecification": {
              "scopeModifiers": [],
              "scopeVariables": [ "time" ]
            },
            "scopeType": "axis_t"
          },
          {
            "scopeSpecification": {
              "scopeModifiers": [ "latitude_longitude" ],
              "scopeVariables": [ "lat","lon" ]
            },
            "scopeType": "location"
          }
        ]
      },
      "variableKeys": [
        "Direction_of_wind_waves_surface",
        "Mean_period_of_wind_waves_surface",
        "Primary_wave_direction_surface",
        "Primary_wave_mean_period_surface",
        "Secondary_wave_direction_surface",
        "Secondary_wave_mean_period_surface",
        "Significant_height_of_combined_wind_waves_and_swell_surface",
        "Significant_height_of_wind_waves_surface",
        "Wind_direction_from_which_blowing_surface",
        "Wind_speed_surface",
        "u-component_of_wind_surface",
        "v-component_of_wind_surface",
        "lat",
        "lon",
        "reftime",
        "time"
      ]
    }
  ]
}

Get the list of contexts (groups) of dataset's variables.

Contexts of variables sounds like something abstract, but in simple terms, context is a group of variables sharing same dimension space.

Some datasets would have only single context, that means that all variables share the very same dimensions. Some datasets contain variables on different altitudes, so every combination of XYZ+time dimension would get its own context. Lon+Lat+Elevation-10m+Time and Lon+Lat+Elevation-90m+Time are pretty typical groups, sort of layers on different altitudes.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}/contexts?apikey={apikey}

RESPONSE

A JSON list of objects where every object represents a single context.

Contexts are machine-generated so they might look cryptic, that's why each context has details about dimensions it covers.

variableKeys — contains all variables grouped in the context.

dimensionKeys — contains names of variables that define dimensions.

referenceSystem.scopes — contains suggestion for dimension interpretations, like "scopeType": "axis_t" gives a hint that particular dimension is related to time axis. Here is a list of scope types supported right now: location, axis_t, axis_z, axis_radial_distance, reference_time, node, classifier, instance, iter. The most valuable scope types are the ones representing common dimensions location, axis_t, axis_z, reference_time, the rest are auxilary.

/datasets/{id}/variables

Request a list of all available variables from particular dataset.
Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables"

querystring = { "apikey": "{apikey}" }

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "variables": [
    {
      "variableKey": "Temperature_surface",
      "contextKey": "reftime_time_lat_lon",
      "variableType": "data",
      "dimensionKeys": ["time", "lat", "lon"],
      "attributes": [],
      "temporalCoverage": {
        "start": 1536872400000,
        "end": 1538373600000
      }
    },
    {
      "variableKey": "Precipitation_rate_surface_2_Hour_Average",
      "contextKey": "reftime_time1_lat_lon",
      "variableType": "data",
      "dimensionKeys": ["time1", "lat", "lon"],
      "attributes": [],
      "temporalCoverage": {
        "start": 1536890400000,
        "end": 1537408800000
      }
    }
  ]

}

A very simple query to list all available variables from a particular dataset.

Each variable has a variableKey for API requests and human-friendly long_name attribute in the list of attributes.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}/variables?apikey={apikey}

/datasets/{id}/variables/{variable}/timestamps

Request a list of all available timestamps from particular dataset and provided variable.
Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_hybrid/timestamps?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_hybrid/timestamps"

querystring = { "apikey": "{apikey}" }

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_hybrid/timestamps',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

["1482775200000", "1482775200000", "1482796800000", "1482796800000", "1482818400000", "1482818400000", "1482840000000", "1482840000000", "1482861600000", "1482861600000", "1482883200000", "1482904800000"]

A very simple query to list all available timestamps for particular dataset and variable.

Timestamps are in "epoch milliseconds."

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}/variables/{variable}/timestamps?apikey={apikey}

/datasets/{id}/variables/{variable}/preview

Request a data sample from particular dataset and variable covering full spatial resolution of the dataset for a single timestamp.
Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_hybrid/preview?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_hybrid/preview"

querystring = { "apikey": "{apikey}" }

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_hybrid/preview',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this (snipped is cut to fit):

{
    "timestamp": 1541268000000,
    "variableKey": "Temperature_hybrid",
    "metadata": {
        "unit": "K",
        "bbox": {
          "latMin": -89.45138549804688,
          "latMax": 89.76100158691406,
          "lonMin": -179.375,
          "lonMax": 180.0
        }
    },
    "lat": [80.0, 79.33, 78.66, 78.0, …, -78.0, -78.66, -79.33, -80.0],
    "values": [
        [null, null, null, null, null, null, -0.02711682595697867, -0.03409404990630811, …],
        [null, null, null, null, null, null, -0.060692500078029496, -0.058580634445273394, …],
        [null, null, null, null, -0.011209596925575731, -0.012524769932849181, -0.025995750416178534, …],
        [null, null, null, null, null, -0.02935991804472002, -0.00636995307786792, 0.002944547254725269, …],
        [-0.04303262674907531, -0.027542892698230785, -0.024892436973680928, -0.018868911062971692, …],
        [-0.011008735306573496, -0.009209316019202714, -0.010557913755058318, -0.0044006413503971985, …],
        [null, null, null, -0.009542706584614492, -0.010108897142034697, -0.015939873399166467, …],
        [null, null, null, null, null, null, 0.005938973218893649, -0.011210041432247124, …],
        [null, null, 0.09552701189844665, -0.01748571686550157, -0.04741710525163343, …],
        [null, -0.09562515519618932, -0.05986652267218364, -0.07228101183713344, …],
    ],
    "lon": [-180.0, -179.33, -178.66, -178.0, …, 177.33, 178.0, 178.66, 179.33]
}

Return an object with X/Y (Longitude/Lattitude) arrays and a two-dimensional array of data values for the provided combination of dataset ID and, its variable and timestamp.

Attributes to plot the data: lon for the X axis, lat for the Y axis, each row in the values array corresponds to a single value of lon and every item in every row corresponds to a value of lat.

HTTP REQUEST

GET http://api.planetos.com/v1/datasets/{id}/variables/{variable}/preview?apikey={apikey}

HTTP QUERY PARAMETERS

timestamp

optional

latest available

Data sampling request enables selection of particular timestamp. By default system automatically selects latest available timestamp.

1541268000000

API output format

Data Values Output Format

{
  "stats": {
    "timeMin": "2016-09-06T18:00:00",
    "count": 1,
    "offset": 0,
    "nextOffset": 1,
    "timeMax": "2016-09-22T18:00:00"
  },
  "entries": [{
    "context": "reftime_time_hybrid_lat_lon",
    "axes": {
      "latitude": 49.495601654052734,
      "reftime": "2016-09-06T18:00:00",
      "longitude": -50.507659912109375,
      "time": "2016-09-06T18:00:00",
      "z": 1.0
    },
    "data": {
      "Temperature_hybrid": 286.1189880371094
    }
  }]
}

Let's start with an API output example for the GFS forecast by taking one variable Temperature_hybrid from the list of 200+ variables. Use of single variable will make the example more readable.

Root elements are stats and entries. Stats just describes user's query. Usually, it duplicates query parameters (like count and start/end), but in case user omits the use of some query parameters this section shows defaults that were used.

Entries section is a list of data samples selected by API query. In the example above we use default count setting which is 1. So we have a single entry.

Every entry has assigned XY, optionally Z and two timestamp coordinates as a part of axes object. It is easy to notice that reftime is always same as time for observational datasets, unlike GFS in our example, which is forecast.

So reftime dimension is only useful for forecasts and some modelled datasets, where timestamp of dataset entry creation is different from the timestamp that dataset entry is describing.

Data section of every entry may contain more than one variable. It is possible to query all variables from any dataset by just omitting var parameter. Please take into account that variables are grouped by context. For more details about Contexts see the Contexts API.

Here is an example of annotated data sample.

Bulk data packaging (β)

A set of experimental API endpoints for packaging larger data requests in binary form (zipped NetCDF files) and asynchronously fetching them for offline workflow.

GET /packages

Request a list of previously submitted user's packages.
Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/packages?apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/packages"

querystring = { "apikey": "{apikey}" }

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/packages',
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "packageKeys": [
    "0d823a53-61b7-41a6-9ce4-31b03eee212e",
    "6f9ba790-ddb0-4db8-b0b6-53c96d954888",
    "c40fef32-8c71-4f10-a098-9e995e3a8a47"
  ]
}

A very simple query to list all of the previously submitted packages.

The output contains a plain list of package IDs, which could be used to check each package status and download if a package is successfully generated.

HTTP REQUEST

GET http://api.planetos.com/v1/packages?apikey={apikey}

PUT /packages

Submit area-based package request for noaa_ww3_global_1.25x1d dataset. Make sure to replace {apikey} with your own API key:

curl -g --request PUT \
  --url 'http://api.planetos.com/v1/packages?dataset=noaa_ww3_global_1.25x1d&polygon=[[-90,32],[-90,23],[-96,23],[-96,32],[-90,32]]&apikey={apikey}'

import requests

url = "http://api.planetos.com/v1/packages"

querystring = {
  "dataset": "noaa_ww3_global_1.25x1d",
  "polygon": "[[-90,32],[-90,23],[-96,23],[-96,32],[-90,32]]",
  "apikey": "{apikey}"
}

response = requests.request("PUT", url, params=querystring)

print(response.text)

var request = require("request");

var options = { method: 'PUT',
  url: 'http://api.planetos.com/v1/packages',
  qs: {
    dataset: 'noaa_ww3_global_1.25x1d',
    polygon: '[[-90,32],[-90,23],[-96,23],[-96,32],[-90,32]]',
    apikey: '{apikey}'
  },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

  {
    "packageKey": "0d823a53-61b7-41a6-9ce4-31b03eee212e",
    "packageSpec": {
      "queryFilter": {
        "datasetKey": "noaa_ww3_global_1.25x1d",
        "geometryFilter": {
          "geometry": {
            "type": "Polygon",
            "coordinates": [[[-90,32],[-90,23],[-96,23],[-96,32],[-90,32]]]
          },
          "type": "Arbitrary"
        },
        "zFilter": {
          "type": "FirstValue"
        }
      }
    }
  }

Submit area-based package creation request for bulk data download.

HTTP REQUEST

PUT http://api.planetos.com/v1/packages?dataset=noaa_ww3_global_1.25x1d&polygon=[[-90,32],[-90,23],[-96,23],[-96,32],[-90,32]]&apikey={apikey}

HTTP QUERY PARAMETERS

Query parameters of package creation API could be copied directly from the /area query. It is designed for the cases where synchronous /area query takes too long (for larger time spans or hi-res datasets).

dataset required	Dataset ID `noaa_hrrr_surface_hourly`
polygon required	Polygon defined by the list of Longitude-Latitude pairs. `[[-90,32],[-90,23],[-96,23],[-96,32],[-90,32]]`
package	Custom package ID. Instead of using auto generated UUIDs, it's possible to supply custom unique identifier for your package. `CentralEurope_temperature_2016`

RESPONSE

The output contains confirmation object with packageKey attribute, which can be used to poll packages creation status and download packaged data when it's ready.

GET /packages/`{id}`

Request package status by its ID.
Make sure to replace {apikey} with your own API key:

curl --request GET \
  --url 'http://api.planetos.com/v1/packages/{package_id}?apikey={apikey}'

import requests

package_id = '0d823a53-61b7-41a6-9ce4-31b03eee212e'  # example ID, please replace
url = "http://api.planetos.com/v1/packages/%s" % (package_id)

querystring = { "apikey": "{apikey}" }

response = requests.request("GET", url, params=querystring)

print(response.text)

var request = require("request");

var package_id= '0d823a53-61b7-41a6-9ce4-31b03eee212e'; // example ID, please replace

var options = { method: 'GET',
  url: 'http://api.planetos.com/v1/packages/' + package_id,
  qs: { apikey: '{apikey}' },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "packageSubmitted": true,
  "packageStatus": {
    "message": "success"
  },
  "packageResult": {
    "success": true
  }
}

An endpoint for querying submitted package creation status.

The output contains object that contains confirmation that package is in processing queue or successfully generated.

The main attribute for package generation completion is packageResult.success.

HTTP REQUEST

GET http://api.planetos.com/v1/packages/<package_id>?apikey={apikey}

GET /packages/`{id}`/data

curl --request GET -O \
  --url 'http://api.planetos.com/v1/packages/{package_id}/data?apikey={apikey}'

An endpoint for fetching zipped NetCDF files by package ID.

HTTP REQUEST

GET http://api.planetos.com/v1/packages/<package_id>/data?apikey={apikey}

API Console

API Console provides simple UI for building API query interactively. It has short descriptions of query parameters and output JSON schema. If the user enters his personal API key into an appropriate query field, API Console allows to execute that query and see results.

Rate Limits

API rate limits are dependent on your current plan. Free accounts are limited to 100 calls per day.

If you'd like to request a rate limit increase, please contact datahub@intertrust.com with more information on your needs.

Policies

By using the Planet OS REST API, you agree to our terms of service. Please take a moment to review the terms.

Datasets delivered via Planet OS data access interfaces may be subject to third party licenses that govern acceptable end-uses of the data. If you are unsure of a dataset's license or restrictions, we encourage you to contact the data publisher directly for clarification.

Planet OS reserves the right to suspend or terminate accounts that violate our policies. If you're a mindful and considerate developer, this shouldn't be an issue for you.

Examples

Jupyter Notebooks

We've published a collection of Jupyter notebooks on GitHub that provide API use case examples in Python. The notebooks are well-annotated so you can learn as you step through the commands.

The repository includes details on how to install Jupyter and the required Python modules, as well as tips to get you started.

Matlab Examples

We've published a point API example for Matlab and are looking for additional use cases and examples. If you're a Matlab user who's interested in providing code samples utilizing the Planet OS API, let's collaborate! Contact us for more information.

Point API JavaScript Wrapper

This interactive JavaScript demo allows you to select a point on a map and uses the Planet OS API to return GFS forecast data at that point.

The source code is available on GitHub and our Data Visualization Engineer provides detailed breakdown in Using the Planet OS REST API with Javascript.

Support

Supported Browsers

Chrome 48+
Internet Explorer 11+ (older versions are not supported by Microsoft)
Safari 8+
Firefox 40+

Slack Community

Join the Planet OS Slack Community to discuss new features, request datasets, and ask for help from Planet OS team members and other data enthusiasts.

Contact Us

Feedback, support requests, and other inquiries may be directed to datahub@intertrust.com.

Planet OS Product Guide

Datasets

Summary

Extent

Variables

Dimensions

License

Data Access

REST API

Limits

REST API (v1)

Authentication

Example of an Authenticated HTTP Request

Search & Discovery Endpoints

Dataset Search

HTTP REQUEST

HTTP QUERY PARAMETERS

RESPONSE

Search facet values

HTTP REQUEST

RESPONSE

Dataset Endpoints

/datasets

HTTP REQUEST

RESPONSE

/datasets/{id}

HTTP REQUEST

RESPONSE

/datasets/{id}/point

HTTP REQUEST

HTTP QUERY PARAMETERS

RESPONSE

/datasets/{id}/area

HTTP REQUEST

HTTP QUERY PARAMETERS

RESPONSE

/datasets/{id}/area (β)

HTTP REQUEST

HTTP QUERY PARAMETERS

/datasets/{id}/stations

HTTP REQUEST

RESPONSE

/datasets/{id}/stations/{station_id}

HTTP Request

HTTP Query Parameters

Response

/datasets/{id}/contexts

HTTP REQUEST

RESPONSE

/datasets/{id}/variables

HTTP REQUEST

/datasets/{id}/variables/{variable}/timestamps

HTTP REQUEST

/datasets/{id}/variables/{variable}/preview

HTTP REQUEST

HTTP QUERY PARAMETERS

API output format

Data Values Output Format

Bulk data packaging (β)

GET /packages

HTTP REQUEST

PUT /packages

HTTP REQUEST

HTTP QUERY PARAMETERS

RESPONSE

GET /packages/{id}

HTTP REQUEST

GET /packages/{id}/data

HTTP REQUEST

API Console

Rate Limits

Policies

Examples

Jupyter Notebooks

Matlab Examples

Point API JavaScript Wrapper

Support

Supported Browsers

Slack Community

Contact Us

GET /packages/`{id}`

GET /packages/`{id}`/data