SMSA Express APIsmsaexpress.com ↗

"""
SMSA Express Shipment Tracking API Client

Track shipments on SMSA Express by entering tracking numbers (AWB numbers).
Supports multiple tracking numbers in a single request.

Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, List, Dict, Any


class ParseClient:
    """Client for interacting with the Parse API for SMSA Express shipment tracking."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.

        Args:
            api_key: Your Parse API key. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "bbefb5fe-6810-4dba-9726-6bea4f024e8f"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Set PARSE_API_KEY environment variable or pass api_key parameter."
            )

    def _call(
        self, endpoint: str, method: str = "POST", **params
    ) -> Dict[str, Any]:
        """
        Make a request to the Parse API.

        Args:
            endpoint: The endpoint name to call.
            method: HTTP method (GET or POST).
            **params: Query/body parameters to send.

        Returns:
            JSON response as dictionary.

        Raises:
            requests.exceptions.RequestException: If the request fails.
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json",
        }

        try:
            if method.upper() == "GET":
                response = requests.get(url, headers=headers, params=params)
            elif method.upper() == "POST":
                response = requests.post(url, headers=headers, json=params)
            else:
                raise ValueError(f"Unsupported HTTP method: {method}")

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            print(f"API request failed: {e}")
            raise

    def track_shipment(
        self,
        tracking_numbers: str,
        language: str = "EN",
    ) -> Dict[str, Any]:
        """
        Track one or more shipments by their SMSA Express tracking numbers (AWB numbers).

        Args:
            tracking_numbers: One or more SMSA Express tracking numbers (AWB numbers),
                            separated by commas or spaces (e.g. '290019498498' or
                            '290019498498,290019934499').
            language: Language for tracking response. Accepts: EN, AR, FR. Defaults to EN.

        Returns:
            Dictionary containing tracking_numbers, shipments array, and total_found count.

        Example:
            >>> client = ParseClient()
            >>> result = client.track_shipment("290019498498")
            >>> print(f"Found {result['total_found']} shipment(s)")
        """
        return self._call(
            "track_shipment",
            method="POST",
            tracking_numbers=tracking_numbers,
            language=language,
        )


def display_shipment_info(shipment: Dict[str, Any]) -> None:
    """
    Pretty print shipment tracking information.

    Args:
        shipment: Shipment data dictionary.
    """
    print("\n" + "=" * 60)
    for key, value in shipment.items():
        if isinstance(value, dict):
            print(f"  {key}:")
            for sub_key, sub_value in value.items():
                print(f"    {sub_key}: {sub_value}")
        elif isinstance(value, list):
            print(f"  {key}: {len(value)} items")
            for item in value[:3]:
                print(f"    - {item}")
            if len(value) > 3:
                print(f"    ... and {len(value) - 3} more")
        else:
            print(f"  {key}: {value}")
    print("=" * 60)


if __name__ == "__main__":
    # Initialize the client
    client = ParseClient()

    # Practical use case: Track multiple shipments and display results
    print("SMSA Express Shipment Tracking Example")
    print("-" * 60)

    # Example 1: Track a single shipment
    print("\n1. Tracking a single shipment...")
    single_tracking = "290019498498"
    result = client.track_shipment(single_tracking)

    print(f"Queried tracking numbers: {result['tracking_numbers']}")
    print(f"Total shipments found: {result['total_found']}")

    if result["total_found"] > 0:
        print(f"\nShipment details:")
        for shipment in result["shipments"]:
            display_shipment_info(shipment)
    else:
        print("No shipments found for this tracking number.")

    # Example 2: Track multiple shipments in one request
    print("\n\n2. Tracking multiple shipments...")
    multiple_tracking = "290019498498,290019934499"
    result = client.track_shipment(multiple_tracking)

    print(f"Queried tracking numbers: {result['tracking_numbers']}")
    print(f"Total shipments found: {result['total_found']}")

    if result["total_found"] > 0:
        print(f"\nProcessing {result['total_found']} shipment(s):\n")
        for idx, shipment in enumerate(result["shipments"], 1):
            print(f"Shipment #{idx}:")
            display_shipment_info(shipment)
    else:
        print("No shipments found for the provided tracking numbers.")

    # Example 3: Track with different language
    print("\n\n3. Tracking with Arabic language preference...")
    result = client.track_shipment("290019498498", language="AR")

    print(f"Language: AR (Arabic)")
    print(f"Total shipments found: {result['total_found']}")

    if result["total_found"] > 0:
        for shipment in result["shipments"]:
            display_shipment_info(shipment)

    # Example 4: Batch processing workflow
    print("\n\n4. Batch processing multiple tracking numbers...")
    tracking_list = [
        "290019498498",
        "290019934499",
        "290019111222",
    ]

    batch_results = {}
    for tracking_num in tracking_list:
        print(f"Processing tracking number: {tracking_num}...")
        try:
            result = client.track_shipment(tracking_num)
            batch_results[tracking_num] = result
        except Exception as e:
            print(f"Failed to track {tracking_num}: {e}")
            batch_results[tracking_num] = {"error": str(e)}

    # Summary report
    print("\n\nBatch Processing Summary:")
    print("-" * 60)
    successful = sum(1 for r in batch_results.values() if "total_found" in r)
    failed = len(batch_results) - successful

    print(f"Total requests: {len(batch_results)}")
    print(f"Successful: {successful}")
    print(f"Failed: {failed}")

    for tracking_num, result in batch_results.items():
        if "total_found" in result:
            print(f"  {tracking_num}: {result['total_found']} shipment(s) found")
        else:
            print(f"  {tracking_num}: Error - {result.get('error', 'Unknown error')}")