AGAPE

    Atmospheric Grid Analysis & Profile Extraction

 
The AGAPE tool allows you to extract and download profiles based on instrument, location, date, height, SNR, and orientation parameters. If you should encounter any problems, we ask that you take the time to report them to us at genesis@jpl.nasa.gov. AGAPE has a graphical interface and an API that enables scripted downloads.

The occultation dataset is very large. Most AGAPE queries are fast, but when quering large, complex geographic boundaries with no temporal or other subselections queries can take as long as minute to complete. If a query times out, its result may have been cached, so wait a few moments and hit the reload button. The downloads are streamed, so the size of the file is not precisely known a-priori (except when cached), but will be computed and shown after the download starts.

The AGAPE tool can display between 50 and 10,000 occultations. Each page of occultations can be downloaded separately, or the entire dataset corresponding to the query can be downloaded with the download all button. The occultations in the table are those displayed on the map. The polygon tool on the map can be used to select a subset of occultations in latitude-longitude space. Multiple polygons can be drawn.

Most interactive features have tooltips on hover that explain their purpose. Launch the AGAPE tool below:

Launch AGAPE

AGAPE has been tested and is supported on Chrome, Firefox and Safari.

Using the API

 

The AGAPE API has three endpoints:

Action URL Use
download https://genesis.jpl.nasa.gov:8000/download/ Download a tar file containing occultations matching the query parameters.
list https://genesis.jpl.nasa.gov:8000/occultations/ Get a json list containing information for occultations matching the query parameters.
status https://genesis.jpl.nasa.gov:8000/status Get the latest data import status and total dataset statistics.

 

Download

TARs can simply contain files (flat) or be organized in a directory structure (hierarchical).

For flat tar files: https://genesis.jpl.nasa.gov:8000/download/flat

For hierarchical tar files: https://genesis.jpl.nasa.gov:8000/download/hierarchical

The easiet way to generate a query is to use the graphical interface and hit the clipboard button next to one of the download buttons. This will copy the corresponding download link to your clipboard. Otherwise download URLs can be constructed manually using the query parameter table. The multiple column indicates if the parameter may be specified more than once.

Parameter Multiple Function
p yes Include occultations on the given platform(s)
l yes Get level(s) of data: L1a, L1b, or L2
s no Inclusive lower bound date and time in GPS time of the occultation: YYYY-MM-DDTHH:MM
e no Exclusive upper bound date and time in GPS time of the occultation: YYYY-MM-DDTHH:MM
b yes Polygon(s) encoded with Google's polyline algorithm. Here's a python implementation.
v yes The software version that processed the occultation. The available versions are listed on the AGAPE page, with the periods replaced with the letter p.
vx no Set to 'true' will fetch the latest processing version available for each occultation.
start no The occultation number to start at.
length no The number of occultations to include in the download.
order[0][column] no The integer column number to order on. The column numbers correspond to the orderable columns listed in the AGAPE table, indexed from 1.
order[0][dir] no desc if the occultations should be added to the tar in descending order, asc for ascending.
an no A lower bound on the lowest altitude in kilometers.
ax no An upper bound on the lowest altitude in kilometers.
cnl no A lower bound on the mininum CA-SNR.
cnh no An upper bound on the mininum CA-SNR.
cxl no A lower bound on the maximum CA-SNR.
cxh no An upper bound on the maximum CA-SNR.
pnl no A lower bound on the mininum P2-SNR.
pnh no An upper bound on the mininum P2-SNR.
pxl no A lower bound on the maximum P2-SNR.
pxh no An upper bound on the maximum P2-SNR.
cdnl no A lower bound on the minimum CA phase delay in kilometers.
cdnh no An upper bound on the minimum CA phase delay in kilometers.
cdxl no A lower bound on the maximum CA phase delay in kilometers.
cdxh no An upper bound on the maximum CA phase delay in kilometers.
pdnl no A lower bound on the minimum P2 phase delay in kilometers.
pdnh no An upper bound on the minimum P2 phase delay in kilometers.
pdxl no A lower bound on the maximum P2 phase delay in kilometers.
pdxh no An upper bound on the maximum P2 phase delay in kilometers.
lon no An upper bound on the link orientation angle from east. 0 to 180, 0 to -180
lox no A lower bound on the link orientation angle from east. 0 to 180, 0 to -180
avn no An upper bound on the angle to velocity. 0 to 180.
avx no A lower bound on the angle to velocity. 0 to 180.
lata no Latitude bounding box A. Bounding box is counter clockwise A->B 
latb no Latitude bounding box B. Bounding box is counter clockwise A->B
lnga no Longitude bounding box A. Bounding box is counter clockwise A->B
lngb no Longitude bounding box B. Bounding box is counter clockwise A->B

 

​

For instance, to download a flat TAR file containing the latest versions of L2 data from PAZ occultations for the month of January 2021, one could do:

wget "https://genesis.jpl.nasa.gov:8000/download/flat?p=paz-h&p=paz-v&l=L2&vx=true&f=Text&s=2021-01-01T00:00&e=2021-02-01T00:00"

​Individual files and tars of data for individual occultations may also be downloaded if you know the numerical identifier of the file or occultation (see list api below). The occultation link takes the TAR format argument as well :

https://genesis.jpl.nasa.gov:8000/download/file/xxxxxxxx
https://genesis.jpl.nasa.gov:8000/download/occultation/xxxxxxxx/flat

The size of a download in bytes can be obtained a-priori by using the size endpoint. The size will likely not exactly match the download size because it will not take into account tar file overhead. For instance to get the size of the above download we could do:

