API User Guide

API Basics

The chart below is a beginner’s guide to using an API.

 
 Using the ASF API — Overview
Build an API command: Program+URL+keywords
For more details, see Build API Command
Command
Selections Notes
1) Choose a program

Choose a command-line program to transfer data using a URL

Choose cURL or WGET

Construct command at the command line

2) Use the ASF API URL

https://api.daac.asf.alaska.edu/services/search/param? 
3) Choose
Keywords
Define your search using keywords such as asfframe, absoluteOrbit, output. Choose keyword output‘s value based on intended use. See below.See the keyword list
Download, search or visualize — by including the appropriate Output  keyword value in the API command
For more details, see Search and Download.
UsesOutput Keyword Values
Helpful Software
SearchCSVExcel
 JSONCustom script, JSON viewer
 COUNT 
 VisualizeKMLGoogle Earth
 GEOJSON

Custom script, JSON viewer

 DownloadMETALINK (default)aria2 required
 JSON

Custom script, direct download of URLs

 DOWNLOAD

Custom script, direct download of URLs

Note: A research agreement is required for access to JERS-1 and RADARSAT-1 data. Please complete the required Research Agreement, or contact user support at the link or number below.

Quick Guide for Power Users

API URL: https://api.daac.asf.alaska.edu/services/search/param?keyword=value\&…

Keywords: See here for a full list of keywords.

Output: Default output format is METALINK; users can also specify CSV, KML, JSON, COUNT, DOWNLOAD, and GEOJSON.

Authenticate* and Download: Linux/Mac Examples

Aria2 — Download Known Granule
    aria2c –http-auth-challenge=true –http-user=CHANGE_ME –http-passwd=’CHANGE_ME’ “https://api.daac.asf.alaska.edu/services/search/param?granule_list=S1A_EW_GRDM_1SDH_20151003T040339_20151003T040443_007983_00B2A6_DDE4&output=metalink”
Aria2 — Download Based on Platform and Time-Range Search
 aria2c –http-auth-challenge=true –http-user=CHANGE_ME –http-passwd=’CHANGE_ME’ “https://api.daac.asf.alaska.edu/services/search/param?platform=Sentinel-1A&intersectsWith=point(-122.425 37.77)&start=2016-07-01T00:00:00&output=metalink”
Wget — Download Known Metalink
 wget -c –http-user=CHANGE_ME –http-password=’CHANGE_ME’ “https://datapool.asf.alaska.edu/GRD_MD/SA/S1A_EW_GRDM_1SDH_20151003T040339_20151003T040443_007983_00B2A6_DDE4.zip”

*Use Earthdata username and password

Search, Visualize, Download

The API can be used to search, visualize, or download SAR data from the ASF data pool depending on the choice of ‘output’ keyword value. The default output is METALINK, which is useful for downloading data.

Search and Visualize

  Searches can be done with CSV or JSON output. Note that CSV returns many more fields than JSON. Users may visualize data with KML files and Google Earth. The API will return a maximum of 10,000 results for a given search.

     Search and Visualize via browser
A non-command-line option is to visualize your results by pasting the URL and keywords into a browser. You’ll need to have Google Earth or another program installed. You can also do CSV, JSON, or METALINK searches via the browser and get a file returned. If you do this, use ‘&’ instead of ‘\&’. This is a great option if you are not scripting, or for smaller searches.

API Uses and Output Keywords
UsesOutput Values
Helpful Software
SearchCSVExcel
 JSONCustom script, JSON viewer
CountCOUNTCommand line
VisualizeKMLBrowser, Google Earth
 GEOJSONhttp://geojson.io
DownloadMETALINK (default)aria2 required
 DOWNLOADPython required

Download Setup Steps

Do these one-time setup steps prior to using the API Download Tool to download data from the ASF data pool.

1) Get an Earthdata Login account

