Openperplex JavaScript Library

A streamlined asynchronous client for the Openperplex API. All API calls are asynchronous, with support for both standard JSON responses and streaming responses via async generators.

Installation

npm install openperplex-js

Quick Start

const { Openperplex } = require("openperplex-js");
const client = new Openperplex("YOUR_API_KEY");

// Standard JSON response
const result = await client.search("example query");

// Streaming response
const stream = await client.searchStream("example query");
for await (const data of stream) {
    console.log(data);
}

API Reference

Constructor

const client = new Openperplex(apiKey)

• apiKey (string, required): Your Openperplex API key

Methods

search(query, options)

Perform a standard search and receive the full JSON response.

const result = await client.search("your query", {
    date_context: null,           // Optional date context (e.g., "Today is Tuesday 19 of November 2024 and the time is 9:40 PM")
    location: "us",               // Default: "us" (Options: "us", "ca", "uk", "mx", "es", "de", "fr", "pt", "nl", "tr", "it", "pl", "ru", "za", "ae", "sa", "ar", "br", "au", "cn", "kr", "jp", "in", "ps", "kw", "om", "qa", "il", "ma", "eg", "ir", "ly", "ye", "id", "pk", "bd", "my", "ph", "th", "vn")
    model: "o3-mini-medium",      // Default: "gpt-4o-mini" (Options: "o3-mini-medium", "o3-mini-high", "gpt-4o", "gpt-4o-mini")
    response_language: "auto",    // Default: "auto" (Options: "auto", "en", "fr", "es", "de", "it", "pt", "nl", "ja", "ko", "zh", "ar", "ru", "tr", "hi")
    answer_type: "text",         // Default: "text" (Options: "text", "markdown", "html")
    search_type: "general",      // Default: "general" (Options: "general", "news")
    return_citations: false,      // Default: false (Boolean)
    return_sources: false,        // Default: false (Boolean)
    return_images: false,        // Default: false (Boolean)
    recency_filter: "anytime"    // Default: "anytime" (Options: "hour", "day", "week", "month", "year", "anytime")
});

searchStream(query, options)

Perform a search that streams its responses using an async generator.

const stream = await client.searchStream("your query", {
  // Same options as search() method
});

for await (const data of stream) {
  console.log(data);
}

getWebsiteText(url)

Retrieve text content from a website.

const result = await client.getWebsiteText("https://example.com");

getWebsiteScreenshot(url)

Retrieve a screenshot of a website.

const result = await client.getWebsiteScreenshot("https://example.com");

getWebsiteMarkdown(url)

Retrieve markdown representation of a website.

const result = await client.getWebsiteMarkdown("https://example.com");

queryFromUrl(url, query, options)

Query a website's content.

const result = await client.queryFromUrl(
  "https://example.com",
  "What is this page about?",
  {
    response_language: "auto",    // Default: "auto"
    answer_type: "text",         // Default: "text"
    model: "o3-mini-medium"      // Default: "o3-mini-medium"
  }
);

customSearch(systemPrompt, userPrompt, options)

Perform a custom search with system and user prompts.

const result = await client.customSearch(
  "You are a helpful assistant",
  "Explain quantum computing",
  {
    location: "us",               // Default: "us" (Options: "us", "ca", "uk", "mx", "es", "de", "fr", "pt", "nl", "tr", "it", "pl", "ru", "za", "ae", "sa", "ar", "br", "au", "cn", "kr", "jp", "in", "ps", "kw", "om", "qa", "il", "ma", "eg", "ir", "ly", "ye", "id", "pk", "bd", "my", "ph", "th", "vn")
    model: "o3-mini-medium",     // Default: "gpt-4o-mini" (Options: "o3-mini-medium", "o3-mini-high", "gpt-4o", "gpt-4o-mini")
    response_language: "auto",   // Default: "auto" (Options: "auto", "en", "fr", "es", "de", "it", "pt", "nl", "ja", "ko", "zh", "ar", "ru", "tr", "hi")
    search_type: "general",      // Default: "general" (Options: "general", "news")
    return_images: false,        // Default: false (Boolean)
    return_sources: false,       // Default: false (Boolean)
    temperature: 0.2,            // Default: 0.2 (Range: 0.0 to 1.0)
    recency_filter: "anytime",   // Default: "anytime" (Options: "hour", "day", "week", "month", "year", "anytime")
    top_p: 0.9                   // Default: 0.9 (Range: 0.0 to 1.0)
  }
);

customSearchStream(systemPrompt, userPrompt, options)

Perform a custom search that streams its responses.

const stream = await client.customSearchStream(
  "You are a helpful assistant",
  "Explain quantum computing",
  {
    // Same options as customSearch() method
  }
);

