3 Ordering Data API

Basic Order Creation

To create an order, POST a set of JSON data to

https://www.ngdc.noaa.gov/next-web/rest/orders

Ordering does not typically happen until after first querying catalog services to determine what data is available for a particular set of selection criteria. Once these criteria are established, the same criteria are then send along with additional ordering attributes as part of an order request. Thereafter, order status can be queried until the system indicates that an order is ready, at which time it can be retrieved from the specified URL.

An order consists of a list of items, each item being of a particular type of dataset (multibeam, trackline, dmsp, sounding...). The criteria and attributes that can or must be specified within each item will vary with datatype. Each item is essentially a map of these criteria and attributes that uses the keys available to that particular type of item.

An example of a the JSON data sent is shown below for a multibeam item.

{ "email":"sam.spade@noaa.gov",
  "items":[
    {"dataset":"Multibeam", "geometry": "geometry criteria"  }
  ]
}

This request should generate a prompt response acknowledging receipt of the order or indicating that there is a problem with the order. The 'status' shown will indicate whether or not the order has been completed. An example of such a JSON response is shown below.

{ "id":63,
  "dateCreated":"'2012-05-23 16:15:23.0'",
  "lastUpdated":"'2012-05-23 16:16:11.0'",
  "startTime":"'2012-05-23 16:15:38.0'",
  "endTime":"'2012-05-23 16:15:39.0'",
  "elapsedTime":1000,
  "status":"NOTIFIED",
  "datasetCount":1,
  "errorCount":0,
  "url":"'https://www.ngdc.noaa.gov/next-delivery/next1337811323154/next1337811323154.tar.gz'",
  "items":[
    {"dataset":"Multibeam","url":"'https://www.ngdc.noaa.gov/next-web/item?id=64'"}
  ]
}

Trackline ordering can be a bit more complicated than what is shown here, as a catalog request first identifies surveys associated with specified criteria, after which the order can be refined to a subset of the original request by specifying individual surveys (by surveyId) and ancillary file categories. Refer to the Trackline catalog page for details. If a geometry (bounding box) criterion is specified, then the points for all selected surveys are automatically clipped to the bounding box. Otherwise, all points are included from each selected survey.

3.1 Filtering Orders

Each data set and the criteria they support are listed below.

MGG Multibeam Bathymetric Data

1. time: supported by parameters startYear and endYear, to bound the time
2. bounding box (spatial): supported by a geometry parameter specified in the format minx,miny,maxx,maxy using decimal degrees.
3. ship: supported by a platforms parameter set to ship name (case-sensitive)
4. survey: supported by a surveys parameter set to survey name (case-sensitive)

MGG Trackline Data

XYZ ordering options, a zParam value should be specified when ordering XYZ data.

1. file format: supported by a format parameter. The value must be one of the following: M77T, XYZ.
2. survey name(s): supported by a survey parameter. May include multiple survey names in a comma-delimited list.
3. survey type(s): supported by a surveyType parameter. The following values are recognized:… May include multiple survey types in a comma-delimited list.
4. platform(s): supported by a platform parameter, for name of ship, vessel, iceberg, etc. May include multiple platform names in a comma-delimited list.
5. institution(s): supported by an institution parameter. May include multiple institution names in a comma-delimited list.
6. start year: supported by a startYear parameter. Must be a four digit year.
7. end year: supported by an endYear parameter. Must be a four digit year.
8. date added: The date range in which the survey was added to the dataset. Supported by a firstDateAdded parameter and lastDateAdded parameter. The value should be a date string in one of the following formats: yyyy '-' MM ['-' dd] OR yyyy '-' DDD.
9. bounding box (spatial): supported by a geometry parameter specified in the format minx,miny,maxx,maxy using decimal degrees.
10. NGDC file name: supported by a useNGDCId parameter whose value is either true or false

STP Ionospheric Data

1. time: supported by parameters obsStartTime and obsEndTime to bound the observation time of a file in the results
2. bounding box (spatial): supported by a geometry parameter specified in the format minx,miny,maxx,maxy using decimal degrees.
3. station: supported by specifying a stationName parameter, e.g. "BC840"

STP DMSP Data

1. time: supported by parameters orbitStartTime and orbitEndTime to bound the observation time of a file in the results
2. satellite: supported by specifying a satellite name, e.g. F10, F11, F18...
3. coverage point (spatial): supported by geometry set to a longitude,latitude in decimal degrees

STP DSCOVR Data

1. satellite: specify a satellite name from which data originated (e.g. DSCOVR)
2. processing environment: select data from particular processing environments with the processEnvs parameter. Multiple values are comma-separated.
3. data types: select particular types of data files with the dataTypes parameter. Multiple values are comma-separated.
4. time data were collected: from dataStartTime to dataEndTime. Use ISO 8601 date/time format (e.g. yyyy-MM-dd T HH:mm Z).
5. time data were processed: from processStartTime to processEndTime. Use ISO 8601 date/time format (e.g. yyyy-MM-dd T HH:mm Z).

Archived Data

1. trackingIds: specify a comma-separated list of tracking Ids (each a sequence of hex digits of the form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

3.2 Example Orders in JSON

More examples of JSON data to create orders:

In general the search criteria such as geometry and stationName are optional, but their careful use will prevent selecting too much data.

Mixed data types in a single order

Example POST: Ionospheric and Multibeam data in the same order

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset":"Multibeam", "geometry": "geometry criteria"  }
    {"dataset":"Ionosphere", "geometry": "geometry criteria" , "stationName": "BC840"  }
  ]
}

Example POST: Multibeam and Sounding (NOS) data in the same order

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset":"Multibeam", "ship": "Robert Conrad" , "survey": "RC2605" },
    {"dataset":"Sounding", "geometry": "-40,-40,10,10" , "startYear": "2010" , "endYear": "2011" }
  ]
}

The Bounding box latitude-longitude parameter (indicated as "geometry") is a string composed of four floating point numbers in the order of "minX, minY, maxX, maxY" (or "minLon, minLat, maxLon, maxLat" )

Example POST: Time Constrained Multibeam Request

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset":"Multibeam", "geometry": "geometry criteria" , "startYear": "2010" , "endYear": "2010" }
  ]
}

Example POST: Multibeam Request by ship and survey

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset":"Multibeam", "ship": "Robert Conrad" , "survey": "RC2605" }
  ]
}

Example POST: Time Constrained Ionospheric Request

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset":"Ionosphere", "geometry": "geometry criteria" , "startTime": "02-DEC-10" , "endTime": "01-DEC-10" }
  ]
}

Example POST: Time Constrained Trackline Request

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset": "Trackline", "survey": "RC2014,BOMEXDI", "geometry": "-40,-40,10,10" , "startYear": "2010" , "endYear": "2011" , "format": "M77T" }
  ]
}

Example POST: Time Constrained Dscovr Request

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset": "Dscovr", "dataStartTime": "2015-12-29T00:00Z" ,"dataEndTime": "2015-12-31T00:00Z"  }
  ]
}

Example POST: processEnvs and dataTypes Constrained Dscovr Request

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset": "Dscovr", "processEnvs": "oe" ,"dataTypes": "vc0"  }
  ]
}

Example POST: trackingIds Constrained Archive Request

{ "email":"somebody@noaa.gov",
  "items":[
    {"dataset": "Archive", "trackingIds": "9753f7db-d162-4957-b180-1f812e82263a,a3a84536-9c07-4c58-91a8-d0325a8a33d3" }
  ]
}