Using ISO 3166-1 in Software

Buy data    Donate

The ISO 3166 standard is very convenient for computer software. Many software designers have decided to use the Alpha-2 codes to represent countries, at least internally. Because these codes are part of an international standard, designers can point to the standard to support their choices. For political reasons, users may want to demand the inclusion or exclusion of certain entities in a country list. (Past and present controversies include Palestine, East Timor, Taiwan, and the Panama Canal Zone.) When confronted over these issues, the designer can respond, "I've used the international standard list of countries. If you have complaints, you should address them to the ISO 3166 Maintenance Agency."

Typically, a software product will incorporate a table of countries. Each row of the table will have an ISO code and the corresponding country name, possibly along with other attributes. The application displays and recognizes a country if and only if it appears in the table. The ISO codes are apt to be used internally, because they are uniform and don't take much space in memory. The names are shown wherever the user interface requires a country name to be displayed.

A designer who plans to use ISO 3166 in this way should ask a number of questions. Here are answers to some of them.

Q. Is it allowed?

A. ISO's latest statement  on this topic says, in paraphrase, that ISO does not intend to charge for its intellectual property in the ISO 3166 codes. If your product uses the ISO codes as an added value, you should at least purchase a copy of the standard document, and thus support the work of ISO.

Q. Is there a one-to-one correspondence between ISO codes and real-world countries?

A. This is a much more complex question than it appears on the surface. It depends partly on whether you agree with the selection of countries on the ISO 3166-1 list, which may be controversial. Changes in the real world must be taken into account, too.

Q. At any given time, are the countries on the ISO list exhaustive and exclusive?

A. "Exhaustive" means that every location on earth is in some country on the list. "Exclusive" means that, except for locations right on the border, each location is in only one country.

The ISO list is exhaustive, except that the high seas are not included. However, there are some areas whose sovereignty is in dispute, and the standard is usually noncommittal about those areas. Parts of Jammu and Kashmir, Western Sahara, and the Spratly and Paracel Islands in the South China Sea are among the territories at issue. Of these, Western Sahara is the only one with its own ISO country code; Morocco has controlled it for decades, but the U.N. still hopes to hold a referendum there to see if the inhabitants want independence. There are also some tiny condominiums, such as the ╬le des Faisans, which lies between France and Spain and belongs equally to both countries.

In a different sense, the ISO list is not exhaustive. You will occasionally find some postal addresses that mention a country not found in the standard. One common example is French West Indies (or Antilles franšaises, or FWI), which corresponds to Guadeloupe and Martinique.

The ISO list is only exclusive if you redefine some of the countries. The prefatory text of the standard document clearly states that a country's remote territories may be given a separate code, when such a code is needed for purposes of communication. Legally, France's dÚpartements d'outre-mer (French Guiana, Guadeloupe, Martinique, etc.) are an integral part of France, but each one has its own ISO code. Sometimes "remote" isn't very far away. Hong Kong and Macao, special autonomous regions of China, have their own codes, although they are directly contiguous to China. If you want to make the ISO list exclusive, you must either delete these remote territories from the list, or define the countries so that they don't include the remote territories. The latter choice is usually acceptable. When people hear "France", they usually think of metropolitan (European) France, not the overseas departments.

Q. Does it ever happen that two codes represent the same country at the same time?

A. FR has always stood for France. In 1993, ISO added a code FX, representing "Metropolitan France". There is no plausible way to interpret the extent of the two entities "France" and "Metropolitan France" so that they don't overlap. ISO withdrew the Metropolitan France entry in 1997, but there's no guarantee that they won't do something similar in the future.

Q. Does it ever happen that two different countries have the same code?

A. Not at the same time, but a code may be retired at one time and then reinstated with a different meaning at a later time. The text of the standard document says that retired codes will stay retired for at least five years. This has already happened. GE was retired for Gilbert Islands in about 1979, and reused for Georgia in 1992. AI was retired for Afars and Issas in 1977, and reused for Anguilla in about 1985. CS was retired for Czechoslovakia in 1993, and reused for Serbia and Montenegro in 2003. This last change has provoked some protests. The codes that were dropped by 1979 hardly ever got included in computer systems, but CS was present in many computer systems as legacy or archived data.

Q. Can the same country have more than one name?

