eodms_rapi package

eodms_rapi.eodms module

class eodms_rapi.eodms.EODMSRAPI(username, password, show_timestamp=True)[source]

Bases: object

The EODMSRAPI Class containing the methods for the eodms_rapi

cancel_orderItem(orderId, itemId)[source]
cancel_order_item(order_id, item_id)[source]

Removes an Order Item from the EODMS using the RAPI.

Parameters:
  • order_id (int or str) – The Order ID of the Order Item to remove.

  • item_id (int or str) – The Order Item ID of the Order Item to remove.

Returns:

Returns the contents of the Delete request (always empty).

Return type:

byte str

clear_results()[source]

Clears the cumulative results.

Returns:

n/a

create_destination(dest_type, dest_name, **kwargs)[source]

Create a new destination using the given dest_type and dest_name.

Parameters:
  • dest_type (str) – The destination type, either “FTP” or “Physical”.

  • dest_name (str) – The destination name

  • kwargs

Options for FTP:

hostname: The fully qualified domain name of the target FTP server. username: The username used to log in to the target FTP server. password: The password used to log in to the target FTP server. string_val: A readable string representation of the whole object, typically “ftp://{user}@{host}/{path}” path: After logging in to the FTP server, change directory to this path (optional; default is the root directory) can_edit: “true” if the currently connected user is allowed to modify the properties of this Order Destination object (server to client only)

Options for Physical:

customerName: The name of the customer who will receive the order (required). contactEmail: An email address that can be used to contact the customer if necessary (required). organization: The names of any organization and organizational units necessary to identify the delivery location (optional). phone: A phone number that can be used to contact the customer if necessary (optional). addrs: A list of physical delivery addresses (1 address is required, a maximum of 3). city: The city or other community of the physical delivery address (required). stateProv: The name or code identifying the state or other administrative region required for the physical delivery address (required for most countries). country: The name of the country to which the product is to be delivered (required). postalCode: Any code that is necessary for the postal system to successfully deliver the product (required for many countries). classification: This is the security classification of the physical address (optional).

delete_destination(dest_type, dest_name)[source]

Deletes a specific destination using the dest_type and dest_name.

Parameters:
  • dest_type (str) – The destination type, either “FTP” or “Physical”.

  • dest_name (str) – The destination name

download(items, dest, wait=10.0, max_attempts=None, show_progress=True)[source]

Downloads a list of order items from the EODMS RAPI.

Parameters:
  • items (list or dict) –

    A list of order items returned from the RAPI.

    Example:

    {'items': [
        {'recordId': '8023427',
         'status': 'SUBMITTED',
         'collectionId': 'RCMImageProducts',
         'itemId': '346204',
         'orderId': '50975'},
    ...]}
    

    or

    [{
        'recordId': '8023427',
        'status': 'SUBMITTED',
        'collectionId': 'RCMImageProducts',
        'itemId': '346204',
        'orderId': '50975'
    }, ...]
    

  • dest (str) – The local download folder location.

  • wait (float or int) – Sets the time to wait before checking the status of all orders.

  • max_attempts (int) – The number of download attempts before stopping downloads. If None, the script will continue to check and download orders until all orders have been downloaded.

  • show_progress – Determines whether to show progress while

downloading an image :type show_progress: bool

Returns:

A list of the download (completed) items.

Return type:

list

download_image(url, dest_fn, fsize, show_progress=True)[source]

Given a list of remote and local items, download the remote data if it is not already found locally.

