Package `ftep_api`

Utility module to make using F-TEP REST API easier to use from Python scripts.

Version 0.0.16 (5.9.2023)

Python requirements: requests, requests_toolbelt, clint. Install F-TEP REST API with

pip install ftep_api-0.0.16-py3-none-any.whl

An example:

import ftep_api as ftep
api = ftep.FtepApi(user,pw)
try:
  # See what services are available
  print(api.getServices())

  # Get a description of the service's inputs and outputs
  print(api.describeService('VegetationIndices'))

  # Prepare service inputs
  # inputDict should be a dict of list of strings, with the key being the 
  # input name defined in the service description. 
  #
  # A single-valued parameter can be given in the dict as such, the value 
  # will be converted to a list with a single string value with str if needed. 
  # Multi-valued parameters have to be specified as lists in the dict.
  inputDict = {
    'inputfile':'sentinel2:///S2A_MSIL1C_20190428T095031_N0207_R079_T35VLF_20190428T115403',
    'vegIndex':'NDVI',
    'targetResolution':10
  }

  # Launch the job
  (jobId, jobStatus, outputs) = api.launchAndWaitForJob('VegetationIndices', inputDict)

  # do something with the outputs
  print(jobId)
  print(jobStatus)
  print(outputs)
  ...
except (ftep.FtepError,ValueError) as e:
  print(e)

Sub-modules

ftep_api.data
ftep_api.error

Classes

class AuthenticationError (message=None)

Class for exceptions when F-TEP authentication has failed.

Ancestors

FtepError
builtins.Exception
builtins.BaseException

class EodataObject (json)

Class for holding the metadata of a satellite image.

Methods

def getEodataPath(self): Returns the /eodata path of the file. This path is used when the image is accessed directly from the file system and not via the F-TEP service input mechanism.
def getFtepUri(self): Returns the F-TEP URI of the file. This URI is used when the image is used as a service input.
def getName(self): Returns the name of the object.

class FtepApi (user, password)

Class for managing F-TEP REST API functionality.

Logs in to the F-TEP platform.

Raises AuthenticationError if the login does not succeed.

Ancestors

ftep_api.base.FtepBase

Methods

def addUsersToGroup(self, users, groupId)

