Skip to content
This repository has been archived by the owner on Jan 3, 2024. It is now read-only.

L2SS REST Interface Specification V1

Jump to bottom
Omkar edited this page Dec 4, 2016 · 11 revisions

L2SS REST Interface Specification V1

General

This document specifies the RESTful client-server interface for the HiTIDE application. Version 1.

Search Dataset

GET /l2ss-services/l2ss/dataset/search

Description: List available datasets. By default returns all available datasets.

Parameters:

Name Type Description
variable string Search for datasets with variable name. For multi-value input, this input can be used multiple times. Example: Sea Surface Temperature
sensor String Search for datasets with sensor. For multi-value input, this input can be used multiple times.
provider String Search for datasets with provider. For multi-value input, this input can be used multiple times.
startTime date Lower time bound. If not specified, lower time bound of the dataset will be used. Example: 2011-12-31T23:59:59-06:00Z
endTime date Upper time bound. If not specified, upper time bound of the dataset will be used. Example: 2019-12-31T23:59:59-06:00Z
datasetId string Search dataset belong to given PODAAC Dataset persistent ID
itemsPerPage int number of results to return.
startIndex int start index of result

Example

search for dataset metadata with podaac dataset id

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/dataset/search?datasetId=PODAAC-ASOP2-25X01

search for datasets which have variable Sea Surface Temperature or Surface Wind

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/dataset/search?variable=Sea%20Surface%20Temperature&variable=Surface%20Wind

Dataset Variable

GET /l2ss-services/l2ss/dataset/variable

Description: retrieves dataset configuration information including variables.

Parameters:

Name Type Description
datasetId string datasetId for the configuration information

Example

retrieve dataset configuration information for dataset with persistent id PODAAC-ASOP2-25X01

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/dataset/variable?datasetId=PODAAC-ASOP2-25X01

Search Granules

GET /l2ss-services/l2ss/granule/search

Description: Retrieve all base granule information (datasetId, start time, end time) matching the specified datasetId, date, and region. This approach may change if the data/querying turns out to be too expensive. Response is structured in a minimalistic way to cut down on the file size.

Parameters:

Name Type Description
datasetId string Search granules belong to given PODAAC Dataset persistent ID
bbox string Search granules with Bounding box Ex: [-180,-90,180,90] (w,s,e,n)
startTime date Lower time bound. If not specified, lower time bound of the granules will be used. Example: 2011-12-31T23:59:59-06:00Z
endTime date Upper time bound. If not specified, upper time bound of the granules will be used. Example: 2019-12-31T23:59:59-06:00Z
name string Search granules with exact name or name pattern using wildcard search Example: ascat* this matches name that starts with "ascat"
sort string Sort output. There are two strings delimited by space. The first string is the field name, and the second string is 'asc' or 'desc' Example: sort=Granule-Name asc
itemsPerPage int number of results to return.
startIndex int start index of result

Example

search for granules for dataset persistentId = PODAAC-ASOP2-25X01

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/granule/search?datasetId=PODAAC-ASOP2-25X01

search for granules for dataset persistentId = PODAAC-ASOP2-25X01 and granule name pattern 2015123 and sorted by Granule-StartTime.

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/granule/search?datasetId=PODAAC-ASOP2-25X01&name=*20150123*&sort=Granule-StartTime%20asc

Granules Availability

GET /l2ss-services/l2ss/granule/availability

Description: calculates granule counts per day or month from given date range.

Parameters:

Name Type Description
datasetId string Search granules belong to given PODAAC Dataset persistent ID
startTime date Lower time bound. If not specified, lower time bound of the granules will be used. Example: 2011-12-31T23:59:59-06:00Z
endTime date Upper time bound. If not specified, upper time bound of the granules will be used. Example: 2019-12-31T23:59:59-06:00Z
gap string The size of each date range expressed as an interval to be added to the lower bound. Example: "DAY", "MONTHS"
bbox string Search granules with Bounding box Example: [-180,-90,180,90] (w,s,e,n)

Example

calculate daily granule counts from 2014-10-12 11:42:00Z to 2016-10-12 11:42:00Z for dataset persistentId = PODAAC-ASOP2-25X01

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/granule/availability?datasetId=PODAAC-ASOP2-25X01&startTime=2014-10-12T11:42:00Z&endTime=2016-10-12T11:42:00Z&gap=DAY

calculate monthly granule counts from 2014-10-12 11:42:00Z to 2016-10-12 11:42:00Z for dataset persistentId = PODAAC-ASOP2-25X01

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/granule/availability?datasetId=PODAAC-ASOP2-25X01&startTime=2014-10-12T11:42:00Z&endTime=2016-10-12T11:42:00Z&gap=MONTHS

