UNAVCO Logo
 
 
UNAVCO SAR API

UNAVCO's SAR Application Programming Interface (API) provides a set of web services for searching the UNAVCO SAR archive. The API can be used to search the archive and retrieve metadata for pertinent SAR holdings. Queries are sent as HTTP GET or HTTP POST requests for resources based upon API parameters supplied in the request. Each query requires a base access point, a resource name, and, optionally, depending on the resource name, a parameter list:

    <base access point>: http://facility.unavco.org/SarArchive

    <resource name>: QueryFields or SarScene

    full URL construction:

         <base access point>/<resource name>
         <base access point>/<resource name>?parameter1=value
         <base access point>/<resource name>?parameter1=value&parameter2=value
         <base access point>/<resource name>?parameter1=value&parameter2=value&...
The API returns the search result in the open, text-based data exchange format JSON.

See also the UNAVCO SAR API Command-line Client which uses this API.


The QueryFields resource name is used to get a listing of all query field values as needed for, say, the values of the SarScene parameters status, collectionName, satellite, beamSwath, beamMode, and polarization:

         http://facility.unavco.org/SarArchive/QueryFields

Note 1: The values returned for each parameter by QueryFields may or may not correspond to metadata of scenes depending on the mission or sensor capabilities, e.g. the polarization parameter.

Note 2: The QueryFields resource name does not use a parameter list.


The SarScene resource name is used for a request of scene metadata:

         http://facility.unavco.org/SarArchive/SarScene?<parameter list>

One or more of the following can be used with SarScene to construct its parameter list. Omitting a parameter in a search is equivalent to allowing all values for that particular parameter:


status — accepts a list of comma-separated values for scene status; the current possible values are:

    archived — scenes archived at UNAVCO or Supersites
    orderable — scenes that can be ordered from ESA (or possibly other space agencies in the future)
    requested — scenes that have been requested for ordering
    ordered — scenes that have advanced from requested to actually having been ordered
    unavailable — scenes that were ordered, but then found to be not available at ESA and therefore could not be delivered
status=archived,requested,ordered


collectionName — accepts a list of comma-separated collection names; the current possible values are:

    WInSAR ESA — WInSAR-acquired scenes with ESA-approved access
    EarthScope ESA — EarthScope-acquired scenes with ESA-approved access
    EarthScope CSA — EarthScope-acquired scenes with CSA-approved access
    Supersites — scenes at Supersites
    WInSAR orderable — scenes that have a status of orderable only by WInSAR Full members (i.e. not WInSAR Adjunct I or Adjunct II members or other SAR data users)
    TerraSAR-X collection names
collectionName=Supersites


start / end — accepts an ISO 8601 formatted date (YYYY-MM-DD) that represents valid range for the dates of interest; currently these parameters can only be set to the day granularity; start implies a start time in that day of 00h:00m:00s and end implies an end time in that day of 23h:59m:59.9...s:

start=2010-10-30&end=2011-10-30


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:

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 )


satellite — accepts a list of comma-separated satellite mission abbreviated names:

satellite=ERS1,ERS2,ENV1

(Note: The UNAVCO SAR API also allows a parameter synonym of platform in order to be compatible with ASF's API.)


beamSwath — accepts a list of comma-separated beam swath abbreviated names:

beamSwath=S1,S2,S3


beamMode — accepts a list of comma-separated beam mode abbreviated names:

beamMode=HS,IM,ScanSAR


track — accepts a list of comma-separated values and/or ranges for track (i.e. relative orbit) numbers:

track=0,1,3-5

(Note: The UNAVCO SAR API also allows a parameter synonym of relativeOrbit in order to be compatible with ASF's API.)


frame — accepts a list of comma-separated values and/or ranges for frame numbers:

frame=300,310-350



sceneSize — accepts a list of comma-separated values; the current possible values are:

    swath — scene acquisition length > 18 seconds
    frame — scene acquisition length <= 18 seconds and > 14 seconds
    subframe — scene acquisition lenght <= 14 seconds
sceneSize=frame,sub-frame


orbit — accepts a list of comma-separated values and/or ranges for orbit numbers:

orbit=31560-32740

(Note: The UNAVCO SAR API also allows a parameter synonym of absoluteOrbit in order to be compatible with ASF's API.)


polarization — accepts a list of comma-separated polarizations or polarization combinations:

polarization=HH,HH+HV

or if '+' does not work, use %2b for the hexadecimal replacement of '+":

polarization=HH,HH%2bHV


flightDirection — accepts a list of comma-separated satellite flight directions ('A'=ascending, 'D'=descending):

flightDirection=D


lookDirection — accepts a list of comma-separated SAR look directions ('L'=left, 'R'=right):

lookDirection=R


format — accepts a list of comma-separated SAR scene format types; the current possible values are:

    CEOS
    Envisat — ESA's N1 format for Envisat scenes, but also used for some ERS scenes
    COSAR
    STF
    unspecified — for scenes that are orderable, and will be in one of the above formats when actually available
format=CEOS,ENVISAT


processingType — accepts a list of comma-separated SAR scene processing types; the current possible values are:

    L0
    SLC
processingType=SLC

(Note: The UNAVCO SAR API also allows a parameter synonym of processingLevel in order to be compatible with ASF's API.)



Example 1: find all archived RadarSAT-1 scenes with an ascending flight direction in STF format within the specified polygon:
http://facility.unavco.org/SarArchive/SarScene?satellite=RSAT&flightDirection=A&format=STF&status=archived&intersectsWith=POLYGON ((-111.3942 44.8975, -111.3832 44.7143, -111.0316 44.7143, -111.0481 44.9305, -111.3942 44.8975))

Example 2: find all archived and orderable Envisat scenes in the WInSAR ESA and the WInSAR orderable collections within the same specified polygon:
http://facility.unavco.org/SarArchive/SarScene?satellite=ENV1&status=archived,orderable&collectionName=WInSAR ESA,WInSAR Orderable&intersectsWith=POLYGON ((-111.3942 44.8975, -111.3832 44.7143, -111.0316 44.7143, -111.0481 44.9305, -111.3942 44.8975))



Sponsors and Partners for UNAVCO SAR activities

Last modified Tuesday, 16-Oct-2012 17:35:33 UTC