A NASA EOSDIS Earthdata Login account is required for downloading data from ASF. Earthdata Login accounts are easy to register for on the Earthdata Login — Create Profile page.

After creating your account, you must log into Vertex, accept the Terms of Service, and set your Study Area before downloading data.

2) Install a Command-Line Download Tool

ASF’s recommended tool for bulk downloads is the ASF Bulk Download Python Script

aria2 can also be used for downloads. 

Wget comes installed on most Linux distributions and is also available for Windows, Mac, and other platforms.

Bulk Download with Aria2

The API Download Tool supports downloading API search results with aria2 in one easy command!

  1. Include your Earthdata username and password
  2. Include your API search URL and keywords
  3. Make sure output=metalink
  4. Run it!
Linux/Mac Example — Log in, search, and download results in one command

aria2c --http-auth-challenge=true --http-user=CHANGE_ME --http-passwd='CHANGE_ME' "https://api.daac.asf.alaska.edu/services/search/param?granule_list=S1A_EW_GRDM_1SDH_20151003T040339_20151003T040443_007983_00B2A6_DDE4&output=metalink"
Windows Example — Log in, search, and download results in one command

aria2c --check-certificate=false --http-auth-challenge=true --http-user=CHANGE_ME --http-passwd="CHANGE_ME" "https://api.daac.asf.alaska.edu/services/search/param?granule_list=S1A_EW_GRDM_1SDH_20151003T040339_20151003T040443_007983_00B2A6_DDE4&output=metalink"

Having trouble?  See the Troubleshooting page for resolutions to common issues.

Additional aria2 options at sourceforge.net.

Download Without Installing Aria2

Users without access to aria2 can still download files, but it takes a few more steps:

  1. Run your API search with output=CSV
  2. Review your search results for the download URL(s) of the file(s) you want
  3. Download those files one at a time using Wget
Linux/Mac Example — Download a datapool file using Wget

wget -c --http-user=CHANGE_ME --http-password='CHANGE_ME' "https://datapool.asf.alaska.edu/GRD_MD/SA/S1A_EW_GRDM_1SDH_20151003T040339_20151003T040443_007983_00B2A6_DDE4.zip"
Windows Example — Download a datapool file using Wget

wget --check-certificate=off -c --http-user=CHANGE_ME --http-password="CHANGE_ME" "https://datapool.asf.alaska.edu/GRD_MD/SA/S1A_EW_GRDM_1SDH_20151003T040339_20151003T040443_007983_00B2A6_DDE4.zip"

Having trouble?  See the Troubleshooting page for resolutions to common issues.

Additional wget options at the GNU Wget Manual

A Note About Passwords

You can store your Earthdata username and password in a configuration file instead of including them in every download command.  This can make downloads more convenient, and hides your credentials from other users that have access to see commands being run on your system.  If you save your password in a file, make sure to set the file’s permissions so other users can’t read it!

Linux/Mac Example — Create and use a configuration file with aria2

echo 'http-user=CHANGE_ME' >> aria2.conf
echo 'http-passwd=CHANGE_ME' >> aria2.conf
chmod 600 aria2.conf

aria2c --conf-path=aria2.conf --http-auth-challenge=true "https://api.daac.asf.alaska.edu/services/search/param?granule_list=S1A_EW_GRDM_1SDH_20151003T040339_20151003T040443_007983_00B2A6_DDE4&output=metalink"
Linux/Mac Example — Create and use a configuration file with Wget

echo 'http_user=CHANGE_ME' >> wget.conf
echo 'http_password=CHANGE_ME' >> wget.conf
chmod 600 wget.conf

export WGETRC="wget.conf"
wget -c "https://datapool.asf.alaska.edu/GRD_MD/SA/S1A_EW_GRDM_1SDH_20151003T040339_20151003T040443_007983_00B2A6_DDE4.zip"

You can store other default options in your configuration file as well.  Refer to the complete documentation on configuration files for aria2 and Wget.

Build API Command

