NosibleClient

Class: NosibleClient

Nosible API Client

The main client class for interacting with the Nosible AI Search API. This class provides a comprehensive interface for performing various types of searches, scraping web content, and analyzing topic trends.

Features:

Fast Search: Quick, optimized searches with configurable result limits (10-100 results)
AI Search: Advanced AI-powered searches with custom instructions
Bulk Search: Large-scale searches for extensive data collection (1000-10000 results)
URL Scraping: Extract structured content from web pages
Topic Trends: Analyze trending topics and their popularity over time

The client automatically handles rate limiting, request validation, and response parsing. It also supports optional OpenRouter integration for enhanced LLM capabilities.

Example

// Initialize with API key
const client = new NosibleClient('your-api-key');

// Or use environment variable NOSIBLE_API_KEY
const client = new NosibleClient();

// Initialize with default search parameters
const clientWithDefaults = new NosibleClient({
  apiKey: 'your-api-key',
  searchDefaults: {
    nResults: 20,
    algorithm: 'hybrid-2',
    continent: 'North America'
  }
});

// Perform a fast search (will use defaults from client)
const results = await clientWithDefaults.fastSearch({
  question: 'Who has invested in Nosible?'
  // nResults, algorithm, and continent will use defaults
});

// Perform a fast search
const results = await client.fastSearch({
  question: 'Who has invested in Nosible?',
  nResults: 15
});

// Access search results
console.log(`Found ${results.length} results`);
results.forEach(result => {
  console.log(`Title: ${result.title}`);
  console.log(`URL: ${result.url}`);
  console.log(`Content: ${result.content.substring(0, 200)}...`);
});

Constructors

Constructor

new NosibleClient(params?): NosibleClient

Defined in: src/client.ts:257

Creates a new NosibleClient instance.

The client can be initialized in several ways:

With a string API key
With an object containing API keys
With no parameters (uses environment variables)

Environment variables:

NOSIBLE_API_KEY: Your Nosible API key (required if no params provided)
LLM_API_KEY: Optional OpenRouter API key for LLM features

Parameters

params?

Configuration options. Can be a string API key or an object with detailed configuration.

string | { apiKey?: string; llmApiKey?: string; openAiBaseURL?: string; sentimentModel?: string; expansionsModel?: string; searchDefaults?: { autoGenerateExpansions?: boolean; expansions?: string[]; sqlFilter?: string; algorithm?: "string" | "baseline" | "lexical" | "hamming" | "hybrid-1" | "hybrid-2" | "hybrid-3" | "company"; nResults?: number; nProbes?: number; nContextify?: number; minSimilarity?: number; mustInclude?: string[]; mustExclude?: string[]; brandSafety?: "safe" | "sensitive" | "unsafe"; language?: string; continent?: "Africa" | "Asia" | "Europe" | "North America" | "Oceania" | "South America" | "Worldwide"; region?: "North America" | "Oceania" | "South America" | "Worldwide" | "Caribbean" | "Central Africa" | "Central America" | "Central Asia" | "Central Europe" | "East Africa" | "East Asia" | "Eastern Europe" | "Middle East" | "North Africa" | "Northern Europe" | "South Asia" | "Southeast Asia" | "Southern Africa" | "Southern Europe" | "Sub-Saharan Africa" | "The Amazon Basin" | "The Andes" | "The Arctic Region" | "The Balkans" | "The Caucasus" | "The Horn of Africa" | "The Levant" | "The Middle East" | "The Sahel" | "West Africa" | "Western Europe"; country?: string; sector?: string; industryGroup?: string; industry?: string; subIndustry?: string; iabTier1?: string; iabTier2?: string; iabTier3?: string; iabTier4?: string; companies?: string[]; publishStart?: Date; publishEnd?: Date; visitedStart?: Date; visitedEnd?: Date; certain?: boolean; includeNetlocs?: string[]; excludeNetlocs?: string[]; includeCompanies?: string[]; excludeCompanies?: string[]; includeDocs?: string[]; excludeDocs?: string[]; }; }

Returns

NosibleClient

Throws

When no valid API key is provided

Example

// Initialize with string API key
const client = new NosibleClient('your-api-key');

// Initialize with object configuration
const client = new NosibleClient({
  apiKey: 'your-nosible-api-key',
  llmApiKey: 'your-openrouter-api-key'
});

// Initialize with default search parameters
const client = new NosibleClient({
  apiKey: 'your-nosible-api-key',
  searchDefaults: {
    nResults: 20,
    algorithm: 'hybrid-2',
    continent: 'North America'
  }
});

