Geoconvert converts (obvious) data like zipcode, postcode, address, country name, French department name, Americain state name, Canadian province or territory name to generic data.
- Languages available for country names: deutsch, english, french, portuguese, spanish.
- Languages available for capital names: deutsch, english, french.
Supports Python 3.8, 3.9, 3.10 and 3.11.
Install the latest version from Github:
pip install https://github.com/jurismarches/geoconvert/archive/master.zip>>> from geoconvert.convert import (
... address_to_country_code,
... address_to_subdivision_code,
... address_to_country_and_subdivision_codes,
... )
>>> address_to_country_code("Bienvenue à Londres") # FR
'GB'
>>> address_to_country_code("Bienvenue à Londres", lang="fr")
'GB'
>>> address_to_country_code("Bienvenue à Londres", lang="en")
>>> address_to_country_code("Welcome to Cyprus") # EN
'CY'
>>> address_to_country_code("Welcome to Los Angeles, California")
'US'
>>> address_to_country_code("Welcome to Los Angeles, CA")
>>> address_to_country_code("Willkommen bei Kairo") # DE
'EG'
>>> address_to_country_code("Bem vindo ao Afeganistão") # PT
'AF'
>>> address_to_country_code("Bienvenidos a Nueva Zelanda") # ES
'NZ'
>>> address_to_country_code("659 Ocean Ave, Lakewood, New Jersey 08701")
'US'
>>> address_to_country_code("Le Chemin des Garennes, Jersey JE3 2FE, Jersey")
'JE'
>>> address_to_subdivision_code("2 pl. Saint-Pierre, 44000 Nantes, France") # FR
'44'
>>> address_to_subdivision_code("2 pl. Saint-Pierre, 44000 Nantes", country="FR")
'44'
>>> address_to_subdivision_code("2 pl. Saint-Pierre, 44000 Nantes", country="US")
>>> address_to_subdivision_code("1800 W Erie Ave, Lorain, OH 44052") # US
'OH'
>>> address_to_subdivision_code("1800 W Erie Ave, Lorain, OH 44052", country="FR")
>>> address_to_subdivision_code("196 Voie Camillien-Houde, Montréal, QC H3H 1A1") # CA
'QC'
>>> address_to_country_and_subdivision_codes("1170 Cattus Island Blvd, Toms River, New Jersey") # US
('US', 'NJ')
>>> address_to_country_and_subdivision_codes("Montréal, Québec") # CA
('CA', 'QC')
>>> address_to_country_and_subdivision_codes("1800 W Erie Ave, Lorain, OH 44052") # US
('US', 'OH')
>>> address_to_country_and_subdivision_codes("96524 Föritztal OT Neuhaus-Schierschnitz") # DE not found
(None, None)
>>> address_to_country_and_subdivision_codes("96524 Föritztal OT Neuhaus-Schierschnitz Germany") # DE found
('DE', 'TH')
>>> address_to_country_and_subdivision_codes("Kairo", lang="de")
('EG', None)
>>> address_to_country_and_subdivision_codes("Kairo", lang="de", country="EG")
('EG', None)
>>> address_to_country_and_subdivision_codes("Kairo", lang="de", country="US")
(None, None)Geoconvert mainly provides mainly two types of functions:
- one converts an input containing a country or capital name to a two-letter country code (ISO 3166-1 alpha 2) using a set of available languages.
- the other converts an address of a given country to a subdivision code (department code for France, province or territory code for Canada, state code for the United States of America).
Some usage examples are shown below. For more examples, take a look at the unit tests.
The main function you are looking for is the following, converting a country or a capital name to a country code. By default, it uses all the available languages to guess the country code:
>>> from geoconvert.convert import address_to_country_code
>>> address_to_country_code("Bienvenue à Kinshasa") # FR
'CD'
>>> address_to_country_code("Welcome to Cyprus") # EN
'CY'
>>> address_to_country_code("Willkommen bei Kairo") # DE
'EG'
>>> address_to_country_code("Bem vindo ao Afeganistão") # PT
'AF'
>>> address_to_country_code("Bienvenidos a Nueva Zelanda") # ES
'NZ'If you known the language of your input data, you may select that language for more efficiency (available choices: "de" for german, "en" for english, "fr" for french, "pt" for portuguese):
>>> address_to_country_code("Bienvenue à Kinshasa", lang="fr")
'CD'
>>> address_to_country_code("Welcome to Cyprus", lang="en")
'CY'
>>> address_to_country_code("Willkommen bei Kairo", lang="de")
'EG'
>>> address_to_country_code("Bem vindo ao Afeganistão", lang="pt")
'AF'
>>> address_to_country_code("Bienvenidos a Nueva Zelanda", lang="es")
'NZ'There are more specific functions, for which you can also select a language (all of them are used by default):
>>> from geoconvert.convert import (
... country_name_to_country_code, capital_name_to_country_code
... )
>>> country_name_to_country_code(" Le nigéria c'est trop sympa", lang="fr")
'NG'
>>> capital_name_to_country_code('Kairo', lang="de")
'EG'Geoconvert also gives you the abilty to find the code associated to a smaller part of a given country, namely:
- the province or territory code for Canada,
- the department code for France,
- the department codes of a French region,
- the state code for the United States of America.
The main function you are looking for is address_to_subdivision_code.
It converts an address to a subdivision code.
By default, it uses all the available subdivisions to guess the subdivision code:
>>> address_to_subdivision_code("2 pl. Saint-Pierre, 44000 Nantes, France") # FR
'44'
>>> address_to_subdivision_code("1800 W Erie Ave, Lorain, OH 44052") # US
'OH'
>>> address_to_subdivision_code("196 Voie Camillien-Houde, Montréal, QC H3H 1A1") # CA
'QC'There should be no confusion between French and US postcodes:
>>> address_to_subdivision_code("2 pl. Saint-Pierre, 44000 Nantes", country="US")
>>> address_to_subdivision_code("1800 W Erie Ave, Lorain, OH 44052", country="FR")
>>> address_to_subdivision_code("96524 Föritztal OT Neuhaus-Schierschnitz", country="US")You can find the state code associated with an address, via the postcode, state name (in Portuguese) or code:
>>> from geoconvert.convert import br_address_to_state_code
>>> br_address_to_state_code("Luz, 01120-010")
'SP'
>>> br_address_to_state_code("Piauí")
'PI'
>>> br_address_to_state_code("Dourados, MS")
'MS'You may use more specific functions, depending on your needs:
>>> from geoconvert.convert import (
... br_postcode_to_state_code, br_state_name_to_state_code
... )
>>> br_postcode_to_state_code("Mariana, 04094-050")
'SP'
>>> br_state_name_to_state_code("a capital do estado do maranhao.")
'MA'You can find the province or territory code associated with an address, via the postcode, province or territory name (in French or English) or code:
>>> from geoconvert.convert import ca_address_to_province_code
>>> ca_address_to_province_code("H3T 1X6")
'QC'
>>> ca_address_to_province_code("Toronto, Ontario")
'ON'
>>> ca_address_to_province_code("Toronto, ON")
'ON'
>>> ca_address_to_province_code("Québec")
'QC'
>>> ca_address_to_province_code("Terre-Neuve-et-Labrador")
'NL'
>>> ca_address_to_province_code("Newfoundland and Labrador")
'NL'
>>> ca_address_to_province_code("Bldg 158, Iqaluit, NU X0A 0H0, Canada")
'NU'
>>> ca_address_to_province_code("52-58 Franklin Rd, Inuvik, NT X0E 0T0, Canada")
'NT'You may use more specific functions, depending on your needs:
>>> from geoconvert.convert import (
... ca_postcode_to_province_code, ca_province_name_to_province_code
... )
>>> ca_postcode_to_province_code("Iqaluit X0A 0H0")
'NU'
>>> ca_postcode_to_province_code("Inuvik X0E 0T0")
'NT'
>>> ca_province_name_to_province_code("Welcome to Ontario")
'ON'You can find the department code associated with an address or department name:
>>> from geoconvert.convert import fr_address_to_dept_code
>>> fr_address_to_dept_code("Chemin du Solarium Le Haut Vigneau 33175 GRADIGNAN CEDEX")
'33'
>>> fr_address_to_dept_code("Loire-Atlantique")
'44'
>>> fr_address_to_dept_code("LOIRE - ATLANTIQUE")
'44'
>>> fr_address_to_dept_code("Loire - ")
'42'You can also derive the main department and the list of all departments which are part of a given region from its name:
>>> from geoconvert.convert import fr_region_name_to_info
>>> # Returns the deparment code where the head of the region is
>>> # and the list of all the departments in the region.
>>> fr_region_name_to_info('Les Pays de la Loire, une superbe région')
('44', ['44', '49', '53', '72', '85'])You may use more specific functions, depending on your needs:
>>> from geoconvert.convert import (
... fr_address_to_dept_code,
... fr_dept_name_to_dept_code,
... fr_postcode_to_dept_code,
... )
>>> fr_postcode_to_dept_code("Chemin du Solarium Le Haut Vigneau 33175 GRADIGNAN CEDEX")
'33'
>>> fr_dept_name_to_dept_code("Loire - Atlantique")
'44'
>>> fr_dept_name_to_dept_code("Loire - ")
'42'You can find the state code associated with an address, via the postcode, state name (in English) or code:
>>> from geoconvert.convert import us_address_to_state_code
>>> us_address_to_state_code("Sunnyvale, CA 94085")
'CA'
>>> us_address_to_state_code("New Hampshire")
'NH'
>>> us_address_to_state_code("Los Angeles, CA")
'CA'You may use more specific functions, depending on your needs:
>>> from geoconvert.convert import (
... us_postcode_to_state_code, us_state_name_to_state_code
... )
>>> us_postcode_to_state_code("6931 Rings Rd, Amlin, OH 43002")
'OH'
>>> us_state_name_to_state_code("Welcome to West Virginia")
'WV'You can derive both country and subdivision codes at the same time:
>>> from geoconvert.convert import address_to_country_and_subdivision_codes
>>> address_to_country_and_subdivision_codes("Montréal, QC, Canada")
('CA', 'QC')
>>> address_to_country_and_subdivision_codes("Montréal, Québec")
('CA', 'QC')
>>> address_to_country_and_subdivision_codes("Montréal, QC")
(None, None)
>>> address_to_country_and_subdivision_codes("Montréal, QC", country="CA")
('CA', 'QC')
>>> address_to_country_and_subdivision_codes("Montréal", country="CA")
(None, None)
>>> address_to_country_and_subdivision_codes("Montréal, QC", country="US")
(None, None)
>>> address_to_country_and_subdivision_codes("Kairo", lang="de")
('EG', None)
>>> address_to_country_and_subdivision_codes("Kairo", lang="de", country="EG")
('EG', None)
>>> address_to_country_and_subdivision_codes("Kairo", lang="de", country="US")
(None, None)Result format can be choosen between a tuple and an iso code
>>> address_to_country_and_subdivision_codes("14467 Potsdam")
('DE', 'BB')
>>> address_to_country_and_subdivision_codes("14467 Potsdam", iso_format=True)
'DE-BB'
>>> address_to_country_and_subdivision_codes("Eschborn Germany")
('DE', None)
>>> address_to_country_and_subdivision_codes("Eschborn Germany", iso_format=True)
'DE'There should be no confusion between french, deutsch and US postcodes:
>>> address_to_country_and_subdivision_codes("2 pl. Saint-Pierre, 44000 Nantes", country="US")
(None, None)
>>> address_to_country_and_subdivision_codes("6931 Rings Rd, Amlin, OH 43002", country="FR")
(None, None)
>>> address_to_country_and_subdivision_codes("Straße 3 53119 Bonn", country="US")
(None, None)Just run pytest:
make testDo not forget to install the dependencies first, preferably in a vitrual environment:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements_test.txtTo release a new version you must update __version__ on geoconvert/__init__.py
and tag the master branch with the same version.
- Add the data in dictionaries, where the key is the name, and the value is the corresponding country code.
- These dictionaries must be named
countries_<language_code>ingeoconvert/data/countries.pyand/orcapitals_<language_code>ingeoconvert/data/capitals.py. The language code is a two-letter, lowercase code. For instance, for italian, the language code is "it". - Use already existing data as a template, especially to handle
special_countries. - Add the corresponding dictionnary to
language_to_country_namesand/orlanguage_to_capital_names. This allows theaddress_to_country_code,country_name_to_country_code, andcapital_name_to_country_codefunctions to use this language. - Add the language to the list of available languages at the top of this README.
- Add examples which are specific for this language in the README, doctests and tests,
especially for
address_to_country_codeandaddress_to_country_and_subdivision_codes.
- Add the data in dictionaries in
geoconvert/data/subdivisions/<country_name>.py, where<country_name>is the lowercase country name in English (for instance,geoconvert/data/subdivisions/germany.pyfor Germany). - Add functions that allow you convert an address to a subdivision code :
- a base function
<country_code>_address_to_<subdivision_name>_codethat uses the other implemented functions converting an address to a subdivision code (e.g.,ca_address_to_province_code) - a function converting the full subdivision name to the subdivision code
(e.g.,
ca_province_name_to_province_code) - a function converting a postcode from that country to a subdivision
(e.g.,
ca_postcode_to_province_code). This is optionnal, but highly recommended. - optionnally, a regex finding the subdivision code directly from the text can be used
as the last option in
<country_code>_address_to_<subdivision_name>_code.
- a base function
- Add the base function to the
country_to_subdivision_lookup_functiondictionary under the corresponding uppercase country code key. This allows this function to be used by theaddress_to_subdivision_codeandaddress_to_country_and_subdivision_codesfunctions. - Add the newly available subdivisions to the list at the top of this README.
- Add examples which are specific for this country in the README, doctests and tests,
especially the
address_to_subdivision_codeandaddress_to_country_and_subdivision_codesfunctions. Each added function must be tested as well.