Metadata-Version: 2.4
Name: pysquirrel
Version: 1.3
Summary: Python package designed to fetch NUTS administrative divisions
License-Expression: MIT
License-File: LICENSE
Author: Scenario Services team, ECE program, IIASA
Maintainer: David Almeida
Maintainer-email: almeida@iiasa.ac.at
Requires-Python: >=3.10,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: openpyxl (>=3.1.5,<4.0)
Requires-Dist: pydantic (>=2.8.2,<3.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0)
Project-URL: Repository, https://github.com/iiasa/pysquirrel
Description-Content-Type: text/markdown

# pysquirrel - NUTS administrative region utility

[![license](https://img.shields.io/badge/License-MIT-blue)](https://github.com/iiasa/pysquirrel/blob/main/LICENSE)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![pytest](https://img.shields.io/github/actions/workflow/status/iiasa/pysquirrel/pytest.yml?logo=GitHub&label=pytest)](https://github.com/iiasa/pysquirrel/actions/workflows/pytest.yml)
[![DOI](https://zenodo.org/badge/791752279.svg)](https://zenodo.org/doi/10.5281/zenodo.13683405)

Copyright 2025 IIASA Scenario Services team

This repository is licensed under the [MIT License](LICENSE).

## Overview

**pysquirrel** is a Python package designed to work with NUTS administrative divisions.

The current NUTS version is valid from 1 January 2024.
The UK NUTS version is valid from January 2018.

## Background

From the [Eurostat website](https://ec.europa.eu/eurostat/web/nuts/overview)

The [NUTS
classification](https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:Nomenclature_of_territorial_units_for_statistics_(NUTS))
(Nomenclature of territorial units for statistics) is a geographical nomenclature subdividing the economic territory of the European Union (EU) into regions at three different levels (NUTS 1, 2 and 3 respectively, moving from larger to smaller territorial units). Above NUTS 1, there is the 'national' level of the Member States.

NUTS is used for:

- collecting, developing and harmonising European regional statistics
- carrying out socio-economic analyses of the regions
- framing of EU regional policies

## Usage

**pysquirrel** allows searching the list of all territorial units by specifying the 
parameters and the values to search as shown below:

```python
>>> import pysquirrel

>>> pysquirrel.nuts.get(country_code="AT")  # gets all regions in Austria by EU country code

>>> pysquirrel.nuts.get(iso3="AUT")  # gets all regions in Austria by ISO3 country code

>>> pysquirrel.nuts.get(level=3)  # gets all NUTS3 regions

>>> pysquirrel.nuts.get(country_code="AT", level=3)  # gets all NUTS3 regions in Austria
```

Each Region object consists of five attributes:
- a NUTS code (e.g.: AT127)
- a country code
- a label (the full region name)
- a NUTS level (1, 2 or 3)
- a parent code (corresponding to the NUTS parent region)

## NUTS regions geojsons

The geojson files for the NUTS 1, 2 and 3 regions are 
available in the [scse-geojson](https://github.com/iiasa/scse-geojson) repository.

## Eurostat copyright notice on NUTS region data file

This package imports the NUTS spreadsheet from the Eurostat website.

Please note that pysquirrel is not developed, maintained or affiliated
with Eurostat. The [Eurostat copyright notice
applies](https://ec.europa.eu/eurostat/web/main/help/copyright-notice).

The Eurostat editorial content is licensed under the [Creative Commons
Attribution 4.0 International licence](https://creativecommons.org/licenses/by/4.0/). Reuse
of statistical metadata such as the NUTS classification is authorised
with due citation of the source.

> European Commission, Eurostat, Statistical regions in the European
> Union and partner countries -- NUTS and statistical regions 2021 --
> 2022 edition, Publications Office of the European Union, 2022,
> https://data.europa.eu/doi/10.2785/321792

## Acknowledgement

This package is developed and maintained by the *Scenario Services & Scientific Software*
research theme at the IIASA Energy, Climate, and Enviroment program.
Visit https://software.ece.iiasa.ac.at for more information.

