A file with country or area codes is not necessarily straight forward. A phone
can't display much information. And a single area code may be used by many
different towns and villages.
So the location displayed may be of a region rather then a city. Or a city in a region which uses the same area code. And this may not be the biggest city in that region. Perhaps it's a place virtually unknown to anyone.
Maybe you prefer a finely grained area file. Or perhaps just a rough indication of where the call originates from.
All of this does have it's limitations. Quite often telephone numbers
can be ported outside the original region. PSTN (fixed line) telephone
numbers can also be ported to VOIP.
Some countries have abolished area codes altogether. In which case calling your next door neighbour requires dialling what used be an area code.
The same place may be known by different names using different languages or
even writing systems.
In The Netherlands, 'The Hague' is know as 'Den Haag' or 's Gravenhage'. Which is short for 'Des Graven hage'. Meaning: 'The count's hedge'. And in eastern Europe, The Hague is known as 'Гага'.
On top of that some countries are multi-lingual. In Belgium, the north speaks Dutch, the south French and the east German. In Switzerland it's French, German and Italian. Consequently, the same place may have many different names, even within the same country!
In Belgium, Antwerp is known as Antwerpen (Dutch) or Anvers (French). And Brussels as Brussel or Bruxelles.
To accommodate the above, there may be different versions of the same area- or country code file. Files in different languages. And files with different granularity or resolution.
There are two types of files;
The region files. These roughly correspond to continents. These are the lookup files of last resort. If an area code can't be found, these files will tell you the country.
And the area files. These contain the area codes of the towns and villages on a per country basis.
Area files are Alpha-Nummeric.tsv or Alpha-Nummeric-Alpha.tsv. The first bit is a two-letter ISO country code. The next bit a one to four digit country code. It may be followed by a two letter ISO code indicating language or a 'fake' (not used by ISO) code indicating resolution. The file extension is '.tsv'. Meaning: Tab Separated Values.
Region files are region1.tsv to region9.tsv. There is also a region1fs.tsv (fs: Federal States), which contains not just countries but also individual states within countries in Region 1.
These files come in two formats;
Number <Tab> Country <Line Feed>
31 The Netherlands
Number <Tab> ISO Two letter country code <Space> Location <Line Feed>
3171 NL The Hague
The first version is a entry in a region file, the second in an area file.
The character set of these files is UTF-8.
The combined length of the 'ISO CC' and 'Location' fields is limited to 20 characters and 31 bytes (with UTF-8 a character may be more then one byte).
You can add your own files. TSV files can be easily manipulated with tools like Awk, Sed and Tr.
If you find errors in any of the databases, please let me know. You can test their contents here.