auscophub.saraclient¶
Functions for interface to the SARA client API.
These routines can be used to build client-side applications for searching and downloading data.
The most obvious way to use these routines is as follows:
urlOpener = saraclient.makeUrlOpener()
sentinel = 2
paramList = ['startDate=2017-05-01', 'completionDate=2017-05-31']
results = saraclient.searchSara(urlOpener, sentinel, paramList)
This would return a list of multi-level dictionary objects created from the JSON output of the server, one for each matching zipfile. The paramList can be any of the parameters which the SARA API accepts, these are passed straight through to the API.
The default SARA server is hard-wired in this module. However, the server name, and the protocol to be used, can both be over-ridden using the following environment variables
AUSCOPHUB_SARA_PROTOCOL (default https)AUSCOPHUB_SARA_SERVERHOST (default copernicus.nci.org.au)
-
exception
auscophub.saraclient.SaraClientError¶
-
auscophub.saraclient.getFeatAttr(feature, localName)¶ Given a feature dictionary as returned by the SARA API, and the local name for some attribute of interest, this function knows how to navigate through the feature structures to find the relevant attribute.
The main reason for this function is to give a simple, flat namespace, without requiring that other parts of the code decompose the multi-level structure of the feature objects.
Note that the local names are NOT the same as the names in the feature structure, but are simple local names used unambiguously. Only a subset of attributes are handled.
-
auscophub.saraclient.getRemoteFilename(downloadUrl, proxy)¶ Given the SARA download URL, ask the server what the actual filename is.
At the moment, this uses “curl -I” to do the work, but I would much prefer to do this directly in Python. In theory this should be possible, but I can’t get the authentication to work. When I do, I will change this code, and thus may require extra arguments. I also suspect that the re-directs which the SARA server does will cause me trouble, but I have yet to get to that point.
In the meantime, this is slow, but at least it works.
I am a bit unsure about this approach……
-
auscophub.saraclient.makeQueryUrl(sentinelNumber, paramList)¶ Return a full URL for the query defined by the given parameters
-
auscophub.saraclient.makeUrlOpener(proxy=None)¶ Use the crazy urllib2 routines to make a thing which can open a URL, with proxy handling if required. Return an opener object, which is used as:
reader = opener.open(url)
-
auscophub.saraclient.readJsonUrl(urlOpener, url)¶ Read the contents of the given URL, returning the object created from the JSON which the server returns
-
auscophub.saraclient.searchSara(urlOpener, sentinelNumber, paramList)¶ Search the GA/NCI SARA Resto API, according to a set of parameter name/value pairs, as given in paramList. The names and values are those allowed by the API, as described at
Each name/value pair is added to a HTTP GET URL as a separate name=value string, separated by ‘&’, creating a single query.
The overall effect of multiple name/value pairs is that each one further restricts the results, in other words they are being AND-ed together. Note that this is not because of the ‘&’ in the constructed URL, that is just the URL separator character. This means that there is no mechanism for doing an OR of multiple search conditions.
If sentinelNumber is None, then all Sentinels are searched, using the “all collections” URL of the API. I am not sure how useful that might be.
Parameters: - urlOpener – Object as created by the makeUrlOpener() function
- sentinelNumber (int) – an integer (i.e. 1, 2 or 3), identifying which Sentinel family
- paramList (list) – List of name=value strings, corresponding to the query parameters defined by the SARA API.
Returns: The return value is a list of the matching datasets. Each entry is a feature object, as given by the JSON output of the SARA API. This list is built up from multiple queries, because the server pages its output, so the list is just the feature objects, without all the stuff which would be repeated per page.
-
auscophub.saraclient.simplifyFullFeature(feature)¶ Given a full feature object as returned by the server (a GeoJSON-compliant object), extract just the few interesting pieces, and return a single dictionary of them. The names are ones I made up, and do not comply with any particular standards or anything. They are intended purely for internal use within this software.