Adds the array of F-TEP user URLs (in the format https://f-tep.com/secure/api/v2.0/users/NN, where NN is the ID number of the user) to the given group if they are not in the group already.

Raises WebResponseError if query fails (e.g. the group was not found).

def cancelJob(self, jobID)

Cancels the job if it is queued (i.e. in status CREATED).

Raises ValueError in case of invalid parameters. Raises WebResponseError at unexpected responses.

def deleteFile(self, fileId)

Deletes the given file from F-TEP. Note that this does not check whether the file is in use!

Raises WebResponseError at unexpected responses.

def describeService(self, serviceName)

Returns a readable description of a service, or None if the service was not found.

Raises WebResponseError at unexpected responses.

def downloadFile(self, fileId, outputDir=None, printInfo=True, printWarning=True)

Downloads the given file from F-TEP. Uses the original name of the file. The output directory can be specified with outputDir.

printInfo and printWarning can be set to False to remove printing messages to standard output.

Returns the full path of the downloaded file, or raises FtepDataError if download fails.

def downloadUrl(self, fileUrl, outputFile, printInfo=True, printWarning=True)

Downloads the resources from the given URL from F-TEP. Uses the original name of the file. The output directory can be specified with outputDir.

printInfo and printWarning can be set to False to remove printing messages to standard output.

Returns the full path of the downloaded file, or raises FtepDataError if download fails.

def findDataBasketIdByName(self, dataBasketName)

Returns the data basket ID for the given name, or None if the basket was not found.

Raises WebResponseError if query fails.

def findGroupIdByName(self, groupName)

Returns the group ID for the given groupName, or None if the group was not found.

Raises WebResponseError if query fails.

def getFtepFileFromId(self, fileId)

Return the FtepFile for the given file ID.

def getFtepFileFromName(self, fileName)

Return a list of FtepFile instances that match the given file name.

def getFtepFileFromUri(self, fileUri)

Return the FtepFile for the given file URI.

def getFtepFiles(self, types=['OUTPUT_PRODUCT', 'REFERENCE_DATA'])

Returns the OUTPUT_PRODUCT and REFERENCE_DATA files as a list of FtepFile instances.

types is a list of OUTPUT_PRODUCT, REFERENCE_DATA or EXTERNAL_PRODUCT.

Returns None if there were processing errors, an empty list if no files were found but processing successful.

Raises ValueError at invalid types specification. Raises WebResponseError at unexpected responses.

def getFtepFilesForUser(self, userId, types=['OUTPUT_PRODUCT', 'REFERENCE_DATA'])

Returns the OUTPUT_PRODUCT and REFERENCE_DATA files as a list of FtepFile instances.

types is a list of OUTPUT_PRODUCT, REFERENCE_DATA or EXTERNAL_PRODUCT.

Returns None if there were processing errors, an empty list if no files were found but processing successful.

Raises ValueError at invalid types specification. Raises WebResponseError at unexpected responses.

def getGroupSharesForFile(self, fileId)

Returns the groups the file is shared with as a list of FtepGroupShare instances.

Raises WebResponseError at unexpected responses.

def getGroupSharesForService(self, serviceId)

Returns the groups the service is shared with as a list of FtepGroupShare instances.

Raises WebResponseError at unexpected responses.

def getGroupSharesForServices(self)

Returns the services as a list of FtepObject instances with the group share information set.

Returns None if there were processing errors, an empty list if no services were found but processing successful.

Raises WebResponseError at unexpected responses.

def getGroups(self)

Returns the group names as a list of FtepObject instances.

Returns None if there were processing errors, an empty list if no groups were found but processing successful.

Raises WebResponseError at unexpected responses.

def getJobConfigJson(self, jobID)

Returns the job config data as JSON.

Raises WebResponseError at unexpected responses.

def getJobJson(self, jobID)

Returns the job data as JSON.

Raises WebResponseError at unexpected responses.

def getJobLogJson(self, jobID)

Returns the job log as JSON.

Raises WebResponseError at unexpected responses.

def getJobOutputs(self, jobID)

Returns the job outputs as a dict of lists of FtepFile instances.

Raises WebResponseError at unexpected responses.

def getJobStatus(self, jobID)

Get the job status string (CREATED, RUNNING, COMPLETED, ERROR, CANCELLED).

Raises ValueError in case of invalid parameters. Raises WebResponseError at unexpected responses.

def getServiceId(self, serviceName)

Returns the id number of the service, or None if the service was not found.

Raises WebResponseError at unexpected responses.

def getServiceJson(self, serviceName)

Returns the service description as JSON, or None if the service was not found.

Raises WebResponseError at unexpected responses.

def getServices(self)

Returns the services as a list of FtepObject instances.

Returns None if there were processing errors, an empty list if no services were found but processing successful.

Raises WebResponseError at unexpected responses.

def launchAndWaitForJob(self, serviceName, inputs, interval_s=10, max_wait_s=None)

Launches the given service with the given inputs, waits for job completion and returns a tuple (jobId, jobStatus, outputs).

Raises ValueError in case of invalid parameters. Raises WebResponseError at unexpected responses.

def launchJob(self, serviceName, inputs)

Creates a Job Configuration object and launches the job. Returns job ID.

Inputs should be a dict of list of strings, with the key being the input name defined in the service description. The values will be converted to lists of string with str if needed.

Raises ValueError if inputs do not meet the restrictions in the service specification.

Raises WebResponseError at unexpected responses.

def listGroupUsers(self, groupId)

Returns an array of F-TEP user URLs (in the format https://f-tep.com/secure/api/v2.0/users/NN, where NN is the ID number of the user) for the given group.

Raises WebResponseError if query fails (e.g. the group was not found).

def searchSatelliteData(self, mission, startTime=None, endTime=None, aoi=None, identifier=None, processingLevel=None, platform=None, productType=None, maxCloudCover=None, orbitDirection=None, maxresults=500)

Returns the images as a list of EodataObject instances.

Arguments:

mission – One of sentinel1, sentinel2, sentinel3, landsat
startTime – Query start time, e.g. 2021-07-14T00:00:00.000Z
endTime – Query end time, e.g. 2021-10-14T23:59:59.999Z
aoi – A polygon WKT, e.g. POLYGON((24.43359375 63.27318217465046,24.43359375 60.37042901631506,38.320312499999986 60.37042901631506,38.320312499999986 63.27318217465046,24.43359375 63.27318217465046))
identifier – Product identifier string
processingLevel – Product processing level. Options are mission and platform specific:
sentinel1: 1,2
sentinel2: 1C, 2A
sentinel3: 1, 2
landsat/Landsat-5: 1G, 1T
landsat/Landsat-7: 1G, 1T, 1GT
landsat/Landsat-8: 1G, 1T, 1GT
platform – One of Landsat-5, Landsat-7, Landsat-8. Only for mission landsat.
productType – One of GRD, SLC, OCN, RAW. Only for mission sentinel1.
maxCloudCover – An integer in the range [0,100]. Only for missions sentinel2 and landsat.
orbitDirection – Either ASCENDING or DESCENDING. Only for missions sentinel1 and sentinel3.
maxresults – Maximum number of returned images.

Returns None if there were processing errors, an empty list if no images were found but processing successful.

Raises WebResponseError at unexpected responses.

def shareFile(self, fileId, groupName, groupPermission='READ')

Share the file with the given group.

groupPermission is one of READ, WRITE, ADMIN

Raises ValueError if group is not found. Raises WebResponseError is sharing fails.

def shareService(self, serviceName, groupName, groupPermission='SERVICE_USER')

Share the service with the given group.

groupPermission is one of SERVICE_USER, SERVICE_READONLY_DEVELOPER, SERVICE_DEVELOPER, SERVICE_OPERATOR. Default is SERVICE_USER.

Raises ValueError if service is not found. Raises ValueError if group is not found. Raises WebResponseError is sharing fails.

def terminateJob(self, jobID)

Stops the job if it running or cancels the job if it is queued.

Raises ValueError in case of invalid parameters. Raises WebResponseError at unexpected responses.

def terminateSystematicProcessing(self, systematicID, stopJobs=True)

Terminate the systematic processing which cancels all its queued subjobs. By default stops all its subjobs that are RUNNING.

Raises ValueError in case of invalid parameters. Raises WebResponseError at unexpected responses.

def uploadFile(self, filepath, wkt=None, filetype='OTHER')

Uploads the local file to F-TEP. Returns the FtepFile instance.

File type options are GEOTIFF, SHAPEFILE and OTHER.

File type GEOTIFF is automatically detected from .tif suffix. Wkt is detected automatically.

Shapefiles must be uploaded as a single zip file with filetype SHAPEFILE. Wkt is detected automatically.

For other file types use filetype OTHER and specify wkt geometry as a closed longitude-latitude polygon string, e.g.
POLYGON((lon1 lat1, lon2 lat2, lon3 lat3, lon4 lat4, lon1 lat1))

Usage example:

myFtepFile = api.uploadFile("/tmp/data.csv", wkt="POLYGON((20 60, 30 60, 30 70, 20 70, 20 60))", filetype="OTHER")
print(myFtepFile.getUri())

Raises ValueError if invalid input file. Raises WebResponseError if upload fails.

def waitForJob(self, jobID, interval_s=10, max_wait_s=None)

Wait for the execution of a job. Returns the status of the job.

Raises ValueError in case of invalid parameters. Raises WebResponseError at unexpected responses.

class FtepDataError (message)

Class for exceptions when retrieved F-TEP data is not what expected.

Ancestors

FtepError
builtins.Exception
builtins.BaseException

class FtepError (*args, **kwargs)

Ancestors

builtins.Exception
builtins.BaseException

Subclasses

class FtepFile (fileId, uri, url)

Class for holding the ID, F-TEP URI and HTTP URL of a file.

Methods

def getFileId(self): Returns the ID of the file. This ID is used when sharing files with shareFile function.
def getUri(self): Returns the F-TEP URI of the file. This URI is used when files are specified as inputs to services.
def getUrl(self): Returns the HTTP URL of the file. This URL is used when the file is queried through the REST API. To downloaded a file append /dl to the returned URL.

class FtepGroupShare (groupId, name, permission)

Class for holding F-TEP group ID, name and permission level information.

Methods

def getGroupId(self): Returns the ID of the group.
def getName(self): Returns the name of the group.
def getPermission(self): Returns the permission level (READ, WRITE, ADMIN).

class FtepObject (objectType, objectId, name, description, url)

Class for holding the ID, name, description and HTTP URL of a F-TEP service or group.

Methods

def getDescription(self): Returns the description of the object.
def getGroupShares(self)
def getId(self): Returns the ID of the object.
def getName(self): Returns the name of the object.
def getUrl(self): Returns the HTTP URL of the file. This URL is used when the object is queried through the REST API.
def setGroupShares(self, groupShares)

class WebResponseError (message, response, expected_code)

Class for exceptions when http call response is not as expected.

Ancestors

FtepError
builtins.Exception
builtins.BaseException