flags.py

"""
Retreives relevant ICAO country code based on supplied ICAO.
Modified from https://github.com/wiedehopf/tar1090/blob/master/html/flags.js by WeegeeNumbuh1
Mostly generated from the assignment table in the appendix to Chapter 9 of
Annex 10 Vol III, Second Edition, July 2007 (with amendments through 92, 2024-11-28)
Matches this commit: https://github.com/wiedehopf/tar1090/commit/28d21edcf86182eb066b569af916feb4085656ac
Previously: 38cfa15353f9dcbee4ed1433f6873fe2a4356997
Last update: November 2025
"""
from functools import lru_cache

ICAO_Ranges = [
    {"start": 0x004000, "end": 0x0047FF, "country": "Zimbabwe", "country_code": "zw"},
    {"start": 0x006000, "end": 0x006FFF, "country": "Mozambique", "country_code": "mz"},
    {"start": 0x008000, "end": 0x00FFFF, "country": "South Africa", "country_code": "za"},
    {"start": 0x010000, "end": 0x017FFF, "country": "Egypt", "country_code": "eg"},
    {"start": 0x018000, "end": 0x01FFFF, "country": "Libya", "country_code": "ly"},
    {"start": 0x020000, "end": 0x027FFF, "country": "Morocco", "country_code": "ma"},
    {"start": 0x028000, "end": 0x02FFFF, "country": "Tunisia", "country_code": "tn"},
    {"start": 0x030000, "end": 0x0307FF, "country": "Botswana", "country_code": "bw"},
    {"start": 0x032000, "end": 0x032FFF, "country": "Burundi", "country_code": "bi"},
    {"start": 0x034000, "end": 0x034FFF, "country": "Cameroon", "country_code": "cm"},
    {"start": 0x035000, "end": 0x0357FF, "country": "Comoros", "country_code": "km"},
    {"start": 0x036000, "end": 0x036FFF, "country": "Republic of the Congo", "country_code": "cg"},
    {"start": 0x038000, "end": 0x038FFF, "country": "Côte d'Ivoire", "country_code": "ci"},
    {"start": 0x03E000, "end": 0x03EFFF, "country": "Gabon", "country_code": "ga"},
    {"start": 0x040000, "end": 0x040FFF, "country": "Ethiopia", "country_code": "et"},
    {"start": 0x042000, "end": 0x042FFF, "country": "Equatorial Guinea", "country_code": "gq"},
    {"start": 0x044000, "end": 0x044FFF, "country": "Ghana", "country_code": "gh"},
    {"start": 0x046000, "end": 0x046FFF, "country": "Guinea", "country_code": "gn"},
    {"start": 0x048000, "end": 0x0487FF, "country": "Guinea-Bissau", "country_code": "gw"},
    {"start": 0x04A000, "end": 0x04A7FF, "country": "Lesotho", "country_code": "ls"},
    {"start": 0x04C000, "end": 0x04CFFF, "country": "Kenya", "country_code": "ke"},
    {"start": 0x050000, "end": 0x050FFF, "country": "Liberia", "country_code": "lr"},
    {"start": 0x054000, "end": 0x054FFF, "country": "Madagascar", "country_code": "mg"},
    {"start": 0x058000, "end": 0x058FFF, "country": "Malawi", "country_code": "mw"},
    {"start": 0x05A000, "end": 0x05A7FF, "country": "Maldives", "country_code": "mv"},
    {"start": 0x05C000, "end": 0x05CFFF, "country": "Mali", "country_code": "ml"},
    {"start": 0x05E000, "end": 0x05E7FF, "country": "Mauritania", "country_code": "mr"},
    {"start": 0x060000, "end": 0x0607FF, "country": "Mauritius", "country_code": "mu"},
    {"start": 0x062000, "end": 0x062FFF, "country": "Niger", "country_code": "ne"},
    {"start": 0x064000, "end": 0x064FFF, "country": "Nigeria", "country_code": "ng"},
    {"start": 0x068000, "end": 0x068FFF, "country": "Uganda", "country_code": "ug"},
    {"start": 0x06A000, "end": 0x06AFFF, "country": "Qatar", "country_code": "qa"},
    {"start": 0x06C000, "end": 0x06CFFF, "country": "Central African Republic", "country_code": "cf"},
    {"start": 0x06E000, "end": 0x06EFFF, "country": "Rwanda", "country_code": "rw"},
    {"start": 0x070000, "end": 0x070FFF, "country": "Senegal", "country_code": "sn"},
    {"start": 0x074000, "end": 0x0747FF, "country": "Seychelles", "country_code": "sc"},
    {"start": 0x076000, "end": 0x0767FF, "country": "Sierra Leone", "country_code": "sl"},
    {"start": 0x078000, "end": 0x078FFF, "country": "Somalia", "country_code": "so"},
    {"start": 0x07A000, "end": 0x07A7FF, "country": "Eswatini", "country_code": "sz"},
    {"start": 0x07C000, "end": 0x07CFFF, "country": "Sudan", "country_code": "sd"},
    {"start": 0x080000, "end": 0x080FFF, "country": "Tanzania", "country_code": "tz"},
    {"start": 0x084000, "end": 0x084FFF, "country": "Chad", "country_code": "td"},
    {"start": 0x088000, "end": 0x088FFF, "country": "Togo", "country_code": "tg"},
    {"start": 0x08A000, "end": 0x08AFFF, "country": "Zambia", "country_code": "zm"},
    {"start": 0x08C000, "end": 0x08CFFF, "country": "DR Congo", "country_code": "cd"},
    {"start": 0x090000, "end": 0x090FFF, "country": "Angola", "country_code": "ao"},
    {"start": 0x094000, "end": 0x0947FF, "country": "Benin", "country_code": "bj"},
    {"start": 0x096000, "end": 0x0967FF, "country": "Cabo Verde", "country_code": "cv"},
    {"start": 0x098000, "end": 0x0987FF, "country": "Djibouti", "country_code": "dj"},
    {"start": 0x09A000, "end": 0x09AFFF, "country": "Gambia", "country_code": "gm"},
    {"start": 0x09C000, "end": 0x09CFFF, "country": "Burkina Faso", "country_code": "bf"},
    {"start": 0x09E000, "end": 0x09E7FF, "country": "São Tomé and Príncipe", "country_code": "st"},
    {"start": 0x0A0000, "end": 0x0A7FFF, "country": "Algeria", "country_code": "dz"},
    {"start": 0x0A8000, "end": 0x0A8FFF, "country": "Bahamas", "country_code": "bs"},
    {"start": 0x0AA000, "end": 0x0AA7FF, "country": "Barbados", "country_code": "bb"},
    {"start": 0x0AB000, "end": 0x0AB7FF, "country": "Belize", "country_code": "bz"},
    {"start": 0x0AC000, "end": 0x0ADFFF, "country": "Colombia", "country_code": "co"},
    {"start": 0x0AE000, "end": 0x0AEFFF, "country": "Costa Rica", "country_code": "cr"},
    {"start": 0x0B0000, "end": 0x0B0FFF, "country": "Cuba", "country_code": "cu"},
    {"start": 0x0B2000, "end": 0x0B2FFF, "country": "El Salvador", "country_code": "sv"},
    {"start": 0x0B4000, "end": 0x0B4FFF, "country": "Guatemala", "country_code": "gt"},
    {"start": 0x0B6000, "end": 0x0B6FFF, "country": "Guyana", "country_code": "gy"},
    {"start": 0x0B8000, "end": 0x0B8FFF, "country": "Haiti", "country_code": "ht"},
    {"start": 0x0BA000, "end": 0x0BAFFF, "country": "Honduras", "country_code": "hn"},
    {"start": 0x0BC000, "end": 0x0BC7FF, "country": "Saint Vincent and the Grenadines", "country_code": "vc"},
    {"start": 0x0BE000, "end": 0x0BEFFF, "country": "Jamaica", "country_code": "jm"},
    {"start": 0x0C0000, "end": 0x0C0FFF, "country": "Nicaragua", "country_code": "ni"},
    {"start": 0x0C2000, "end": 0x0C2FFF, "country": "Panama", "country_code": "pa"},
    {"start": 0x0C4000, "end": 0x0C4FFF, "country": "Dominican Republic", "country_code": "do"},
    {"start": 0x0C6000, "end": 0x0C6FFF, "country": "Trinidad and Tobago", "country_code": "tt"},
    {"start": 0x0C8000, "end": 0x0C8FFF, "country": "Suriname", "country_code": "sr"},
    {"start": 0x0CA000, "end": 0x0CA7FF, "country": "Antigua and Barbuda", "country_code": "ag"},
    {"start": 0x0CC000, "end": 0x0CC7FF, "country": "Grenada", "country_code": "gd"},
    {"start": 0x0D0000, "end": 0x0D7FFF, "country": "Mexico", "country_code": "mx"},
    {"start": 0x0D8000, "end": 0x0DFFFF, "country": "Venezuela", "country_code": "ve"},
    {"start": 0x100000, "end": 0x1FFFFF, "country": "Russia", "country_code": "ru"},
    {"start": 0x201000, "end": 0x2017FF, "country": "Namibia", "country_code": "na"},
    {"start": 0x202000, "end": 0x2027FF, "country": "Eritrea", "country_code": "er"},
    {"start": 0x300000, "end": 0x33FFFF, "country": "Italy", "country_code": "it"},
    {"start": 0x340000, "end": 0x37FFFF, "country": "Spain", "country_code": "es"},
    {"start": 0x380000, "end": 0x3BFFFF, "country": "France", "country_code": "fr"},
    {"start": 0x3C0000, "end": 0x3FFFFF, "country": "Germany", "country_code": "de"},
    # UK territories are officially part of the UK range
    # add extra entries that are above the UK and take precedence
    {"start": 0x400000, "end": 0x4001BF, "country": "Bermuda", "country_code": "bm"},
    {"start": 0x4001C0, "end": 0x4001FF, "country": "Cayman Islands", "country_code": "ky"},
    {"start": 0x400300, "end": 0x4003FF, "country": "Turks and Caicos Islands", "country_code": "tc"},
    {"start": 0x424135, "end": 0x4241F2, "country": "Cayman Islands", "country_code": "ky"},
    {"start": 0x424200, "end": 0x4246FF, "country": "Bermuda", "country_code": "bm"},
    {"start": 0x424700, "end": 0x424899, "country": "Cayman Islands", "country_code": "ky"},
    {"start": 0x424B00, "end": 0x424BFF, "country": "Isle of Man", "country_code": "im"},
    {"start": 0x43BE00, "end": 0x43BEFF, "country": "Bermuda", "country_code": "bm"},
    {"start": 0x43E700, "end": 0x43EAFD, "country": "Isle of Man", "country_code": "im"},
    {"start": 0x43EAFE, "end": 0x43EEFF, "country": "Guernsey", "country_code": "gg"},
    # catch all United Kingdom for the even more obscure stuff
    {"start": 0x400000, "end": 0x43FFFF, "country": "United Kingdom", "country_code": "gb"},
    {"start": 0x440000, "end": 0x447FFF, "country": "Austria", "country_code": "at"},
    {"start": 0x448000, "end": 0x44FFFF, "country": "Belgium", "country_code": "be"},
    {"start": 0x450000, "end": 0x457FFF, "country": "Bulgaria", "country_code": "bg"},
    {"start": 0x458000, "end": 0x45FFFF, "country": "Denmark", "country_code": "dk"},
    {"start": 0x460000, "end": 0x467FFF, "country": "Finland", "country_code": "fi"},
    {"start": 0x468000, "end": 0x46FFFF, "country": "Greece", "country_code": "gr"},
    {"start": 0x470000, "end": 0x477FFF, "country": "Hungary", "country_code": "hu"},
    {"start": 0x478000, "end": 0x47FFFF, "country": "Norway", "country_code": "no"},
    {"start": 0x480000, "end": 0x487FFF, "country": "Netherlands", "country_code": "nl"},
    {"start": 0x488000, "end": 0x48FFFF, "country": "Poland", "country_code": "pl"},
    {"start": 0x490000, "end": 0x497FFF, "country": "Portugal", "country_code": "pt"},
    {"start": 0x498000, "end": 0x49FFFF, "country": "Czechia", "country_code": "cz"},
    {"start": 0x4A0000, "end": 0x4A7FFF, "country": "Romania", "country_code": "ro"},
    {"start": 0x4A8000, "end": 0x4AFFFF, "country": "Sweden", "country_code": "se"},
    {"start": 0x4B0000, "end": 0x4B7FFF, "country": "Switzerland", "country_code": "ch"},
    {"start": 0x4B8000, "end": 0x4BFFFF, "country": "Turkey", "country_code": "tr"},
    {"start": 0x4C0000, "end": 0x4C7FFF, "country": "Serbia", "country_code": "rs"},
    {"start": 0x4C8000, "end": 0x4C87FF, "country": "Cyprus", "country_code": "cy"},
    {"start": 0x4CA000, "end": 0x4CAFFF, "country": "Ireland", "country_code": "ie"},
    {"start": 0x4CC000, "end": 0x4CCFFF, "country": "Iceland", "country_code": "is"},
    {"start": 0x4D0000, "end": 0x4D07FF, "country": "Luxembourg", "country_code": "lu"},
    {"start": 0x4D2000, "end": 0x4D27FF, "country": "Malta", "country_code": "mt"},
    {"start": 0x4D4000, "end": 0x4D47FF, "country": "Monaco", "country_code": "mc"},
    {"start": 0x500000, "end": 0x5007FF, "country": "San Marino", "country_code": "sm"},
    {"start": 0x501000, "end": 0x5017FF, "country": "Albania", "country_code": "al"},
    {"start": 0x501800, "end": 0x501FFF, "country": "Croatia", "country_code": "hr"},
    {"start": 0x502800, "end": 0x502FFF, "country": "Latvia", "country_code": "lv"},
    {"start": 0x503800, "end": 0x503FFF, "country": "Lithuania", "country_code": "lt"},
    {"start": 0x504800, "end": 0x504FFF, "country": "Moldova", "country_code": "md"},
    {"start": 0x505800, "end": 0x505FFF, "country": "Slovakia", "country_code": "sk"},
    {"start": 0x506800, "end": 0x506FFF, "country": "Slovenia", "country_code": "si"},
    {"start": 0x507800, "end": 0x507FFF, "country": "Uzbekistan", "country_code": "uz"},
    {"start": 0x508000, "end": 0x50FFFF, "country": "Ukraine", "country_code": "ua"},
    {"start": 0x510000, "end": 0x5107FF, "country": "Belarus", "country_code": "by"},
    {"start": 0x511000, "end": 0x5117FF, "country": "Estonia", "country_code": "ee"},
    {"start": 0x512000, "end": 0x5127FF, "country": "North Macedonia", "country_code": "mk"},
    {"start": 0x513000, "end": 0x5137FF, "country": "Bosnia and Herzegovina", "country_code": "ba"},
    {"start": 0x514000, "end": 0x5147FF, "country": "Georgia", "country_code": "ge"},
    {"start": 0x515000, "end": 0x5157FF, "country": "Tajikistan", "country_code": "tj"},
    {"start": 0x516000, "end": 0x5167FF, "country": "Montenegro", "country_code": "me"},
    {"start": 0x600000, "end": 0x6007FF, "country": "Armenia", "country_code": "am"},
    {"start": 0x600800, "end": 0x600FFF, "country": "Azerbaijan", "country_code": "az"},
    {"start": 0x601000, "end": 0x6017FF, "country": "Kyrgyzstan", "country_code": "kg"},
    {"start": 0x601800, "end": 0x601FFF, "country": "Turkmenistan", "country_code": "tm"},
    {"start": 0x680000, "end": 0x6807FF, "country": "Bhutan", "country_code": "bt"},
    {"start": 0x681000, "end": 0x6817FF, "country": "Micronesia, Federated States of", "country_code": "fm"},
    {"start": 0x682000, "end": 0x6827FF, "country": "Mongolia", "country_code": "mn"},
    {"start": 0x683000, "end": 0x6837FF, "country": "Kazakhstan", "country_code": "kz"},
    {"start": 0x684000, "end": 0x6847FF, "country": "Palau", "country_code": "pw"},
    {"start": 0x700000, "end": 0x700FFF, "country": "Afghanistan", "country_code": "af"},
    {"start": 0x702000, "end": 0x702FFF, "country": "Bangladesh", "country_code": "bd"},
    {"start": 0x704000, "end": 0x704FFF, "country": "Myanmar", "country_code": "mm"},
    {"start": 0x706000, "end": 0x706FFF, "country": "Kuwait", "country_code": "kw"},
    {"start": 0x708000, "end": 0x708FFF, "country": "Laos", "country_code": "la"},
    {"start": 0x70A000, "end": 0x70AFFF, "country": "Nepal", "country_code": "np"},
    {"start": 0x70C000, "end": 0x70C7FF, "country": "Oman", "country_code": "om"},
    {"start": 0x70E000, "end": 0x70EFFF, "country": "Cambodia", "country_code": "kh"},
    {"start": 0x710000, "end": 0x717FFF, "country": "Saudi Arabia", "country_code": "sa"},
    {"start": 0x718000, "end": 0x71FFFF, "country": "South Korea", "country_code": "kr"},
    {"start": 0x720000, "end": 0x727FFF, "country": "North Korea", "country_code": "kp"},
    {"start": 0x728000, "end": 0x72FFFF, "country": "Iraq", "country_code": "iq"},
    {"start": 0x730000, "end": 0x737FFF, "country": "Iran", "country_code": "ir"},
    {"start": 0x738000, "end": 0x73FFFF, "country": "Israel", "country_code": "il"},
    {"start": 0x740000, "end": 0x747FFF, "country": "Jordan", "country_code": "jo"},
    {"start": 0x748000, "end": 0x74FFFF, "country": "Lebanon", "country_code": "lb"},
    {"start": 0x750000, "end": 0x757FFF, "country": "Malaysia", "country_code": "my"},
    {"start": 0x758000, "end": 0x75FFFF, "country": "Philippines", "country_code": "ph"},
    {"start": 0x760000, "end": 0x767FFF, "country": "Pakistan", "country_code": "pk"},
    {"start": 0x768000, "end": 0x76FFFF, "country": "Singapore", "country_code": "sg"},
    {"start": 0x770000, "end": 0x777FFF, "country": "Sri Lanka", "country_code": "lk"},
    {"start": 0x778000, "end": 0x77FFFF, "country": "Syria", "country_code": "sy"},
    {"start": 0x789000, "end": 0x789FFF, "country": "Hong Kong", "country_code": "hk"},
    {"start": 0x780000, "end": 0x7BFFFF, "country": "China", "country_code": "cn"},
    {"start": 0x7C0000, "end": 0x7FFFFF, "country": "Australia", "country_code": "au"},
    {"start": 0x800000, "end": 0x83FFFF, "country": "India", "country_code": "in"},
    {"start": 0x840000, "end": 0x87FFFF, "country": "Japan", "country_code": "jp"},
    {"start": 0x880000, "end": 0x887FFF, "country": "Thailand", "country_code": "th"},
    {"start": 0x888000, "end": 0x88FFFF, "country": "Viet Nam", "country_code": "vn"},
    {"start": 0x890000, "end": 0x890FFF, "country": "Yemen", "country_code": "ye"},
    {"start": 0x894000, "end": 0x894FFF, "country": "Bahrain", "country_code": "bh"},
    {"start": 0x895000, "end": 0x8957FF, "country": "Brunei", "country_code": "bn"},
    {"start": 0x896000, "end": 0x896FFF, "country": "United Arab Emirates", "country_code": "ae"},
    {"start": 0x897000, "end": 0x8977FF, "country": "Solomon Islands", "country_code": "sb"},
    {"start": 0x898000, "end": 0x898FFF, "country": "Papua New Guinea", "country_code": "pg"},
    {"start": 0x899000, "end": 0x8997FF, "country": "Taiwan", "country_code": "tw"},
    {"start": 0x8A0000, "end": 0x8A7FFF, "country": "Indonesia", "country_code": "id"},
    {"start": 0x900000, "end": 0x9007FF, "country": "Marshall Islands", "country_code": "mh"},
    {"start": 0x901000, "end": 0x9017FF, "country": "Cook Islands", "country_code": "sk"},
    {"start": 0x902000, "end": 0x9027FF, "country": "Samoa", "country_code": "ws"},
    {"start": 0xA00000, "end": 0xAFFFFF, "country": "United States", "country_code": "us"},
    {"start": 0xC00000, "end": 0xC3FFFF, "country": "Canada", "country_code": "ca"},
    {"start": 0xC80000, "end": 0xC87FFF, "country": "New Zealand", "country_code": "nz"},
    {"start": 0xC88000, "end": 0xC88FFF, "country": "Fiji", "country_code": "fj"},
    {"start": 0xC8A000, "end": 0xC8A7FF, "country": "Nauru", "country_code": "nr"},
    {"start": 0xC8C000, "end": 0xC8C7FF, "country": "Saint Lucia", "country_code": "lc"},
    {"start": 0xC8D000, "end": 0xC8D7FF, "country": "Tonga", "country_code": "to"},
    {"start": 0xC8E000, "end": 0xC8E7FF, "country": "Kiribati", "country_code": "ki"},
    {"start": 0xC90000, "end": 0xC907FF, "country": "Vanuatu", "country_code": "vu"},
    {"start": 0xC91000, "end": 0xC917FF, "country": "Andorra", "country_code": "ad"},
    {"start": 0xC92000, "end": 0xC927FF, "country": "Dominica", "country_code": "dm"},
    {"start": 0xC93000, "end": 0xC937FF, "country": "Saint Kitts and Nevis", "country_code": "kn"},
    {"start": 0xC94000, "end": 0xC947FF, "country": "South Sudan", "country_code": "ss"},
    {"start": 0xC95000, "end": 0xC957FF, "country": "Timor-Leste", "country_code": "tl"},
    {"start": 0xC97000, "end": 0xC977FF, "country": "Tuvalu", "country_code": "tv"},
    {"start": 0xE00000, "end": 0xE3FFFF, "country": "Argentina", "country_code": "ar"},
    {"start": 0xE40000, "end": 0xE7FFFF, "country": "Brazil", "country_code": "br"},
    {"start": 0xE80000, "end": 0xE80FFF, "country": "Chile", "country_code": "cl"},
    {"start": 0xE84000, "end": 0xE84FFF, "country": "Ecuador", "country_code": "ec"},
    {"start": 0xE88000, "end": 0xE88FFF, "country": "Paraguay", "country_code": "py"},
    {"start": 0xE8C000, "end": 0xE8CFFF, "country": "Peru", "country_code": "pe"},
    {"start": 0xE90000, "end": 0xE90FFF, "country": "Uruguay", "country_code": "uy"},
    {"start": 0xE94000, "end": 0xE94FFF, "country": "Bolivia", "country_code": "bo"},
    {"start": 0xF00000, "end": 0xF07FFF, "country": "ICAO (temporary)", "country_code": "??"},
    {"start": 0xF09000, "end": 0xF097FF, "country": "ICAO (special use)", "country_code": "??"},

    # Block assignments mentioned in Chapter 9 section 4, at the "end" so they are only used if
    # nothing above applies. The commented-out sections below were old assignments, just kept here for reference.
    # {"start": 0x200000, "end": 0x27FFFF, "country": "Unassigned (AFI region)", "country_code": "??"},
    # {"start": 0x280000, "end": 0x28FFFF, "country": "Unassigned (SAM region)", "country_code": "??"},
    # {"start": 0x500000, "end": 0x5FFFFF, "country": "Unassigned (EUR / NAT regions)", "country_code": "??"},
    # {"start": 0x600000, "end": 0x67FFFF, "country": "Unassigned (MID region)", "country_code": "??"},
    # {"start": 0x680000, "end": 0x6FFFFF, "country": "Unassigned (ASIA region)", "country_code": "??"},
    # {"start": 0x900000, "end": 0x9FFFFF, "country": "Unassigned (NAM / PAC regions)", "country_code": "??"},
    # {"start": 0xB00000, "end": 0xBFFFFF, "country": "Unassigned (reserved for future use)", "country_code": "??"},
    # {"start": 0xEC0000, "end": 0xEFFFFF, "country": "Unassigned (CAR region)", "country_code": "??"},
    # {"start": 0xD00000, "end": 0xDFFFFF, "country": "Unassigned (reserved for future use)", "country_code": "??"},
    # {"start": 0xF00000, "end": 0xFFFFFF, "country": "Unassigned (reserved for future use)", "country_code": "??"},
]

@lru_cache(maxsize=500)
def getICAO(icao: str) -> str:
    """ Returns country code from ICAO Range. Input must be a hexadecimal as string. Returns '??' if no match. """
    try:
        if icao.startswith("~"): return "??"
        hexa = int(icao, 16)
        for entry in ICAO_Ranges:
            if hexa >= entry['start'] and hexa <= entry['end']:
                return entry['country_code']
        return "??"
    except Exception:
        return "??"