A. Certainly. Country names come in various degrees of formality (Commonwealth of Australia, Australia, Oz). There are exonyms (Espa˝a, Spain, Espagne, Spanien, etc.) - names for countries in different languages. Since some countries have more than one official language, it may be impossible to select a single name to be the "native" form (BelgiŰ, Belgique). There are abbreviations in common use (FYROM for Former Yugoslav Republic of Macedonia). There are obsolete names that are still in common use (Za´re for Democratic Republic of Congo). You can't be sure whether to look for Federated States of Micronesia under 'F' or 'M' in an index. If country names are for display only, and all users are expected to speak the same language, it's easy to pick a standard form for each country name in that language. If, however, country names will be input by users in free form, you may need a large list of alternate country names to match them, or even include a pattern-matching algorithm. Congo poses a special problem. Currently there are two countries: the Republic of Congo and the Democratic Republic of Congo. For brevity, they are sometimes distinguished as Congo-Brazzaville and Congo-Kinshasa (using the capital cities). Some users may want to refer to either one as just "Congo".

Q. What kinds of real-world change can affect a table of countries?

A. Countries can merge, split, or acquire territory from another country. In these processes, their names can change or stay the same. When a country is removed or changed, you may want to know what is its successor country: the country that will henceforth own its foreign embassies, be responsible for its debts, and so on. In recent history, East and West Germany merged to form Germany. The formal name of the new country, Bundesrepublik Deutschland (Federal Republic of Germany), was the same as the formal name of West Germany before the merge. Germany was the successor to both of the former countries. North and South Yemen merged to form Yemen in another case, and North and South Vietnam are yet another. Splits have been more common. The most complex split was the breakup of the Soviet Union into its fifteen constituent republics, which occurred over a period of several months. The name "Soviet Union" disappeared from the map. The Russian Federation is the successor state to the Soviet Union. From the period immediately after World War II, Ukraine and Byelorussia had their own seats in the General Assembly of the United Nations, although they were subject to the Soviet Union in the same way as the other republics. Consequently, they were given ISO codes from the very beginning, and didn't need new codes in 1992. Another recent dissolution was that of Yugoslavia, from which Slovenia, Croatia, Bosnia and Herzegovina, and the Former Yugoslav Republic of Macedonia painfully detached themselves. Several years later, Yugoslavia changed its name to Serbia and Montenegro, and subsequently broke up into two countries: Montenegro and Serbia. Eritrea seceded from Ethiopia, which remained in existence with diminished territory. Czechoslovakia split into the Czech Republic and Slovakia, which had formerly been administrative divisions of Czechoslovakia. It's common for territory to be transferred from one country to another on a small scale; often, these transfers are called boundary adjustments. Sometimes it happens as a result of war or purchase. The United States acquired some of its territory by purchase, in 1803 (Louisiana), 1853 (Gadsden), and 1867 (Alaska). After World War I, there were many significant transfers of territory. For example, Alsace-Lorraine was shifted from Germany to France.

Name changes may occur, even without changes in territory. East Timor changed to Timor-Leste; Za´re changed to Democratic Republic of Congo; Cambodia changed to Khmer Republic, then Kampuchea, and then back to Cambodia. Often the ISO country code changes to match the country name (BU for Burma to MM for Myanmar), but there will be a delay between the name change and the code change.

Q. How can a software product handle these changes?

A. All I can give is some general suggestions and questions. What attributes of a country are used to support the application's functionality? What, precisely, is the entity that has those attributes?

If a location moves from one country to another due to border changes, and there are archived records that show the location belonging to the first country, must those records be updated to the second country? That is, suppose you have a transaction record that shows the city and country where the transaction took place. Now, suppose that city becomes part of a different country. Do you want to leave the record unchanged, so that it indicates the country where the transaction took place at the time it took place? Or do you want to update the record, so that the city/country combination is consistent with the present-day situation? Actually, having both a city and a country field in the transaction record is probably bad design (it's denormalized, anyway). If the city is known, the country for that city can be looked up in the city table.

If you need to know what country the city was in at a past date, you will have to add at least one table to keep track of the many-to-many relationship between cities and countries over time.

According to good design principles, the ISO code should not be used as primary key in a table of countries. It would be better to use an arbitrary, system-generated key. ISO codes change, but the system-generated key can be kept to mean the same thing forever.

Since the relationship between countries and their names (or codes) is one-to-many, it may be useful to add tables of aliases.

Back to main statoids page Last updated: 2006-07-01
Copyright © 2003, 2005, 2006 by Gwillim Law.