Alaska Satellite FacilityAPI to Synthetic Aperture Radar Images
ASF has developed and deployed an Application Programming Interface (API) as an additional avenue to access our collection of Synthetic Aperture Radar images. The purpose of this API is to present users a flexible web service that facilitates the search for and visualization of ASF Synthetic Aperture Radar images, delivery of relevant metadata about those images, as well as facilitate the bulk delivery of those images, to the Synthetic Aperture Radar data user community.
The ASF API as a Search Tool
The access point for the ASF API is (http://api.daac.asf.alaska.edu/services/search/param). It should be noted that access through web browser navigation to this address will not produce a successful connection to the ASF API. Success with this address is achieved through the command line interface using utilities such as WGET or cURL.
Either WGET or cURL are more than adequate for accessing the ASF API. Both are often installed on Linux systems, cURL is part of the Mac OS and WGET can be installed. The MS-Windows OS does not come with either installed but both are available. You can read about some of the differences between WGET and cURL here and here. Both utilities are open-source and free.
The API can be used in numerous ways to process direct data requests. As a search tool, the ASF API processes requests received as HTTP GET or HTTP POST requests based upon the presently defined API keyword parameters. The available keywords are listed here with additional details below.
| Keyword | Definition | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| absoluteOrbit | For ALOS PALSAR this value corresponds to the path number. For ERS-1, ERS-2, and RADARSAT-1 this value corresponds to the orbit count within the orbit cycle. For UAVSAR it is the flight ID. | ||||||||||||||||||
| asfframe | This is an ASF / JAXA frame reference. See also 'frame'. Settings: Any number, series of numbers, or number range from 1 to 900 for ERS, RADARSAT, JERS. 0-7200 for ALOS PALSAR. |
||||||||||||||||||
| bbox | Deprecated. | ||||||||||||||||||
| beam | Deprecated. See 'beamMode'. | ||||||||||||||||||
| beamMode | The beam mode used to acquire the data. example: beamMode=FBS Settings:
|
||||||||||||||||||
| beamSwath | Beam Swath is specific sensor configuration for beam mode and look angle. example: beamSwath=43,PLR Settings:
|
||||||||||||||||||
| collectionName | For UAVSAR and AIRSAR data collections, limit searches by general location, site description, or data grouping as supplied by flight agency or project. example: collectionName=HAITI Settings: Uses a wildcard search, so you could search for "ICE" and get anything with ICE in its collection name. Only UA/AS. |
||||||||||||||||||
| direction | Deprecated. See 'flightDirection'. | ||||||||||||||||||
| flightDirection | Satellite orbit direction during data acquisition example: flightDirection=descending Settings: A, ASC, ASCENDING, D, DESC, DESCENDING |
||||||||||||||||||
| flightLine | Specify a flightline for UAVSAR or AIRSAR. example: flightLine=05901,flightLine=gilmorecreek045-1.93044 |
||||||||||||||||||
| format | Format of the API search results returned. If not specified, default return is metalink. See also 'output'. Settings: CSV, JSON, KML, METALINK |
||||||||||||||||||
| frame | Preferred frame range using ESA frame reference (even for ALOS PALSAR); specify individual frames, define the frame range, or use both in the same query. See also 'asfframe'. example: frame=300,310-350 Settings: Any number, series of numbers, or number range from 0 to 7200 |
||||||||||||||||||
| granule_list | Comma-separated list of specific granules. Large lists will need to utilize a POST request. note: specifying a granule list will cause most other keywords to be ignored example: granule_list=R1_12345_FN1_F001,R1_12345_FN1_F002 |
||||||||||||||||||
| intersectsWith | Accepts a list of polygons, line segments ("linestring"), or a point defined in multipoint 2-D Well-Known Text (WKT); currently each polygon must be explicitly closed, i.e. the first vertex and the last vertex of each listed polygon must be identical; coordinate pairs for each vertex are in decimal degrees of longitude followed by decimal degree of latitude. Examples: intersectsWith=multipolygon (((30 20, 10 40, 45 40, 30 20)),((15 5, 40 10, 10 20, 5 10, 15 5))) intersectsWith=polygon (( -119.543 37.925, -118.443 37.7421, -118.682 36.8525, -119.77 37.0352, -119.543 37.925 )) intersectsWith=linestring ( -119.543 37.925, -118.443 37.7421 ) intersectsWith=point ( -119.543 37.925 ) |
||||||||||||||||||
| limit | Maximum number of data records to return from your ASF API query. See also 'maxResults'. | ||||||||||||||||||
| lookAngle | Deprecated. See 'offNadirAngle'. | ||||||||||||||||||
| lookDirection | Left or right direction of data acquisition example: lookDirection=L Settings: R, RIGHT, L, LEFT |
||||||||||||||||||
| maxResults | Maximum number of data records to return from the ASF API or SSARA Federated API query. | ||||||||||||||||||
| orbit | Deprecated. See 'absoluteOrbit'. | ||||||||||||||||||
| offnadir | Deprecaed. See 'offNadirAngle'. | ||||||||||||||||||
| offNadirAngle | Off-nadir angles for ALOS PALSAR example: offNadirAngle=21.5 Settings: 21.5, 23.1, 27.1, 34.3, 41.5, 50.8 |
||||||||||||||||||
| output | Format of the API search results returned. If not specified, default return is metalink for ASF API or html for SSARA Federated API. MAP setting only valid for SSARA Federated API. Settings: CSV, JSON, KML, METALINK, MAP |
||||||||||||||||||
| path |
Deprecated. See 'relativeOrbit'. | ||||||||||||||||||
| platform | Remote sensing platform that acquired the data. example: platform=ALOS Settings: A3, AI, AS, E1, E2, ERS-1, ERS-2, J1, JERS-1, R1, UA, AIRMOSS, AIRSAR, ALOS, ERS-1, ERS-2, JERS-1, RADARSAT-1, UAVSAR |
||||||||||||||||||
| polarization | example: polarization=VV Settings:
|
||||||||||||||||||
| polygon | Bounding polygon in the digital lat/long format; enter coordinates in counter clockwise direction example: polygon=-155.08,65.82,-153.28,64.47,-149.94,64.55, -149.50,63.07,-153.5,61.91 | ||||||||||||||||||
| processing | Deprecated. See 'processingLevel'. | ||||||||||||||||||
| processingLevel | Processing level already performed on to the raw data. example: processingLevel=L0,L1 Settings:
|
||||||||||||||||||
| relativeOrbit | Path or track of satellite during data acquisition. For UAVSAR it is the flight line. example: relativeOrbit=500,550-580 Settings:
|
||||||||||||||||||
| start/end | Date of data acquisition; enter a start date, end date or both to form a valid range example: start=2010-10-30T11:59:59UTC\&end=1991-10-01T00:00:00UTC |
Development of additional parameters to refine queries to the API is ongoing, and in response to user’s needs. Please contact us if there is a specific parameter that would be useful in your search and visualization of the SDC holdings.
The ASF API as a Visualization Tool
The ASF API currently searches the contents of the pre-processed, directly downloadable, ASF datapool. The ASF API returns processed SAR data, csv files, and SAR browse imagery, the format being defined by the user. We have designed the API to surpass the limitations of 1000 item search, but have capped its capacity at 10,000 for manageability.
To get the API to return a .csv file of your preferred area of interest and the data available for it, you will need to add the parameter "&format=csv" to your code string. Below is an example query where the returns are in .csv format.
To have the API return a .kml file of your preferred area of interest, enter “&format=kml” as your format parameter in your code string. Below is an example query where the returns are in .kml format.
To have the API return a Metalink file of your preferred area of interest, enter “&format=metalink” as your format parameter in your code string. Below is an example query where the returns are in Metalink format.
The Metalink file is the default API return format. The Metalink file itself is in an xml type of format, and contains the specific URL information relevant to the data returned with the API query. Additional information about Metalink files in general can be found at the Metalinker webpage. Using Metalink files for the actual downloading of data has currently only been optimized for the download clients identified on the Bulk Download of the ASF Datapool page.
The ASF API as a Bulk Download Tool
The primary purpose of the ASF API is to deliver to users the specific ASF data pool data they desire in an efficient and accurate manner. All returns from the ASF API are collected in a Metalink file and delivered to the user. We recommend the aria2 download client for command line data returns from the ASF data pool. Additional information about the Metalink files, aria2 and additional download clients that support Metalink files can be found at the Bulk Download of the ASF Datapool page.
There are specific and general guidelines we have identified that the user needs to incorporate into their scripted ASF API requests.
Authentication requirements – To access the ASF datapool SAR data collection, you will need to be an approved and authenticatable user; i.e. an URSA account holder with a valid proposal on file. The ASF API authenticates against our internal system with a series of cookies which will need to be acquired every time one performs a batch download. Below are the required statements to obtain the cookies.
The above snippet will save your authentication cookie into a file called cookies.txt.
Simple Example of a Download Script Request to the ASF API:
# Get the authentication cookie.
print "Authenticating.\n";
`wget --save-cookies cookies.txt --post-data='user_name=CHANGE_ME&user_password=CHANGE_ME' --no-check-certificate https://ursa.asfdaac.alaska.edu/cgi-bin/login -o /dev/null -O /dev/null`;
print "Authenticated\n";
# Get the metalink file.
print "Fetching file list...\n";
`wget http://api.daac.asf.alaska.edu/services/search/param?polygon=-155.08,65.82,-153.28,64.47,-149.94,64.55,-149.50,63.07,-153.5,61.91\&platform=R1\&processing=L1 -o /dev/null -O downloads.metalink`;
print "Fetched file list\n";
# make a directory to save everything in.
print "Creating data directory\n";
mkdir('data');
print "Data directory created.\n";
print "Starting data download.\n";
# Download the data.
system('aria2c --summary-interval=10 -j 10 -d data --load-cookies=cookies.txt --auto-file-renaming=false --allow-overwrite=false -M downloads.metalink');
print "Download Completed.\n";
exit;
The Seamless Synthetic Aperture Radar Access (SSARA) Federated API
A beta federated data query and data product download capability from distributed airborne and spaceborne SAR archives at ASF and UNAVCO/WInSAR is now available. To interact with this beta federated querier please visit the Interactive API Tool for Accessing Synthetic Aperture Radar Data and select the "SSARA Federated API Query" tab. For more information regarding this joint venture please visit InSAR ACCESS.
If you have questions as to how best utilize the ASF API, please contact the ASF User Support.
Page last modified March 20, 2013.
