NAV Navbar
Planetos logo
cURL Python NodeJS Matlab
  • Planet OS Product Guide
  • Datasets
  • Data Access
  • REST API (v1)
  • Examples
  • Support
  • 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

    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_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 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.

    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.

    API Output 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}

    Experimental Web endpoints (α)

    A set of experimental API endpoints for making OpenDAP protocol more accessible for web applications.

    GET /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/v1a/datasets/noaa_gfs_global_sflux_0.12d/variables?apikey={apikey}'
    
    import requests
    
    url = "http://api.planetos.com/v1a/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/v1a/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:

    {
      "noaa_gfs_global_sflux_0.12d": [
        {
          "longName": "Temperature @ Ground or water surface",
          "name": "Temperature_surface"
        },
        {
          "longName": "Ground Heat Flux @ Ground or water surface",
          "name": "Ground_Heat_Flux_surface"
        },
        {
          "longName": "Downward Long-Wave Rad. Flux @ Ground or water surface",
          "name": "Downward_Long-Wave_Radp_Flux_surface"
        },
        {
          "longName": "Downward Short-Wave Radiation Flux @ Ground or water surface",
          "name": "Downward_Short-Wave_Radiation_Flux_surface"
        }
      ]
    }
    

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

    Each variable has a name for API requests and human-friendly longName for using in UI or data visualizations.

    HTTP REQUEST

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

    GET /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/v1a/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_surface/timestamps?apikey={apikey}'
    
    import requests
    
    url = "http://api.planetos.com/v1a/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_surface/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/v1a/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_surface/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/v1a/datasets/{id}/variables/{variable}/timestamps?apikey={apikey}

    GET /variables/{variable}/timestamps/{timestamp}/data

    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/v1a/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_surface/timestamps/1482904800000/data?apikey={apikey}'
    
    import requests
    
    url = "http://api.planetos.com/v1a/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_surface/timestamps/1482904800000/data"
    
    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/v1a/datasets/noaa_gfs_global_sflux_0.12d/variables/Temperature_surface/timestamps/1482904800000/data',
      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):

    {
        "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],
        "metadata": {
            "timestamp": "1480982400000",
            "opendapQuery": "http://thredds.planetos.com/thredds/dodsC/…",
            "unit": "meter/sec",
            "bbox": {
                "latMax": -80.0,
                "lonMin": -180.0,
                "lonMax": 179.33333333333331,
                "latMin": 80.0
            }
        }
    }
    

    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/v1a/datasets/{id}/variables/{variable}/timestamps/{timestamp}/data?apikey={apikey}

    HTTP QUERY PARAMETERS

    horizontal_sampling_maxpoints
    optional
    1000
    Horizontal sampling setting defines desired maximum number of samples on Longitude axis. Default is 1000. To disable sampling and use original data resolution use false string value.
    false

    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.

    API Console

    API Console

    API Console

    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.

    API Matlab example

    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.

    JavaScript demo

    Support

    Supported Browsers

    Slack Community

    PlanetOS 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.