Metadata-Version: 2.4
Name: padam-api
Version: 1.0.0
Summary: Official Python SDK for Padam.id PLN Outage API
Author-email: Akbar Naufal Awalin <akbar@padam.id>
License: MIT
Project-URL: Homepage, https://padam.id
Project-URL: Repository, https://github.com/anauwal2/padam-python-sdk
Project-URL: Documentation, https://padam.id/docs
Keywords: pln,outage,indonesia,electricity,api,padam
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0

# padam-api

Official Python SDK for the [Padam.id](https://padam.id) PLN Outage API - the first PLN outage API in Indonesia.

## Installation

```bash
pip install padam-api
```

## Quick Start

```python
from padam_api import PadamClient

client = PadamClient(api_key="your_api_key")

# Check power outage at a location
outage = client.check_outage(-6.2088, 106.8456)
print(outage.summary.has_outage)

# Get meter billing and token estimate
meter = client.get_meter_summary(meter_id="566601485354")
print(meter.consumer_name)
```

## Usage

### Initialize Client

```python
from padam_api import PadamClient

client = PadamClient(
    api_key="your_api_key",
    base_url="https://padam.id/api",  # optional
    timeout=10  # optional, default 10 seconds
)
```

### Check Power Outage

Check for power outages within 500m radius of a location.

```python
result = client.check_outage(-6.2088, 106.8456)

print(f"Total poles: {result.summary.total_poles}")
print(f"Poles ON: {result.summary.poles_on}")
print(f"Poles OFF: {result.summary.poles_off}")
print(f"Has outage: {result.summary.has_outage}")

# Iterate through poles
for pole in result.poles:
    print(f"{pole.name}: {pole.status}")
```

### Get Meter Summary

Get billing history and token estimate for a meter.

```python
# Using meter ID (recommended)
result = client.get_meter_summary(meter_id="566601485354")

# Or using account ID
result = client.get_meter_summary(account_id="8651306")

print(f"Consumer: {result.consumer_name}")
print(f"Energy type: {result.energy_type}")
print(f"Energy: {result.energy} VA")

# Token estimate (prepaid meters)
if result.token_estimate:
    print(f"Remaining days: {result.token_estimate.remaining_days}")
    print(f"Remaining kWh: {result.token_estimate.remaining_kwh}")
    print(f"Daily usage: {result.token_estimate.daily_usage_kwh} kWh")

# Billing history
for entry in result.billing_history:
    print(f"{entry.date}: Rp {entry.amount:,} ({entry.kwh} kWh)")
```

### Error Handling

```python
from padam_api import PadamClient, PadamAPIError

try:
    result = client.check_outage(-6.2088, 106.8456)
except PadamAPIError as e:
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print(f"Status code: {e.status_code}")
```

### Context Manager

```python
with PadamClient(api_key="your_api_key") as client:
    result = client.check_outage(-6.2088, 106.8456)
    print(result.summary.has_outage)
```

## API Reference

### PadamClient

#### Constructor

```python
PadamClient(
    api_key: str,
    base_url: str = "https://padam.id/api",
    timeout: int = 10
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | str | required | Your API key |
| `base_url` | str | `https://padam.id/api` | API base URL |
| `timeout` | int | `10` | Request timeout in seconds |

#### Methods

- `check_outage(latitude: float, longitude: float)` - Check power outage at location
- `get_meter_summary(meter_id: str = None, account_id: str = None)` - Get meter summary
- `close()` - Close the underlying session

## Response Types

### OutageCheckResponse

- `success: bool`
- `latitude: float`
- `longitude: float`
- `radius: int`
- `summary: OutageSummary`
- `poles: List[Pole]`
- `credits_remaining: int`

### MeterSummaryResponse

- `success: bool`
- `account_id: str`
- `meter_id: str`
- `consumer_name: str`
- `energy_type: str`
- `energy: int`
- `is_prepaid: bool`
- `token_estimate: TokenEstimate`
- `billing_history: List[BillingEntry]`
- `credits_remaining: int`

## License

MIT

## Author

Akbar Naufal Awalin
