geosub v0.1.2a0
Lookup ISO 3166-2 geographic subdivisions from postal and country codes.
It leverages offline data from www.geonames.org to determine the approximate location and search for the geographic subdivision information from pycountry, all without the need for network requests or external APIs.
Contents:
Contents:
Introduction
geosub aims to provide a straightforward and efficient solution for applications requiring geographic subdivision data.
It is less feature-rich and complete, but easier to use and lighter than API-based services.
Features include:
No API Key Required: No need to manage API keys, pay fees, or use external API services.
Offline Functionality: Performs all operations offline.
Bundled Data: Comes packaged with all necessary geographical data.
On-Demand Data Loading: Loads data as needed to minimize memory usage.
Minimal Dependencies: Keeps additional dependencies to a minimum.
Getting Started
To get started with geosub, see the Installation section, followed by the Usage guide to see how to implement geosub in your projects.
Limitations
Some countries are not supported, and there are no guarantees that every postal code will be found.
Here are some details about supported and unsupported locations:
- geosub.SUPPORTED_COUNTRY_CODES = ['AD', 'AR', 'AU', 'AT', 'AZ', 'BE', 'BR', 'CA', 'CH', 'CN', 'CO', 'CY', 'CZ', 'DE', 'DZ', 'EC', 'ES', 'FI', 'FR', 'GB', 'GP', 'GT', 'GF', 'HR', 'HU', 'IN', 'IE', 'IT', 'JP', 'LI', 'LK', 'LU', 'MA', 'MC', 'MX', 'MT', 'MQ', 'MW', 'MY', 'YT', 'NL', 'NO', 'NZ', 'PK', 'PE', 'PH', 'PT', 'RE', 'RO', 'SJ', 'PM', 'SK', 'SE', 'TH', 'TR', 'UA', 'UY', 'US', 'WF']
ISO 3166-1 alpha-2 codes that should be supported.
There may still be some gaps in the data, especially within some of the smaller territories.
- geosub.SUPPORTED_LOCATIONS = ['Andorra', 'Argentina', 'Australia', 'Austria', 'Azerbaijan', 'Belgium', 'Brazil', 'Canada', 'Switzerland', 'China', 'Colombia', 'Cyprus', 'Czechia', 'Germany', 'Algeria', 'Ecuador', 'Spain', 'Finland', 'France', 'United Kingdom', 'Guadeloupe', 'Guatemala', 'French Guiana', 'Croatia', 'Hungary', 'India', 'Ireland', 'Italy', 'Japan', 'Liechtenstein', 'Sri Lanka', 'Luxembourg', 'Morocco', 'Monaco', 'Mexico', 'Malta', 'Martinique', 'Malawi', 'Malaysia', 'Mayotte', 'Netherlands', 'Norway', 'New Zealand', 'Pakistan', 'Peru', 'Philippines', 'Portugal', 'Réunion', 'Romania', 'Svalbard and Jan Mayen', 'Saint Pierre and Miquelon', 'Slovakia', 'Sweden', 'Thailand', 'Türkiye', 'Ukraine', 'Uruguay', 'United States', 'Wallis and Futuna']
Countries, territories or areas of interest that should be supported.
There may still be some gaps in the data, especially within some of the smaller territories.
- geosub.UNSUPPORTED_COUNTRY_CODES = ['AW', 'AF', 'AO', 'AI', 'AX', 'AL', 'AE', 'AM', 'AS', 'AQ', 'TF', 'AG', 'BI', 'BJ', 'BQ', 'BF', 'BD', 'BG', 'BH', 'BS', 'BA', 'BL', 'BY', 'BZ', 'BM', 'BO', 'BB', 'BN', 'BT', 'BV', 'BW', 'CF', 'CC', 'CL', 'CI', 'CM', 'CD', 'CG', 'CK', 'KM', 'CV', 'CR', 'CU', 'CW', 'CX', 'KY', 'DJ', 'DM', 'DK', 'DO', 'EG', 'ER', 'EH', 'EE', 'ET', 'FJ', 'FK', 'FO', 'FM', 'GA', 'GE', 'GG', 'GH', 'GI', 'GN', 'GM', 'GW', 'GQ', 'GR', 'GD', 'GL', 'GU', 'GY', 'HK', 'HM', 'HN', 'HT', 'ID', 'IM', 'IO', 'IR', 'IQ', 'IS', 'IL', 'JM', 'JE', 'JO', 'KZ', 'KE', 'KG', 'KH', 'KI', 'KN', 'KR', 'KW', 'LA', 'LB', 'LR', 'LY', 'LC', 'LS', 'LT', 'LV', 'MO', 'MF', 'MD', 'MG', 'MV', 'MH', 'MK', 'ML', 'MM', 'ME', 'MN', 'MP', 'MZ', 'MR', 'MS', 'MU', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NU', 'NP', 'NR', 'OM', 'PA', 'PN', 'PW', 'PG', 'PL', 'PR', 'KP', 'PY', 'PS', 'PF', 'QA', 'RU', 'RW', 'SA', 'SD', 'SN', 'SG', 'GS', 'SH', 'SB', 'SL', 'SV', 'SM', 'SO', 'RS', 'SS', 'ST', 'SR', 'SI', 'SZ', 'SX', 'SC', 'SY', 'TC', 'TD', 'TG', 'TJ', 'TK', 'TM', 'TL', 'TO', 'TT', 'TN', 'TV', 'TW', 'TZ', 'UG', 'UM', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WS', 'YE', 'ZA', 'ZM', 'ZW']
ISO 3166-1 alpha-2 codes that are not supported.
- geosub.UNSUPPORTED_LOCATIONS = ['Aruba', 'Afghanistan', 'Angola', 'Anguilla', 'Åland Islands', 'Albania', 'United Arab Emirates', 'Armenia', 'American Samoa', 'Antarctica', 'French Southern Territories', 'Antigua and Barbuda', 'Burundi', 'Benin', 'Bonaire, Sint Eustatius and Saba', 'Burkina Faso', 'Bangladesh', 'Bulgaria', 'Bahrain', 'Bahamas', 'Bosnia and Herzegovina', 'Saint Barthélemy', 'Belarus', 'Belize', 'Bermuda', 'Bolivia, Plurinational State of', 'Barbados', 'Brunei Darussalam', 'Bhutan', 'Bouvet Island', 'Botswana', 'Central African Republic', 'Cocos (Keeling) Islands', 'Chile', "Côte d'Ivoire", 'Cameroon', 'Congo, The Democratic Republic of the', 'Congo', 'Cook Islands', 'Comoros', 'Cabo Verde', 'Costa Rica', 'Cuba', 'Curaçao', 'Christmas Island', 'Cayman Islands', 'Djibouti', 'Dominica', 'Denmark', 'Dominican Republic', 'Egypt', 'Eritrea', 'Western Sahara', 'Estonia', 'Ethiopia', 'Fiji', 'Falkland Islands (Malvinas)', 'Faroe Islands', 'Micronesia, Federated States of', 'Gabon', 'Georgia', 'Guernsey', 'Ghana', 'Gibraltar', 'Guinea', 'Gambia', 'Guinea-Bissau', 'Equatorial Guinea', 'Greece', 'Grenada', 'Greenland', 'Guam', 'Guyana', 'Hong Kong', 'Heard Island and McDonald Islands', 'Honduras', 'Haiti', 'Indonesia', 'Isle of Man', 'British Indian Ocean Territory', 'Iran, Islamic Republic of', 'Iraq', 'Iceland', 'Israel', 'Jamaica', 'Jersey', 'Jordan', 'Kazakhstan', 'Kenya', 'Kyrgyzstan', 'Cambodia', 'Kiribati', 'Saint Kitts and Nevis', 'Korea, Republic of', 'Kuwait', "Lao People's Democratic Republic", 'Lebanon', 'Liberia', 'Libya', 'Saint Lucia', 'Lesotho', 'Lithuania', 'Latvia', 'Macao', 'Saint Martin (French part)', 'Moldova, Republic of', 'Madagascar', 'Maldives', 'Marshall Islands', 'North Macedonia', 'Mali', 'Myanmar', 'Montenegro', 'Mongolia', 'Northern Mariana Islands', 'Mozambique', 'Mauritania', 'Montserrat', 'Mauritius', 'Namibia', 'New Caledonia', 'Niger', 'Norfolk Island', 'Nigeria', 'Nicaragua', 'Niue', 'Nepal', 'Nauru', 'Oman', 'Panama', 'Pitcairn', 'Palau', 'Papua New Guinea', 'Poland', 'Puerto Rico', "Korea, Democratic People's Republic of", 'Paraguay', 'Palestine, State of', 'French Polynesia', 'Qatar', 'Russian Federation', 'Rwanda', 'Saudi Arabia', 'Sudan', 'Senegal', 'Singapore', 'South Georgia and the South Sandwich Islands', 'Saint Helena, Ascension and Tristan da Cunha', 'Solomon Islands', 'Sierra Leone', 'El Salvador', 'San Marino', 'Somalia', 'Serbia', 'South Sudan', 'Sao Tome and Principe', 'Suriname', 'Slovenia', 'Eswatini', 'Sint Maarten (Dutch part)', 'Seychelles', 'Syrian Arab Republic', 'Turks and Caicos Islands', 'Chad', 'Togo', 'Tajikistan', 'Tokelau', 'Turkmenistan', 'Timor-Leste', 'Tonga', 'Trinidad and Tobago', 'Tunisia', 'Tuvalu', 'Taiwan, Province of China', 'Tanzania, United Republic of', 'Uganda', 'United States Minor Outlying Islands', 'Uzbekistan', 'Holy See (Vatican City State)', 'Saint Vincent and the Grenadines', 'Venezuela, Bolivarian Republic of', 'Virgin Islands, British', 'Virgin Islands, U.S.', 'Viet Nam', 'Vanuatu', 'Samoa', 'Yemen', 'South Africa', 'Zambia', 'Zimbabwe']
Countries, territories or areas of interest that are not supported.