SMN Climate Data Downloader

Python toolkit for downloading historical daily climatological records from Mexico's National Meteorological Service (SMN).

Spanish version: README_ES.md

Overview

SMN Climate Data Downloader is a lightweight Python toolkit designed to download historical daily climatological records from the Mexican National Meteorological Service (SMN).

The project consists of two complementary utilities:

• parse_kml.py extracts climatological station metadata from the official SMN KMZ file and generates a CSV database of available stations.
• downloader.py automatically downloads daily climatological records for every station within a selected Mexican state.

This repository was originally developed to support hydrological and hydroinformatics research, but it can also be used in environmental studies, water resources management, agriculture, and geospatial analysis. The code is intentionally simple, making it easy to understand, modify, and adapt to different research needs.

---

Quick Start

1. Install the required Python packages.
2. Download the official SMN climatological station KMZ file.
3. Run parse_kml.py to generate stations_data.csv.
4. Set the desired state in downloader.py.
5. Run downloader.py to download historical climatological records.

---

Features

• Download historical daily climatological records directly from the official SMN website.
• Automatically retrieve data for all climatological stations within a selected Mexican state.
• Generate a station database from the official SMN KMZ file.
• Save each station's records as individual text files for further processing and analysis.
• Lightweight implementation with minimal dependencies and an easy-to-understand codebase.

---

Workflow

1. Download the official climatological station KMZ file from the SMN website.
2. Run parse_kml.py to generate the station database (stations_data.csv).
3. Select the desired Mexican state in downloader.py.
4. Run the downloader to retrieve historical daily climatological records for every station in that state.

Note

This repository contains only the source code. The official SMN station KMZ file must be downloaded separately from the Mexican National Meteorological Service (SMN) website. This ensures that the station database is always generated from the most up-to-date information available.

---

Requirements

Before using this project, make sure you have:

• Python 3.9 or later
• An internet connection
• The official SMN climatological station KMZ file

The required Python packages can be installed using the provided requirements.txt file.

---

Installation

Option 1 — Clone the repository

Clone the repository using Git:

git clone https://github.com/ximenaanell86/smn-climate-data-downloader.git
cd smn-climate-data-downloader

Option 2 — Download as a ZIP file

If you prefer not to use Git, download the repository as a ZIP file from GitHub and extract it to your preferred working directory.

Install the required packages

Install the project dependencies using:

pip install -r requirements.txt

Download the official SMN station file

Download the latest climatological station KMZ file from the official website of the Mexican National Meteorological Service (SMN):

https://smn.conagua.gob.mx/es/climatologia/informacion-climatologica/informacion-estadistica-climatologica

Save the downloaded file in the root directory of the project with the following name:

EstacionesClimatologicas.kmz

Your project folder should now look similar to this:

smn-climate-data-downloader/
│
├── EstacionesClimatologicas.kmz
├── downloader.py
├── parse_kml.py
├── requirements.txt
└── ...

Generate the station database

Run:

python parse_kml.py

This will generate:

stations_data.csv

containing the metadata for all climatological stations available in the official SMN KMZ file.

The project is now ready to download historical climatological records.

---

Usage

1. Select the desired state

Open downloader.py and modify the configuration variables according to the state you want to download.

For example:

STATE = "VERACRUZ DE IGNACIO DE LA LLAVE"
STATE_ABBR = "ver"

The state name must match the corresponding entry in stations_data.csv.

2. Run the downloader

Execute:

python downloader.py

The script will:

• Read the station database (stations_data.csv).
• Filter stations belonging to the selected state.
• Download the historical daily climatological records for each station.
• Save the downloaded files in the downloaded_data/ directory.

3. Download progress

During execution, the script displays the download progress in the terminal, indicating:

• Current station
• Station identifier
• Download status
• Existing files that are skipped

Example:

Downloading data for station 30003...
✓ Download completed.

Downloading data for station 30021...
✓ Download completed.

Downloading data for station 30068...
File already exists. Skipping download.

---

Output

The downloaded files are stored in the downloaded_data/ directory.

Example:

downloaded_data/
│
├── 30003.txt
├── 30021.txt
├── 30068.txt
├── ...

Each file contains the historical daily climatological records provided by the Mexican National Meteorological Service (SMN).

---

Project Structure

File	Description
downloader.py	Downloads historical daily climatological records for all stations within a selected Mexican state.
parse_kml.py	Extracts station metadata from the official SMN KMZ file and generates the station database.
stations_data.csv	CSV file containing metadata for all climatological stations.
requirements.txt	Lists the Python packages required to run the project.
.gitignore	Specifies files and directories that should not be tracked by Git.
LICENSE	MIT License.
README.md	Project documentation.

---

Data Source

This project is designed to work with publicly available climatological data provided by the Mexican National Meteorological Service (SMN), operated by the National Water Commission (CONAGUA).

The official climatological station catalog can be downloaded from:

https://smn.conagua.gob.mx/es/climatologia/informacion-climatologica/informacion-estadistica-climatologica

This repository does not distribute or modify official SMN datasets. Users are responsible for downloading the latest station catalog directly from the official SMN website.

---

Citation

If you use this project in academic research, teaching, or professional work, please consider citing this repository:

Anell Parra, X. (2026). SMN Climate Data Downloader [Computer software]. GitHub. https://github.com/ximenaanell86/smn-climate-data-downloader

---

Future Improvements

Possible future enhancements include:

• Support downloading data for multiple states in a single execution.
• Command-line interface (CLI) to simplify execution.
• Progress bar for large downloads.
• Automatic detection of updates to the official SMN station catalog.
• Additional export formats such as CSV or Parquet.
• Support downloading data from individual stations by station ID.

---

License

This project is distributed under the terms of the MIT License.

See the LICENSE file for more information.

---

Disclaimer

This project is an independent open-source utility and is not affiliated with, endorsed by, or maintained by the Mexican National Meteorological Service (SMN) or the National Water Commission (CONAGUA).

Although every effort has been made to ensure the correctness of the code, users are encouraged to verify downloaded data and results before using them for research or operational applications.

---

Acknowledgments

This project was originally developed as part of hydrological and hydroinformatics research involving climatological data from the Mexican National Meteorological Service (SMN).

It is released as an open-source tool to facilitate access to historical climatological records for researchers, students, and professionals working in hydrology, environmental sciences, agriculture, water resources, and geospatial analysis.