NutsTools 0.5.6
Obtain NUTS codes by postal codes
License: MIT
Requires Python: >=3.8

=========
NutsTools
=========


    Convert postal codes to NUTS codes

EU NUTS (an abbreviation for Nomenclature of Territorial Units for Statistics) codes are standardized codes used by the
European Union to define administrative and statistical regions for the purpose of data collection and analysis.

The translation between Postal codes of home addresses and de NUTS code is given at the EU website. This tools
is an  Python interface to easily obtain the code lists and transform postal codes into NUTS codes.

------------
Installation
------------

Install the tool by::

    pip install nutstools

In case you are behind a proxy which requires authentication you may want to install the packages
*requests_kerberos_proxy*. You can install it yourself with::

    pip install requests-kerberos-proxy

or, alternatively, install the nutstools package as::

    pip install nutstools[proxy]

which will automatically include the required proxy packages

-----
Usage
-----

Command line tool
-----------------

This tools can be used to convert postal codes to NUTS codes.
Run the following to get the nuts belong by the postal code 2612AB:

.. code-block:: text

    >> postalcode2nuts.exe -p 2612AB

This yields the following output:

.. code-block:: text

    2612AB    NL333

So the nuts3 code belong to the postal code *2612AB* is *NL333*.

It is also possible to convert the postal codes stored in a file using the -i option.
In case your file with the name *postal_codes.txt* contains the following::

    '8277 AM'
    '2871 KA'
    '9408 BJ'
    '3076 KA'
    '3068 LM'
    '7543 GV'

Running the following::

    >> postalcode2nuts.exe -i postal_codes.txt -o -

gives  the following output:

.. code-block:: text

    8277AM    NL211
    2871KA    NL33B
    9408BJ    NL131
    3076KA    NL33C
    3068LM    NL33C
    7543GV    NL213

In case the output argument *-o -* i is left out, the output filename will be based on
the input file with the suffix *nuts3*, where 3 stands for the nuts level of the output.

Help message
------------

The full help  message of the tools is:

.. code-block:: text

    PS> postalcode2nuts.exe --help
    usage: postalcode2nuts [-h] [--version] [-p POSTALCODE] [-i INPUT_FILE_NAME] [--nuts_file_name NUTS_INPUT_FILE_NAME]
                           [-o OUTPUT_FILE_NAME] [-v] [-vv] [-l LEVEL] [--year {2021}]
                           [--country {DE,SK,FI,DK,IT,LU,LI,SE,LV,TR,UK,ES,EE,HR,MK,CY,IS,AT,RO,HU,BG,BE,PL,CH,RS,IE,CZ,NL,NO,PT,SI,LT,FR,EL}]
                           [--update_settings] [--directory DIRECTORY]

    Converts a postal code to its NUTS code

    options:
      -h, --help            show this help message and exit
      --version             show program's version number and exit
      -p POSTALCODE, --postal_code POSTALCODE
                            Postcode
      -i INPUT_FILE_NAME, --input_file_name INPUT_FILE_NAME
                            Input file with Postal codes
      --nuts_file_name NUTS_INPUT_FILE_NAME
                            Overrule input filename with the NUTS translation data
      -o OUTPUT_FILE_NAME, --output_file_name OUTPUT_FILE_NAME
                            Output file with Postal codes and NUTS
      -v, --verbose         set loglevel to INFO
      -vv, --debug          set loglevel to DEBUG
      -l LEVEL, --level LEVEL
                            The level at we want to get the NUTS-code
      --year {2021}         The year of the NUTS files
      --country {DE,SK,FI,DK,IT,LU,LI,SE,LV,TR,UK,ES,EE,HR,MK,CY,IS,AT,RO,HU,BG,BE,PL,CH,RS,IE,CZ,NL,NO,PT,SI,LT,FR,EL}
                            The country code for the NUTS file
      --update_settings     Update the settings file with the new values
      --directory DIRECTORY
                            The location of the the NUTS files. If not given, the default directory will be picked

Python API
----------

The NUTS conversion can also be used in your own Python code. As an example,
this initialises the default file location (in local cache)
and it downloads the file from the eurostat website::

    from nutstools.postalnuts import NutsPostalCode, NutsData

    nuts_data = NutsData()

At this point the NUTS data file has been downloaded from the Eurostat website
and stored in the default location. You can now create an object with the nuts data::

    nuts = NutsPostalCode(nuts_data.nuts_codes_file)