Granule Preview Image Service

GET /l2ss-services/l2ss/preview/[dataset Id]/[year]/[doy]/[granule name]/[variable].png

Description: returns thumbnail image of selected variable for selected granule.

Parameters:

Name Type Description
datasetId string Search granules belong to given PODAAC Dataset persistent ID
granule name string granule name
year int year in 4 digits
day int day of year in 3 digits.
variable id string Variable id described in dataset variable service

Note Granule search service returns root URL for the images such as follow

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/preview/PODAAC-ASOP2-25X01/2014/140/ascat_20140520_005700_metopa_39 344_eps_o_250_2300_ovw.l2.nc

and variable names can be found from dataset variable service. Both information can be used to form the URL.

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/preview/PODAAC-ASOP2-25X01/2014/140/ascat_20140520_005700_metopa_39
344_eps_o_250_2300_ovw.l2.nc/[variable].png

Example

Thumbnail image for dataset PODAAC-ASOP2-25X01, granule ascat_20140520_005700_metopa_39344_eps_o_250_2300_ovw.l2.nc and "variable wind_speed"

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/preview/PODAAC-ASOP2-25X01/2014/140/ascat_20140520_005700_metopa_39
344_eps_o_250_2300_ovw.l2.nc/wind_speed.png

Image Palette Service

GET /l2ss-services/l2ss/palettes/[palette name].json

Description: returns palette descriptor in json format

Example

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/palettes/paletteMedspirationIndexed.json

Granule Download Service

POST /l2ss-services/l2ss/subset/submit

Description: Submits a job to subset and download. Upon a successful request, token will be returned which can be used to check status.

Parameters:

Name Type Description
query string data collection query in json 
{
  "email":(email address),
  "query":
  [{
    "datasetId":(dataset id), "bbox":(bbox),
    "variables" : [(variable) , (variable) ],
    "granuleIds": [(granule id), (granule id), ...],
    "compact": false
   },
   {
    "datasetId":(dataset id),
    "bbox":(bbox),
    "variables" : [ (variable) , (variable) ],
    "dateRange": {
      "start":(start datetime in YYYY-MM-DDTHH:MM:SS),
      "end":(end datetime in YYYY-MM-DDTHH:MM:SS)
    },
    "granuleNamePattern":(name pattern),
    "compact" : true
   },
   .....
  ]
}

Output Example :

{"token": (token)}

Example query parameter

query={
  "email":"[email protected]",
  "query":
  [
    {
      "compact":true,
      "datasetId":"PODAAC-ASOP2-25X01",
      "bbox":"-180,-90,180,90",
      "variables" : ["lat" , "lon","time","wind_speed" ],
      "granuleIds": ["ascat_20140520_005700_metopa_39344_eps_o_250_2300_ovw.l2.nc","ascat_20140411_175700
_metopa_38800_eps_o_250_2300_ovw.l2.nc"]
    },
    {
      "compact":true,
      "datasetId":"PODAAC-ASOP2-25X01",
      "bbox":"-180,-90,180,90",
      "variables" : ["lat" , "lon","time","wind_speed" ],
      "dataRange":{"start":"2014-04-11T00:57:00", "end":"2014-04-12T05:57:00"},
      "granuleNamePattern":"ascat*"
    }
  ]
}

GET /l2ss-services/l2ss/subset/status

Description: check status on existing download job.

Parameters:

Name Type Description
token string job token. job token is provided when submitting the job.

Output Format :

{
  "totalNumGranule": total number of granules,
  "granuleCompleted": total number of granule processed including one that has error,
  "jobCreated": job created time,
  "resultURLs": [URL to result files],
  "errorCount": total number granules with error,
  "token": token,
  "status": status
}

Status possible values : queued, processing, partial error, done, error

note : partial error means done with some error. error means the whole process failed.

Output Example :

{
  "totalNumGranule": 66,
  "granuleCompleted": 66,
  "jobCreated": "2016-03-08T07:20:01",
  "resultURLs": ["http://podaac-tools.jpl.nasa.gov/cd989a60-713b-4489-93a8-f3f545081a1a/285c8c6e-76ce-478e-b334-00374b84ce1b.zip"],
  "errorCount": 1,
  "token": "cd989a60-713b-4489-93a8-f3f545081a1a",
  "status": "partial error"
}

Example

http://podaac-tools.jpl.nasa.gov/l2ss-services/l2ss/subset/status?token=fakeToken
Clone this wiki locally