Metadata-Version: 2.4
Name: mospi-unitdata
Version: 0.2.0
Summary: Python client for downloading data from the MoSPI Microdata Portal (https://microdata.gov.in)
Project-URL: Homepage, https://microdata.gov.in
Project-URL: Repository, https://github.com/nso-india/mospi-unitdata
Project-URL: Issues, https://github.com/nso-india/mospi-unitdata/issues
Author: DIID, Ministry of Statistics and Programme Implementation, Neeraj Prakash, Satvik Bajpai, Sarthak Srivastava
License-Expression: MIT
License-File: LICENSE
Keywords: api,data,government,india,microdata,mospi,nso,nsoindia,statistics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# MoSPI Unit Data Client

[![PyPI version](https://badge.fury.io/py/mospi-unitdata.svg)](https://badge.fury.io/py/mospi-unitdata)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Python client for downloading microdata from the [MoSPI Microdata Portal](https://microdata.gov.in). 
This package provides a convenient interface to browse, search, and download datasets from the Government of India's National Statistical Office (NSO).

## Installation

```bash
pip install mospi-unitdata
```

## Getting an API Key

To use this package, you need an API key from the MoSPI Microdata Portal:

1.  Visit the [MoSPI Microdata Portal](https://microdata.gov.in).
2.  **Create an account** or sign in if you already have one.
3.  **Verify your email** address (check your inbox for a confirmation link).
4.  **Login** to your account.
5.  Navigate to your **Profile** section.
6.  Click on **Generate API Key** (or view your existing key).

## Usage

```python
from MospiUnitdata import list_datasets, list_files, download_file, download_dataset
```

### List datasets

```python
# List all datasets
datasets = list_datasets("YOUR_API_KEY")

# List a specific page
datasets = list_datasets("YOUR_API_KEY", page=1)

# Search by keyword
datasets = list_datasets("YOUR_API_KEY", query="labour force")

for d in datasets:
    print(f"{d['id']} ({d['idno']}): {d['title']}")
```

### List files in a dataset

```python
files = list_files("DDI-IND-NSO-ASI-2020-21", "YOUR_API_KEY")

for f in files:
    print(f"{f['name']} ({f.get('size', '?')})")
```

### Download a single file

```python
download_file("DDI-IND-NSO-ASI-2020-21", "ASI_DATA_2020_21_CSV.zip", "./data", "YOUR_API_KEY")
```

### Download all files in a dataset

```python
download_dataset("DDI-IND-NSO-ASI-2020-21", "./data", "YOUR_API_KEY")
```

### Interactive mode (legacy)

```python
from MospiUnitdata import getDatasets

getDatasets("./data", "YOUR_API_KEY")
```

This opens an interactive prompt to browse and select datasets page by page.

## API Reference

| Function | Description |
|----------|-------------|
| `list_datasets(api_key, page=None, query=None)` | List datasets. Returns all if no page specified. Optional keyword search. |
| `list_files(dataset_id, api_key)` | List files available in a dataset. |
| `download_file(dataset_id, file_name, folder_path, api_key)` | Download a single file from a dataset. |
| `download_dataset(dataset_id, folder_path, api_key)` | Download all files from a dataset. |
| `getDatasets(folder_path, api_key)` | Interactive browser and downloader (legacy). |

## Requirements
- Python 3.9+
- `requests` >= 2.31.0

## License

This project is licensed under the MIT License.
