Web API Endpoints

Express.js web API reference for Social Analyzer

Overview

Social Analyzer includes an Express.js web server providing REST API endpoints for profile analysis, settings management, and task control.

---

Starting the Web Server

Node.js

npm start
# Server runs on http://localhost:9005

Docker

docker run -p 9005:9005 qeeqbox/social-analyzer

---

Base URL

http://localhost:9005

All endpoints are relative to this base URL.

---

Endpoints

POST /analyze_string

Analyze a username across social media platforms.

string · string · required

Username to analyze. Can be a single username or comma-separated list for batch analysis.

"johndoe"
"johndoe,janedoe,user123"

uuid · string · required

Unique task identifier (UUID format). Used for logging and task tracking.

"550e8400-e29b-41d4-a716-446655440000"

option · string · required

Comma-separated analysis options. Available options:

• FindUserProfilesFast - Fast profile detection
• GetUserProfilesFast - Fast profile retrieval
• FindUserProfilesSlow - Deep profile detection (not compatible with Fast)
• ShowUserProfilesSlow - Show advanced profiles without finding
• FindUserProfilesSpecial - Specialized detection methods
• LookUps - External search engine lookups
• CustomSearch - Google custom search integration
• FindOrigins - Name origin analysis
• SplitWordsByUpperCase - Split username by uppercase letters
• SplitWordsByAlphabet - Split username alphabetically
• FindSymbols - Detect symbols in username
• FindNumbers - Detect numbers in username
• FindAges - Guess age from username
• ConvertNumbers - Convert numbers to words
• WordInfo - Get word information
• MostCommon - Find most common words
• ExtractMetadata - Extract OSINT metadata
• NetworkGraph - Generate relationship graph (requires ExtractMetadata)
• CategoriesStats - Generate category statistics
• MetadataStats - Generate metadata statistics

"FindUserProfilesFast,GetUserProfilesFast"
"FindUserProfilesSlow,ShowUserProfilesSlow,ExtractMetadata"

group · boolean

Automatically set to true if string contains commas (batch mode)

Response

username · string

Analyzed username

uuid · string

Task UUID

info · object

Analysis metadata

Show info fields

items · array

Search engine results

original · string

Original username

corrected · string

Corrected/normalized username

total · number

Total profiles checked

checking · string

Status message

user_info_normal · object

Fast scan results

Show user_info_normal fields

data · array

Array of detected profiles with link, rate, status, title, etc.

type · string

Scan type (“all”)

user_info_advanced · object

Slow/deep scan results (if enabled)

Show user_info_advanced fields

data · array

Advanced detection results

type · string

Scan type (“all”, “show”, or “noshow”)

user_info_special · object

Special detection results (if enabled)

Show user_info_special fields

data · array

Special detection results

type · string

Scan type (“all”)

ages · array

Guessed ages from username (if FindAges enabled)

names_origins · array

Name origin analysis (if FindOrigins enabled)

table · object

Parsed username components

Show table fields

prefix · array

Detected prefixes

name · array

Detected names

number · array

Detected numbers

symbol · array

Detected symbols

unknown · array

Unknown components

maybe · array

Possible word matches

common · array

Most common words (if MostCommon enabled)

words_info · array

Word information from dictionary (if WordInfo enabled)

custom_search · array

Google custom search results (if CustomSearch enabled)

graph · object

Network relationship graph (if NetworkGraph enabled)

Show graph structure

graph.nodes · array

Graph nodes

graph.links · array

Graph edges/connections

stats · object

Statistics (if CategoriesStats or MetadataStats enabled)

Show stats fields

categories · object

Category distribution

countries · object

Country distribution

logs · string

Task log contents

Example Request

curl -X POST http://localhost:9005/analyze_string \
  -H "Content-Type: application/json" \
  -d '{
    "string": "johndoe",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "option": "FindUserProfilesFast,GetUserProfilesFast,ExtractMetadata"
  }'

Example Response

{
  "username": "johndoe",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "info": {
    "items": [],
    "original": "johndoe",
    "corrected": "johndoe",
    "total": 15,
    "checking": "Using johndoe with no lookups"
  },
  "user_info_normal": {
    "data": [
      {
        "link": "https://www.youtube.com/johndoe",
        "rate": "100%",
        "status": "good",
        "title": "John Doe - YouTube",
        "language": "English",
        "type": "Video",
        "extracted": {
          "profiles": ["@johndoe"],
          "urls": ["https://example.com"]
        }
      }
    ],
    "type": "all"
  },
  "user_info_advanced": {
    "data": [],
    "type": "all"
  },
  "user_info_special": {
    "data": [],
    "type": "all"
  },
  "ages": [],
  "names_origins": [],
  "table": {
    "name": ["john"],
    "maybe": ["doe"]
  },
  "common": [],
  "words_info": [],
  "custom_search": [],
  "graph": {
    "graph": {
      "nodes": [],
      "links": []
    }
  },
  "stats": {
    "categories": {},
    "countries": {}
  },
  "logs": "[init] Starting analysis...\n[Done] Analysis complete"
}

---

GET /get_settings

Retrieve current server settings and available websites.

Response

proxy · string

Configured proxy URL (empty if none)

user_agent · string

Current User-Agent header

google · array

Google API credentials (partially masked)

["AIzaSyBCDE******", "012345678f******"]

websites · array

Available websites with selection status

Show website object

index · number

Website index in the list

url · string

Website domain

selected · string

Selection status (“true” or “false”)

global_rank · number

Website popularity rank

Example Request

curl http://localhost:9005/get_settings

Example Response