(Adapted from the eodms-api-client ( https://pypi.org/project/eodms-api-client/) developed by Mike Brady)

Parameters:
  • url (str) – The download URL of the image.

  • dest_fn (str) – The local destination filename for the download.

  • fsize (int) – The total filesize of the image.

  • show_progress – Determines whether to show progress while

downloading an image :type show_progress: bool

edit_destination(dest_type, dest_name, **kwargs)[source]

Edits an existing destination using the given dest_type and dest_name

Parameters:
  • dest_type (str) – The destination type, either “FTP” or “Physical”.

  • dest_name (str) – The destination name

  • kwargs

Options for FTP:

hostname: The fully qualified domain name of the target FTP server. username: The username used to log in to the target FTP server. password: The password used to log in to the target FTP server. string_val: A readable string representation of the whole object, typically “ftp://{user}@{host}/{path}” path: After logging in to the FTP server, change directory to this path (optional; default is the root directory) can_edit: “true” if the currently connected user is allowed to modify the properties of this Order Destination object (server to client only)

Options for Physical:

customerName: The name of the customer who will receive the order (required). contactEmail: An email address that can be used to contact the customer if necessary (required). organization: The names of any organization and organizational units necessary to identify the delivery location (optional). phone: A phone number that can be used to contact the customer if necessary (optional). addrs: A list of physical delivery addresses (1 address is required, a maximum of 3). city: The city or other community of the physical delivery address (required). stateProv: The name or code identifying the state or other administrative region required for the physical delivery address (required for most countries). country: The name of the country to which the product is to be delivered (required). postalCode: Any code that is necessary for the postal system to successfully deliver the product (required for many countries). classification: This is the security classification of the physical address (optional).

get_availableFields(collection=None, name_type='all')[source]
get_available_fields(collection=None, name_type='all', ui_fields=False)[source]

Gets a dictionary of available fields for a collection from the RAPI.

Parameters:
  • collection (str) – The Collection ID.

  • name_type (str) – The field name type to search for.

  • ui_fields – Determines whether to return fields that the

EODMS UI website uses. :type ui_fields: bool

Returns:

A dictionary containing the available fields for the given collection.

Return type:

dict

get_collection_id(coll)[source]
Gets the full collection ID using the input collection ID which can be a

substring of the collection ID.

Parameters:

coll (str) – The collection ID to check.

Returns:

The full collection ID.

Return type:

str

get_collections(as_list=False, opt='id', redo=False)[source]

Gets a list of available collections for the current user.

Parameters:
  • as_list (bool) – Determines the type of return. If False, a dictionary will be returned. If True, only a list of collection IDs will be returned.

  • opt (str) – Determines whether the list of collections should be just titles or both titles and ids.

  • redo (bool) – Determines whether to get the list from the RAPI again.

Returns:

Either a dictionary of collections or a list of collection IDs depending on the value of as_list.

Return type:

dict

get_conv(field)[source]

Converts a field name into the set naming convention (self.name_conv).

Parameters:

field (str) – The field name.

Returns:

The field name with the proper naming convention (‘words’,

‘upper’ or ‘camel’). :rtype: str

get_err_msg()[source]

Gets the error message of this class after an error occurred.

Returns:

The error message

Return type:

str

get_fieldChoices(collection, field=None)[source]
get_field_choices(collection, field=None, full=False)[source]

Gets the available choices for a specified field. If no choices exist, then the data type is returned.

Parameters:
  • collection (str) – The collection containing the field.

  • field (str) – The field name or field ID.

Returns:

Either a list of choices or a string containing the data type.

Return type:

list or str

get_msg()[source]

Gets the latest self.msg

Returns:

The self.msg

Return type:

str

get_order(order_id)[source]

Gets an specified order from the EODMS RAPI.

Parameters:

order_id (str or int) – The Order ID of the specific order.

Returns:

A JSON dictionary of the specific order.

Return type:

dict

get_orderItem(itemId)[source]
get_orderParameters(collection, recordId)[source]
get_order_item(item_id)[source]

Submits a query to the EODMS RAPI to get a specific order item.

Parameters:

item_id (str or int) – The Order Item ID of the image to retrieve from the RAPI.

Returns:

A dictionary containing the JSON format of the results from the RAPI.

Return type:

dict

get_order_parameters(collection, record_id)[source]

Gets the list of available Order parameters for a given image record.

Parameters:
  • collection (str) – The Collection ID for the query.

  • record_id (int or str) – The Record ID for the image.

Returns:

A JSON dictionary of the order parameters.

Return type:

dict

get_orders(order_res=None, dtstart=None, dtend=None, max_orders=100, status=None, out_format='json')[source]

Sends a query to retrieve orders from the RAPI.

Parameters:
  • order_res (list) – The results from an order submission. If this value is included, dtstart, dtend and max_orders will be ignored.

  • dtstart (datetime.datetime) – The start date for the date range of the query.

  • dtend (datetime.datetime) – The end date for the date range of the query.

  • max_orders (int) – The maximum number of orders to retrieve.

  • status (str) – The status of the orders to retrieve.

  • out_format (str) – The format of the results.

Returns:

A JSON dictionary of the query results containing the orders.

Return type:

dict

get_ordersByRecords(records)[source]
get_orders_by_records(records)[source]

Gets a list of orders from the RAPI based on a list of records.

Parameters:

records (list) – A list of records used to get the list of orders.

Returns:

A list of results from the RAPI.

Return type:

list

get_rapiUrl()[source]
get_rapi_url()[source]

Gets the previous URL used to query the RAPI.

return: The RAPI URL. rtype: str

get_record(collection, record_id, output='full')[source]

Gets an image record from the RAPI.

Parameters:
  • collection (str) – The Collection ID of the record.

  • record_id (str or int) – The Record ID of the image.

  • output (str) – The format of the results (either ‘full’, ‘raw’ or ‘geojson’).

get_results(form='raw', show_progress=True)[source]

Gets the self.results in a given format

Parameters:
  • form (str) –

    The type of format to return.

    Available options:

    • raw: Returns the JSON results straight from the RAPI.

    • brief: Returns the JSON results with the ‘raw’ metadata but

      in the field convention.

    • full: Returns a JSON with full metadata information.

    • geojson: Returns a FeatureCollection of the results

      (requires geojson package).

  • show_progress – Determines whether to show progress while

fetching metadata :type show_progress: bool

Returns:

A dictionary of the results from self.results variable.

Return type:

dict

is_json(my_json)[source]

Checks to see in the input item is in JSON format.

Parameters:

my_json (str) – A string value from the requests results.

Returns:

True if a valid JSON format, False if not.

Return type:

boolean

log_msg(messages, msg_type='info', log_indent='', out_indent='')[source]

Logs a message to the logger.

Parameters:
  • messages (str or list) – Either a single message or a list of messages to log.

  • msg_type (str) – The type of log (‘debug’, ‘info’, ‘warning’, ‘error’, etc.)

  • log_indent (str) – The amount of indentation for the log. (ex: ‘ ‘).

  • out_indent (str) – The amount of indentation for the printout. (ex: ‘ ‘).

order(results, priority='Medium', parameters=None, destinations=None)[source]

Sends an order to EODMS using the RAPI.

Parameters:
  • results (list) –

    A list of JSON results from the RAPI.

    The results list must contain a collectionId key and a

    recordId key for each image.

  • priority (str or list) –

    Determines the priority of the order.

    If you’d like to specify a separate priority for each image, pass a list of dictionaries containing the recordId (matching the IDs in results) and priority, such as:

    [{"recordId": 7627902, "priority": "Low"}, ...]
    

    Priority options: “Low”, “Medium”, “High” or “Urgent”

  • parameters (list) –

    Either a list of parameters or a list of record

    items.

    Use the get_order_parameters method to get a list of available

    parameters.

    Parameter list: [{"|internalName|": "|value|"}, ...]

    Example:

    [
        {"packagingFormat": "TARGZ"},
        {"NOTIFICATION_EMAIL_ADDRESS":
            "kevin.ballantyne@canada.ca"},
    ...]
    
    Parameters for each record: ``[{“recordId”: |recordId|,

    ”parameters”: [{”|internalName|”: “|value|”}, …]}]``

    Example:

    [
        {"recordId": 7627902,
         "parameters": [{"packagingFormat": "TARGZ"},
            ...]}
    ]
    

  • destinations (list) – A JSON representation of an array of order destinations

parse_metadata(image_res)[source]

Parses the metadata results from the RAPI for better JSON.

Parameters:

image_res (dict) – A dictionary of a single record from the RAPI.

print_message(msg)[source]
print_results(results=None)[source]

Pretty prints the specified results.

Parameters:

results (dict) – A JSON of results from the RAPI.

remove_duplicate_orders(orders)[source]

Removes any duplicate images from a list of orders

Parameters:

orders (list) – A list of orders.

Returns:

A unique list of orders

Return type:

list

reset()[source]

Resets specific values for the EODMSRAPI.

Returns:

n/a

retrieve_destinations(collection=None, record_id=None)[source]

Retrieves a list of order destinations for the current profile.

Parameters:
  • collection (str) – The Collection Id. If this value is set, then the record_id must be set as well.

  • record_id – The Record Id for a specific image. If this value is set, then the collection must be set as well.

search(collection, filters=None, features=None, dates=None, result_fields=None, max_results=None)[source]

Sends a search to the RAPI to search for image results.

Parameters:
  • collection (str) – The Collection ID for the query.

  • filters (dict) –

    A dictionary of query filters and values in the following format:

    {"|filter title|": ("|operator|", ["value1", "value2", ...]), ...}

    Example:

    {"Beam Mnemonic": {'=': []}}
    

  • features (list) –

    A list of tuples containing the operator and filenames or coordinates of features to use in the search. The features can be:

    • a filename (ESRI Shapefile, KML, GML or GeoJSON)

    • a WKT format string

    • the ‘geometry’ entry from a GeoJSON Feature

    • a list of coordinates (ex: [(x1, y1), (x2, y2), ...])

  • dates (list) –

    A list of date range dictionaries with keys start and end. The values of the start and end can either be a string in format yyyymmdd_hhmmss or a datetime.datetime object.

    Example:

    [{"start": "20201013_120000", "end": "20201013_150000"}]
    

  • result_fields (str) – A name of a field to include in the query results.

  • max_results (str or int) – The maximum number of results to return from the query.

search_url(url, **kwargs)[source]

Submits a URL to the RAPI.

Parameters:
  • url (str) – A valid RAPI URL (with or without the path)

  • kwargs (dict) –

    Options include:<br> filters (dict): A dictionary of filters and values for the

    RAPI.<br>

    features (list): A list of geometries for the query.<br> dates (list): A list of date range dictionaries containing keys

    ’start’ and ‘end’.<br>

set_attempts(number)[source]

Sets number of attempts to be made to the RAPI before the script ends.

Parameters:

number (int) – The value for the number of attempts.

set_fieldConvention(convention)[source]
set_field_convention(convention)[source]

Sets the naming convention of the output fields.

Parameters:

convention (str) –

The type of naming convention for the fields.

  • words: The label with spaces and words will be returned.

  • camel (default): The format will be lower camel case like

’camelCase’. - upper: The format will be all uppercase with underscore for spaces.

set_orderTimeout(timeout)[source]
set_order_timeout(timeout)[source]

Sets the timeout limit for an order to the RAPI.

Parameters:

timeout (float) – The value of the timeout in seconds.

set_queryTimeout(timeout)[source]
set_query_timeout(timeout)[source]

Sets the timeout limit for a query to the RAPI.

Parameters:

timeout (float) – The value of the timeout in seconds.

set_root_url(url)[source]

Sets the root URL of the RAPI.

Parameters:

url (str) – The new URL.

class eodms_rapi.eodms.QueryError(msgs)[source]

Bases: object

The QueryError class is used to store error information for a query.

get_msgs(as_str=False)[source]

Gets the messages stored with the QueryError.

Parameters:

as_str – Determines whether to return a string or a list of

messages. :type as_str: boolean

Returns:

Either a string or a list of messages.

Return type:

str or list

eodms_rapi.geo module

class eodms_rapi.geo.EODMSGeo(eodmsrapi=None)[source]

Bases: object

The Geo class contains all the methods and functions used to perform geographic processes mainly using OGR.

add_geom(in_src)[source]

Processes the source and converts it for use in the RAPI.

Parameters:

in_src (str) –

The in_src can either be:

  • a filename (ESRI Shapefile, KML, GML or GeoJSON) of multiple

features - a WKT format string of a single feature - the ‘geometry’ entry from a GeoJSON Feature - a list of coordinates (ex: [(x1, y1), (x2, y2), ...])

Returns:

A string of the WKT of the feature.

Return type:

str

convert_coords(coord_lst, geom_type)[source]

Converts a list of points to GeoJSON format.

Parameters:
  • coord_lst (list) – A list of points.

  • geom_type (str) – The type of geometry, either ‘Point’, ‘LineString’ or ‘Polygon’.

Returns:

A dictionary in the GeoJSON format.

Return type:

dict

convert_imageGeom(coords, output='array')[source]
convert_image_geom(coords, output='array')[source]

Converts a list of coordinates from the RAPI to a polygon geometry, array of points or as WKT.

Parameters:
  • coords (list) – A list of coordinates from the RAPI results.

  • output (str) – The type of return, can be ‘array’, ‘wkt’ or ‘geom’.

Returns:

Either a polygon geometry, WKT or array of points.

Return type:

multiple types

convert_toGeoJSON(results, output='FeatureCollection')[source]
convert_toWKT(in_feat, in_type)[source]
convert_to_geojson(results, output='FeatureCollection')[source]

Converts RAPI results to GeoJSON geometries.

Parameters:
  • results (list) – A list of results from the RAPI.

  • output (str) – The output of the results (either ‘FeatureCollection’ or ‘list’ for a list of features in geojson)

Returns:

A dictionary of a GeoJSON FeatureCollection.

Return type:

dict

convert_to_wkt(in_feat, in_type)[source]

Converts a feature into WKT format.

Parameters:
  • in_feat (dict or list) – The input feature, either as a GeoJSON dictionary or list of points.

  • in_type (str) – The type of the input, whether it’s ‘json’, ‘list’ or ‘file’.

Returns:

The input feature converted to WKT.

Return type:

str

get_features(in_src)[source]

Extracts the features from an AOI file.

Parameters:

in_src (str) – The input filename of the AOI file. Can either be a GML, KML, GeoJSON, or Shapefile.

Returns:

The AOI in WKT format.

Return type:

str

process_polygon(geom, t_crs)[source]