agmarknet 0.2.2

Pythonic pandas wrapper for the official AGMARKNET REST API.

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.
• 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.
• Local Lookup Cache: Loads static lookup tables from a built-in filters.json database file, completely eliminating network requests and rate limits when resolving names to IDs.
• Native Multi-Query Iteration: Natively accepts lists of states and commodities (e.g. commodity=["Cotton", "Tomato"], state=["Maharashtra", "Gujarat"]). The SDK sequentially downloads and combines each combination to avoid server timeouts and rate limits, returning a single merged DataFrame.
• 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

pip install agmarknet

---

Usage Guide

1. Initialization

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.

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).

# 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:

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:

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 when using or sharing data generated by this tool.