{
  "proxy": "",
  "user_agent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:86.0) Gecko/20100101 Firefox/86.0",
  "google": [
    "AIzaSyBCDE******",
    "012345678f******"
  ],
  "websites": [
    {
      "index": 0,
      "url": "youtube.com",
      "selected": "true",
      "global_rank": 2
    },
    {
      "index": 1,
      "url": "twitter.com",
      "selected": "true",
      "global_rank": 8
    }
  ]
}

---

POST /save_settings

Update server settings and website selections.

websites · string

Comma-separated indices of websites to select

"0,1,5,10,25"

google_key · string

Google API key (or masked value to keep current)

google_cv · string

Google Custom Search engine ID (or masked value to keep current)

user_agent · string

Custom User-Agent header

proxy · string

Proxy URL (empty to disable)

Response

response · string

Success message

"Done"

Example Request

curl -X POST http://localhost:9005/save_settings \
  -H "Content-Type: application/json" \
  -d '{
    "websites": "0,1,2,3,4",
    "user_agent": "CustomBot/1.0",
    "proxy": "",
    "google_key": "AIzaSyBCDE******",
    "google_cv": "012345678f******"
  }'

---

POST /get_logs

Retrieve the last log line for a task.

uuid · string · required

Task UUID

Response

Returns plain text (not JSON):

• Last log line if file exists and has content
• "nothing_here_error" if log file doesn’t exist
• "nothinghere" if UUID is empty

Example Request

curl -X POST http://localhost:9005/get_logs \
  -H "Content-Type: application/json" \
  -d '{"uuid": "550e8400-e29b-41d4-a716-446655440000"}'

Example Response

[Finished] Analyzing: johndoe Task: 550e8400-e29b-41d4-a716-446655440000

---

GET /generate

Generate username combinations from a list of words.

option · string · required

Must be “Generate”

words · array · required

Array of 2-7 words to combine

Response

combinations · array

All possible combinations of the input words

["johndoe", "doejohn", "john", "doe"]

Example Request

curl "http://localhost:9005/generate?option=Generate&words[]=john&words[]=doe"

Example Response

{
  "combinations": [
    "johndoe",
    "doejohn",
    "john",
    "doe"
  ]
}

---

POST /cancel

Cancel a running analysis task.

option · string · required

Must be “on” to trigger cancellation

uuid · string · required

Task UUID to cancel (sanitized, alphanumeric and hyphens only)

Response

response · string

Success message

"Done"

Example Request

curl -X POST http://localhost:9005/cancel \
  -H "Content-Type: application/json" \
  -d '{
    "option": "on",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

---

Special Test Endpoint

The /analyze_string endpoint has a special test mode:

curl -X POST http://localhost:9005/analyze_string \
  -H "Content-Type: application/json" \
  -d '{
    "string": "test_user_2021_2022_",
    "uuid": "test",
    "option": "FindUserProfilesFast"
  }'

If a file named test.json exists in the server directory, it will be returned instead of performing actual analysis.

---

Error Responses

All endpoints may return:

"Error"

When:

• Required parameters are missing
• Invalid data is provided
• Internal errors occur

---

Integration Examples

JavaScript/Node.js

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

async function analyzeUsername(username) {
  try {
    const response = await axios.post('http://localhost:9005/analyze_string', {
      string: username,
      uuid: uuidv4(),
      option: 'FindUserProfilesFast,GetUserProfilesFast,ExtractMetadata'
    });
    
    console.log(`Found ${response.data.user_info_normal.data.length} profiles`);
    
    response.data.user_info_normal.data.forEach(profile => {
      console.log(`[${profile.rate}] ${profile.link}`);
    });
    
    return response.data;
  } catch (error) {
    console.error('Error:', error.message);
  }
}

analyzeUsername('johndoe');

Python

import requests
import uuid
import json

def analyze_username(username):
    url = 'http://localhost:9005/analyze_string'
    
    payload = {
        'string': username,
        'uuid': str(uuid.uuid4()),
        'option': 'FindUserProfilesFast,GetUserProfilesFast,ExtractMetadata'
    }
    
    try:
        response = requests.post(url, json=payload)
        response.raise_for_status()
        
        data = response.json()
        
        profiles = data.get('user_info_normal', {}).get('data', [])
        print(f"Found {len(profiles)} profiles\n")
        
        for profile in profiles:
            print(f"[{profile['rate']}] {profile['link']}")
            if 'title' in profile:
                print(f"  {profile['title']}")
            print()
        
        return data
        
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

result = analyze_username('johndoe')

cURL with Polling

#!/bin/bash

USERNAME="johndoe"
UUID=$(uuidgen)

echo "Starting analysis for $USERNAME..."

# Start analysis
curl -X POST http://localhost:9005/analyze_string \
  -H "Content-Type: application/json" \
  -d "{
    \"string\": \"$USERNAME\",
    \"uuid\": \"$UUID\",
    \"option\": \"FindUserProfilesFast,GetUserProfilesFast\"
  }" > results.json

echo "Analysis complete. Results saved to results.json"

# Extract detected profiles
jq '.user_info_normal.data[] | "[\(.rate)] \(.link)"' results.json

---

Notes

The web server is single-threaded by default. For production use, consider using a process manager like PM2 or running multiple instances behind a load balancer.

UUIDs in /cancel and /get_logs are sanitized to alphanumeric and hyphens only. Use standard UUID format.

For long-running tasks, poll /get_logs periodically to monitor progress:

watch -n 2 'curl -s -X POST http://localhost:9005/get_logs -H "Content-Type: application/json" -d "{\"uuid\": \"$UUID\"}"'

---

See Also

CLI Reference

Command-line interface documentation

Python API

Python class and methods reference

Output Formats

Understanding result structures

Quickstart

Get started with Social Analyzer