for await (const data of stream) {
  console.log(data);
}

Parameters

Common Parameters for Search Methods

• query: The search query or question
• date_context: Optional date context string (e.g., "Today is Tuesday 19 of November 2024 and the time is 9:40 PM"). If not provided, the current date on the API server is used
• location: Country code for localized results (default: "us")
• model: Model to use for the search. Options are "o3-mini-medium", "o3-mini-high", "gpt-4o", "gpt-4o-mini" (default)
• response_language: Language code for the response (default: "auto")
• answer_type: Answer format. Options are "text" (default), "markdown", or "html"
• search_type: Type of search. Options are "general" (default) or "news"
• return_citations: Boolean indicating whether to include citations (default: false)
• return_sources: Boolean indicating whether to include sources (default: false)
• return_images: Boolean indicating whether to include images (default: false)
• recency_filter: Filter for recency. Options: "hour", "day", "week", "month", "year", "anytime" (default)

Custom Search Parameters

• system_prompt: A prompt defining the system behavior
• user_prompt: The user query for the custom search
• temperature: Float controlling output randomness (default: 0.2)
• top_p: Float controlling output diversity (default: 0.9)

Supported Locations

The location parameter accepts the following country codes:

🇺🇸 us (United States), 🇨🇦 ca (Canada), 🇬🇧 uk (United Kingdom), 🇲🇽 mx (Mexico), 🇪🇸 es (Spain), 🇩🇪 de (Germany), 🇫🇷 fr (France), 🇵🇹 pt (Portugal), 🇳🇱 nl (Netherlands), 🇹🇷 tr (Turkey), 🇮🇹 it (Italy), 🇵🇱 pl (Poland), 🇷🇺 ru (Russia), 🇿🇦 za (South Africa), 🇦🇪 ae (United Arab Emirates), 🇸🇦 sa (Saudi Arabia), 🇦🇷 ar (Argentina), 🇧🇷 br (Brazil), 🇦🇺 au (Australia), 🇨🇳 cn (China), 🇰🇷 kr (Korea), 🇯🇵 jp (Japan), 🇮🇳 in (India), 🇵🇸 ps (Palestine), 🇰🇼 kw (Kuwait), 🇴🇲 om (Oman), 🇶🇦 qa (Qatar), 🇮🇱 il (Israel), 🇲🇦 ma (Morocco), 🇪🇬 eg (Egypt), 🇮🇷 ir (Iran), 🇱🇾 ly (Libya), 🇾🇪 ye (Yemen), 🇮🇩 id (Indonesia), 🇵🇰 pk (Pakistan), 🇧🇩 bd (Bangladesh), 🇲🇾 my (Malaysia), 🇵🇭 ph (Philippines), 🇹🇭 th (Thailand), 🇻🇳 vn (Vietnam)

Supported Languages

The response_language parameter accepts the following language codes:

• auto: Auto-detect the user question language (default)
• en: English
• fr: French
• es: Spanish
• de: German
• it: Italian
• pt: Portuguese
• nl: Dutch
• ja: Japanese
• ko: Korean
• zh: Chinese
• ar: Arabic
• ru: Russian
• tr: Turkish
• hi: Hindi

Best Practices

• Query Precision: Provide clear and concise queries to obtain accurate results
• Custom Search: Use customSearch or customSearchStream for specific queries with your own system and user prompts. Be specific with the user prompt as it's used for web search
• API Key Security: Never hard-code your API key in source code. Use environment variables or secure configuration management
• Error Handling: Implement robust error handling for API errors and network issues
• Asynchronous Usage: For concurrent requests, use the streaming methods appropriately
• Date Context: When historical context matters, specify the date_context parameter
• Localization: Use the location parameter to get localized results
• Response Language: Specify response_language for responses in different languages
• Model Selection: Choose the appropriate model for your use case
• Search Type: Use search_type to specify between general or news searches

Error Handling

The library includes a custom OpenperplexError class for error handling:

try {
  const result = await client.search("example query");
} catch (error) {
  if (error instanceof OpenperplexError) {
    console.error(`API Error ${error.statusCode}: ${error.detail}`);
  } else {
    console.error("Unexpected error:", error);
  }
}

Request Timeouts

All API requests have a default timeout of 40 seconds (40000ms).

SSE Stream Handling

The streaming methods (searchStream and customSearchStream) use Server-Sent Events (SSE) and handle:

• Data events (data: lines)
• Event markers (event: lines)
• End-of-stream signals
• Error events

Community & Support

Join our Discord community to get help, share your projects, and discuss the latest updates.

For any issues, feature requests, or further questions, please open an issue in our GitHub repository.