Noimosiny Python SDK

Python client library for the Noimosiny API (OSINT and reverse-lookup platform).

Installation

Install the package via pip:

pip install noimosiny

Note: For local development, ensure dependencies are installed via pip install requests.

Quick Start

Initialize the Client using your API token (which can be obtained from the settings page on the Noimosiny dashboard). You can retrieve your balance and perform searches within a context manager block:

import os
from noimosiny import Client, NoimosinyError

def main():
    # Load API token from environment
    api_key = os.environ.get("NOIMOSINY_API_KEY", "your-api-key-here")

    try:
        # Use Client as a context manager for clean session closing
        with Client(api_key) as client:
            # Check account balances
            gold = client.get_gold_credits()
            silver = client.get_silver_credits()
            print(f"Balances: Gold={gold} credits | Silver={silver} credits")

            # Perform a reverse email lookup
            print("Running reverse email lookup...")
            results = client.search_email("user@example.com")
            print("Results:", results)
            
    except NoimosinyError as e:
        print(f"API Error occurred: {e}")

if __name__ == "__main__":
    main()

API Reference & Endpoints

Under the hood, the Noimosiny API routes all client actions to a single endpoint (POST https://api.noimosiny.com/v1/execute). The SDK abstracts this payload structure entirely into clean, pythonic method calls.

Rate Limits

• 5 simultaneous requests.
• 60 requests per minute.

Account & Balances

get_gold_credits() -> int

Retrieves your current Gold credit balance. Gold credits are consumed by reverse search queries (email, phone, username).

• Equivalent API payload method: getGoldCredits
• Example Return Value: 1000

get_silver_credits() -> int

Retrieves your current Silver credit balance. Silver credits are consumed by advanced tool queries.

• Equivalent API payload method: getSilverCredits
• Example Return Value: 5000

Reverse Search Operations

All search operations return a python dictionary matching the API's standard response format. Each query will scan several internal modules and return success statuses along with metadata from matches.

search_email(email: str) -> dict

Perform a reverse email lookup to find associated social media profiles and online registration records.

• Equivalent API payload parameter: "type": "reverse_email"
• Response Format Example:

  {
      "type": "reverse_email",
      "query": "user@example.com",
      "results": [
          {
              "module": "TikTok",
              "success": true,
              "data": {
                  "id": "70397021345678",
                  "likes": 28506,
                  "region": "Australia",
                  "videos": 792,
                  "private": false,
                  "language": "en",
                  "username": "johndoe",
                  "verified": false,
                  "followers": 1029,
                  "following": 670,
                  "created_at": "2021-12-10 00:14:02",
                  "profile_url": "https://tiktok.com/@johndoe",
                  "display_name": "John Doe",
                  "social_profiles": {
                      "youtube": "John Doe"
                  }
              }
          }
      ]
  }
  

search_phone(phone: str) -> dict

Perform a reverse phone number search to find ownership details, carrier details, and geographical location info.

• Equivalent API payload parameter: "type": "reverse_phone"
• Response Format Example:

  {
      "type": "reverse_phone",
      "query": "+1234567890",
      "results": [
          {
              "module": "PhoneUS1",
              "success": true,
              "data": {
                  "zip": "12345",
                  "city": "New York",
                  "name": "John Doe",
                  "type": "Landline",
                  "state": "NY",
                  "county": "New York",
                  "carrier": "WINDSTREAM NUVOX, INC. - FL",
                  "latitude": "40.7128",
                  "longitude": "-74.0060",
                  "risk_scale": 0.6,
                  "risk_description": "possibly unsafe caller"
              }
          }
      ]
  }
  

search_username(username: str) -> dict

Perform a reverse search on a username to check registry status and profiles across multiple social networks.

• Equivalent API payload parameter: "type": "reverse_username"
• Response Format Example:

  {
      "type": "reverse_username",
      "query": "johndoe",
      "results": [
          {
              "module": "Instagram",
              "success": true,
              "data": {
                  "url": "https://instagram.com/johndoe",
                  "username": "johndoe",
                  "image": "https://scontent-atl3-1.cdninstagram.com/v/............",
                  "followers_count": 918,
                  "following_count": 0,
                  "posts_count": 0,
                  "is_private": true,
                  "is_verified": false,
                  "is_business": false,
                  "is_professional": false
              }
          }
      ]
  }
  

Error Handling

All SDK-specific exceptions subclass NoimosinyError. Catching it handles any API or connection issue:

from noimosiny import Client
from noimosiny.exceptions import (
    NoimosinyError,
    AuthenticationError,
    RateLimitError,
    InsufficientCreditsError,
    BadRequestError,
    ServerError
)

try:
    with Client("API_KEY") as client:
        client.search_email("test@example.com")
except AuthenticationError:
    print("Invalid API Key.")
except RateLimitError:
    print("Too many requests. Please throttle your queries.")
except InsufficientCreditsError:
    print("Your account is out of credits.")
except BadRequestError as e:
    print(f"Invalid query parameters: {e}")
except ServerError:
    print("An unexpected server-side error occurred on the Noimosiny API.")
except NoimosinyError as e:
    print(f"Generic SDK error: {e}")

Exception Hierarchy

• NoimosinyError (Base exception class)
  • AuthenticationError (401 Unauthorized)
  • RateLimitError (429 Too Many Requests)
  • APIRequestError (Base for request validation & API responses)
    • BadRequestError (400 Bad Request)
    • InsufficientCreditsError (403 Forbidden)
    • APITimeoutError (408 Request Timeout)
    • ServerError (500+ Internal Server Error)