Python SDK

The Surfer Protocol Python SDK provides a simple interface to interact with the Surfer-Data desktop application.

Prerequisites

  1. Desktop Application: The Surfer desktop application must be running in the background for the SDK to work.

Note: The desktop app runs a local server on port 2024 that the SDK communicates with. Make sure the server is running before using the SDK.

Installation

pip install surfer-protocol

Quick Start

from surfer_protocol import SurferClient

# Initialize the client
client = SurferClient()

# Get data for a specific platform
data = client.get("bookmarks-001")

# Export data for a platform
export_result = client.export("bookmarks-001")

API Reference

SurferClient

The main client class for interacting with the Surfer Protocol desktop application.

from surfer_protocol import SurferClient

client = SurferClient()

Methods

get(platform_id: str) -> dict

Retrieves the most recent data for a specific platform.

# Get Twitter bookmarks
bookmarks = client.get("bookmarks-001")

# Get Gmail data
emails = client.get("gmail-001")

# Get iMessage data
messages = client.get("imessage-001")

export(platform_id: str) -> dict

Triggers a new export for a specific platform.

export_result = client.export("bookmarks-001")

Platform IDs

The following platform IDs are currently supported:

  • bookmarks-001: Twitter bookmarks
  • gmail-001: Gmail messages
  • imessage-001: iMessage conversations
  • connections-001: LinkedIn connections
  • notion-001: Notion workspace
  • chatgpt-001: ChatGPT history

Response Schemas

All API responses follow a standard format:

{
    "company": str,        # Company name
    "name": str,          # Platform name
    "runID": str,        # Unique export identifier
    "timestamp": int,    # Unix timestamp of export
    "content": List[Dict] # Platform-specific data
}

To view the full schema for each platform, see the platforms page and choose the platform you're interested in.

Example Applications

Check out our Cookbook for example applications built with Surfer Protocol.

Error Handling

The SDK includes built-in error handling for common scenarios:

try:
    client = SurferClient()
    data = client.get("bookmarks-001")
except ConnectionError as e:
    print("Failed to connect to Surfer desktop app. Is it running?")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Best Practices

  1. Connection Management: The client automatically manages the connection and cleans up resources when destroyed.
  2. Error Handling: Always wrap API calls in try-except blocks to handle potential connection issues.
  3. Resource Efficiency: Reuse the same client instance for multiple operations instead of creating new instances.