Aral Balkan

Introducing Open Country Codes: easy to use ISO 3166 country codes for your apps.

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.

Comments

• Hi Edd, I use memcache to cache the results with the refresh set to one day.

  by Aral on 2008-06-02 18:36:04

• 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

  by Dan on 2008-06-02 03:02:30

• Thanks...very useful - but what about alpha-3? Hint, hint...

  by JB on 2008-06-02 01:15:37

• 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?

  by James Turnbull on 2008-06-03 09:51:17

• Hi Aral, Good thinking. Thanks for taking the time out of your busy schedule to do this for the development community. Adrian

  by Adrian Parr on 2008-06-03 08:53:51

• 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 Edd

  by Edd Parris on 2008-06-02 18:18:22

• 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_

  by Aral on 2008-06-03 16:04:23

• 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.)

  by Aral on 2008-06-03 16:10:06

• 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?

  by James Turnbull on 2008-06-01 22:34:16

• Thank you so, so much! This is excellent.

  by jnakai on 2008-06-01 23:09:52

• 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.

  by John on 2008-07-16 00:28:43

• Thank you so, so much!

  by alftuga on 2008-06-02 10:49:06

• 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.

  by Stuart on 2008-06-02 15:55:40

• Any hope that we might see a Web Services enabled, or better yet (from my perspective) a Flash Remoting enabled version of the "feeds?"

  by Dru on 2008-06-01 22:41:06

• @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 :)

  by Aral on 2008-06-02 13:52:53

• 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.

  by Aral on 2008-06-02 15:00:05

• thanks. super site

  by celil on 2008-06-12 12:23:22

• 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!

  by Cyril Doussin on 2008-06-01 22:30:17

• excellent - that's really useful! :-D

  by atom on 2008-06-01 22:26:00

• Excellent. Hoping to port this to a few modules that Drupal uses. Thanks :D

  by Ashe Dryden on 2008-06-01 22:38:40

• Great post! Comes in very handy for a country login thingie-majingy i need to finish, thanks alot. Murten Saerbi

  by Murten Saerbi on 2008-06-04 18:05:55

• 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 ?

  by raxy on 2008-06-19 14:15:24

• 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"

  by Nathan de Vries on 2008-06-02 08:57:54

• Hey Stuart, Cool, I added tuple of tuples to the Python view. Thanks for the tip :)

  by Aral on 2008-06-02 16:15:36

• 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

  by Noel on 2008-06-03 02:32:46

• Why not a Java enum implementation as well?

  by Robert Ross on 2008-10-31 14:35:59

• 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.

  by Mark Melville on 2009-02-03 18:39:20

• 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!

  by Richy C. on 2008-12-19 14:20:32

• [...] public links >> 3166 ISO 3166 country names and 2-letter country codes for HTML, Python ... Saved by debaird on Sat 01-11-2008 Jeroen Frijters: New Development Snapshot Saved by [...]

  by Recent Links Tagged With "3166" - JabberTags on 2008-11-02 14:34:34

• It looks like this has been broken for a number of months - all the feeds are empty. Any chance of fixing it?

  by Stuart Herring on 2010-03-10 09:58:19

• Great idea! However, I find the (e.g. JSON) data structure you chose somehow sub-optimal. Checking values for validity assumes that one has to iterate over the whole array and checking each object's key for existence of a value. Why not using a flat object?

  by Peter Geil on 2010-06-10 17:42:45

• Hi, First of all, absolutely fantastic that you've created an open version of this, very much appreciated. However, it doesn't seem to work anymore, all of the lists are empty. Will this be fixed ? And, does it have the country name also in native language (e.g. "Germany" = "Deutschland") ? Cheers, Rens

  by Rens on 2011-07-20 13:19:56

• just wonder, I'm looking for a list with country calling codes, for input choice when adding phone numbers in an app. Is there something similar, or would this list work here? Guess I'd need another table with the prefixes (+45, +34 etc) right? Cheers

  by Petter Palander on 2011-06-10 12:07:39

• Simply they doesn't work. Nothing returned from any links in http://opencountrycodes.appspot.com

  by Gabri on 2011-10-16 13:30:32

• Nice, but the site seems to return empty data sets? No countries :(

  by o_0oo on 2011-12-02 11:55:53

• All your feeds are empty, bro. Could you get that fixed? :-)

  by Tomas Sandven on 2012-01-22 22:43:45