Fermi LAT Data Query API

Typical Workflow

POST /query              -> receive query_id
GET  /query/{id}/status  -> poll until complete
GET  /query/{id}/results -> retrieve file metadata and download URLs
-> download each file from the url field returned by /results

API Architecture

The API acts as a frontend to the existing Fermi LAT backend infrastructure:

1. Client submits a query via HTTP (JSON payload)
2. The API validates and normalizes parameters
3. A query is submitted to the Queue Manager
4. One or more backend servers process the request:
   • Photon Server
   • Spacecraft Server
   • Event Server (if applicable)
5. Results are staged on the HEASARC FTP area
6. The API exposes status and result metadata

Base URL

https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1

All endpoints below are relative to this base URL.

1. Submit a Query

POST /query

Submits a new Fermi LAT data query for processing.

Request Parameters

Example Request

curl -k -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "coordfield": "128.836,-45.1764",
    "shapefield": 15,
    "coordsystem": "J2000",
    "timefield": "772109936,787661936",
    "timetype": "MET",
    "energyfield": "100,300000",
    "photonOrExtendedOrNone": "Photon",
    "spacecraft": "on"
  }' \
  https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1/query

Example Response

{
  "query_id": "L2601082002167F48EE3069",
  "status": "submitted",
  "status_url": "/ssc/data/access/lat/query/api/v1/query/L2601082002167F48EE3069/status",
  "results_url": "/ssc/data/access/lat/query/api/v1/query/L2601082002167F48EE3069/results"
}

Example: Submit with Zenith Angle

curl -k -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "coordfield": "128.836,-45.1764",
    "shapefield": 15,
    "coordsystem": "J2000",
    "timefield": "772109936,787661936",
    "timetype": "MET",
    "energyfield": "100,300000",
    "photonOrExtendedOrNone": "Photon",
    "spacecraft": "on",
    "zenithangle": 85
  }' \
  https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1/query

2. Check Query Status

GET /query/{query_id}/status

Returns the current state of the query, including queue position and server execution status.

Example Request

curl -k \
  https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1/query/L2601082002167F48EE3069/status

Example Response

{
  "query_id": "L2601082002167F48EE3069",
  "queue_status": [
    { "server": "Photon Server", "queue_rank": 0, "time_remaining": "Unknown" },
    { "server": "Spacecraft Server", "queue_rank": 0, "time_remaining": "Unknown" }
  ],
  "running_status": [
    { "server": "Photon Server", "status": "Completed", "time_remaining": "N/A" }
  ],
  "servers_status": [
    { "name": "Photon Server", "position": "Query complete", "time_remaining": "N/A" }
  ],
  "state": "Query completed"
}

3. List Result Files

GET /query/{query_id}/results

Returns metadata for all result files associated with the query, including a ready-to-use download url for each one.

Example Request

curl -k \
  https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1/query/L2601082002167F48EE3069/results

Example Response

{
  "query_id": "L2601082002167F48EE3069",
  "state": 2,
  "files": [
    {
      "name": "L2601082002167F48EE3069_PH00.fits",
      "entries": 703,
      "size": "0.09",
      "status": "available",
      "url": "https://fermi.gsfc.nasa.gov/FTP/fermi/data/lat/test/queries/L2601082002167F48EE3069_PH00.fits"
    }
  ]
}

Listing Only File Names

curl -k \
  https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1/query/L2601082002167F48EE3069/results \
  | jq -r '.files[].name'

4. Download Result Files

Result files are staged on the HEASARC FTP infrastructure. Each entry returned by /results includes a complete url — use that rather than assembling the path yourself, so downloads keep working if the storage location changes.

Download Every File From a Query

curl -k \
  https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1/query/L2601082002167F48EE3069/results \
  | jq -r '.files[].url' \
  | xargs -n1 curl -L -O

Download a Single File

curl -L -O \
  "$(curl -k https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1/query/L2601082002167F48EE3069/results \
     | jq -r '.files[0].url')"

All-Sky Queries

All-sky queries retrieve data covering the entire sky and are treated specially by the backend. The following rules apply:

• shapefield must be > 60° (typically 180)
• Observation window must be <= 24 hours
• Coordinates may be set to 0.0,0.0 or left blank

Example: All-Sky Query

curl -k -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "coordfield": "0.0,0.0",
    "shapefield": 180,
    "coordsystem": "J2000",
    "timefield": "2008-08-04 15:43:36,2008-08-05 09:14:33",
    "timetype": "Gregorian",
    "energyfield": "100,300000",
    "photonOrExtendedOrNone": "Photon",
    "spacecraft": "on"
  }' \
  https://fermi.gsfc.nasa.gov/ssc/data/access/lat/query/api/v1/query

Error Responses

Errors are returned as JSON with an error field and an appropriate HTTP status code.

{ "error": "Zenith angle must be between 0 and 180 degrees." }