Python SDK

Official Python SDK for the Heydeo API.

Installation

pip install heydeo

Quick Start

from heydeo import HeydeoClient

# Initialize the client
client = HeydeoClient(
    api_key="your-api-key",
    base_url="https://api.heydeo.ai/v1",  # Optional
)

# Search for shipments
shipments = client.shipments.search(
    origin="US",
    destination="CN",
    hs_code="8517",
    page=1,
    limit=20,
)

print(shipments)

Async Support

The SDK supports both synchronous and asynchronous usage:

from heydeo import AsyncHeydeoClient
import asyncio

async def main():
    client = AsyncHeydeoClient(api_key="your-api-key")
    
    shipments = await client.shipments.search(
        origin="US",
        destination="CN",
    )
    
    print(shipments)

asyncio.run(main())

Configuration

client = HeydeoClient(
    api_key="your-api-key",           # Required
    base_url="https://api.heydeo.ai/v1",  # Optional
    timeout=30,                       # Optional (default: 30s)
    max_retries=3,                    # Optional (default: 3)
)

Shipments

Search Shipments

shipments = client.shipments.search(
    origin="US",
    destination="CN",
    hs_code="8517",
    date_from="2024-01-01",
    date_to="2024-12-31",
    page=1,
    limit=20,
)

Get Shipment Details

shipment = client.shipments.get("shipment-id")

HS Codes

Search HS Codes

hs_codes = client.hs_codes.search(
    query="smartphone",
    chapter="85",  # Optional
)

Get HS Code Details

hs_code = client.hs_codes.get("8517")

Buyers

Search Buyers

buyers = client.buyers.search(
    country="CN",
    hs_code="8517",
    min_volume=1000,
)

Get Buyer Details

buyer = client.buyers.get("buyer-id")

Documents

Generate Document

from heydeo.types import DocumentType

document = client.documents.generate(
    type=DocumentType.COMMERCIAL_INVOICE,
    shipment_id="shipment-id",
    data={
        "invoice_number": "INV-001",
        "seller": {"name": "Acme Corp", "address": "..."},
        "buyer": {"name": "Buyer Ltd", "address": "..."},
        "items": [
            {"description": "Product A", "quantity": 100, "unit_price": 50}
        ],
    },
)

Download Document

pdf_bytes = client.documents.download("document-id")

Error Handling

from heydeo.exceptions import (
    HeydeoError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
)

try:
    shipments = client.shipments.search(origin="US")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
except ValidationError as e:
    print(f"Validation error: {e}")
except HeydeoError as e:
    print(f"API error: {e}")

Type Hints

The SDK includes full type hints with Pydantic models:

from heydeo import HeydeoClient
from heydeo.types import Shipment, HSCode, Buyer

client = HeydeoClient(api_key="your-api-key")

shipments: list[Shipment] = client.shipments.search(
    origin="US",
    destination="CN",
)

# Access typed fields
for shipment in shipments:
    print(shipment.origin_country)
    print(shipment.destination_country)
    print(shipment.hs_code)

📚 Additional Resources