// Initialize using environment variables
const client = new NosibleClient();

Properties

llmClient

llmClient: OpenAI | undefined

Defined in: src/client.ts:199

Optional OpenAI client for LLM integration via OpenRouter

expansionsModel

expansionsModel: string = "openai/gpt-4o"

Defined in: src/client.ts:201

LLM model to use for expansions

Methods

fastSearch()

fastSearch(params): Promise<ResultSet>

Defined in: src/client.ts:414

Performs a fast search query with optimized performance.

Fast search is designed for quick, efficient queries with smaller result sets. It's ideal for real-time applications, autocomplete features, or when you need rapid responses with a limited number of highly relevant results.

Features:

Optimized for speed (10-100 results)
Supports advanced filtering and search algorithms
Rate limited to prevent quota exceeded errors
Returns structured ResultSet with metadata

Parameters

params

ClientSearchParamsSchema

Search parameters including question, filters, and result count

Returns

Promise<ResultSet>

Promise resolving to a ResultSet containing search results and metadata

Example

// Basic fast search
const results = await client.fastSearch({
  question: 'latest AI technology trends',
  nResults: 20
});

// Advanced fast search with filters
const filteredResults = await client.fastSearch({
  question: 'machine learning startups',
  nResults: 50,
  algorithm: 'hybrid-2',
  minSimilarity: 0.7,
  mustInclude: ['artificial intelligence', 'funding'],
  mustExclude: ['cryptocurrency'],
  continent: 'North America'
});

// Process results
console.log(`Found ${results.length} results`);
for (const result of results) {
  console.log(`Title: ${result.title}`);
  console.log(`URL: ${result.url}`);
  console.log(`Similarity: ${result.similarity}`);
}

fastSearches()

fastSearches(params): Promise<ResultSet[]>

Defined in: src/client.ts:525

Executes multiple searches in parallel using fast search.

This method allows you to run multiple searches simultaneously, which is significantly faster than executing them sequentially. It accepts either a SearchSet instance or an object containing an array of questions with shared search parameters.

Parameters

params

Either a SearchSet instance or an object with questions and shared parameters

SearchSet |

{ questions: string[]; autoGenerateExpansions?: boolean; expansions?: string[]; sqlFilter?: string; algorithm?: "string" | "baseline" | "lexical" | "hamming" | "hybrid-1" | "hybrid-2" | "hybrid-3" | "company"; nResults?: number; nProbes?: number; nContextify?: number; minSimilarity?: number; mustInclude?: string[]; mustExclude?: string[]; brandSafety?: "safe" | "sensitive" | "unsafe"; language?: string; continent?: "Africa" | "Asia" | "Europe" | "North America" | "Oceania" | "South America" | "Worldwide"; region?: "North America" | "Oceania" | "South America" | "Worldwide" | "Caribbean" | "Central Africa" | "Central America" | "Central Asia" | "Central Europe" | "East Africa" | "East Asia" | "Eastern Europe" | "Middle East" | "North Africa" | "Northern Europe" | "South Asia" | "Southeast Asia" | "Southern Africa" | "Southern Europe" | "Sub-Saharan Africa" | "The Amazon Basin" | "The Andes" | "The Arctic Region" | "The Balkans" | "The Caucasus" | "The Horn of Africa" | "The Levant" | "The Middle East" | "The Sahel" | "West Africa" | "Western Europe"; country?: string; sector?: string; industryGroup?: string; industry?: string; subIndustry?: string; iabTier1?: string; iabTier2?: string; iabTier3?: string; iabTier4?: string; companies?: string[]; publishStart?: Date; publishEnd?: Date; visitedStart?: Date; visitedEnd?: Date; certain?: boolean; includeNetlocs?: string[]; excludeNetlocs?: string[]; includeCompanies?: string[]; excludeCompanies?: string[]; includeDocs?: string[]; excludeDocs?: string[]; }

Either a SearchSet instance or an object with questions and shared parameters

questions

string[] = ...

Array of search questions (when not using SearchSet)

autoGenerateExpansions?

boolean = ...

expansions?

string[] = ...

sqlFilter?

string = ...

algorithm?

Returns

Promise<ResultSet[]>

Promise that resolves to an array of ResultSet objects, one for each search

Examples

// Using SearchSet instance
const search1 = new Search({ question: "machine learning", nResults: 10 });
const search2 = new Search({ question: "artificial intelligence", nResults: 10 });
const searchSet = new SearchSet([search1, search2]);

const results = await client.fastSearches(searchSet);
// results[0] contains results for "machine learning"
// results[1] contains results for "artificial intelligence"

