Metadata-Version: 2.4
Name: agmarknet
Version: 0.2.1
Summary: Pythonic pandas wrapper for the official AGMARKNET REST API.
Project-URL: Homepage, https://github.com/agmarknet/agmarknet
Project-URL: Issues, https://github.com/agmarknet/agmarknet/issues
Author: Manojkumar Patil
License: MIT License
        
        Copyright (c) 2026 Manojkumar Patil
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agmarknet,agriculture,arrivals,commodity,prices
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# agmarknet (Unofficial Python SDK)

A Pythonic client and pandas wrapper for the official AGMARKNET REST API. This library enables research analysts, developers, and data scientists to easily query market prices and arrivals data directly into pandas DataFrames without scraping HTML.

---

> [!IMPORTANT]
> **Unofficial Implementation & Compliance Disclaimer**
> 
> This is an **unofficial** Python SDK. It is not developed, endorsed, or supported by the Government of India. 
> 
> By using this library, you agree to comply with the official website policies of AGMARKNET:
> - **Source Policy:** The official AGMARKNET portal is maintained by the Directorate of Marketing & Inspection (DMI), Department of Agriculture & Farmers Welfare, Ministry of Agriculture & Farmers Welfare, Government of India. The portal provides timely and reliable information to farmers, traders, consumers, researchers, and other stakeholders.
> - **Copyright Policy:** Information fetched from AGMARKNET may be reproduced free of charge, provided the material is reproduced accurately, not used in a derogatory or misleading context, and the source is acknowledged as [https://agmarknet.gov.in](https://agmarknet.gov.in).
> - **Terms & Conditions & Legal Purpose:** The data fetched by this library should not be used for legal purposes. The Directorate of Marketing & Inspection (DMI) and the developers of this SDK are not liable for any loss arising from the use of this information. These terms are governed by Indian law, and any disputes will fall under Indian jurisdiction.
> - **Disclaimer of Authenticity:** Market prices and arrival data are reported and shared by the respective APMC/Markets. Users are advised to exercise their discretion and judgment before making decisions using this data. The Department/DMI shall not be responsible for any errors or the authenticity of the data.

---

## Features

- **Automated Name Resolution:** Query using friendly name strings (e.g. state `"Karnataka"`, commodity `"Tomato"`, market `"Bangarpet APMC"`). The SDK resolves names to official AGMARKNET IDs under the hood using exact, case-insensitive, and fuzzy matching.
- **Support for Price & Arrival Quantity/Units:** Fetch comprehensive daily reports including prices and arrival quantities.
- **Historical Chunking:** Seamlessly query long date ranges (e.g., since 2007). The SDK automatically splits request windows into yearly chunks to circumvent backend limitations, de-duplicates rows, and sorts the result chronologically.
- **Pagination Handling:** Transparently fetches all pages from the paginated backend API and merges them into a single pandas DataFrame.
- **Requests Session Configuration:** Configures timeouts, retries, and headers out-of-the-box.

---

## Installation

```bash
pip install agmarknet
```

---

## Usage Guide

### 1. Initialization
```python
from agmarknet import Agmarknet

# Create an instance of the AGMARKNET client
api = Agmarknet()
```

### 2. Fetching Daily Price and Arrival Reports
By default, the SDK requests both price and arrival data (`data_type="both"`). This ensures you get prices (min, max, modal) as well as arrival volumes and unit names.

```python
df = api.report(
    from_date="2026-06-01",
    to_date="2026-06-05",
    commodity="Tomato",
    state="Karnataka",
    district="Kolar",        # Optional
    market="Bangarpet APMC"  # Optional
)

print(df.head())
```

#### Returned Columns
When using `data_type="both"` (default), the returned DataFrame includes the following fields:
- `arrival_date`: The date of the record.
- `state_name` & `district_name` & `market_name`: Geographical identifiers.
- `cmdt_grp_name` & `cmdt_name` & `variety_name` & `grade_name`: Commodity details.
- `min_price` & `max_price` & `model_price`: Price metrics.
- `unit_name_price`: Currency/Weight unit (e.g. `Rs./Quintal`).
- `arrival_qty`: Volume of commodity arrival.
- `unit_name_arrival`: Arrival weight unit (e.g. `Metric Tonnes`).

### 3. Choosing a Report Type
You can customize the fetched columns by passing the `data_type` parameter:
- **`both`** (default): Fetches both prices and arrival volumes.
- **`price`**: Fetches only price-related fields.
- **`arrival`**: Fetches only arrival-related fields (date, quantity, units).

```python
# Fetch price only
price_df = api.report(
    from_date="2026-06-01",
    to_date="2026-06-05",
    commodity="Tomato",
    state="Karnataka",
    data_type="price"
)
```

### 4. Fetching Long Historical Datasets
The backend API restricts very large queries. To fetch years of historical data, use the `start` and `end` parameters. The SDK automatically partitions the request by calendar year, manages page-by-page downloads, and compiles the result:

```python
historical_df = api.report(
    start="2015-01-01",
    end="2026-07-01",
    commodity="Tomato",
    state="Karnataka",
    district="Kolar",
    market="Bangarpet APMC",
    progress=True  # Displays download progress in stdout/stderr
)
```

### 5. Accessing Metadata & Filters
You can inspect the underlying tables used for name-to-ID resolution:

```python
filters = api.filters()

# Access commodity metadata
print(filters.commodities.head())

# Access states metadata
print(filters.states.head())

# Access markets metadata
print(filters.markets.head())
```

---

## License & Attribution
Distributed under the MIT License. Data is provided by the Directorate of Marketing & Inspection, Government of India. Always acknowledge [https://agmarknet.gov.in](https://agmarknet.gov.in) when using or sharing data generated by this tool.
