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}
HTTP QUERY PARAMETERS
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.
Search facet values
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
andindexAxes
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 thenoaa_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.