The Nuts translation are stored at the same location in the file the *nuts.nuts_data* attribute. At this point you
can get a nuts code for a specific postal with as::

    post_code = "2612AB"
    nuts_code = nuts.one_postal2nuts(postal_code=post_code)
    print(f"Postal code {post_code} has nuts code {nuts_code}")

Which yields the output:

.. code-block:: text

    Postal code 2612AB has nuts code NL333

Conversion of a list of postal code is also possible as::

    postal_codes = [
        "8277 AM",
        "2871 KA",
        "9408 BJ",
        "3076 KA",
        "3068 LM",
        "7543 GV",
        "4181 DG",
    ]

    all_codes = nuts.postal2nuts(postal_codes=postal_codes)

giving as output:

.. code-block:: text

    8277AM    NL211
    2871KA    NL33B
    9408BJ    NL131
    3076KA    NL33C
    3068LM    NL33C
    7543GV    NL213
    4181DG    NL224
    Name: NUTS3, dtype: object

The same can be done for NUTS level 1::

    all_codes = nuts.postal2nuts(postal_codes=postal_codes, level=1)

which gives the following output:

.. code-block:: text

    8277AM    NL2
    2871KA    NL3
    9408BJ    NL1
    3076KA    NL3
    3068LM    NL3
    7543GV    NL2
    4181DG    NL2
    Name: NUTS1, dtype: object


Default Settings
----------------

By default, postalcode2nuts will download the nuts code from the website
https://gisco-services.ec.europa.eu/tercet/NUTS-2021/.

The data is stored in *C:\\Users\\MyUser\\AppData\\Local* (windows) or *.local/share* (Linux)
in the directory *nutstools*. This location can be altered via the command line argument
*--directory <location>*.

The current location of the settings file can be found with:

.. code-block:: text

     >postalcode2nuts.exe --config_show

This give the current settings file location and default settings:

.. code-block:: text

    Settings file : C:\Users\username\AppData\Local\nutstools\nutstools_settings.yml
    Nuts code file: C:\Users\username\AppData\Local\nutstools\Cache\pc2020_NL_NUTS-2021_v2.0.zip
    URL of source : https://gisco-services.ec.europa.eu/tercet/NUTS-2021//pc2020_NL_NUTS-2021_v2.0.zip
    Country to show: NL
    Year of data: 2021

The default settings are stored in the file *nutstools_settings.yml*. The contents of this file
contains all the default choices, such as the default country for which the NUTS code conversion
is applied (default is for The Netherlands using the code 'NL').
The contents of the settings file look like:

.. code-block:: yaml

    COUNTRY_CODES: !!set
        <list of country codes>
    DEFAULT_COUNTRY: NL
    DEFAULT_YEAR: '2021'
    NUTS_CODE_DEFAULT_DIRECTORY: C:/Users/MyUser/AppData/Local/nutstools
    NUTS_DATA:
      '2021':
        files:
          NL: pc2020_NL_NUTS-2021_v2.0.zip
        url: https://gisco-services.ec.europa.eu/tercet/NUTS-2021/
    NUTS_YEARS: !!
      '2021': null

After running the code for the first time, the NUTS data file can be found in the *Cache* directory
at the same location. The next time the tool is run, the Cached files are used instead of downloading the
file again.

In case you want to alter the default choices, you can just modify the settings file to your needs.
Alternatively, you can run your code one time with the *--update* option in order to overwrite your settings.
For instance, to obtain the NUTS code of a Belgium Postal code you can do:

.. code-block:: text

    >> postalcode2nuts.exe --country BE -p 1083 --update_settings

This yields the following output:

.. code-block:: text

    1083    BE100

Note the the *--update_setting* option only needs to be given one time. This forces
the settings file to be overwritten. The next runs, the last country will be picked.

The settings file name and location can be retrieved again:

.. code-block:: text

     >postalcode2nuts.exe --config_show

This give the current settings file location and default settings:

.. code-block:: text

    Settings file : C:\Users\username\AppData\Local\nutstools\nutstools_settings.yml
    Nuts code file: C:\Users\username\AppData\Local\nutstools\Cache\pc2020_BE_NUTS-2021_v1.0.zip
    URL of source : https://gisco-services.ec.europa.eu/tercet/NUTS-2021//pc2020_BE_NUTS-2021_v1.0.zip
    Country to show: BE
    Year of data: 2021

Note
====

This project has been set up using PyScaffold 4.3.1. For details and usage
information on PyScaffold see https://pyscaffold.org/.

.. image:: https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold
    :alt: Project generated with PyScaffold
    :target: https://pyscaffold.org/