gfetchert 0.1.8
Fetch CHIRPS rainfall data easily for any date and location using latitude/longitude or place name.
License: MIT
Requires Python: >=3.9

# 🌦️ Gfetchert — Smart CHIRPS Rainfall Fetcher

**Gfetchert** is a Python library that retrieves **daily rainfall data** from the [CHIRPS 2.0](https://data.chc.ucsb.edu/products/CHIRPS-2.0/) dataset for any given date, location, or coordinate pair.

It automates downloading, decompressing, and reading global rainfall `.tif` files directly from the UCSB Climate Hazards Center, so you can analyze or integrate historical precipitation data in a single command.

---

## 🚀 Key Capabilities

- 🌍 Works globally — fetch rainfall from any place or coordinate.  
- 📅 Accepts any date format (`YYYY-MM-DD`, `30/09/2007`, `July 30, 2007`).  
- 🧠 Intelligent output:
  - Returns a **float** for single-date queries.
  - Returns a **DataFrame** for date ranges.  
- 📄 Reads from **CSV, Excel, or PDF** datasets automatically.  
- ⚡ Handles missing data and network interruptions gracefully.  
- 💾 Caches downloads locally to avoid re-fetching.  

---

## 📦 Installation

Install from PyPI:

```bash
pip install gfetchert
Optional (for PDF support):


pip install tabula-py
🧠 Basic Usage
1️⃣ Fetch rainfall for coordinates

from gfetchert import get_rainfall

# For one date (returns float)
rain = get_rainfall(lat=29.32, lon=76.88, start="2007-07-30")
print(rain)   # Output: 12.4

# For a date range (returns DataFrame)
data = get_rainfall(lat=29.32, lon=76.88, start="2007-07-28", end="2007-08-02")
print(data)
Output:


         date  rainfall_mm
0  2007-07-28          5.3
1  2007-07-29          0.0
2  2007-07-30         12.4
3  2007-07-31          1.7
4  2007-08-01          0.0



2️⃣ Fetch rainfall by location name

rain = get_rainfall(location="Dehradun, India", start="2020-07-15")
print(rain)
Internally, Gfetchert geocodes your location and fetches rainfall for that coordinate.





3️⃣ Fetch rainfall for multiple rows (CSV, Excel, PDF)

from gfetchert.file_ops import fetch_from_file

# Automatically detects file format
fetch_from_file("rainfall_points.csv")
fetch_from_file("stations.xlsx")
fetch_from_file("field_data.pdf")
Each file must contain:


date, latitude, longitude
Output file example:

rainfall_points_with_rainfall.csv





📊 Input Format Example
date	latitude	longitude
2007-07-30	29.32	76.88
2007-08-01	30.55	79.56
2007-09-21	26.32	91.67





⚙️ Parameters
Parameter	 Type	  Description
lat	         float	  Latitude in decimal degrees.
lon	         float	  Longitude in decimal degrees.
location	 str	  Location name (auto-resolved via geocode).
start	     str	  Start date — accepts most date formats.
end	         str	  End date (optional). Defaults to start.
download_dir str	  Folder to store .tif rainfall files.

🧾 Return Values
Case	      Output Type	       Description
Single date   float	               Rainfall (mm) for that date
Date range	  pandas.DataFrame	   Table of daily rainfall values



📁 Example Output (CSV)


         date  rainfall_mm
0  2007-07-30         12.4
1  2007-07-31          0.0
2  2007-08-01          3.1











🌾 Practical Use Cases
*Landslide / flood susceptibility modeling

*Agricultural water balance analysis

*Rainfall-runoff simulation

*Climate research and hydrological studies

*Remote-sensing and GIS automation

👨‍💻 Author
Developed by Nikhil
A noob.

🪪 License
MIT License © 2025 Nikhil

Use, modify, and distribute freely for both academic and commercial purposes.



🌍 Data Source
Data provided by:
Climate Hazards Group InfraRed Precipitation with Station data (CHIRPS)
University of California, Santa Barbara (UCSB)
https://data.chc.ucsb.edu/products/CHIRPS-2.0/





🧩 Example Workflow

from gfetchert import get_rainfall

rainfall = get_rainfall(lat=26.32, lon=91.75, start="2020-06-01", end="2020-06-10")
rainfall.to_csv("assam_rainfall_june.csv", index=False)
This instantly generates a rainfall dataset for your region and time window — ready for model input or visualization.






🏗️ Version History
Version	Release Date	Notes
0.1.0	Nov 2025	Initial prototype
0.1.3	Dec 2025	Added CHIRPS fetch + automation
0.1.4	Dec 2025	Fixed raster reading and error handling
0.1.5	Dec 2025	Added file format support (CSV, Excel, PDF)
0.1.6	Dec 2025	Smart scalar return + flexible date parser

💡 Tip
You can chain Gfetchert directly with any ML or GIS pipeline:


rain = get_rainfall(lat=27.1, lon=88.6, start="2023-08-01", end="2023-08-31")
rain.to_csv("sikkim_august_rainfall.csv", index=False)




----> Now your rainfall data is ready for machine learning or spatial visualization.