gfetchert 0.1.6

Fetch CHIRPS rainfall data easily for any date and location using latitude/longitude or place name.

🌦️ Gfetchert — Smart CHIRPS Rainfall Fetcher

Gfetchert is a Python library that retrieves daily rainfall data from the 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:

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.