Uploading Satellite Avoidance Logs

These are the instructions to upload satellite avoidance log files to the NRAO ODS API. These logs describe various mitigating actions taken by satellite operators to avoid interference with telescopes.

Upload Instructions

Send your satellite avoidance log file to the NRAO ODS API using the multipart/form-data content type. You’ll need to include:

  • Your authentication token in the Authorization header

  • Your log file attached under the field name file

curl -X 'POST' \
  'https://ods.nrao.edu/sat_avoidance_logs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <EXAMPLE_TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<facility_start_date_end_date>.csv;type=text/csv'

Response 200 OK

{
  "ingested_records": "<number of records ingested>"
}

Satellite avoidance log format

The following CSV header row is expected:

utc_time,freq_lower_mhz,freq_upper_mhz,avoidance_type,angular_threshold,sat_id

  • utc_time - (UTC datetime without timezone, format: YYYY-MM-DD HH:MM:SS), e.g., 2025-08-30 00:05:57

  • freq_lower_mhz - (float) in MHz

  • freq_upper_mhz - (float) in MHz

  • avoidance_type - (str), one of [outer, inner]

  • angular_threshold - (Optional, float), in degrees (omit column altogether if not available)

  • sat_id - (int)

File name

The CSV file name must start with an agreed-upon facility abbreviation to describe where the avoidance action was taken. The suggested filename format is <FACILITY>_Logs_<utc_date_start>_to_<utc_date_end>.csv,

where:

  • <FACILITY> can be:

    • VLA (upper case)

    • GBT (upper case)

    • vlba_<STATION> (lower case vlba) with upper case station name

      • where <STATION> = {SC, HN, NL, FD, LA, PT, KP, OV, BR, MK}.

  • <utc_date_start> and <utc_date_end> are in the format of YYYY-MM-DD

Recommendations

  • Record the timestamps in a small time interval (at most every 10-15 seconds) during the entire avoidance event. If it’s less than one second, a single record entry in the logs will be sufficient.

  • Keep file sizes reasonable. File size is capped at 750 kB. Much smaller is preferred, e.g. less than 5000 records.

  • Use the ODS API responsibly. If uploading multiple files, please pause for at least ten seconds between each upload.

  • Use unique filenames for uploads to aid in troubleshooting

  • If your request fails with a validation error, address, then reupload the entire file. We ignore records we’ve seen before but this will help make sure the full file is ingested.