CQ DX Marathon

Resources, Hints & Tips: Data Formats

Data format information for Participants

The DX Marathon Submission Tool accepts information in the following formats:

ADIF Log

You can provide one or more ADIF files with any number of QSOs and the tool will use only those for the current year and help you review and select one for each entity and zone.

At a minimum, it has to include QSO_DATE, TIME_ON, CALL, BAND, and MODE.

If it includes DXCC or CQZ fields, we use them to assign the QSO to the right entity or zone. If they are not present, we do simple callsign prefix matching, but this can be less accurate so consider including them on the ADIF file when you generate it if at all possible.

Excel Scoresheet

You can keep track of your DX Marathon QSOs using a Scoresheet in any Spreadsheet application as long as you can export it as XLSX or CSV. See our sample offered in our software page or the details below.

DXM XML File

The submission ultimatily uses an XML file to represent the entire submission. You can get a copy of this file as a backup, and load it again on the submission tool to continue working on it, or to review past years’ submissions.

Data format information for Developers

If you want to create applications that help users prepare their submissions files, these are the details you need to know in order to generate files that will work well with the Submission Tool.

If your application already helps our participants select the best QSOs for their entry, you can use either of the three formats described below to generate files that include only one QSO per entity or zone. Either of the three formats described below will work. We’d prefer DXM over CSV over ADIF, but pick the one that’s easier for you to generate with your application’s particular constrains and available libraries.

On the other hand, if your application wants to produce a large list of QSOs and let the participants use the Submission Tool to review and select them for their entry, we recommend generating files that include all the QSOs for the entire year, with as much information as possible. These files can include QSOs for other years as well and the Submission Tool will ignore them. We prefer ADIF files for this purpose, but if that’s not possible you can use a CSV file. DXM files will not work in this case.

You can use the Submission Tool to test and validate any files you produce. Nothing is saved until you complete and submit an entry, and even then, you can always update it with a later one. We do ask you to use your own callsign when testing submissions, and if you are not sure you plan to replace it with a real submission at the end of the year, use {your call}/TEST to indicate the submission is not real.

We recommend joining our Developer Discussion Group to keep up with any updates and discussions, ask for help or bring suggestions.

XLSX or CSV Scoresheet

The file must have the following columns, with these names as headers near the top of the table:

  • Prefix - Must match exactly one of the prefixes listed in the Country List
  • Day - Day of the month for the QSO, one or two digits.
  • Month - Month of the year for the QSO, one or two digits.
  • Time - UTC Time of the QSO, in “HHMM” or “HH:MM” format
  • Band - Band for the QSO: “6m”, “10m”, “12m”, “15m”, “17m”, “20m”, “30m”, “40m”, “60m”, “80m”, “160m”
  • Mode - Mode for the QSO: “DIGITAL”, “CW”, or “PHONE”
  • Callsign - Callsign of the station worked

You can include other columns, or data before the header, and they will be ignored. If your spreadsheet application supports multiple tabs, the scoresheet must be the first tab of the file.

If the file has more than one entry for the same entity or zone, then the earliest QSO will be selected by default, and any other QSOs will be available for review and selection.

You can use the Scoresheet offered in our software page directly or as a template.

The original scoresheet available up to 2023 does not quite exactly match these requirements, but it will still be supported by the Submission Tool for the near future. If you want to keep using that particular file for longer, you’ll have to update the list of prefixes to match the Country List, but we suggest using the new version instead.

ADIF Log

Use the latest version of ADIF 3.

You can generate a file with any number of QSOs, and the tool will help the user make selections for each entity and zone. The earliest confirmed QSO for each entity or zone will be selected by default, and any other QSOs will be available for review and selection. Only QSOs for the current year will be considered, but it is OK to include QSOs for other years as well.

Or you can generate a file with a specific QSO for each entity and each zone by using the DXCC, REGION and CQZ fields as described below to assign them.

At a minimum, each QSO has to include: QSO_DATE, TIME_ON, CALL, BAND, and MODE.

Use the DXCC field to assign a QSO to an Entity. Use the CQZ field to assing a QSO to a Zone. If the QSO does not include these fields, the tool will use the CALL field to match the QSO with the appropriate entity and zone by using simple prefix matching rules.