API commands can be incorporated into scripts or used at the command line via the Mac terminal window, Command Prompt window on Windows, or on Linux systems.

      1. File-transfer program (cURL or WGET
      2. Base URL
      3. Keywords and values

Program   Base URL                                             Keywords and Values
curl      https://api.daac.asf.alaska.edu/services/search/param?platform=R1\&absoluteOrbit=25234\&output=CSV 
Windows Example
curl “https://api.daac.asf.alaska.edu/services/search/param?platform=R1&absoluteOrbit=25234&output=CSV” > myfilename.csv

Hint: Copying and pasting quotation marks causes errors for Windows users. Delete and re-type the quotes after pasting.


1) Choose a File Transfer Program and options

Both WGET and cURL are often installed on Linux systems. cURL is part of the Mac OS, and WGET can be installed. MS-Windows OS does not come with either installed, but both can be downloaded. cURL is easier to set up on a Windows machine.

Browser Option
Searches can be done in the browser. Paste just the URL and keywords into a browser to search, visualize, or get a metalink file for downloading data. Connect keywords with “&” when using the browser. A file is returned, or you can open results in Google Earth to visualize.

Send all search results to a file
WGET option ‘-O myfilename‘ or cURL ‘https://….   > myfilename‘ will send all search results into a file. To download data from ASF, use the .metalink extension on your filename. The metalink output is default for ASF searches, but can be explicitly called with keyword output=METALINK.

Example — query results sent to a metalink file:
wget -O myfilename.metalink https://api.daac.asf.alaska.edu/services/search/param?intersectsWith=point%28-119.543+37.925%29\&platform=ALOS\&output=metalink
curl https://api.daac.asf.alaska.edu/services/search/param?granule_list=ALPSRP074606580,ALPSRP021910740,ALPSRP085800750 >myfilename.metalink

Hint: Copy/pastes of examples that span multiple lines introduce error for Mac/Linux users. Copy and paste one line at a time.

Windows Example
curl  “https://api.daac.asf.alaska.edu/services/search/param?granule_list=ALPSRP074606580,ALPSRP021910740,ALPSRP085800750” > myfilename.metalink

2) Use the Base URL

The ASF API URL is 
https://api.daac.asf.alaska.edu/services/search/param?

3) Choose Keywords

Keywords are used to find the desired data. Use as many or as few keywords as needed.

 

Sample Keywords
KeywordDescription and Values
asfframe

This is an ASF / JAXA frame reference. See also ‘frame’.
Values: Any number, series of numbers, or number range from 1 to 900 for ERS, RADARSAT, JERS. 0-7200 for ALOS PALSAR.

output

Format of the API search results returned. If not specified, default return is METALINK for ASF API.

Example: output=CSV

Values: CSV, JSON, KML, METALINK, COUNT, DOWNLOAD, GEOJSON

platform

Remote sensing platform that acquired the data.
Example: platform=ALOS

Values: A3, AI, AS, E1, E2, J1, ERS-1, ERS-2, JERS-1, R1, UA, AIRSAR, ALOS, ERS-1, ERS-2, JERS-1, RADARSAT-1, SEASAT, Sentinel-1A, UAVSAR

Syntax hints:

  ·A”?” separates the URL from the keywords.
  ·The keywords are joined by  “\&” for command line in Mac/Linux or “&” in browser and Windows.
  ·The base URL and keywords may not have any spaces.
  ·Some keywords contain characters that must be encoded.
  ·Keywords are case sensitive.

Keyword Character Encoding:
URLs may not contain spaces, or parentheses. Some keywords, such as intersectsWith, have parentheses and spaces.  Those characters must be encoded as shown in the table below.

Character Encoding
URL SymbolReplace with ASCII
spaceremove spaces in URL or use ‘%20’. Use ‘+’  in keyword values
(%28
)%29

For a complete list of URL codes, please see URL Encoding Reference.

