Python CLI - Social Analyzer

The Python CLI provides the most comprehensive command-line interface for Social Analyzer, with additional features like screenshots, custom logging, and the ability to import it as a Python module in your own projects.

Prerequisites

Install Python 3

Ensure Python 3.6 or higher is installed on your system.

Choose installation method

You can either install as a package from PyPI or clone from GitHub.

Installation

PyPI Package
From Source

pip3 install social-analyzer

Run as a module:

python3 -m social-analyzer --username "johndoe"

git clone https://github.com/qeeqbox/social-analyzer
cd social-analyzer
pip3 install -r requirements.txt

Run directly:

python3 app.py --username "johndoe"

Basic Usage

Simple Username Search

Search for a single username:

python3 -m social-analyzer --username "johndoe"

Multiple Usernames

Search for multiple users (comma-separated):

python3 -m social-analyzer --username "johndoe,janedoe"

For the rest of this guide, examples use python3 app.py syntax. If you installed via PyPI, replace with python3 -m social-analyzer.

CLI Arguments

Required Arguments

Argument	Description	Example
`--username`	Username(s) to search	`"johndoe"` or `"johndoe,janedoe"`

Website Selection

All Websites
Specific Websites
Top Ranked
By Country
By Type

python3 app.py --username "johndoe" --websites all

Searches all 900+ supported platforms (default).

python3 app.py --username "johndoe" --websites "youtube tiktok tumblr"

Space-separated list of specific platforms.

python3 app.py --username "johndoe" --top 100

Search only top N websites by global ranking.

python3 app.py --username "johndoe" --countries "us br ru"

Filter websites by country code(s).

python3 app.py --username "johndoe" --type "Music"

Filter by category (Adult, Music, Gaming, etc.).

Analysis Mode

Mode	Description
`fast`	Quick detection using basic techniques (default)
`slow`	Deep analysis with advanced detection
`special`	Special detections for Facebook, Gmail, etc.

python3 app.py --username "johndoe" --mode fast

Detection Method

python3 app.py --username "johndoe" --method all

all - Combines find and get (shows detected + unknown)
find - Only shows detected profiles
get - Shows all profiles regardless of detection status

Output Format

Pretty (default)
JSON

python3 app.py --username "johndoe" --output pretty

Colored, human-readable terminal output.

python3 app.py --username "johndoe" --output json

Structured JSON for integration and automation.

Filtering Results

Filter by Quality

# Good matches only (default)
python3 app.py --username "johndoe" --filter "good"

# Multiple quality levels
python3 app.py --username "johndoe" --filter "good,maybe"

# All quality levels
python3 app.py --username "johndoe" --filter "all"

Filter options:

good - High confidence (100% match rate or higher)
maybe - Medium confidence (50-99% match rate)
bad - Low confidence (less than 50% match rate)
all - All matches

Filter by Profile Status

# Detected profiles only (default)
python3 app.py --username "johndoe" --profiles "detected"

# Multiple statuses
python3 app.py --username "johndoe" --profiles "detected,unknown"

# All statuses
python3 app.py --username "johndoe" --profiles "all"

Profile status options:

detected - Successfully found profiles
unknown - Profiles with uncertain status
failed - Failed connection attempts

Data Extraction

Extract Patterns

python3 app.py --username "johndoe" --extract

Extracts additional information from detected profiles:

URLs and links
Email addresses
Phone numbers
Other patterns

Extract Metadata

python3 app.py --username "johndoe" --metadata

Extracts HTML meta tags from profile pages:

Open Graph tags
Twitter Cards
Schema.org structured data
Profile descriptions

Combined Extraction

python3 app.py --username "johndoe" --extract --metadata

Display Options

Customize Output Fields

python3 app.py --username "johndoe" --options "link,rate,title"

Available fields:

link - Profile URL
rate - Detection confidence percentage
title - Page title
text - Extracted text content

Trim Long Strings

python3 app.py --username "johndoe" --trim

Limits text content to 50 characters for cleaner output.

Python-Specific Features

Logging and Screenshots

Enable logging

python3 app.py --username "johndoe" --logs

Creates a temporary directory with detailed logs.

Custom log directory

python3 app.py --username "johndoe" --logs --logs_dir "/path/to/logs"

Specify a custom location for log files.

Enable screenshots

python3 app.py --username "johndoe" --logs --screenshots

Captures screenshots of detected profiles (requires Chrome).

Screenshots require the latest version of Chrome to be installed and only work when --logs is also enabled.

Simplify Output

python3 app.py --username "johndoe" --simplify

Outputs only profile links with 100% match rate - perfect for quick checks:

[Detected] 3 Profile[s]
https://twitter.com/johndoe
https://github.com/johndoe
https://reddit.com/user/johndoe

Silent Mode

python3 app.py --username "johndoe" --silent

Disables all terminal output (useful when using JSON output in scripts).

Timeout Configuration

python3 app.py --username "johndoe" --timeout 5

Sets a custom delay (in seconds) between requests to avoid rate limiting.

Custom Headers

python3 app.py --username "johndoe" --headers '{"User-Agent": "Custom Agent"}'

Provides custom HTTP headers as a JSON dictionary.

Complete Examples

python3 app.py --username "johndoe"

Using as a Python Module

You can import Social Analyzer as a module in your own Python projects:

Basic Import

from importlib import import_module

# Initialize
SocialAnalyzer = import_module("social-analyzer").SocialAnalyzer()

