HyP3 API


Username
API Key



Documentation



Authentication


All HyP3 API calls require a username and an api_key, default is to include them both. For functions with a format parameter either 'json' or 'csv' are accepted (default is json). To call a function using this web interface, find it in the list below and click the 'pin' button.


Disable/Enable API Key


You can disable and re enable your API key as long as you have logged in first. While your API key is disabled it cannot be used to make requests.
4079487172 308-658-9993

Login


The api_key is acquired by logging in through earthdata. After logging in through earthdata you will be given an api_key which is required along with your username.


Reset Api Key


After the earthdata login is complete, you can reset your api_key as long as you are logged in. The old api_key will be invalid and a new one will be provided. Endpoint is /reset_api_key


Parameters:

  • Required:default
  • Optional:id, status, sub_id, granule, format

Description:

Returns a JSON or CSV array of job information with the specified attributes.


Return Dictionary:

id, sub_id, user_id, process_id, status, granule, granule_url, other_granules, other_granule_urls, request_time, processed_time, priority, message

Parameters:

  • Required:default
  • Optional:job_id, process_id, status, sub_id, granule, format

Description:

Return a JSON dictionary of time series job information with the specified attributes and the granules of those time series jobs


Return Dictionary:

id, sub_id, user_id, process_id, status, granule granule_url, other_granules, other_granule_urls, request_time, processed_time, priority, message, granules

Parameters:

  • Required:default
  • Optional:id, sub_id, sub_ids, creation_date, group_id, group_ids, process_id, start_date, end_date, page, page_size, format

Description:

Returns a JSON or CSV array of product information with the specified attributes. (start_date, end_date) specify a range of creation_date's.


Return Dictionary:

id, sub_id, name, url, browse_url, browse_thumbnail, browse_geo_image, browse_geo_xml, process_id, size, creation_date, group_ids

Parameters:

  • Required:default, group_id
  • Optional:page, format

Description:

Returns a JSON or CSV array of products from the given public group.


Return Dictionary:

id, sub_id, name, url, browse_url, browse_thumbnail, browse_geo_image, browse_geo_xml, process_id, size, page_size, creation_date, group_ids

Parameters:

  • Required:default, id
  • Optional:format

Description:

Returns a JSON dictionary or CSV array containing information about the requested process.


Return Dictionary:

id, name, description, requires_pair, supports_time_series_processing, requires_dual_pol

Parameters:

  • Required:default
  • Optional:format

Description:

Returns a JSON or CSV array of all available processes. Each entry is as described by get_process.


Return Dictionary:

id, name, description, requires_pair, supports_time_series_processing, requires_dual_pol

Parameters:

  • Required:default
  • Optional:id, name, format

Description:

Returns a JSON or CSV array of group information with the specified attributes.


Return Dictionary:

id, name, description, subscription_ids, users

Parameters:

  • Required:default
  • Optional:id, name

Description:

Returns a JSON or CSV array of groups for the given public group.


Return Dictionary:

id, name, description, subscription_ids, users

Parameters:

  • Required:default
  • Optional:id, process_id, name, location, start_date, end_date, enabled, group_id, format

Description:

Returns a JSON or CSV array of subscription information with the specified attributes.


Return Dictionary:

id, process_id, user_id, name, location, start_date, end_date, enabled, group_ids

Parameters:

  • Required:default, group_id
  • Optional:format

Description:

Returns a JSON or CSV array of subscriptions from the given public group.


Return Dictionary:

id, process_id, user_id, name, location, start_date, end_date, enabled, group_ids

Parameters:

  • Required:default, granule, process_id
  • Optional:priority, message, other_granules

Description:

Schedules a new processing request and returns a JSON dictionary indicating whether or not the request succeeded, and an error message. If the process_id specifies a process that requires a granule pair, then other_granules must also be supplied.


Return Dictionary:

status, (message or id)

Parameters:

  • Required:default
  • Optional:none

Schedules multiple processing requests as described by an input file. The file is uploaded through a POST parameter called 'file'. It can either be in JSON or a CSV format, the endpoint will interpret it according to its extension.

Each item in the file can have the following parameters:

  • process_id, priority, message, granule, other_granule

Parameter requirements are the same as for one_time_process. Here are some example files:

process_id, granule, priority
2, S1_GRANULE, 10
8, S1_GRANULE, 20

or

{[{
    "process_id": 2,
    "granule": "S1_GRANULE",
    "priority": 10
},
{
    "process_id": 8,
    "granule": "S1_GRANULE",
    "priority": 20
}]}

Return Dictionary:

status, (message or id)

Parameters:

  • Required:default, name
  • Optional:description

Description:

Creates a new subscription group. Returns a JSON dictionary indicating that the request succeeded, or an error message


Return Dictionary:

status, id

Parameters:

  • Required:default, id
  • Optional:name, description, add_subs, rem_subs, add_users, rem_users, icon, is_public

Description:

Sets the values of name, description, subscriptions and/or users. add_subs and rem_subs must be passed as a list of sub_id's. add_users and rem_users must be passed as a list of usernames. The icon attribute is a text field, but is not fully implemented yet. It will likely represent a font-awesome identifier.


Return Dictionary:

status, message

Parameters:

  • Required:default, crop_to_selection (bool), name, process_id, platform, location
  • Optional:polarization, start_date, end_date, description, extra_arguments, enabled (bool default is True), group_id

Description:

Schedules a new subscription and returns a JSON dictionary indicating whether or not the request succeeded, as well as an error message in the event of failure. note: If crop_to_selection is false any granules overlapping your location will be fully processed and sent; if true, you will only be sent the portions of the granules overlapping your location.


Return Dictionary:

status, id

Parameters:

  • Required:default, id
  • Optional:none

Description:

Sets the property 'enabled' of a subscription to False. No further actions will be taken based on this subscription until it is enabled again. Returns a JSON dictionary.


Return Dictionary:

status, message

Parameters:

  • Required:default, id
  • Optional:none

Description:

Sets the property 'enabled' of a subscription to True. The subscription will be treated as active from then on, until it is disabled once again. Returns a JSON dictionary.


Return Dictionary:

status, message

Parameters:

  • Required:default, id
  • Optional:project_id, name, description, end_date

Description:

Sets the values of name, description, and/or end_date for the subscription with given id


Return Dictionary:

status, message

Parameters:

  • Required:default, process_id, granule_list
  • Optional:priority, message

Description:

Creates a time series process using the granule stack provided, returning a JSON dictionary indicating the success of the request


Return Dictionary:

job_info, successful_granules, unsuccessful_granules

Parameters:

  • Required:default, process_id, latitude, longitude
  • Optional:priority, message

Description:

Creates a time series process using the granule stack generated via a CMR query with the provided latitude, and longitude, return a JSON dictionary indicating the success of the request


Return Dictionary:

ascending_job_info, ascending_granules, descending_job_info, descending_granules, failed_ascending_granules, failed_descending_granules

Parameters:

  • Required:default, latitude, longitude
  • Optional:none

Finds a viable ascending and descending stack of granules for the given coordinates. This runs the same CMR query as time_series_from_lat_lon but only returns the granule list instead of starting the time series process. These resulting lists can be submitted to time_series_from_list to create a valid time series.


Return Dictionary:

ascending, descending