Example — encoding
intersectsWith=point(-119.543 37.925) --> intersectsWith=point%28-119.543+37.925%29

Keywords  may contain a single value or a range of values, depending on the requirements of the particular keyword. For example, “frame=300,310-350” contains both a single value and a range.  The geographic area to be searched can be defined using either the older polygon keyword, or the newer intersectswithIntersectswith has the advantage of allowing a line, a point, or a multi-area search in addition to a single polygon.

4) Put it All Together — Examples

Mac/Linux Examples

Search
curl https://api.daac.asf.alaska.edu/services/search/param?platform=r1\&asfframe=300\&output=CSV > myfilename.csv

Visualize 
wget -O myfilename.kml https://api.daac.asf.alaska.edu/services/search/param?granule_list=ALPSRP074606580,ALPSRP077086550\&output=KML

Visualize — in browser and Google Earth
https://api.daac.asf.alaska.edu/services/search/param?granule_list=ALPSRP074606580,ALPSRP077086550&output=KML Download
wget -c -O myfilename.metalink https://api.daac.asf.alaska.edu/services/search/param?granule_list=ALPSRP074606580,ALPSRP077086550\&output=METALINK

Windows examples

Search
curl  “https://api.daac.asf.alaska.edu/services/search/param?platform=r1&asfframe=300&output=CSV” > myfilename.csv 

Visualize
curl “https://api.daac.asf.alaska.edu/services/search/param?granule_list=ALPSRP074606580,ALPSRP077086550&output=KML” >myfilename.kml

Download
curl -L “https://api.daac.asf.alaska.edu/services/search/param?granule_list=ALPSRP074606580,ALPSRP077086550&output=METALINK” >myfilename.metalink

Keywords

Keywords are used to find the desired data. Use as many or as few keywords as needed.

Sample Keyword
KeywordDescription and Values
asfframe

This is an ASF / JAXA frame reference. See also ‘frame’.
Values: Any number, series of numbers, or number range from 1 to 900 for ERS, RADARSAT, JERS. 0-7200 for ALOS PALSAR.

Available keywords and descriptions are listed to the right.  Click the keyword to expand.

Syntax hints:
  ·A”?” separates the URL from the keywords.
  ·The keywords are joined by  “\&” for command line, or “&” in the browser.
  ·The base URL and keywords may not have any spaces.
  ·Some keywords contain characters that must be encoded.
  ·Keywords are case sensitive.

Keyword Character Encoding:
For searches to be successful, URLs may not contain spaces, or parentheses. Some keywords, such as intersectsWith, have parentheses and spaces. Therefore those characters must be encoded as shown in the table below.

Character Encoding
URL SymbolReplace with ASCII
spaceremove spaces in URL or use ‘%20’. Use ‘+’  in keyword values
(%28
)%29
+%2B

Deprecated Keywords

KeywordNote
beamSee beamMode
directionSee flightDirection
formatSee output
limitSee maxResults
lookAngleSee offNadirAngle
minPercentCoherenceDeprecated
minPercentTroposphereDeprecated
minPercentUnwrappedDeprecated
orbitSee absoluteOrbit
offnadirSee offNadirAngle
pathSee relativeOrbit
processingSee processingLevel
slaveStart/SlaveEndDeprecated
varianceTroposphereDeprecated

Active Keywords

For ALOS, ERS-1, ERS-2, JERS-1, and RADARSAT-1, Sentinel-1A, Sentinel-1B this value corresponds to the orbit count within the orbit cycle. For UAVSAR it is the Flight ID.

Examples:
RADARSAT: absoluteOrbit=25436;
PALSAR: absoluteOrbit=25436-25445, 25450;
UAVSAR: absoluteOrbit=12006

This is primarily an ASF / JAXA frame reference. However, some platforms use other conventions. See ‘frame’ for ESA-centric frame searches.

