imergpy 1.2.3

Download, extract, average, plot, and analyze NASA GPM IMERG precipitation data from Python or a local web UI.

imergpy

imergpy is a Python package and local web interface for downloading NASA GPM IMERG precipitation data through NASA Earthdata/GES DISC. It can extract point rainfall time series and compute grid-cell average rainfall for selected countries or square areas.

Download NASA Rainfall Data With 2 Lines

• Download NASA IMERG satellite rainfall as a time series.
• Excel file is saved automatically.
• Use Point, Country Average, or Square Region Average.
• Available from 1998-01-01 to today, depending on NASA product availability.
• Supports half-hourly, daily, and monthly data.
• Uses GES DISC OTF subset download with wget and Earthdata cookies.
• No Linux or advanced technical knowledge needed.

Two-Line Python Download

After installation, download point rainfall with:

import imergpy
excel_path, records = imergpy.get_precipitation(6.9271, 79.8612, "2025-11-27 00:00", "2025-11-27 23:30", "EARTHDATA_USERNAME", "EARTHDATA_PASSWORD", run_type="late", freq="hhr")

Replace EARTHDATA_USERNAME and EARTHDATA_PASSWORD with your NASA Earthdata login. The result is saved as an Excel file.

Quick Start(MacOS/Windows/Linux)

Install:

pip install imergpy

Open the web app:

python -m imergpy.cli

Your browser should open automatically. Enter your NASA Earthdata username/password in the local page and choose a point, country, or square area.

Two Ways To Use

• Method 1: Use Python code.
• Method 2: Use the local web interface.
• Both methods save Excel output automatically.

Features

• Local web UI launched with python -m imergpy.cli
• Python API for scripted workflows
• Point, country, and square-area selection in the web map
• Grid-cell average precipitation for country and square-area selections
• Half-hourly, daily, and monthly IMERG products
• Early, Late, and Final IMERG run types where available
• GES DISC OTF subset download using wget, Earthdata credentials, and cookies
• Excel export with separate Start Time and End Time columns
• Basic rainfall plotting and statistics utilities

Web UI

python -m imergpy.cli

Python API Example

import imergpy

excel_path, records = imergpy.get_precipitation(
    lat=6.9271,
    lon=79.8612,
    start_datetime="2025-11-27 00:00",
    end_datetime="2025-11-27 23:30",
    username="EARTHDATA_USERNAME",
    password="EARTHDATA_PASSWORD",
    run_type="late",
    freq="hhr",
    interp_method="nearest",
)

print(excel_path)

Four-Point Point Download

For point rainfall, you can download only the tiny subset around the four surrounding IMERG grid points and choose nearest or linear interpolation:

import imergpy

excel_path, records = imergpy.get_precipitation_four_points(
    lat=6.9,
    lon=79.8,
    start_datetime="2025-11-25",
    end_datetime="2025-11-25",
    username="EARTHDATA_USERNAME",
    password="EARTHDATA_PASSWORD",
    run_type="late",
    freq="daily",
    method="linear",
)

print(excel_path)

Example Files

• examples/point_download.py
• examples/country_japan_average.py
• examples/square_area_average.py
• examples/ATTRIBUTE_REFERENCE.txt

Accepted date formats:

• YYYY-MM
• YYYY-MM-DD
• YYYY-MM-DD HH:MM

NASA Earthdata Credentials

You need a free NASA Earthdata account. After creating the account, authorize GES DISC under Earthdata authorized applications.

For the easiest first test, replace EARTHDATA_USERNAME and EARTHDATA_PASSWORD directly in the examples above. For shared scripts, keep credentials private and avoid uploading passwords to GitHub.

NASA Download Method

imergpy uses only the NASA GES DISC OTF subset service. It calls wget with your Earthdata username/password and stores Earthdata cookies in ~/.urs_cookies.

You must have wget installed and available in your terminal path.

Legal And Data Use Notice

imergpy is an independent open-source tool. It is not developed, endorsed, or certified by NASA, GES DISC, or the GPM mission team.

Users are responsible for:

• creating and using their own NASA Earthdata account,
• accepting and following NASA/GES DISC data access terms,
• citing NASA GPM IMERG data correctly in reports, papers, and products,
• checking data quality, latency, and suitability before operational or scientific use,
• keeping Earthdata usernames, passwords, and tokens private.

This software is provided under the MIT License without warranty.

Development

For local development:

git clone https://github.com/LakshithaSenavirathna/imergpy.git
cd imergpy
pip install -e ".[dev]"

Run tests:

pytest

Build package files:

python -m build

Publishing instructions are in PUBLISHING.md.

Upgrade

To upgrade to a newer imergpy version:

pip install --upgrade imergpy

License

MIT License. Developed by Lakshitha S. Senavirathna.