Islands on the Air - API - IOTA Listings files
banner

IOTA Listings

Introduction

This page provides access to downloadable versions of the IOTA Group Listings, which may be included and redistributed with logging software, etc. Please see the licence for the full terms and conditions of use, since by downloading the files you are deemed to have understood and agreed to the conditions. You are also strongly encouraged to read the information about the group list to fully understand how the list is structured.

Support

Since provision of the listings to software developers is not considered a core part of the IOTA programme, we regret that we cannot offer any support for users of these files. If you would like to comment on them, however, please do email iota.online@rsgb.org.uk as we will read your thoughts. If you are sure you have found a mistake in the files after fully reading the documentation, please file a bug report.

Licence

Your use of the files below is subject to the following terms. By downloading the files, you warrant that you have read and fully accepted these conditions:

The Radio Society of Great Britain hereby grants you a non-exclusive licence to download, save, reproduce and/or retransmit the IOTA Listings files in any form whatsoever, subject to the following conditions:

  1. For the purpose of this licence, 'Official URL' refers to http://www.rsgbiota.org/xml/fulllist.xml and/or http://www.rsgbiota.org/api/public/listings/shortlist.csv or any URL to which these URLs redirect;
  2. references to 'we/our' in this licence refer to the Radio Society of Great Britain, the IOTA sub-committee and the software developers. References to 'you/your' refer to the person downloading this file or, in the case of an automated download, to the software developer whose programming caused the automated download.
  3. this licence is time-limited and expires six months after download of this file or (in the case of XML listings) at the time specified in the HTTP-Expires header sent with the file or (in the case of CSV listings) at midnight UTC on the date given on the line starting '# EXPIRES: ' whichever is the sooner;
  4. this licence may be renewed any number of times by fetching a new copy of the file from an Official URL which will also be governed by the limitation on duration detailed in the preceding clause;
  5. the file will be included in any software application without modification or adaption in any way, except that comments may be translated into other languages. Under no circumstances may group names and/or island names be translated;
  6. sub-group IDs and island IDs must not be visible to end-users through any User Interface;
  7. whilst we will endeavour to ensure that copies of the files are made available on a permanent basis at the Official URL, we cannot guarantee its availability at all times, nor can we accept responsibility for any consequences of this. As a result, your software must respond correctly to specified HTTP headers (including redirect headers) when fetching the file;
  8. for XML versions, the content of the <copyright> tag must be displayed in your software in any documentation, help files and/or 'about' screens. For the CSV file, the text on the line commencing '# COPYRIGHT: ' must be shown in help files and/or 'about' screens.
  9. the terms of this licence may be varied without warning. The version of the terms by which you are bound is the one in force when the file was last downloaded from an Official URL;
  10. these terms shall be governed by the laws of England only;
  11. we can provide no support for these files and accept no responsibility for any consequences of their use or misuse howsoever caused to the maximum extent permitted in law;
  12. nothing in this licence shall, under any circumstances, be construed as assigning copyright in the listings to you.

About IOTA Groups

Background

The IOTA award is about contacting island groups, not individual islands. As the name suggests, an island group contains one or more individual islands.

Group locations

The group is defined by a set of coordinates, creating a rectangle, which forms the outer boundary of the group. It is important to be aware, however, that there may well be areas of sea or mainland within this boundary, and that some group boundaries overlap with others. You must not, therefore, assume that, given a set of coordinates, a certain IOTA group reference is correct. This is only possible to know given the island name.

The island name

The island name is intrinsic to IOTA data. An IOTA Group reference number which is not accompanied by an island name, and where the island name cannot be unambiguously known by the server (currently only IOTA Contest QSOs), is considered invalid. This is not a rule only designed for the database: since 2000, all QSL Cards valid for IOTA must also have the island name printed on them.

Every island in the database has an ID number to identify it. Your software must use the ID number to refer to the island in communications through the forthcoming API, but in no circumstances must end-users see the island ID number. Although it is a unique number, the island ID is normally accompanied by the group reference.

There may be more than one island in the same group with the same name. In these cases, and if the islands are not in separate sub-groups, check the island comment tag to see whether disambiguation is possible. At some future date, we will likely also provide geographical coordinates to disambiguate such cases. In the meantime, if it is not clear which to use, treat such cases as synonymous.

In some cases, QSL cards for QSOs before 2000 may not provide the island name. Where we know of such cases, the group name may be repeated as an island name. Customers should only use this island name where a more precise island name is not known.

Sub-groups

Many IOTA Groups (which are generally politically defined) contain one or more groups of geographically-recognised groups. For example, in France, the 'Bretagne (Finistere South) Region Group' (EU-094) contains the islands of Moutons and Verte but also all of the islands known as the Glenan Islands. In such cases, the individual Glenan Islands will be named as members of the Glenan Islands sub-group. Again, end-users must not be made aware of sub-groups or sub-group reference numbers but where an island in one sub-group has the same name as one in another sub-group or in the wider group, the sub-group name may be required for disambiguation.

Where all islands in a sub-group count for IOTA, the sub-group will sometimes only contain one island, which has the same name as the sub-group.

Sub-sub-groups

The design of the IOTA database allows for sub-sub-groups (ie. groups of islands inside a sub-group, inside a group). At present, you will be relieved to hear, this is unused!

Excluded islands

In the case of some groups, a list of specifically excluded islands is given. These are either islands which count for a neighbouring group but which experience shows some users might get confused about, or islands within the group boundary which fail the IOTA qualification criteria. The IDs supplied with these should be ignored. At present, you cannot look up the ID of an excluded island to get the group which it does count for, though this information may be included in the island comments.

Sub-groups may be excluded. If part of a sub-group is included and part excluded, the sub-group ID in the content and excluded sections will match.

DXCC entity, prefixes