Values:
Any valid number, series of numbers, or number range for a given platform.

  • ERS, JERS, RADARSAT: ASF frames 0 to 900.
  • ALOS PALSAR: JAXA frames 0 to 7200.
  • SEASAT: ESA-like frames 0208 to 3458  (must use a leading zero for frames 208-999).
  • Sentinel-1: In-house values 0 to 1184.

Note:
Use in-range value for a successful search.

Examples:
asfframe=300 or asfframe=2845-2855 or asfframe=2800,2845-2855

For interferometric SAR (InSAR) analysis, Perpendicular Baseline is the spatial distance between the first and second observations measured perpendicular to the satellite look direction and provides an indication of the sensitivity to topographic height.

Works for ERS-1, ERS-2, JERS, RADARSAT-1, ALOS PALSAR. (Not Sentinel-1)

Example:
maxBaselinePerp=1500 or maxBaselinePerp=50.5

For interferometric SAR (InSAR) analysis, Perpendicular Baseline is the spatial distance between the first and second observations measured perpendicular to the satellite look direction and provides an indication of the sensitivity to topographic height.

Works for ERS-1, ERS-2, JERS, RADARSAT-1, ALOS PALSAR. (Not Sentinel-1)

Example:
minBaselinePerp=100 or minBaselinePerp=50.5

Bounding boxes define an area using two long/lat points. The Bounding box parameters are 4 comma-separated numbers: lower left longitude,latitude, and upper right longitude,latitude. Best choice for very wide search areas.

Example:
bbox=-150.2,65.0,-150.1,65.5

The beam mode used to acquire the data. See also beamSwath.

Example:
beamMode=FBS or beamMode=EW,IW or beamMode=ScanSAR+Wide (URL encoding required for space in name)

PLATFORMValues
AIRSAR3FP, ATI, XTI
ALOSFBD, FBS, PLR, WB1, WB2, DSN
ERS-1Standard, STD
ERS-2Standard, STD
JERS-1Standard, STD
RADARSAT-1Standard, STD, Fine, High, Low, Wide, Narrow, ScanSAR+Wide, ScanSAR+Narrow
SEASATStandard, STD
SMAPStandard, STD
Sentinel-1AEW, IW, S1, S2, S3, S4, S5, S6, WV
Sentinel-1BEW, IW, S1, S2, S3, S4, S5, S6, WV
UAVSARPOL, RPI

BeamSwath encompases a look angle and beam mode.

Example:
beamSwath=0 or beamswadth or beamSwath=FN1,FN2,FN3,FN4,FN5

PLATFORMValues
AIRSAR3FP, ATI, XTI
ALOS1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 15, 16, 17, 18, 19, 20
ERS-1STD
ERS-2STD
JERS-1STD
RADARSAT-1FN1, FN2, FN3, FN4, FN5, SNA, SNB, ST1, ST2, ST3, ST4, ST5, ST6, ST7, SWA, SWB, WD1, WD2, WD3, EH3, EH4, EH6, EL1
SEASATSTD
Sentinel-1AEW, IW, S1, S2, S3, S4, S5, S6, WV
Sentinel-1BEW, IW, S1, S2, S3, S4, S5, S6, WV
UAVSARPOL, RPI

For UAVSAR and AIRSAR data collections only. Search by general location, site description, or data grouping as supplied by flight agency or project.

Example:
collectionName=Haiti

More examples:
UAVSAR: collectionName=Iceland collectionName=earthquake; AIRSAR: collectionName=Denali

Doppler provides an indication of how much the look direction deviates from the ideal perpendicular flight direction acquisition.

Example:
maxDoppler=1500 or maxDoppler=1500.5

Doppler provides an indication of how much the look direction deviates from the ideal perpendicular flight direction acquisition.

Example:
minDoppler=100 or minDoppler=1500.5

Rotation of the polarization plane of the radar signal impacts imagery. HH and HV signals become mixed.

One-way rotations exceeding 5° are likely to significantly reduce the accuracy of geophysical parameter recovery, such as forest biomass.

