Bimiyun JavaScript SDK

A JavaScript SDK for the Bimiyun Search API, providing a simple and intuitive interface for accessing Bimiyun's powerful search capabilities.

Table of Contents

• Installation
• Quick Start
• Usage Examples
• API Reference
• Configuration
• Error Handling
• Testing
• Contributing
• License

Installation

You can install the Bimiyun JavaScript SDK using npm:

npm install bimiyun-javascript

Or using yarn:

yarn add bimiyun-javascript

Quick Start

// To install: npm i bimiyun-javascript
const { bimiyun } = require('bimiyun-javascript');

const client = bimiyun({ apiKey: "ak-********************" });

client.search("artificial intelligence", {
    lang: "en"
})
.then(console.log);

Usage Examples

Basic Search

const { bimiyun } = require('bimiyun-javascript');

const client = bimiyun({ apiKey: "ak-********************" });

// Simple search with just query
client.search("python programming")
    .then(response => {
        // Access the organic results
        const results = response.organic || [];
        results.forEach(result => {
            console.log(result.title);
            console.log(result.link);
            console.log(result.snippet);
            console.log();
        });
    })
    .catch(error => {
        console.error(error);
    });

Using Async/Await

const { bimiyun } = require('bimiyun-javascript');

const client = bimiyun({ apiKey: "ak-********************" });

async function search() {
    try {
        const response = await client.search("python programming");

        // Access the organic results
        const results = response.organic || [];
        results.forEach(result => {
            console.log(result.title);
            console.log(result.link);
            console.log(result.snippet);
            console.log();
        });
    } catch (error) {
        console.error(error);
    }
}

search();

Search with All Parameters

const { bimiyun } = require('bimiyun-javascript');

const client = bimiyun({ apiKey: "ak-********************" });

// Search with all available parameters
client.search("machine learning tutorials", {
    lang: "en",
    safe: true,
    mode: "fulltext",
    maxResults: 5
})
.then(response => {
    const results = response.organic || [];
    console.log(`Found ${results.length} results`);
});

Custom Base URL and Timeout

const { bimiyun } = require('bimiyun-javascript');

const client = bimiyun({
    apiKey: "ak-********************",
    baseUrl: "https://custom.bimiyun.com",
    timeout: 60
});

client.search("custom search").then(console.log);

API Response Format

The search() method returns the raw API response in the following format:

{
  "organic": [
    {
      "title": "Result Title",
      "date": "",
      "link": "https://example.com",
      "position": 1,
      "site_name": "Example.com",
      "snippet": "Description text...",
      "text": "Full text..."
    }
  ]
}

Field descriptions:

• title: Search result title
• date: Publication date (if available)
• link: URL of the search result
• position: Position in the results list
• site_name: Name of the website
• snippet: Brief description or excerpt from the page
• text: Full text of the page

API Reference

bimiyun(config)

Factory function to create a Bimiyun client instance.

Parameters:

• config.apiKey: Your Bimiyun API key (required)
• config.baseUrl: Base URL for the API (optional, default: https://search.bimiyun.com)
• config.timeout: Request timeout in seconds (optional, default: 30)

Returns:

• BimiyunClient instance

BimiyunClient.search(query, options?)

Perform a search with the given query and return the raw API response.

Parameters:

• query: Search query string (required)
• options: Search options (optional)
  • lang: Language code for search results (e.g., 'am' for Amharic, 'en' for English) (optional)
  • maxResults: Maximum number of results to return (optional, default: 5, range: 1-10)
  • safe: Safe search mode: true or false (optional, default: true)
  • mode: Result detail mode: 'snippet' for brief descriptions or 'fulltext' for detailed content (optional, default: 'fulltext')

Returns:

• Promise<BimiyunResponse>: Promise resolving to raw API response object containing the search results

Alternative: Using BimiyunClient class directly

If you prefer, you can still use the class directly:

const { BimiyunClient } = require('bimiyun-javascript');

const client = new BimiyunClient("ak-********************");
client.search("artificial intelligence", { lang: "en" })
    .then(console.log);

Configuration

Environment Variables

You can configure the API key using environment variables:

export BIMIYUN_API_KEY="your-api-key"

Then in your code:

const { bimiyun } = require('bimiyun-javascript');

const client = bimiyun({ apiKey: process.env.BIMIYUN_API_KEY });

Error Handling

The SDK returns rejected promises for API errors:

const { bimiyun } = require('bimiyun-javascript');

const client = bimiyun({ apiKey: "ak-********************" });

client.search("test query")
    .then(response => {
        const results = response.organic || [];
        // Process results...
    })
    .catch(error => {
        if (error.message.includes("timed out")) {
            console.error("Network timeout error");
        } else if (error.message.includes("API request failed")) {
            console.error("API error");
        } else {
            console.error("General error:", error.message);
        }
    });

Common error conditions:

• Invalid API key
• Rate limiting
• Network timeouts
• Invalid parameters

Testing

The SDK includes a simple test file. To run the test:

1. First, replace the placeholder API key in tests/test-search.js with your actual API key
2. Then run the test:

npm run test

Contributing

Contributions are welcome! Please see our contributing guide for more information.

License

MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please:

1. Check the documentation
2. Open an issue on GitHub
3. Contact support at [email protected]

Changelog

0.1.0

• Basic search functionality
• Simple factory function bimiyun() for easy initialization
• Advanced search with SearchOptions
• Result extraction methods
• API status check
• Error handling
• Comprehensive data models