// Using questions array with shared parameters
const params = {
  questions: [
    "renewable energy trends",
    "solar power developments",
    "wind energy innovations"
  ],
  nResults: 15,
  language: "en",
  region: "us",
  publishStart: new Date("2023-01-01")
};

const results = await client.fastSearches(params);
// All searches use the same shared parameters but different questions

// Advanced usage with mixed parameters
const searches = [
  new Search({
    question: "blockchain technology",
    nResults: 20,
    algorithm: "cosine"
  }),
  new Search({
    question: "cryptocurrency markets",
    nResults: 15,
    minSimilarity: 0.8
  })
];

const searchSet = new SearchSet(searches);
const results = await client.fastSearches(searchSet);

aiSearch()

aiSearch(params): Promise<ResultSet>

Defined in: src/client.ts:596

Performs an AI-powered search with custom instructions.

AI search leverages advanced language models to understand complex queries and custom instructions, providing more contextually relevant results. This method is ideal for nuanced searches that require understanding intent, context, or specific analytical requirements.

Features:

Natural language understanding of complex queries
Custom instructions for specialized search behavior
Context-aware result ranking and filtering
Rate limited for optimal performance

Parameters

params

AI search parameters including question and custom instructions

prompt

string = ...

agent?

string = ...

Returns

Promise<ResultSet>

Promise resolving to a ResultSet containing AI-enhanced search results

Example

// Basic AI search
const results = await client.aiSearch({
  question: 'What are the environmental impacts of renewable energy?',
  instruction: 'Focus on recent studies and quantitative data'
});

// AI search with specific analytical focus
const analysisResults = await client.aiSearch({
  question: 'company financial performance',
  instruction: 'Compare revenue growth and profit margins across quarters',
  nResults: 25,
  algorithm: 'hybrid-3'
});

// AI search for competitive analysis
const competitiveResults = await client.aiSearch({
  question: 'competitors in the cloud computing market',
  instruction: 'Identify key players, market share, and competitive advantages'
});

bulkSearch()

bulkSearch(params): Promise<ResultSet>

Defined in: src/client.ts:664

Performs a bulk search for large-scale data collection.

Bulk search is designed for comprehensive data gathering and analysis tasks. It supports large result sets (1000-10000 results) and provides efficient download mechanisms for extensive datasets. Results are encrypted and downloaded asynchronously for optimal performance.

Features:

Large-scale data collection (1000-10000 results)
Encrypted result delivery for security
Asynchronous download processing
Comprehensive filtering and search options
Rate limited for optimal server performance
Supports both raw parameters and Search instances

Parameters

params

ClientSearchParamsSchema

Bulk search parameters including question or search instance, with comprehensive filtering options

Returns

Promise<ResultSet>

Promise resolving to a ResultSet containing bulk search results

Example

// Basic bulk search
const results = await client.bulkSearch({
  question: 'all articles about artificial intelligence',
  nResults: 5000
});

// Bulk search with comprehensive filtering
const filteredResults = await client.bulkSearch({
  question: 'technology company funding rounds',
  nResults: 10000,
  algorithm: 'hybrid-3',
  minSimilarity: 0.6,
  continent: 'North America',
  region: 'Silicon Valley',
  mustInclude: ['venture capital', 'funding', 'investment'],
  mustExclude: ['cryptocurrency', 'NFT'],
  nProbes: 8,
  nContextify: 512
});

// Bulk search using a Search instance
const search = new Search({
  question: 'renewable energy developments',
  nResults: 7500,
  algorithm: 'hybrid-2'
});
const searchResults = await client.bulkSearch({ search });

// Process bulk results
console.log(`Retrieved ${results.length} results`);
const data = results.toJSON(); // Convert to JSON for analysis

scrapeUrl()

scrapeUrl(url): Promise<WebPageData>

Defined in: src/client.ts:763

Scrapes and extracts structured content from a web URL.

This method fetches the content of a web page and extracts structured information including title, description, main content, metadata, and other relevant details. The scraping is optimized for clean content extraction and handles various website structures and formats.

Features:

Clean content extraction from web pages
Structured data including metadata and content
Handles various website formats and structures
Rate limited to respect website policies
Returns WebPage object with enhanced functionality

Parameters

url

string

The URL to scrape and extract content from

Returns

Promise<WebPageData>

Promise resolving to a WebPage object containing structured content

Example

// Basic URL scraping
const webpage = await client.scrapeUrl('https://example.com/article');