Example:
maxFaradayRotation=3.5

Rotation of the polarization plane of the radar signal impacts imagery. HH and HV signals become mixed.

Example:
minFaradayRotation=2

Satellite orbit direction during data acquisition.

Example:
flightDirection=DESCENDING

Values:
A, ASC, ASCENDING, D, DESC, DESCENDING

Specify a flightline for UAVSAR or AIRSAR.

Example:
UAVSAR: flightLine=05901
AIRSAR: flightLine=gilmorecreek045-1.93044

ESA-referenced frames are offered to give users a universal framing convention. Each ESA frame has a corresponding ASF frame assigned. See also ‘asfframe’.

Note:
The asfframe number rather than the ESA frame number will be returned in your search metalink file.

Example:
frame=300
frame=300-400
frame=300,303,305
frame=300,303,305-315

Values:
Any number from 0 to 7200.

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 including output. 

Example:
granule_list=R1_12345_FN1_F001,R1_12345_FN1_F002

An InSAR stack is composed of all SAR granules that cover the same geographic region, are from the same platform, and were acquired with the same beam mode, look angle, and bandwidth. To obtain InSAR stacks containing a certain number of SAR granules specify a min, max, or both.

Works for ERS-1, ERS-2, JERS, RADARSAT-1, ALOS PALSAR. (Not Sentinel-1)

Example:
maxInsarStackSize=175

An InSAR stack is composed of all SAR granules that cover the same geographic region, are from the same platform, and were acquired with the same beam mode, look angle, and bandwidth. To obtain InSAR stacks containing a certain number of SAR granules specify a min, max, or both.

Works for ERS-1, ERS-2, JERS, RADARSAT-1, ALOS PALSAR. (Not Sentinel-1)

Example:
minInsarStackSize=20

Search by polygon, a line segment (“linestring”), or a point defined in 2-D Well-Known Text (WKT). 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: longitude is followed by latitude.

Note:
 1) Does not support multi-polygon, multi-line or multi-point.
 2) Polygon holes are ignored

Examples (need URL encoding):

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)

Properly URL encoded:
intersectsWith=point%28-119.543+37.925%29

NOTE!
For successful searches, URLs and keywords may not contain spaces or parentheses. Encode as shown below.

Encoding
URLReplace with
comma ,
space +
(%28
)%29

Reference: wc3 URL encoding reference.

Left or right direction of data acquisition.

Example:
lookDirection=L

Values:
R, RIGHT, L, LEFT

Off-nadir angles for ALOS PALSAR

Example:
offNadirAngle=21.5
offNadirAngle=9.7-14
offNadirAngle=21.5,23.1,20.5-24.2

Values:
Most common: 21.5, 23.1, 27.1, 34.3 
Other: 9.7, 9.9, 13.8, 14, 16.2, 17.3, 17.9, 18, 19.2, 20.5, 21.5, 23.1, 24.2, 24.6, 25.2, 25.8, 25.9, 26.2, 27.1, 28.8, 30.8, 34.3, 36.9, 38.8, 41.5, 43.4, 45.2, 46.6, 47.8, 49, 50, 50.8

Format of the API search results returned. If not specified, default return is metalink for ASF API or JSON for SSARA Federated API. MAP setting valid only for SSARA Federated API.

Example:
output=JSON

Values:
CSV, JSON, KML, METALINK, COUNT, DOWNLOAD, GEOJSON

NEW values!
COUNT returns the number of search results
GEOJSON returns the search results in a GeoJSON format
DOWNLOAD returns a bulk download script that includes the scenes returned by the search. 
A full description and guide on using the bulk download script itself can be found here

Note:
JSON returns more fields than CSV for the same query.

Remote sensing platform that acquired the data. Datasets that work together, such as Sentinel 1A/1B and ERS‌-1/2 have multi-platform aliases available (specifically, S1 and ERS).

