Metadata-Version: 2.1
Name: synmax-api-python-client
Version: 4.13.1
Summary: Synmax API client
Home-page: https://github.com/SynMaxDev/synmax-api-python-client.git
Author: SynMax Inc.
Author-email: support@synmax.com
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.11.14
Requires-Dist: aioretry>=6.3.1
Requires-Dist: packaging>=24.2
Requires-Dist: pandas>=2.0.3
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pydantic-core<2.32.0,>=2.27.2
Requires-Dist: requests>=2.32.3
Requires-Dist: tenacity>=9.0.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: urllib3>=2.3.0
Requires-Dist: prance>=25.4.8.0
Requires-Dist: openapi-spec-validator>=0.7.1
Requires-Dist: httpx>=0.28.1

# SynMax API Python Client

[![PyPI version](https://badge.fury.io/py/synmax-api-python-client.svg)](https://pypi.org/project/synmax-api-python-client/)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Proprietary-lightgrey.svg)](https://synmax.com)

The official Python SDK for SynMax APIs—providing unified access to **Hyperion**, **Vulcan**, and **Leviaton** data products.

---

## Introduction

The energy and infrastructure industries rely on timely, accurate data for critical decision-making. The **SynMax API Python Client** solves the challenge of fragmented data access by providing a single SDK to interact with three powerful data platforms:

- **Hyperion**: Near real-time U.S. oil & gas drilling, completion, production data as well as forecasts
- **Vulcan**: Power and infrastructure monitoring with satellite-derived construction status intelligence for power plants, data centers, and LNG facilities
- **Leviaton**: Global LNG vessel tracking, cargo flows, and transaction data with forecasting capabilities

---

## Installation

Install the SDK via pip:

```bash
pip install --upgrade synmax-api-python-client
```

**Requirements:**
- Python 3.10 or higher
- pip (Python package installer)

---

## Authentication

All SynMax APIs authenticate requests using an **API access token** tied to your subscription.

**To obtain an access token, contact:** [support@synmax.com](mailto:support@synmax.com)

Pass your token directly when initializing any client:

```python
access_token = "your_access_token_here"
```

---

## Quick Start

### Hyperion (Oil & Gas Data)

```python
import datetime
from synmax.hyperion.v4 import HyperionApiClient

client = HyperionApiClient(access_token="your_access_token_here")

# Fetch short-term production forecast
data = client.short_term_forecast(
    aggregate_by=["date_prod", "sub_region_natgas"],
    date_prod_min=datetime.date(2025, 5, 1),
    date_prod_max=datetime.date(2025, 6, 30),
)

df = data.df()  # Returns pandas DataFrame
print(df.head())
```

### Vulcan (Power & Infrastructure)

```python
from synmax.vulcan.v2 import VulcanApiClient

client = VulcanApiClient(access_token="your_access_token_here")

# Fetch datacenter project data
datacenters = client.datacenters()

df = datacenters.df()  # Returns pandas DataFrame
print(df.head())
```

### Leviaton (LNG Vessel Tracking)

```python
from synmax.leviaton.v1 import LeviatonApiClient

client = LeviatonApiClient(access_token="your_access_token_here")

# Fetch LNG transactions from US to Europe
transactions = client.transactions(
    origin_country_codes=["US"],
    destination_country_codes=["DE", "FR", "UK", "NL", "BE"],
    from_timestamp="2025-06-01T00:00:00Z",
    to_timestamp="2025-06-23T23:59:59Z",
)

df = transactions.df()  # Returns pandas DataFrame
print(df.head())
```

---

## Usage Patterns

### Fetch Data as DataFrame

Best for datasets that fit in memory:

```python
df = client.some_endpoint(**params).df()
```

### Stream Large Datasets to File

For large datasets, iterate through chunks:

```python
import json

data_generator = client.some_endpoint(**params)

with open("output.json", "w") as f:
    f.write("[\n")
    first = True
    for record in data_generator:
        if not first:
            f.write(",\n")
        json.dump(record, f, indent=2, default=str)
        first = False
    f.write("\n]")
```

---

## Features

- **Unified SDK**: Single package for Hyperion, Vulcan, and Leviaton APIs
- **Pandas Integration**: Native `.df()` method returns data as DataFrames
- **Generator Support**: Memory-efficient streaming for large datasets
- **Type Hints**: Full autocomplete support in modern IDEs

---

## Documentation & Support

| Product   | Documentation |
|-----------|---------------|
| Hyperion  | [apidocs.synmax.com](https://apidocs.synmax.com/) |
| Vulcan    | [docs.vulcan.synmax.com](https://apidocs.vulcan.synmax.com/) |
| Leviaton  | [leviaton.apidocs.synmax.com](https://leviaton.apidocs.synmax.com/) |

**Support:** [support@synmax.com](mailto:support@synmax.com)

---

## License

This SDK is proprietary software. See [synmax.com](https://synmax.com) for licensing details.
