example_advanced.py

"""
ExisEcho API - Advanced Example

This example demonstrates advanced matching options including:
- Weighted columns
- Phonetic matching
- Custom preprocessing
- Multiple columns

Get your FREE test API key by emailing: exisllc@gmail.com
Documentation: https://www.fuzzy-logic.com/Api
"""

from exisecho import ExisEchoClient

# Replace with your API key
API_KEY = "your-api-key-here"


def main():
    # Initialize the client
    client = ExisEchoClient(API_KEY)

    # Sample customer records with multiple fields
    records = [
        {
            "id": "1",
            "fields": {
                "first_name": "Robert",
                "last_name": "Smith",
                "phone": "(555) 123-4567",
                "address": "123 Main Street"
            }
        },
        {
            "id": "2",
            "fields": {
                "first_name": "Bob",
                "last_name": "Smyth",
                "phone": "555-123-4567",
                "address": "123 Main St."
            }
        },
        {
            "id": "3",
            "fields": {
                "first_name": "Dr. Robert",
                "last_name": "Smith Jr.",
                "phone": "5551234567",
                "address": "123 Main Street, Apt 4"
            }
        },
        {
            "id": "4",
            "fields": {
                "first_name": "Jennifer",
                "last_name": "Johnson",
                "phone": "(555) 987-6543",
                "address": "456 Oak Avenue"
            }
        },
        {
            "id": "5",
            "fields": {
                "first_name": "Jenny",
                "last_name": "Johnson",
                "phone": "555.987.6543",
                "address": "456 Oak Ave"
            }
        },
    ]

    print("ExisEcho API - Advanced Example")
    print("=" * 50)
    print()
    print("Using weighted columns and specialized matching options...")
    print()

    # Advanced column options with different settings per column
    column_options = {
        "first_name": {
            "weight": 2.0,              # Name is important
            "usePhoneticMatching": True, # Robert = Bob sounds similar
            "equateSynonyms": True,      # Robert = Bob as synonyms
            "removeHonorifics": True,    # Remove Dr., Mr., etc.
            "ignoreCase": True
        },
        "last_name": {
            "weight": 2.5,              # Last name is most important
            "usePhoneticMatching": True, # Smith = Smyth
            "removePunctuation": True,   # Remove Jr., Sr., etc.
            "ignoreCase": True
        },
        "phone": {
            "weight": 1.5,
            "removeNonDigits": True      # Only compare digits
        },
        "address": {
            "weight": 1.0,
            "equateSynonyms": True,              # Street = St, Avenue = Ave
            "equateAddressAbbreviations": True,  # NYC = New York, SF = San Francisco
            "removePunctuation": True,
            "ignoreCase": True
        }
    }

    result = client.find_duplicates(
        records=records,
        threshold=0.65,
        column_options=column_options
    )

    if result["success"]:
        summary = result["summary"]
        print(f"Results:")
        print(f"  - Records analyzed: {summary['totalRecordsAnalyzed']}")
        print(f"  - Duplicates found: {summary['totalMatches']}")
        print(f"  - Average score: {summary['averageScore']:.0%}")
        print(f"  - Processing time: {summary['processingTimeMs']}ms")
        print()

        if result["matches"]:
            print("Potential Duplicates:")
            print("-" * 60)
            for match in result["matches"]:
                rec1 = next(r for r in records if r["id"] == match["record1Id"])
                rec2 = next(r for r in records if r["id"] == match["record2Id"])

                print(f"Match Score: {match['score']:.0%} ({match['quality']})")
                print(f"  Record {match['record1Id']}:")
                print(f"    Name: {rec1['fields']['first_name']} {rec1['fields']['last_name']}")
                print(f"    Phone: {rec1['fields']['phone']}")
                print(f"    Address: {rec1['fields']['address']}")
                print(f"  Record {match['record2Id']}:")
                print(f"    Name: {rec2['fields']['first_name']} {rec2['fields']['last_name']}")
                print(f"    Phone: {rec2['fields']['phone']}")
                print(f"    Address: {rec2['fields']['address']}")
                print()

        usage = result["usage"]
        print(f"API Usage: {usage['unitsConsumed']} units consumed, {usage['unitsRemaining']} remaining")
    else:
        print(f"Error: {result.get('error', 'Unknown error')}")


if __name__ == "__main__":
    main()