Example:
platform=ALOS
platform=SA, SB
platform=S1

Values:
‌ALOS, A3, AIRSAR, AS, ERS, ERS‌-1, E1, ERS‌-2, E2, JERS‌-1, J1, RADARSAT‌-1, R1, SEASAT, SS, S1, Sentinel, Sentinel-1, Sentinel-1A, SA, Sentinel-1B, SB, SMAP, SP, UAVSAR, UA.

A property of SAR electromagnetic waves that can be used to extract meaningful information about surface properties of the earth.

Examples:
polarization=VV
polarization=VV, HH
polarization=VV%2bVH
polarization=Dual+VV
Encode “+” and “[space]” as shown below.

Encoding
URLReplace with
space +
+%2B
PLATFORMValues (some values require encoding)
AIRSARFULL
ALOSQUADRATURE, HH+5SCAN, HH, HH+4SCAN, VV, HH+3SCAN, FULL, HH+HV, VV+VH
ERS-1VV
ERS-2VV
JERS-1HH
RADARSAT-1HH
SEASATHH
Sentinel-1AVV, VV+VH, Dual VV, VV+VH, Dual HV, HH, HH+HV, VV, Dual VH
Sentinel-1BVV, VV+VH, Dual VV, VV+VH, Dual HV, HH, HH+HV, VV, Dual VH
UAVSARFULL, HH

Bounding polygon in the digital long/lat format; enter coordinates in counter clockwise direction, repeat the first point at the end to close the polygon: in the format ABCDA

Example:
polygon=-155.08,65.82,-153.5,61.91,-149.50,63.07,-149.94,64.55,-153.28,64.47,-155.08,65.82

Level to which the data has been processed, also type of product, such as browse.

Example:
processingLevel=L0,L1

PLATFORMValues
AIRSAR3FP, ATI, LTIF, PTIF, CTIF, PSTOKES, BROWSE, DEM, CSTOKES, JPG, LSTOKES, THUMBNAIL
ALOSL1.0, L1.1, L1.5, RTC_LOW_RES, RTC_HI_RES, BROWSE, THUMBNAIL, METADATA, INTERFEROMETRY
ERS-1L0, L1, BROWSE, THUMBNAIL
ERS-2L0, L1, BROWSE, THUMBNAIL
JERS-1L0, L1, BROWSE, THUMBNAIL
RADARSAT-1L0, L1, BROWSE, THUMBNAIL
SEASATL1, BROWSE, THUMBNAIL
Sentinel-1AMETADATA_GRD, GRD_HS, GRD_HD, GRD_MS, GRD_MD, GRD_FS, GRD_FD, SLC, RAW, OCN, METADATA_RAW, METADATA, METADATA_SLC, THUMBNAIL
Sentinel-1BMETADATA_GRD, GRD_HS, GRD_HD, GRD_MS, GRD_MD, GRD_FS, GRD_FD, SLC, RAW, OCN, METADATA_RAW, METADATA, METADATA_SLC, THUMBNAIL
SMAPL1A_Radar_RO_QA, L1B_S0_LoRes_HDF5, L1B_S0_LoRes_QA, L1B_S0_LoRes_ISO_XML, L1A_Radar_QA, L1A_Radar_RO_ISO_XML, L1C_S0_HiRes_ISO_XML, L1C_S0_HiRes_QA, L1C_S0_HiRes_HDF5, L1A_Radar_HDF5
UAVSARKMZ, PROJECTED, PAULI, PROJECTED_ML5X5, STOKES, AMPLITUDE, BROWSE, COMPLEX, DEM_TIFF, PROJECTED_ML3X3, METADATA, AMPLITUDE_GRD, INTERFEROMETRY, INTERFEROMETRY_GRD, THUMBNAIL

Path or track of satellite during data acquisition. For UAVSAR it is the Line ID.

Example:
relativeOrbit=500,550-580 or UAVSAR: relativeOrbit=05905

