USGS API¶
Examples¶
The where
parameter used for searching a USGS dataset is best understood by example.
from usgs import api
def submit_where_query():
# USGS uses numerical codes to identify queryable fields
# To see which fields are queryable for a specific dataset,
# send off a request to dataset-fields
fields = api.dataset_fields('LANDSAT_8', 'EE')
for field in fields:
print field
# WRS Path happens to have the field id 10036
where = {
10036: '043'
}
scenes = api.search('LANDSAT_8', 'EE', where=where, start_date='2015-04-01', end_date='2015-05-01', max_results=10, extended=True)
for scene in scenes:
print scene
-
usgs.api.
download
(dataset, node, entityids, product)[source]¶ Though USGS supports multiple products in a single request, there’s ambiguity in the returned list. This wrapper only allows a single product per request.
Additionally, the response has no indiction which URL is associated with which scene/entity id. The URL can be parsed, but the structure varies depending on the product.
-
usgs.api.
metadata
(dataset, node, sceneids, extended=False, api_key=None)[source]¶ Request metadata for a given scene in a USGS dataset.
Parameters: - dataset –
- node –
- sceneids –
- extended – Send a second request to the metadata url to get extended metadata on the scene.
- api_key –
-
usgs.api.
search
(dataset, node, lat=None, lng=None, distance=100, ll=None, ur=None, start_date=None, end_date=None, where=None, max_results=50000, starting_number=1, sort_order='DESC', extended=False, api_key=None)[source]¶ Parameters: - dataset – USGS dataset (e.g. EO1_HYP_PUB, LANDSAT_8)
- node – USGS node representing a dataset catalog (e.g. CWIC, EE, HDDS, LPVS)
- lat – Latitude
- lng – Longitude
- distance – Distance in meters used to for a radial search
- ll – Dictionary of longitude/latitude coordinates for the lower left corner of a bounding box search. e.g. { “longitude”: 0.0, “latitude”: 0.0 }
- ur – Dictionary of longitude/latitude coordinates for the upper right corner of a bounding box search. e.g. { “longitude”: 0.0, “latitude”: 0.0 }
- start_date – Start date for when a scene has been acquired
- end_date – End date for when a scene has been acquired
Where: Dictionary representing key/values for finer grained conditional queries. Only a subset of metadata fields are supported. Available fields depend on the value of dataset, and maybe be found by submitting a dataset_fields query.
Max_results: Maximum results returned by the server
Starting_number: Starting offset for results of a query.
Sort_order: Order in which results are sorted. Ascending or descending w.r.t the acquisition date.
Extended: Boolean flag. When true a subsequent query will be sent to the metadataUrl returned by the first query.
Api_key: API key for EROS. Not required for searching.
Todo
Export metadata from the search results e.g.
<numberReturned xsi:type=”xsd:int”>41</numberReturned> <totalHits xsi:type=”xsd:int”>41</totalHits> <firstRecord xsi:type=”xsd:int”>1</firstRecord> <lastRecord xsi:type=”xsd:int”>41</lastRecord> <nextRecord xsi:type=”xsd:int”>41</nextRecord>