# Simple search
results = SocialAnalyzer.run_as_object(
    username="johndoe",
    silent=True
)

print(results)

Advanced Usage

from importlib import import_module

# Initialize
SocialAnalyzer = import_module("social-analyzer").SocialAnalyzer()

# Detailed search with options
results = SocialAnalyzer.run_as_object(
    username="johndoe,janedoe",
    silent=True,
    output="json",
    filter="good",
    metadata=True,
    extract=True,
    timeout=10,
    profiles="detected",
    websites="twitter github reddit"
)

print(results)

Available Parameters

SocialAnalyzer.run_as_object(
    username="",          # Required: username(s) to search
    websites="all",      # Websites to search
    mode="fast",         # Analysis mode
    output="pretty",     # Output format
    options="",          # Fields to display
    method="all",        # Detection method
    filter="good",       # Quality filter
    profiles="detected", # Profile status filter
    countries="all",     # Country filter
    type="all",          # Category filter
    top="0",             # Top N websites
    extract=False,       # Extract patterns
    metadata=False,      # Extract metadata
    trim=False,          # Trim long strings
    logs=False,          # Enable logging
    logs_dir="",         # Custom log directory
    timeout=0,           # Request timeout
    silent=False,        # Disable output
    screenshots=False,   # Capture screenshots
    simplify=False,      # Simplified output
    headers={}           # Custom HTTP headers
)

Processing Results

from importlib import import_module
import json

SocialAnalyzer = import_module("social-analyzer").SocialAnalyzer()

results = SocialAnalyzer.run_as_object(
    username="johndoe",
    silent=True,
    filter="good",
    profiles="detected"
)

# Process detected profiles
if "detected" in results:
    for profile in results["detected"]:
        print(f"Found: {profile['link']}")
        print(f"Confidence: {profile['rate']}")
        print(f"Title: {profile['title']}")
        print("---")

Listing Available Websites

python3 app.py --list

Displays all 900+ supported social media platforms and websites.

Output Examples

Pretty Output

[init] Detections are updated very often, make sure to get the most up-to-date ones
[init] languages.json & sites.json loaded successfully
[Init] Selected websites: 842
[Info] username: johndoe
[Checking] twitter.com
[Checking] github.com
-----------------------
link         : https://twitter.com/johndoe
rate         : %100.00
status       : good
title        : John Doe (@johndoe) / Twitter
language     : English
type         : Social Network
country      : us
rank         : 5
-----------------------
[Detected] 15 Profile[s]

JSON Output

{
  "detected": [
    {
      "link": "https://twitter.com/johndoe",
      "rate": "%100.00",
      "status": "good",
      "title": "John Doe (@johndoe) / Twitter",
      "language": "English",
      "type": "Social Network",
      "country": "us",
      "rank": "5",
      "text": "Software engineer and open source contributor...",
      "metadata": [
        {
          "property": "og:title",
          "content": "John Doe (@johndoe) / Twitter"
        },
        {
          "property": "og:description",
          "content": "Software engineer and open source contributor"
        }
      ]
    }
  ]
}

Performance and Configuration

Worker Threads: The Python version uses 15 worker threads by default for parallel checking. Request Delays: Random delays (10-99ms) between requests help avoid rate limiting. Retry Logic: Failed requests are automatically retried up to 3 times.

Troubleshooting

Module not found error Ensure social-analyzer is installed:

pip3 install --upgrade social-analyzer

Screenshot errors Install Chrome/Chromium and ensure --logs is enabled:

sudo apt-get install chromium-browser
python3 app.py --username "johndoe" --logs --screenshots

Permission errors with log directory Specify a writable directory:

python3 app.py --username "johndoe" --logs --logs_dir "./logs"

Import errors when using as module Use the importlib approach:

from importlib import import_module
SocialAnalyzer = import_module("social-analyzer").SocialAnalyzer()

Get Started

Usage

Features

Configuration

​Prerequisites

​Installation

​Basic Usage

​Simple Username Search

​Multiple Usernames

​CLI Arguments

​Required Arguments

​Website Selection

​Analysis Mode

​Detection Method

​Output Format

​Filtering Results

​Filter by Quality

​Filter by Profile Status

​Data Extraction

​Extract Patterns

​Extract Metadata

​Combined Extraction

​Display Options

​Customize Output Fields

​Trim Long Strings

​Python-Specific Features

​Logging and Screenshots

​Simplify Output

​Silent Mode

​Timeout Configuration

​Custom Headers

​Complete Examples

​Using as a Python Module

​Basic Import

​Advanced Usage

​Available Parameters

​Processing Results

​Listing Available Websites

​Output Examples

​Pretty Output

​JSON Output

​Performance and Configuration

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Installation

Basic Usage

Simple Username Search

Multiple Usernames

CLI Arguments

Required Arguments

Website Selection

Analysis Mode

Detection Method

Output Format

Filtering Results

Filter by Quality

Filter by Profile Status

Data Extraction

Extract Patterns

Extract Metadata

Combined Extraction

Display Options

Customize Output Fields

Trim Long Strings

Python-Specific Features

Logging and Screenshots

Simplify Output

Silent Mode

Timeout Configuration

Custom Headers

Complete Examples

Using as a Python Module

Basic Import

Advanced Usage

Available Parameters

Processing Results

Listing Available Websites

Output Examples

Pretty Output

JSON Output

Performance and Configuration

Troubleshooting