PPQ APIppq.com.au ↗

"""
PPQ (Personalised Plates Queensland) API Client
Get your API key from: https://parse.bot/settings

This module provides a client for checking personalised plate availability,
getting pricing information, and finding similar plate suggestions.
"""

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


class ParseClient:
    """Client for interacting with the PPQ API via Parse."""
    
    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse client.
        
        Args:
            api_key: API key for Parse. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "38c41957-822c-4b80-8444-25c0c70930b7"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")
    
    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make a request to the Parse API.
        
        Args:
            endpoint: The endpoint name (e.g., 'check_availability')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters
            
        Returns:
            Response data from the API
            
        Raises:
            requests.RequestException: If the API 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 == "GET":
                response = requests.get(url, headers=headers, params=params, timeout=30)
            else:  # POST
                response = requests.post(url, headers=headers, json=params, timeout=30)
            
            response.raise_for_status()
            return response.json()
        except requests.RequestException as e:
            raise requests.RequestException(f"API request failed: {e}")
    
    def check_availability(
        self,
        combination: str,
        vehicle_type_id: str = "1"
    ) -> Dict[str, Any]:
        """
        Check whether a specific plate combination is available for purchase.
        
        Args:
            combination: The plate combination (1-7 alphanumeric characters)
            vehicle_type_id: Vehicle type ID (1=Motor Vehicle, 2=Trailer, 3=Motorcycle, 4=Small Trailer)
            
        Returns:
            Availability status, pricing, design options, and compatible design IDs
        """
        return self._call(
            "check_availability",
            method="POST",
            combination=combination,
            vehicle_type_id=vehicle_type_id
        )
    
    def get_plate_ranges(
        self,
        combination: str,
        vehicle_type_id: str = "1"
    ) -> Dict[str, Any]:
        """
        Get available plate ranges with pricing for a given combination.
        
        Faster than check_availability as it doesn't require reCAPTCHA solving.
        
        Args:
            combination: The plate combination (1-7 alphanumeric characters)
            vehicle_type_id: Vehicle type ID (1=Motor Vehicle, 2=Trailer, 3=Motorcycle, 4=Small Trailer)
            
        Returns:
            Available plate ranges, pricing by format, and vehicle type information
        """
        return self._call(
            "get_plate_ranges",
            method="POST",
            combination=combination,
            vehicle_type_id=vehicle_type_id
        )
    
    def get_suggestions(
        self,
        combination: str,
        vehicle_type_id: str = "1"
    ) -> Dict[str, Any]:
        """
        Get alternative plate combination suggestions similar to the input.
        
        Args:
            combination: The plate combination to find suggestions for (1-7 alphanumeric)
            vehicle_type_id: Vehicle type ID (1=Motor Vehicle, 2=Trailer, 3=Motorcycle, 4=Small Trailer)
            
        Returns:
            List of suggested combinations with availability and pricing
        """
        return self._call(
            "get_suggestions",
            method="POST",
            combination=combination,
            vehicle_type_id=vehicle_type_id
        )


def print_availability_details(client: ParseClient, plate: str) -> None:
    """Print detailed availability and pricing information for a plate."""
    print(f"\n{'='*60}")
    print(f"Checking plate: {plate}")
    print(f"{'='*60}")
    
    result = client.check_availability(plate)
    data = result.get("data", {})
    
    if data.get("available"):
        print(f"✓ {plate} is AVAILABLE!")
        design = data.get("default_design", {})
        print(f"  Default design: {design.get('name')}")
        print(f"  Price: ${design.get('buy_price', 0) / 100:.2f}")
        print(f"  Delivery: {design.get('delivery_days')} days")
        
        colours = design.get("foreground_colours", [])
        if colours:
            print(f"  Available colours: {', '.join([c.get('name') for c in colours])}")
        
        design_ids = data.get("available_design_ids", [])
        print(f"  Compatible designs: {len(design_ids)} available")
    else:
        print(f"✗ {plate} is NOT available")
        reason = data.get("reason", "Unknown reason")
        print(f"  Reason: {reason}")


def explore_pricing_options(client: ParseClient, plate: str) -> None:
    """Explore pricing across different plate ranges and formats."""
    print(f"\n{'='*60}")
    print(f"Plate ranges and pricing for: {plate}")
    print(f"{'='*60}")
    
    result = client.get_plate_ranges(plate)
    data = result.get("data", {})
    
    # Display available plate ranges
    ranges = data.get("plate_ranges", [])
    if ranges:
        print("\nPlate Ranges:")
        for range_item in ranges:
            status = "✓" if range_item.get("available") else "✗"
            price = range_item.get("purchase_from_price", 0)
            count = range_item.get("plate_design_count", 0)
            print(f"  {status} {range_item.get('name')}: from ${price} ({count} designs)")
    
    # Display format options with pricing
    formats = data.get("combination_formats", [])
    if formats:
        print("\nFormat Options:")
        for fmt in formats:
            price = fmt.get("price_from", 0)
            max_chars = fmt.get("max_chars", 0)
            print(f"  {fmt.get('name')} ({fmt.get('code')}): ${price} (up to {max_chars} chars)")


def find_alternatives(client: ParseClient, plate: str) -> None:
    """Find and display alternative plate suggestions."""
    print(f"\n{'='*60}")
    print(f"Alternative suggestions for: {plate}")
    print(f"{'='*60}")
    
    result = client.get_suggestions(plate)
    data = result.get("data", {})
    suggestions = data.get("suggestions", [])
    
    if not suggestions:
        print("No suggestions found.")
        return
    
    print(f"\nFound {len(suggestions)} suggestions:\n")
    
    for i, suggestion in enumerate(suggestions[:5], 1):  # Show top 5
        combo = suggestion.get("combination")
        available = "✓" if suggestion.get("available") else "✗"
        price = suggestion.get("priced_from", 0)
        score = suggestion.get("score", 0)
        distance = suggestion.get("levenshtein_distance", 0)
        format_name = suggestion.get("format_name", "Unknown")
        
        print(f"{i}. {available} {combo}")
        print(f"   Format: {format_name}")
        print(f"   Price from: ${price}")
        print(f"   Similarity score: {score} (distance: {distance})")
        print()


if __name__ == "__main__":
    # Initialize client
    client = ParseClient()
    
    # Practical workflow: Search for a plate, check options, and find alternatives
    target_plate = "PYTHON"
    
    # Step 1: Check availability and get detailed pricing
    print_availability_details(client, target_plate)
    
    # Step 2: Explore all pricing options across ranges and formats
    explore_pricing_options(client, target_plate)
    
    # Step 3: If the target plate isn't available, find alternatives
    availability = client.check_availability(target_plate)
    if not availability.get("data", {}).get("available"):
        find_alternatives(client, target_plate)
    
    # Step 4: Try an alternative and check its details
    print("\n" + "="*60)
    print("Workflow complete! Example of checking an alternative...")
    print("="*60)
    
    alt_plate = "PYTHON1"
    print_availability_details(client, alt_plate)