wget -qO- "https://genesis.jpl.nasa.gov:8000/download/size?p=paz-h&p=paz-v&l=L2&vx=true&f=Text&s=2021-01-01T00:00&e=2021-02-01T00:00"
{"total_size": 119754733}

Using some pipe magic you can stream and unpack a tar directly to disk:

wget -qO - "https://genesis.jpl.nasa.gov:8000/download/hierarchical?p=paz-h&p=paz-v&l=L2&vx=true&f=Text&s=2021-01-01T00:00&e=2021-02-01T00:00" | tar -xzvf - -C ./

 

List

To get structured json data describing the occultations you can use the list endpoint with the same query parameters as the download endpoint:
 
https://genesis.jpl.nasa.gov:8000/occultations/
 
As with the download buttons you can build a query in the UI and hit the list copy button to copy a link to the list. There are two differences for list queries. First there are no flat or hierarchical file arguments and second paging parameters must be supplied. For example, the same download query above, for listing would be:
 
https://genesis.jpl.nasa.gov:8000/occultations?p=paz-h&p=paz-v&l=L2&vx=true&f=Text&s=2021-01-01T00:00&e=2021-02-01T00:00&length=50&order[0][column]=3&order[0][dir]=desc&start=0
 
And the structured data looks like:
 

 

{
    "draw": null,
    "data": [
        {
            "id": 8043384,                     # occultation numerical unique id
            "d_id": "20210904_2357paz-v_g64",  # occultation unique descriptive identifier
            "start": "2021-09-04T23:57:42Z",   # start time of occultation GPS time 
            "end": "2021-09-04T23:59:38Z",     # end time of occultation GPS time
            "alt": 0.049222,                   # lowest altitude in km
            "trans": "gps64",                  # transmitter
            "pfrm": "paz-v",                   # platform name
            "cent": [                          # centroid of occultation bounding box
                -89.578988,                    # longitude
                -56.35287949999999             # latitude
            ],
            "lnk": -104.35,                    # link orientation, degrees from east
            "ang": 162.3,                      # angle to velocity
            "casnrmn": 0.231501397,            # minimum CA SNR
            "casnrmx": 558.478763,             # maximum CA SNR
            "p2snrmn": 118.0,                  # minimum P2 SNR
            "p2snrmx": 563.0,                  # maximum P2 SNR
            "caphasemn": 0.015221153,          # Minimum CA atmospheric phase delay (km)
            "caphasemx": 4.48015364,           # Maximum CA atmospheric phase delay (km)
            "p2phasemn": 0.0233609362,         # Minimum P2 atmospheric phase delay (km) 
            "p2phasemx": 0.223796308,          # Maximum P2 atmospheric phase delay (km)
            "data": [                          # list of available data files
                {
                    "id": 35844289,            # data file numerical id
                    "lvl": "L2",               # data level
                    "ver": "2.6",              # processing version
                    "files": [                 # individual files 
                        {
                            "id": 44744956,    # file ID
                            "sz": 26735,       # size in bytes
                            "fmt": "Text"      # file format
                        }
                    ]
                }
            ]
        },
        ...
    ]
    "recordsTotal": 4708 ,                     # Total number of occultations matching the query 
    "start": 0,                                # The number of the occultation this page starts at   
    "length": 50,                              # The number of occultations shown on this page
    "totalSize": null                          # If cached, the total size in bytes if this list were to be downloaded              
}

 

 

Status

The status endpoint provides information about the scale of the dataset and when the last occultations were added to it.

https://genesis.jpl.nasa.gov:8000/status/

 

{
    "last_data": "2021-09-16T10:00:03.449620+00:00",  # The time the last data was successfully imported
    "last_sync": "2021-09-16T10:00:03.449620+00:00",  # The last time new data was checked for
    "totals": {                                       # Statistics on the whole dataset
        "missions": 7,                                # Total number of missions in the dataset
        "platforms": 14,                              # Total number of platforms in the dataset
        "occultations": 8013519,                      # Total number of occultations in the dataset
        "files": 44738969,                            # Total number of files in the dataset
        "bytes": 4515010908574,                       # Total number of bytes in the dataset
        "bytes_h": "  4TB",                           # Human readable number of bytes
        "years": 21                                   # Time range in years of the dataset
    },
    "platforms": {                                    # List of platforms
        "cosmic1": {                                  # Platform name
            "occultations": 0,                        # The number of new occultations from the last import
            "files": 0                                # The number of new files from the last import
        },
        "cosmic2": {
            "occultations": 0,
            "files": 0
        },
        "cosmic3": {
            "occultations": 0,
            "files": 0
        },
        "cosmic4": {
            "occultations": 0,
            "files": 0
        },
        "cosmic5": {
            "occultations": 0,
            "files": 0
        },
        "cosmic6": {
            "occultations": 0,
            "files": 0
        },
        "champ": {
            "occultations": 0,
            "files": 0
        },
        "kompsat5": {
            "occultations": 0,
            "files": 0
        },
        "gracea": {
            "occultations": 0,
            "files": 0
        },
        "graceb": {
            "occultations": 0,
            "files": 0
        },
        "sacc": {
            "occultations": 0,
            "files": 0
        },
        "terrasar-x": {
            "occultations": 218,
            "files": 654
        },
        "paz-h": {
            "occultations": 416,
            "files": 1248
        },
        "paz-v": {
            "occultations": 405,
            "files": 1215
        }
    }
}