In addition, to assign QSOs for the “WAE Entitites” (see the Country List) use the REGION field (see ADIF docs). Alternatively, you can use the “Internal DXCC codes” listed later on this page as values on the DXCC field.

Use the QSL_RCVD field to indicate if the QSO has been confirmed.

In summary, as a software developer, your main choices are to either generate a file with all your QSOs for the year and as much information as possible and use the Submission Tool to help you review and select the specific QSOs for your entry; or you can

DXM XML File

The XML file is the ultimate representation of the submission. It contains not only the QSOs for each entity and zone, but also the entrant contact information, classification, and other details.

DXM XML files generated by third-party applications still need to be loaded, reviewed and submitted though the Official Submission Tool.

The root element is <DXMARATHON>, and it contains an <ENTRY> block with the entrant information, an <ENTITIES> block with a <QSO> for each entity, and a <ZONES> block with a <QSO> for each zone.

The <DXMARATHON> element has year attribute to indicate the marathon year (i.e. “2023”, even if submitting on, say, January 2nd 2024)

The <ENTRY> block is optional, as well as any of the following elements it might contain:

  • <CALL> : The entrant’s callsign
  • <ALT_CALL> : An alternate callsign, if any
  • <NAME> : The entrant’s name
  • <CLASS> : The entrant’s class, one of: FORMULA 5, FORMULA 100, LIMITED, and UNLIMITED
  • <OVERLAY> : Classification Overlay, if relevant. Currently we only accept YOUTH or YL
  • <CQZ> : The CQ Zone where the station is located
  • <GRID> : The Maidenhead Grid Square where the station is located
  • <CITY> : The City where the station is located
  • <STATE> : The State where the station is located
  • <COUNTRY> : The Country where the station is located
  • <EMAIL> : The entrant’s email address
  • <CLUB> : The entrant’s club, if any
  • <SOAPBOX> : Any comments

Each <QSO> has to include the following elements:

  • <CALL> : The callsign of the station worked
  • <OUR_CALL> : The callsign of the entrant’s station (optional)
  • <BAND> : The band where the QSO was made
  • <MODE> : The mode for the QSO. Can be DIGITAL, CW or PHONE.
  • <TIME> : The date of the QSO, in YYYY-MM-DDTHH:MM:SSZ format (ISO 8601)

<QSO> elements inside of <ENTITIES> have to include:

<QSO> elements inside of <ZONES> have to include:

  • <CQZ> : The CQ Zone number for the zone.

The <ENTRY> block is optional. Any information included might be used to prefill the entrant’s details but is not required and some fields might even be ignored if present.

The Submission Tool can generate an XML backup of an entrant’s current data by using the “Download” button available on the page that lists the QSOs, or at the final submission step.

Direct upload of file data (Experimental Feature)

Instead of generating a file, you can also upload the data directly to the Submission Tool. This is an experimental feature, so it might change in the future.

You can pass two paramenters to the page at https://entry.dxmarathon.com/

  • data: a Base64-encoded, GZip-compressed version of the data, either ADIF, XML or Excel
  • label: a text label to include in the button that will show up to allow the user to process the data.

This will only work for smaller files, so it’s not recommended for ADIF files with a large number of QSOs.

If you need assitance implementing this feature, please contact ki2d@ki2d.net.

JSON Data Files

The information displayed in the Resource pages about Callsign Notes, Invalid Callsigns, Bad Spots and Pirates is available in JSON format in two separate files: all-good-calls.json and all-bad-calls.json

Internal DXCC Codes for WAE Entities

Since WAE entities are not part of the official DXCC, we had to come up with our own list of codes, so we recognize the following internal DXCC Codes on ADIF and XML files:

DXCC Code Prefix WAE Entity
901 4U1V ITU Vienna International Center
902 GM/s Shetland Islands
903 IG9 African Italy
904 IT9 Sicily
905 JW/b Bear Island
906 TA1 European Turkey

Note that ADIF supports the REGION field for this purpose (see ADIF docs) so we recommend its use instead of the internal codes whenever possible.