qodev-linkedin-api

Async Python client for LinkedIn data export API.

Installation

From PyPI (recommended)

pip install qodev-linkedin-api
# or
uv add qodev-linkedin-api

From GitHub (alternative)

uv add qodev-linkedin-api --source git+ssh://git@github.com/qodevai/linkedin-api.git

For development

git clone git@github.com:qodevai/linkedin-api.git
cd linkedin-api
make install
make install-hooks  # Set up pre-commit hooks

Quick Start

make install        # Install dependencies
make install-hooks  # Set up pre-commit hooks (recommended)
make check          # Run all quality checks
make test           # Run tests with coverage

Usage

Basic Usage

import asyncio
from linkedin import LinkedInClient

async def main():
    async with LinkedInClient() as client:
        # Get all connections
        connections = await client.get_connections()
        for conn in connections:
            print(f"{conn.first_name} {conn.last_name} - {conn.company}")

        # Get invitations (both sent and received)
        invitations = await client.get_invitations()

        # Get only outgoing invitations
        sent = await client.get_outgoing_invitations()

        # Get inbox messages
        messages = await client.get_inbox()

        # Get changelog (API changes tracking)
        changelog = await client.get_changelog()

asyncio.run(main())

Configuration

from linkedin import LinkedInClient

# Auth token from environment variable (default)
# Set LINKEDIN_AUTH_TOKEN env var
client = LinkedInClient()

# Or pass token directly
client = LinkedInClient(auth_token="your-token-here")

# Custom API version and timeout
client = LinkedInClient(
    api_version="202312",  # LinkedIn API version
    timeout=60.0,          # Request timeout in seconds
)

Error Handling

from linkedin import (
    LinkedInClient,
    AuthenticationError,
    RateLimitError,
    APIError,
)

async def fetch_with_retry():
    try:
        async with LinkedInClient() as client:
            return await client.get_connections()
    except AuthenticationError:
        print("Invalid or expired token")
    except RateLimitError as e:
        print(f"Rate limited. Retry after: {e.retry_after} seconds")
    except APIError as e:
        print(f"API error {e.status_code}: {e}")

Models

All responses are typed Pydantic models:

from linkedin import Connection, Invitation, Message, ChangeLogEntry

# Connection fields
conn: Connection
conn.url           # LinkedIn profile URL
conn.first_name
conn.last_name
conn.email         # Optional
conn.company       # Optional
conn.position      # Optional
conn.connected_on  # Date string

# Invitation fields
inv: Invitation
inv.to
inv.invitee_profile_url
inv.message        # Optional
inv.direction      # "OUTGOING" or "INCOMING"
inv.sent_at        # Date string

# Message fields
msg: Message
msg.conversation_id
msg.from_member
msg.to_member      # Optional
msg.content
msg.date           # Date string
msg.subject        # Optional
msg.folder         # Optional

# ChangeLogEntry fields
entry: ChangeLogEntry
entry.id
entry.method
entry.resource_name
entry.captured_at          # Unix timestamp (ms)
entry.processed_at         # Unix timestamp (ms)
entry.captured_datetime    # Property: datetime object
entry.processed_datetime   # Property: datetime object

Development

Available Commands

make help           # Show all available commands
make install        # Install all dependencies
make install-hooks  # Install pre-commit hooks
make check          # Run all checks (lint, format, typecheck, typos)
make test           # Run tests with coverage
make test-fast      # Run tests without coverage
make lint           # Lint code with ruff
make lint-fix       # Auto-fix lint issues
make format         # Format code with ruff
make typecheck      # Run type checking with pyright
make typos          # Check for typos
make build          # Build package (sdist + wheel)
make clean          # Clean generated files

Pre-commit Hooks

Pre-commit hooks run automatically on every commit:

make install-hooks  # Install once

Hooks include:

• YAML/TOML/JSON validation
• Trailing whitespace removal
• Ruff linting and formatting
• Typos spell checking

Running Checks Manually

# Run all checks (recommended before committing)
make check

# Or run individual checks
make lint
make format-check
make typecheck
make typos

Environment Variables

Requirements

• Python 3.11+
• uv (for development)

License

MIT