Only one DXCC entity is given (the most common), though the IOTA group may span multiple entities. For example, EU-005 is mainland G, GW and GM, but only the DXCC entity number for G is given. Use the semi-colon separated string in the prefixes tag when checking whether a callsign is in the correct group.

Reference number format

For the IOTA Award, the reference number format consists of a continent code (two letters), followed by a hyphen, then three digits, using leading zeros if necessary. For the IOTA Contest (final weekend in July), the reference number format is the same, but without the hyphen. We recommend that software store reference numbers with the hyphen, and only removes it when creating a cabrillo output for the IOTA Contest.

You might come across reference numbers which have a 'X' in place of the hyphen and number greater than 900. These reference numbers were used internally by the former IOTA website for unactivated groups. These groups have since been allocated numbers, and these references are now deprocated and must not be used.

XML Full Group Information

The address http://www.rsgbiota.org/xml/fulllist.xml provides access to the full IOTA Directory listings in XML format. This is the preferred version. The full description of the IOTA XML format used is available.

Sample file

NB: In order to show a sample of the most complex return possible, a fake group has been invented purely for the purposes of this example. This group might have appeared in the printed directory as:
EU-099 VE2, VE3 FAKE SAMPLE GROUP (=Alforo, Algroy, Alvoy, the First Sub-group Islands (namely Bouleaux, Calculot, Fantome and Las Viajas (AKA: Independencia)), the Second Sub-group Islands and, in the Les Embiez Islands, Grand Rouveau and Petit Rouveau.
(Note: not Aruba or Saba or Grand and Petit Gaou in the Les Embiez Islands or islands counting for other groups)

Click to display sample

<?xml version="1.0" encoding="UTF-8"?> <iotaxml xmlns="http://www.rsgbiota.org/xml/"> <head> <created v="1.0">2008-09-05T18:00:00Z</created> <copyright>Includes IOTA Group Information, copyright (c) 1985-2008 Radio Society of Great Britain</copyright> <head> <body> <groupInfo> <grpRef>EU-999</grpRef> <grpName>Fake Sample Group</grpName> <grpComment>Not Aruba or Saba or Grand and Petit Gaou in the Les Embiez Islands or islands counting for other groups.</grpComment> <grpContent> <island id="00010155">Alforo</island> <island id="00010156">Algroy</island> <island id="00010157">Alvoy <isComment>Near Yell</isComment></island> <subGrp id="EU-999-1-0" name="First sub-group islands"> <island id="00003341">Bouleaux</island> <island id="00003340">Calculot</island> <island id="00003339">Fantome</island> <island id="00009067">Las Viajas [AKA: Independencia]</island> </subGrp> <subGrp id="EU-999-2-0" name="Second sub-group islands"> <island id="00003321">Second sub-group islands</island> </subGrp> <subGrp id="EU-999-3-0" name="Les Embiez Islands"> <island id="00010464">Grand Rouveau</island> <island id="00010465">Petit Rouveau</island> </subGrp> </grpContent> <grpExcludes> <island id="00008470">Aruba</island> <island id="00008467">Saba</island> <subGrp id="EU-999-3-0" name="Les Embiez Islands"> <island id="00010469">Grand Gaou</island> <island id="00010470">Petit Gaou</island> </subGrp> </grpExcludes> <position xmlns:gml="http://www.opengis.net/gml"> <gml:Polygon> <gml:outerBoundaryIs> <gml:LinearRing> <gml:coordinates> 50.05, -61.00 50.32, -61.00 50.32, -65.00 50.05, -65.00 50.05, -61.00 </gml:coordinates> </gml:LinearRing> </gml:outerBoundaryIs> </gml:Polygon> </position> <prefixes>G;GM;GW</prefixes> <dxcc id="1">CANADA</dxcc> <pc_credited>48.0</pc_credited> <region>BI</region> </groupInfo> </body> </iotaxml>

Notes

<created> The v attribute (major.minor version) will be increased for each new version. A major version would include the addition of a new IOTA group, the deletion of an existing group, or a group which has changed DXCC entity. A minor version would include spelling corrections, or correcting geographical coordinates. The date which follows it, formatted according to the W3C DATETIME recommendation, is the time that the file was last modified.

<copyright> The child text of this tag must be included in all copyright notices and 'about' screens for your software.

<gml:coordinates> This is a string containing five {latitude, longitude} statements forming a polygon, which is the outer boundary of the group. The coordinates are in the following order: South-West corner, North-West, North-East, South-East, South-West. To reiterate the point explained in the API notes, just because a station is inside this polygon, he is not necessarily on a valid island for this IOTA group.

For more information, see the <groupInfo> tag in the tagset documentation.

CSV Shortlist

The shortlist of group titles is available in CSV format from http://www.rsgbiota.org/api/public/listings/shortlist.csv. Before using this file, however, please consider using the full XML version, which is the preferred version. In particular, the forthcoming IOTA API for managing a user's QSO records will require island IDs for all QSOs, which will not be available if your software only uses the shortlist.

The file format is:

# IOTA CSV Shortlist
# v1.0 2008-09-01
# EXPIRES: 2008-10-01
# COPYRIGHT: Includes IOTA Group Information, copyright (c) 1985-2008 Radio Society of Great Britain
EU-005,Great Britain (Main Island Only),G;GW;GM;M;MW;MM
EU-006,Aran Islands,EI
OC-281,Caroline Island;Millennium Island,T32
# FILE SAMPLE ONLY.

The file is UTF-8 encoded.

For more detail on the prefixes used, see the documentation for the XML <prefixes> tag. The prefix field will be blank for deleted groups.

Island group names which contain semi-colons should be rendered as alternative names. For example, in the last line of the sample above the group name is 'Caroline Island [AKA: Millennium Island]'.