Cherkasyoblenergo API

Unofficial API service for retrieving power outage schedules from cherkasyoblenergo.com. Get real-time and historical power outage information through a RESTful API interface.

📋 Table of Contents

• Cherkasyoblenergo API
  • 📋 Table of Contents
  • ✨ Key Features
  • 🚀 Installation
    • Prerequisites
    • Setup
  • 🔑 API Documentation
    • Base URL
    • Available Endpoints
  • 💻 Development
    • Requirements
    • Local Development
  • 🤝 Contributing
  • ❗ Troubleshooting
  • 🚦 Running Tests
  • ⚡ Free API Access

✨ Key Features

• Real-time power outage schedule data
• Historical data access
• RESTful API interface
• Rate limiting support
• API key authentication
• Docker deployment support

🚀 Installation

Prerequisites

• Docker
• Docker Compose
• PostgreSQL 17 (only if running without Docker)

Setup

1. Clone the repository:

git clone https://github.com/Sigmanor/cherkasyoblenergo-api.git
cd cherkasyoblenergo-api

2. Create .env file with required configurations:

DB_HOST=localhost
DB_PORT=5432
DB_USER=root
DB_PASSWORD=your_strong_db_password
DB_NAME=myCoolDB
ADMIN_PASSWORD=your_strong_admin_password
SERVER_PORT=3000

3. Choose deployment method:

Full Docker deployment (with PostgreSQL):

# Create persistent volume for PostgreSQL
docker volume create postgres_data

# Deploy both app and database
docker-compose --env-file .env up -d --build

App-only deployment (for existing PostgreSQL):

docker-compose -f docker-compose.app-only.yml --env-file .env up -d --build

🔑 API Documentation

Base URL

/cherkasyoblenergo/api

Available Endpoints

• POST /blackout-schedule - Get power outage schedules
• GET /generate-api-key - Generate API key (admin only)
• GET /update-api-key - Manage API keys (admin only)

Detailed API Documentation

💻 Development

Requirements

• Go 1.23 or higher
• PostgreSQL 17
• Docker and Docker Compose (for containerized deployment)

Local Development

# Run locally
go run ./cmd/server/main.go

# Build
go build -o cherkasyoblenergo_api ./cmd/server/main.go

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

❗ Troubleshooting

• Database Connection Issues:
  • For Docker deployment: Check if postgres_data volume is created
  • Verify PostgreSQL credentials and connection settings in .env
  • For full Docker setup, ensure the db service is healthy
• API Key Issues: Ensure proper API key generation and rate limit configuration
• Docker Issues:
  • Check Docker logs: docker-compose logs
  • Verify Docker network configuration
  • Ensure all required environment variables are set

🚦 Running Tests

To run the tests locally:

go test ./...

⚡ Free API Access

Limited free access (2 requests/minute) available for testing. Contact via email for access.