Installation

System Requirements

Python 3.8 or higher
Operating Systems: Windows, macOS, Linux
Dependencies: requests >= 2.25.0 (automatically installed)

Installation Methods

PyPI Installation (Recommended)

Install the latest stable version from PyPI:

pip install python-CIMIS

Development Installation

For the latest development version or to contribute:

# Clone the repository
git clone https://github.com/python-cimis/python-cimis-client.git
cd python-cimis-client

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Virtual Environment (Recommended)

Create an isolated environment for your project:

Using venv (Python 3.3+)

# Create virtual environment
python -m venv cimis_env

# Activate (Windows)
cimis_env\\Scripts\\activate

# Activate (Linux/macOS)
source cimis_env/bin/activate

# Install the library
pip install python-CIMIS

Using conda

# Create conda environment
conda create -n cimis_env python=3.11

# Activate environment
conda activate cimis_env

# Install the library
pip install python-CIMIS

API Key Setup

Register for CIMIS API Access

Visit the CIMIS REST API page
Click “Register for a new account” or “Sign In” if you have an existing account
Fill out the registration form with your information and intended use
Agree to the terms and conditions and submit

Generate Your API Key

After registration approval (usually immediate), log into your account
Navigate to the API Key section
Click “Generate New Key” or “Show API Key”
Copy your API key (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Secure Your API Key

Environment Variable (Recommended)

Windows:

# Command Prompt
set CIMIS_API_KEY=your-actual-api-key-here

# PowerShell
$env:CIMIS_API_KEY="your-actual-api-key-here"

Linux/macOS:

# Temporary (current session)
export CIMIS_API_KEY="your-actual-api-key-here"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export CIMIS_API_KEY="your-actual-api-key-here"' >> ~/.bashrc
source ~/.bashrc

.env File (For Development)

Create a .env file in your project root:

# .env file
CIMIS_API_KEY=your-actual-api-key-here

Warning

Add .env to your .gitignore to prevent committing your API key!

Use with python-dotenv:

pip install python-dotenv

from dotenv import load_dotenv
load_dotenv()

import os
from python_cimis import CimisClient

client = CimisClient(app_key=os.getenv('CIMIS_API_KEY'))

Verification

Test your installation with this script:

#!/usr/bin/env python3
"""Test script to verify Python CIMIS Client installation."""

import os
from datetime import date, timedelta
from python_cimis import CimisClient

def test_installation():
    """Test the installation and API key."""
    try:
        # Check API key
        api_key = os.getenv('CIMIS_API_KEY')
        if not api_key:
            print("❌ Error: CIMIS_API_KEY environment variable not set")
            return False

        print(f"✅ API key found: {api_key[:8]}...{api_key[-4:]}")

        # Initialize client
        client = CimisClient(app_key=api_key)
        print("✅ Client initialized successfully")

        # Test station data
        stations = client.get_stations()
        print(f"✅ Retrieved {len(stations)} stations")

        # Test weather data
        yesterday = date.today() - timedelta(days=1)
        weather_data = client.get_daily_data(
            targets=[2],
            start_date=yesterday,
            end_date=yesterday
        )
        records = weather_data.get_all_records()
        print(f"✅ Retrieved {len(records)} weather records")

        # Test CSV export
        csv_file = client.export_to_csv(weather_data, filename="test_export.csv")
        print(f"✅ CSV exported to: {csv_file}")

        print("\\n🎉 All tests passed! Your installation is working correctly.")
        return True

    except Exception as e:
        print(f"❌ Error: {e}")
        return False

if __name__ == "__main__":
    success = test_installation()
    exit(0 if success else 1)

Save this as test_installation.py and run:

python test_installation.py

Troubleshooting

Common Issues

Permission Denied

ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied

Solutions:

# Option 1: Use --user flag
pip install --user python-CIMIS

# Option 2: Use virtual environment (recommended)
python -m venv venv
venv\\Scripts\\activate  # Windows
source venv/bin/activate  # Linux/macOS
pip install python-CIMIS

Python Version Incompatibility

ERROR: python-CIMIS requires Python '>=3.8' but the running Python is 3.7.x

Solution: Install Python 3.8 or higher from python.org

SSL Certificate Issues

SSL: CERTIFICATE_VERIFY_FAILED

Solutions:

# Update certificates (macOS)
/Applications/Python\\ 3.11/Install\\ Certificates.command

# Upgrade pip and certificates
pip install --upgrade pip certifi

Invalid API Key

CimisAuthenticationError: Invalid API key

Solutions:

Verify your API key is correct (check for extra spaces)
Ensure your CIMIS account is active
Regenerate your API key on the CIMIS website
Check environment variable is set correctly

Getting Help

Documentation: Check this documentation and the API reference
GitHub Issues: Report bugs at the GitHub repository
Examples: See the examples directory
CIMIS Official: Visit the CIMIS website for API documentation