PLATFORMValues
ALOS1-671
ERS-10-2410
ERS-20-500
JERS-10-658
RADARSAT-10-342
SEASAT1-243
UAVSAR various

Maximum number of data records to return from your query. 

Example:
maxResults=10

Limit results to records that have been processed at ASF since a given date and time.

Example:
processingDate=2017-01-01T00:00:00UTC

Date of data acquisition

Natural language
Use phrases such as:

  • start=3 months and a day ago 
  • start=May 30, 2018
  • end=now

Insert ‘+’ in place of spaces.

Example:
platform=SB&start=1+week+ago&end=now
&maxresults=2000&output=csv

UTC
Enter a start date, end date or both to form a valid range.

Example:
start=2010-10-30T11:59:59UTC\&end=2018-10-01T00:00:00UTC

Start and end day of year for desired seasonal range. This keyword is used in conjunction with start/end to specify a seasonal range within an overall date range in choosing values in alignment with Julian calendar.

Example:
season=1,31
season=45,67
season=360,10

Values:
1 through 365

Troubleshooting

Trouble AreaReasonRemedy
Windows cURL “unrecognized protocol”Invisible double quotes involuntarily inserted when copy/pasting example from web page

Delete the visible quotes, which will delete the invisible quotes. Then retype quotes.

Download fails with “401 Unauthorized” or “Authorization failed”Missing or invalid Earthdata username/password

Check that you are correctly including your Earthdata username and password in your download command.  See search for examples.

Download fails with “401 Unauthorized” or “Authorization failed”Special characters in Earthdata password

Passwords with special characters need single quotes on Linux/Mac and double-quotes on Windows.  See search for examples.

Cookie request to /services/authentication/ fails with “410 Gone”Cookie URL has been retired

It’s not longer necessary to request an authorization cookie before downloading data.  See search

Can’t authenticateYou must agree to the new Terms of Service and set your Study areaLog on to Vertex, accept the TOS, and set your Study Area
Wget or cURL command copied from the webpage doesn’t workCopy/paste over multiple lines introduces errorCopy and paste one line, then the next line
Wget or cURL command copied from the webpage doesn’t workQuotes look the same but are interpreted differentlyWhere single quotes are present, delete and retype them in the terminal window
API request with ‘+’ in it failsSome keywords are stored in the database as two words with a space between them, some as two words joined with a ‘+’.Try your API request with a ‘+’. if that doesn’t work, replace the ‘+’ with ‘%2B’. One of them will work.
Download using Aria failsBug in ASF codeFix delivered 

API request fails

https is now required

Make sure you are using https, not http

Can’t download PALSAR data

You must agree to the PALSAR EULA in order to download PALSAR data

Log in to Vertex and agree to the End User License Agreement, then retry downloading

API request hangs, fails, or returns an errorYour URL may include spaces or special characters, especially if you are using the ‘intersectsWith’ keyword

Remove spaces or replace with %20 or +

See URL Character Encoding below

API request hangs or failsSearch may exceed 10,000 results

Narrow search using more keywords to return fewer results or use keyword “maxResults”

API request returns process ID (PID) numbers but does not return query resultsURLs at the command line may require the “&” to be escaped

Replace ampersand “&” with backslash ampersand “\&” in the URL. OR use double quotes ” ” around the URL; URLs submitted via the browser use ampersand “&” without the backslash.

Keyword not respectedKeywords are case sensitive

Ensure that your keywords are capitalized (or not) just as in the Keyword List

Keyword not respectedKeyword is deprecated

See the bottom of the keyword list for a list of deprecated keywords

Certificate rejectedThird-party certificates out of date, a problem for https searches

Use http OR disable certificate checks

curl –insecure

wget –no-check-certificate

CSV vs JSONThe JSON output returns more fields than CSV

It’s a feature. ASF may expand CSV output in the future. Meanwhile, use JSON to get the most information returned