// Access scraped content
console.log(`Title: ${webpage.title}`);
console.log(`Description: ${webpage.description}`);
console.log(`Author: ${webpage.author}`);
console.log(`Published: ${webpage.published}`);
console.log(`Content length: ${webpage.content.length} characters`);

// Extract specific content sections
const mainContent = webpage.content;
const bestChunk = webpage.bestChunk; // Most relevant content chunk

// Use in combination with search
const searchResults = await client.fastSearch({
  question: 'artificial intelligence news',
  nResults: 10
});

// Scrape the top result
if (searchResults.length > 0) {
  const topArticle = await client.scrapeUrl(searchResults[0].url);
  console.log(`Full article: ${topArticle.content}`);
}

topicTrend()

topicTrend(query, sqlFilter?): Promise<TopicTrend>

Defined in: src/client.ts:823

Analyzes topic trends and popularity over time.

This method provides insights into how a topic's popularity and relevance changes over time. It's useful for market research, content strategy, trend analysis, and understanding topic momentum.

Features:

Historical trend analysis for any topic
Popularity metrics and temporal patterns
Optional SQL filtering for refined analysis
Returns TopicTrend object with analytical data

Parameters

query

excludeDocs?

string[] = ...

Returns

Promise<TopicTrend>

Promise resolving to a TopicTrend object containing trend analysis data

Example

// Basic trend analysis
const trends = await client.topicTrend('artificial intelligence');

// Access trend data
console.log(`Topic: ${trends.query}`);
console.log(`Data points: ${trends.data.length}`);
trends.data.forEach(point => {
  console.log(`Date: ${point.date}, Popularity: ${point.popularity}`);
});

// Trend analysis with filtering
const filteredTrends = await client.topicTrend(
  'machine learning',
  'continent = "North America" AND published >= "2023-01-01"'
);

// Analyze multiple related topics
const topics = ['AI', 'machine learning', 'deep learning', 'neural networks'];
for (const topic of topics) {
  const trend = await client.topicTrend(topic);
  console.log(`${topic} trend analysis complete`);
}

// Use trend data for content strategy
const trendingTopics = ['blockchain', 'quantum computing', 'renewable energy'];
const trendAnalyses = await Promise.all(
  trendingTopics.map(topic => client.topicTrend(topic))
);

Class: NosibleClient

Example​

Constructors​

Constructor​

Parameters​

params?​

Returns​

Throws​

Example​

Properties​

llmClient​

expansionsModel​

Methods​

fastSearch()​

Parameters​

params​

Returns​

Example​

fastSearches()​

Parameters​

params​

questions​

autoGenerateExpansions?​

expansions?​

sqlFilter?​

algorithm?​

nResults?​

nProbes?​

nContextify?​

minSimilarity?​

mustInclude?​

mustExclude?​

brandSafety?​

language?​

continent?​

region?​

country?​

sector?​

industryGroup?​

industry?​

subIndustry?​

iabTier1?​

iabTier2?​

iabTier3?​

iabTier4?​

companies?​

publishStart?​

publishEnd?​

visitedStart?​

visitedEnd?​

certain?​

includeNetlocs?​

excludeNetlocs?​

includeCompanies?​

excludeCompanies?​

includeDocs?​

excludeDocs?​

Returns​

Examples​

aiSearch()​

Parameters​

params​

prompt​

agent?​

Returns​

Example​

bulkSearch()​

Parameters​

params​

Returns​

Example​

scrapeUrl()​

Parameters​

url​

Returns​

Example​

topicTrend()​

Parameters​

query​

sqlFilter?​

Example

Constructors

Constructor

Parameters

params?

Returns

Throws

Example

Properties

llmClient

expansionsModel

Methods

fastSearch()

Parameters

params

Returns

Example

fastSearches()

Parameters

params

questions

autoGenerateExpansions?

expansions?

sqlFilter?

algorithm?

nResults?

nProbes?

nContextify?

minSimilarity?

mustInclude?

mustExclude?

brandSafety?

language?

continent?

region?

country?

sector?

industryGroup?

industry?

subIndustry?

iabTier1?

iabTier2?

iabTier3?

iabTier4?

companies?

publishStart?

publishEnd?

visitedStart?

visitedEnd?

certain?

includeNetlocs?

excludeNetlocs?

includeCompanies?

excludeCompanies?

includeDocs?

excludeDocs?

Returns

Examples

aiSearch()

Parameters

params

prompt

agent?

Returns

Example

bulkSearch()

Parameters

params

Returns

Example

scrapeUrl()

Parameters

url

Returns

Example

topicTrend()

Parameters

query

sqlFilter?

publishStart?