Amateur Data Interchange Format 1.0
Ever since software has become a part of amateur radio, there have been as many data formats as there have been ham radio software programmers. Hams have struggled with converting data among various formats. Several hams have been discussing such a standard via an Internet discussion. In early 1996 KK7A promoted the idea of a standard for exchange of ham data. An internet reflector was set up for discussing such a standard. WF1B and WN4AZY, as publishers of commercial ham radio software, have taken the best suggestions from this discussion and formed a proposal. Ray introduced it at the 1996 Dayton hamvention. Within a year, this proposal has adapted adopted by most software publishers. We wish to thank everyone who has contributed to this effort.
ADIF is infinitely extensible--it will never be outgrown. It can handle binary as well as text data. New data elements may be added to this specification without "breaking" older implementations. It may be easily programmed in any language. The data itself is easily read by eye, and may implemented so as to be transferred via Internet without any encoding.
Provide a standard interchange independent of operating system or programming language for amateur data that will permit easy and direct transfer of data conforming to the standard between various amateur programs as well awards and contest sponsors.
Data to be Interchanged:
The ADIF standard must not be limited to log data. It should incorporate other categories such as awards multiplier lists, packet spot data, contest rules, etc., and must be expandable to incorporate any new type of data that may appear in the future as the hobby grows and changes. However, as of version 1.0, only specifications for log data have been implemented. Anyone wishing to interchange other types of data will still find these specifications helpful. All that is necessary to transfer other types of data is to apply to ADIF a definition of fields and records to be transferred.
ADIF consists of three components:
1. Physical specifications--a specification of how fields and records are stored.
2. Field type definitions--Specification of how a particular type of data is stored. For instance, DATE should be stored with ASCII characters in the format YYYYMMDD. Examples of other possible data types are Numeric, Windows .BMP picture, binary data containing unspecified non-textual data, or freeform text containing multiple lines.
3. Field definitions--a list of data elements (Call, QSO Date, DXCC country, etc.), and a description of valid values. Each field has a name that is from one to ten characters long. The field name may include the characters A-Z, 0-9, and _, but must begin with a letter. (This is for easy transfer with xBase and other popular existing data formats).
4. File definitions--a description of a category of data. For instance, log data is defined as all data resulting from a QSO, including exchanged info plus any data related specifically to a QSO, such as band/mode, comments, traffic exchanged during the QSO, awards tracking info, and contest scoring info. A category will include a list of fields supported by the ADIF standard for each category. Each record in the file will contain one or more of the supported fields.
Additional fields that are not part of the ADIF specification for the file may be added by those creating ADIF files. This will permit export of user-defined fields. However, there is of course no guarantee that these undocumented fields will be imported by a program reading ADIF files, or that a chosen name may not be used for another purpose and imported into the wrong field in future ADIF specifications. Therefore, creators of ADIF files are encouraged to cooperate when adding new fields to so as to derive maximum benefit from ADIF.
1. Physical Specifications:
Each data field is preceded by a field name and length enclosed in angle brackets. The name and length are separated by a colon. The field name may be in upper, lower, or mixed case. Case is insignificant. For instance, CALL, Call, or call are equivalent. The length specification is ASCII text in display format, and may be of any non-negative value. The data follows the closing angle bracket. For example:
Records are made up of multiple fields and terminated with <EOR> or <eor> as an end-of-record marker. For example:
An optional field type indicator may follow the field length, separated by a colon: For example:
The field type indicator may be in upper, lower, or mixed case. A field type indicator is optional. For instance, the Field Definition for QSO_DATE specifies that the field is always of type Date, so it is not necessary to repeat it here. However, when exporting user-defined fields that are not part of the ADIF specification, a type indicator will assist anyone attempting to import the data.
Any number of characters of any value except < may be added after a fields data or <eor> and before the start of the next field. This is typically carriage returns and/or line-feeds to make the file easier to read in a text viewer. For example:
In this example, a new line is inserted in the middle of each record, and two newlines are inserted at the end of each record. This makes long records easy to read in a text editor.
Optional header information may be included before the actual data in the file. To include optional header info, the first character of the file must be something other than <. Any amount of header info of any value except <eoh> may be included. The header info must be terminated with <eoh>. Any number of characters of any value except < may follow <eoh>. The first < after <eoh> is the start of the first field of the first data record in the file. Here is an example:
this data was exported using WF1B RTTY version 9, conforming to ADIF standard specification version 9.99<eoh>
If the first character of a file is <, it is presumed to be the first field of the first data record.
The ADIF version may be included in the header info as follows: <adif_ver:4>1.00 is included as part of the header specification, an importing program can easily determine the ADIF version used to create the file. Note that this must not be at the beginning of the header info, because < as the first character indicates that there is no header.
It is important for the programmer importing ADIF data to note that any number of characters of any value may follow the actual data in a field. For example, carriage return/linefeed, or just a line feed. There is nothing in the specifications to prevent an exporter from placing a comment after the actual data. Therefore, after reading a fields data based on the length specification, the programmer should read and discard characters until the start of a new field (<) or <eor> is encountered.
There is no specification for the order in which fields appear. They may appear in any order. Unused fields may be omitted entirely. Therefore, each record will not necessarily have the same fields. The specification does not prohibit a zero-length field, so those writing import programs should allow for this.
There is no specification for field length or maximum field length in the Physical Specifications. Unless there is a length specification in the Field Definition, exporters simply export all data in their field. Importers import as much data as their program can accept.
Note that while these examples have all been of simple ASCII fields, the specification permits data of any type or length. It could be easily used to transfer pictures or text documents, for instance.
2. Field Type Definitions:
|Date||A date specification in YYYYMMDD format|
|Time||A time specification. May be 6 characters long (HHMMSS) if seconds are included, 4 characters (HHMM) if seconds are not included. Time is in 24-hour format, from 0000 to 235959. A zero-length field or omission of the field indicates an empty time value.|
|M||Multi-line text field. For xBase MEMO and similar data.|
|C (Character)||So far everyone who has written an export program has not specified a type for character data. However, it is included in the specifications for consistency.|
3. Field Definitions:
|ADDRESS||M||As it will appear on the mailing label|
|BAND||C||160M, 80M, 40M, 30M, 20M, 17M, 15M, 12M, 10M, 6M, 2M, 70CM,23CM...see table below|
|CNTY||C||US County in the format STATE,COUNTY. For example GA,BARROW. Use CQ County list|
|COMMENT||C||Comment field for QSO|
|CONTEST_ID||C||Contest Indentifier -- SS, ARRLVHF, ARRLDX, etc.|
|DXCC||N||Numeric identifiers from ARRL. See table below|
|GRIDSQUARE||C||4, 6, or 8 or however many characters|
|IOTA||C||HYPHEN MUST BE INCLUDED. Example: NA-001 IOTA PROVIDES DISK IN THIS FORMAT|
|MODE||C||SSB, CW, RTTY, TOR=AMTOR, PKT, AM, FM, SSTV, ATV, PAC=PACTOR,CLO=CLOVER|
|NOTES||M||Long text for digital copy, third party traffic, etc.|
|OPERATOR||C||Callsign of person logging the QSO|
|QSLMSG||M||Personal message to appear on qsl card|
|QSLRDATE||D||QSL Rcvd Date|
|QSLSDATE||D||QSL Sent Date|
|QSL_RCVD||C||Y=Yes, N=No, R=Requested, I=Ignore or Invalid|
|QSL_SENT||C||Y=Yes, N=No, R=Requested, I=Ignore or Invalid|
|QSO_DATE||D||YYYYMMDD in UTC|
|RX_PWR||N||Power of other station in Watts|
|SAT_NAME||C||Name of satellite|
|SRX||N||Received serial number for a contest QSO|
|STX||N||Transmitted serial number for a contest QSO|
|TIME_OFF||C||HHMM or HHMMSS in UTC|
|TIME_ON||C||HHMM or HHMMSS in UTC|
|TX_PWR||N||Power of this station in watts|
|VE_PROV||C||2-letter abbreviations: AB, BC, MB, NB, NF, NS, NT, ON, PE, QC, SK, YT|
DXCC country codes:
Handling transfer of DXCC(tm) country info has been a common problem due to lack of an official list. The ARRL maintains everyone's DXCC status using numeric codes. We have adopted their codes for ADIF transfer of data. We wish to thank the ARRL for making this list available.
NOTE: Since the ARRL assigns the numbers after the country becomes active, we have been unofficially assigning our own numbers. This will become official with ADIF 2.0. Meanwhile, the table lists the ADIF code as well as the ARRL number, when different.
|2||ABU AIL IS||Y|
|4||AGALEGA & ST BRANDON|
|10||AMSTERDAM & ST PAUL|
|11||ANDAMAN & NICOBAR IS|
|16||AUCKLAND & CAMPBELL|
|20||BAKER, HOWLAND IS|
|25||BRITISH N. BORENO||Y|
|32||CEUTA & MELILLA|
|56||FERNANDO DE NORONHA|
|57||FRENCH EQ. AFRICA||Y|
|59||FRENCH WEST AFRICA||Y|
|61||FRANZ JOSEF LAND|
|65||BRITISH VIRGIN IS|
|89||TURKS & CAICOS IS|
|90||TRINIDAD & TOBAGO|
|94||ANTIGUA & BARBUDA|
|107||REPUBLIC OF GUINEA|
|114||ISLE OF MAN|
|124||JUAN DE NOVA|
|139||KURIA MURIA IS||Y|
|147||LORD HOWE IS|
|151||MALYJ VYSOTSKI IS (R1MV)|
|154||YEMEN ARAB REP||Y|
|163||PAPUA NEW GUINEA|
|180||MT ATHOS (SY)|
|184||NETHER N. GUNIEA||Y|
|191||N COOK IS|
|195||PAGALU (ANNOBAR IS)|
|197||PALMYRA & JARVIS IS|
|199||PETER I IS|
|201||PRINCE EDWARD & MARION|
|213||SAINT MARTIN (FJ)|
|216||SAN ANDREAS & PROVIDENCIA|
|219||SAO TOME & PRINCIPE|
|229||GERMAN DEM. REP.||Y|
|230||FED REP OF GERMANY|
|234||S COOK IS|
|235||SOUTH GEORGIA IS|
|238||SOUTH ORKNEY IS|
|240||SOUTH SANDWICH ISLANDS|
|241||SOUTH SHETLAND ISLANDS|
|243||DEM REP OF YEMEN||Y|
|249||ST KITTS & NEVIS|
|250||ST HELENA IS|
|252||ST PAUL ISLAND|
|253||ST PETER & ST PAUL RKS|
|267||TERR NEW GUINEA||Y|
|273||TRINDADE & MARTIN|
|274||TRISTAN DA CUNHA|
|277||ST PIERRE & MIQUELON|
|283||UK BASES ON CYPRUS|
|289||HQ UNITED NATIONS|
|298||WALLIS & FUTUNA|
|391||UNITED ARAB EMIRATES|
|433||NORTH KOREA (HP)|
|511||Ducie Is (VP6)||513|
|512||Chesterfield Is (TX0)|
|513||East Timor (4W)||511|
4. File Definitions:
A log record is the data resulting from logging one QSO. ADIF does not specify a minimum required set of fields for log data. Although a record should contain at least :
it is permissible to export data with any of these items missing.
ADIF, xBase and other formats
As xBase languages and utilities are very popular (perhaps the most popular) for data handling applications, many parties to the ADIF proposal discussion favored using xBase files as the physical specification. However, this standard was not selected, since it is not easily used by those not using an xBase language, and lacks the flexibility and extensibility that ADIF features. However, a de-facto secondary xBase specification exists. Those wishing to use xBase files that will be compatible with each other may simply use ADIF field and record specifications.
We encourage development of public-domain utilities being made available that convert ADIF/xBase files as well as other popular data formats such as Lotus 123, Paradox, MS Access, etc.
Usage of ADIF and limitations
In order to maintain the integrity of ADIF and public confidence therein, these guidelines must be followed by anyone wishing to support ADIF.
ADIF may be freely used by any individual or organization, non-profit or commercial. Anyone claiming "ADIF compatibility" or "ADIF support", or other language with similar meaning, must be able to import and export ADIF data.
Of course data import is not necessary or desirable for all programs. For example, in the case of contesting-only packages, the user will probably want to export the contest data for use in a general logger, but not care about importing data. Authors of such packages shall state they provide "ADIF export compatibility" or "ADIF export support", or other language with similar meaning.
Writing a logging package that imports ADIF but cannot export ADIF is not within keeping of the spirit and intent of ADIF. Such a package cannot truthfully claim to be ADIF compatible or to support ADIF. Authors of programs that only import must state that they support "ADIF import compatibility" or "ADIF import support", or language with similar meaning.
Packages that export and import ADIF may state that they support "ADIF import and export" or a similar phrase. However, any claims of ADIF support without any qualifiers shall mean that the program imports and exports.
Export programs shall be written in good faith so that the data will be of maximum usefulness to the user of the data. Products that export data in such a manner that its usefulness is limited, for example by exporting only a few fields or using non-standard formats or names for fields, cannot claim ADIF compatibility. Export programs should include all data in the file to be exported. If an author has fields that are not in the field list of the ADIF specification, he may export the fields by choosing the most obvious field name, and making a reasonable attempt to notify other ADIF supporters--for example via the ADIF mailing list reflector. In time there will probably be an official standards committee that will maintain the field list.