Open Country Codes: ISO 3166 country names and Alpha-2 country codes in HTML, Python, JavaScript, ActionScript, Flex, JSON, and XML
Why are some things just much harder than they need to be? Finding a current, easy-to-use data source for populating a country selection box, for example.
Most of the clean country data out on the web is second-hand, having at one point in time been scraped and tediously hand-converted from the International Organization for Standardization (ISO)'s page of English country names and code elements.
That list "states the country names (official short names in English) in alphabetical order as given in ISO 3166-1 and the corresponding ISO 3166-1-alpha-2 code elements" of 246 countries and is free to use.
Unfortunately, it's an HTML table. Which means that you have some manual data massaging to do if you want to use it. Sucks big time.
ISO also sells the ISO 3166 "database" for about $148 USD. And it comes in -- get this -- Microsoft Access format. I bet we've all got a copy laying around somewhere, right? Oh wait, it's not 1999! So they want to charge you about 60 cents per country name? Not acceptable.
So what's a developer to do? Scrape the site? Write his one-line regular expression to pull out the data? Solve his own problem and move on?
Nah, let's make things better so that other developers don't lose precious time having to jump through ridiculous hoops! 
Et, voilà, I present to you Open Country Codes.
This simple and deliberately unstyled little app gives you the ISO 3166-1 and ISO 3166-1-alpha-2 country name and country code lists in a variety of ready-to-use formats. There's an HTML country list selection box that you can drop into your page, and pure data structures in Python, JavaScript, ActionScript and a CountryComboBox component for Flex.
There are also JSON and XML feeds that you can use in your applications.
The application pulls in a fresh copy of the list every day and the code samples are dynamically generated.
I hope you find this useful. If you have any suggestions for improving it, please leave me a comment here.
The Open Country Codes: ISO 3166 country names and Alpha-2 country codes in HTML, Python, JavaScript, ActionScript, Flex, JSON, and XML article by Aral Balkan, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial 2.0 UK: England License.
Subscribe to my blog
arsen
Sandip Saini
Melatonina Melatonine
Ken Simpson
Gabriela Portilla
atom
excellent - that’s really useful!
June 1st, 2008 at 11:26 pmCyril Doussin
This is really handy Aral, thanks a lot!
(Note: the very picky person that I am noticed that on the Python page you’d really want to say “As a list of dictionaries”, but, yeah, whatever…)
Good to see you playing with Django btw!
June 1st, 2008 at 11:30 pmJames Turnbull
Aral,
Thanks for this, I’ve scraped that page numerous times myself so it’s comforting to know I’ll never have to bother again.
One minor issue I noticed is that your Title Casing of the country names is a bit off: “Virgin Islands, U.s.” should of course be “U.S.” and there’s debatable casing of “And” and “Of”.
Maybe you’ll have better results with Gruber’s style?
June 1st, 2008 at 11:34 pmAshe Dryden
Excellent. Hoping to port this to a few modules that Drupal uses. Thanks
June 1st, 2008 at 11:38 pmDru
Any hope that we might see a Web Services enabled, or better yet (from my perspective) a Flash Remoting enabled version of the “feeds?”
June 1st, 2008 at 11:41 pmjnakai
Thank you so, so much! This is excellent.
June 2nd, 2008 at 12:09 amJB
Thanks…very useful - but what about alpha-3? Hint, hint…
June 2nd, 2008 at 2:15 amDan
If anyone is looking for languages, I made up a Flex comboBox component for ISO 639-1 language codes. its based off a similar component made made by Peter Elst. demo and source available here: http://dansbigwebpage.com/blog/downloads/
-Dan
June 2nd, 2008 at 4:02 amNathan de Vries
Just to let you know, I can’t comment on your site using Firefox (Linux) so I’m using Opera. Here’s my user agent:
“Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.8.1.14) Gecko/20080418 Ubuntu/7.10 (gutsy) Firefox/2.0.0.14″
June 2nd, 2008 at 9:57 amalftuga
Thank you so, so much!
June 2nd, 2008 at 11:49 amAral
@Cyril: Fixed, thanks for the heads up — and Django rocks big time!
@James: Ah, I’m going to look into the capitalization issue. I’m using my own implementation that handles embedded unicode in the form \uNNNN correctly (neither the built-in string.title() nor Gruber’s handles this well; they both capitalize the U). I will look through Gruber’s again and implement some of the niceties there while maintaining the unicode support.
@Dru: I might add new formats as time goes on. Adding Flash Remoting support is trivial with pyamf. Not sure about web services (just haven’t done anything with them in Python) but I’m assuming it’ll be one import and a couple of lines of code (like most things in Python)
I am concentrating on getting the new Singularity web site up this week, though, so don’t expect an immediate update on this front.
@JB: Can you give me a real-world use-case for alpha-3? I’m not against implementing it, I just want to know where it would be used (everything I’ve seen on the Net pretty much seems to use alpha-2.)
@Nathan: Sorry about that — not sure why you’re experiencing it. I wonder if the theme I’m using on the blog has something to do with it. Must port blog to Python, must port blog to Python (2009?)
If you can narrow this down at all, please do let me know.
@atom, @Ashe, @jnakai, @alftuga: You’re very welcome — I’m glad you’re finding it useful
June 2nd, 2008 at 2:52 pmAral
James, I ended up hacking my own implementation to get the title-case right. Thank you so much for the heads up.
It should be correct now — please let me know if you still notice any issues.
June 2nd, 2008 at 4:00 pmStuart
Nice one Aral this is very handy.
Minor point; in Python a tuple of tuples would work well for data like this (which is unlikely to be changed at runtime) as it’s more efficient use of memory.
June 2nd, 2008 at 4:55 pmAral
Hey Stuart,
Cool, I added tuple of tuples to the Python view. Thanks for the tip
June 2nd, 2008 at 5:15 pmEdd Parris
Hey Aral
How did you get a google app to ‘refresh’ once a day?
Ive been thinking about using app engine for an app that would need to query an rss feed once an hour then generate db entries based on that feed.
cheers
June 2nd, 2008 at 7:18 pmEdd
Aral
Hi Edd,
I use memcache to cache the results with the refresh set to one day.
June 2nd, 2008 at 7:36 pmNoel
This is great. I’ve scraped wikipedia for similar content in the past, but this makes it way easier.
The only feature you’re missing is the ability to pass in a locale to get language specific translations of the country names.
Noel
June 3rd, 2008 at 3:32 amAdrian Parr
Hi Aral,
Good thinking. Thanks for taking the time out of your busy schedule to do this for the development community.
Adrian
June 3rd, 2008 at 9:53 amJames Turnbull
Aral,
We’ll seeing as you asked, here’s the edge cases I spotted, there’s no doubt more. Title casing English is stupidly complex, but introduce foreign country names and it just gets silly!
Heard Island and Mcdonald Islands (McDonald)
RÉunion (Réunion)
Saint BarthÉlemy (Barthélemy)
CÔte D’ivoire (Côte d’Ivoire)
Congo, the Democratic Republic of the
Macedonia, the Former Yugoslav Republic of (for these two the first “The” should be capitalised).
Is the source of the scraper open sourced?
June 3rd, 2008 at 10:51 amAral
Hey James,
Thanks so much for taking the time to send me these.
The erroneous capitalization of É, Ô, etc. was because I was using string methods in certain places instead of unicode e.g., string.lower() instead of unicode.lower(). I’ve now made sure that I’m using unicode everywhere.
I’ve special-cased the other three edge cases as I don’t too much time to devote to making the titlecaser truly generic.
I’m going to put the source up as soon as I get a moment (I’ll update this thread when I do).
_runs off to continue working on the Singularity web site_
June 3rd, 2008 at 5:04 pmAral
By the way, I quickly added (only to the HTML, JS, AS, and Python views at the moment), the option to have the country names truncated by passing a length in the URL (e.g., http://opencountrycodes.appspot.com/html/33). Don’t bank on this syntax staying the same (especially if I’m going to add language support in the future, the URIs might be /html/en/10.)
June 3rd, 2008 at 5:10 pmMurten Saerbi
Great post!
Comes in very handy for a country login thingie-majingy i need to finish, thanks alot.
Murten Saerbi
June 4th, 2008 at 7:05 pmcelil
thanks. super site
June 12th, 2008 at 1:23 pmraxy
HI,
congrats ! big idea and great implem !
In my company, I’m in charge of such a subjet and we intend to internally implement a central service (maybe rdf centric ?) for all our applications.
Where do you go from here now ?
June 19th, 2008 at 3:15 pmJohn
What would be really cool is if you could also include the 3 letter codes, the 3 digit codes, and the currency code for each country.
Thanks for what you have done.
July 16th, 2008 at 1:28 amRobert Ross
Why not a Java enum implementation as well?
October 31st, 2008 at 3:35 pmRichy C.
I’ve got another vote for 3 letter country codes (commonly used on machine readable passports and using 3 characters allows the implementation to be more flexible for ‘made-up countries’ and future expansion).
PHP arrays (and different translations of the country names) would be brilliant!
December 19th, 2008 at 3:20 pmMark Melville
This is amazing. I would like to see it go a step farther and include 3166-2 so that state/province can be populated as well.
February 3rd, 2009 at 7:39 pm