Ujeebu API Client SDK

The UjeebuClient class provides a simple interface to interact with the Ujeebu API. This SDK makes it easy to scrape websites, extract content, search the web, and more.

Installation

npm install @ujeebu-org/ujeebu-sdk

Usage

import { UjeebuClient } from '@ujeebu-org/ujeebu-sdk';

// Initialize with your API key from environment variable
const client = new UjeebuClient(process.env.UJEEBU_API_KEY);

// Use the methods documented below

API Methods

1. Scrape

Retrieve web page content with various options for processing.

async scrape(
  url: string, 
  params?: ScrapeParams, 
  forwardHeaders?: Record<string, string>
): Promise<ScrapeResponse>

Parameters:

• url: The URL to scrape
• params (optional): Configuration options
  • response_type: Format of the response (html, raw, pdf, screenshot, json)
  • js: Enable JavaScript rendering (boolean)
  • wait_for: Element or timeout to wait for
  • ...and many more options
• forwardHeaders (optional): HTTP headers to forward with the request

Example:

// Basic HTML scraping
const htmlResponse = await client.scrape('https://scrape.li');

// Take a screenshot with JavaScript enabled
const screenshotResponse = await client.scrape('https://scrape.li', {
  response_type: 'screenshot',
  js: true,
  js_timeout: 5000
});
console.log(screenshotResponse.data);

// Extract structured data from a page
const data = await client.scrape('https://scrape.li/load-more', {
    wait_for: 5000,
    block_resources: 0,
    js: 1,
    extract_rules: {
        "products": {
            "selector": ".product-card",
            "type": "obj",
            "multiple": true,
            "children": {
                "name": {
                    "selector": ".title",
                    "type": "text"
                },
                "description": {
                    "selector": ".description",
                    "type": "text"
                },
                "price": {
                    "selector": ".price",
                    "type": "text"
                },
                "image": {
                    "selector": ".card__image > img",
                    "type": "image",
                }
            }
        }
    }
});

console.log(data.data.result);

2. Extract

Parse and extract structured content from web articles.

async extract(
  url: string, 
  params?: Record<string, any>, 
  forwardHeaders?: Record<string, string>
): Promise<ExtractResponse>

Parameters:

• url: The URL to extract content from
• params (optional): Extract API params
• forwardHeaders (optional): HTTP headers to forward with the request

Example:

const response = await client.extract('https://ujeebu.com/blog/web-scraping-in-2025-state-of-the-art-and-trends/');
console.log(response.data.article.title);
console.log(response.data.article.text);
console.log(response.data.article.pub_date);

3. Preview Card

Generate a preview card for a URL, similar to social media link previews.

async preview(
  url: string, 
  forwardHeaders?: Record<string, string>
): Promise<CardResponse>

Parameters:

• url: The URL to generate a preview for
• params (optional): Preview API params
• forwardHeaders (optional): HTTP headers to forward with the request

Example:

const response = await client.preview('https://ujeebu.com/blog/web-scraping-in-2025-state-of-the-art-and-trends/);
console.log(response.data.author);
console.log(response.data.title);
console.log(response.data.summary);
console.log(response.data.image);

4. Get PDF

Retrieve a PDF version of a web page.

async getPdf(
  url: string, 
  params?: Omit<ScrapeParams, 'url' | 'response_type'>, 
  forwardHeaders?: Record<string, string>
): Promise<PdfResponse>

Parameters:

• url: The URL to convert to PDF
• params (optional): Scrape API options
• forwardHeaders (optional): HTTP headers to forward with the request

Example:

const response = await client.getPdf('https://scrape.li', {
  js: true,
});

// Save PDF to file
const fs = require('fs');
fs.writeFileSync('example.pdf', response.data);

5. Get Screenshot

Capture a screenshot of a web page.

async getScreenshot(
  url: string, 
  params?: Omit<ScrapeParams, 'url' | 'response_type'>, 
  forwardHeaders?: Record<string, string>
): Promise<ScreenshotResponse>

Parameters:

• url: The URL to screenshot
• params Scrape API options
• forwardHeaders (optional): HTTP headers to forward with the request

Example:

const response = await client.getScreenshot('https://scrape.li', {
  js: true,
  screenshot_fullpage: true,
    // or screenshot_partial: '.element-selector'
});

// Save screenshot to file
const fs = require('fs');
fs.writeFileSync('example.png', response.data);

6. Scrape With Rules

Scrape a web page and extract structured data using extraction rules.

async scrapeWithRules(
  url: string, 
  extractRules: Record<string, any>, 
  params?: Omit<ScrapeParams, 'url' | 'response_type' | 'extract_rules'>, 
  forwardHeaders?: Record<string, string>
): Promise<ScrapeResponseJson>

Parameters:

• url: The URL to scrape
• extractRules: Rules defining the structured data to extract (JSON structure docs)
• params (optional): Scrape API options
• forwardHeaders (optional): HTTP headers to forward with the request

Example:

const response = await client.scrapeWithRules('https://scrape.li/quotes', {
    "quote": {
        "selector": ".quote-card .description",
        "type": "text",
        "multiple": true
    }
});

console.log(response.data.result.quote);

7. SERP Search

Perform search engine queries and get structured results.

async serp(
  params: SerpParams, 
  forwardHeaders?: Record<string, string>
): Promise<SerpResponse>

Parameters:

• params: Search parameters
  • search: Search query
  • search_type: Type of search (text, images, news, videos, maps)
  • lang: Language code
  • location: Location for geo-targeted results
  • device: Device type (desktop, mobile)
  • ...additional parameters
• forwardHeaders (optional): HTTP headers to forward with the request

Example:

const response = await client.serp({
  search: 'Bitcoin',
  search_type: 'search',
  lang: 'en'
});

console.log(response.data.organic_results);

8. Search Text

Convenience method for performing a text search.

async searchText(
  search: string, 
  params?: Omit<SerpParams, 'search' | 'search_type'>
): Promise<ResultsSERPResponse>

Parameters:

• search: The search query
• params (optional): Additional parameters

Example:

const response = await client.searchText('artificial intelligence', {
  lang: 'en',
});

console.log(response.data.organic_results);

9. Search News

Search for news articles.

async searchNews(
  search: string, 
  params?: Omit<SerpParams, 'search' | 'search_type'>
): Promise<NewsSERPResponse>

Parameters:

• search: News search query
• params (optional): Search options
  • lang: Language code
  • location: Location for geo-targeted results
  • ...Additional parameters

Example:

const response = await client.searchNews('Crypto', {
  lang: 'en'
});

console.log(response.data.news);

10. Search Images

Search for images.

async searchImages(
  search: string, 
  params?: Omit<SerpParams, 'search' | 'search_type'>
): Promise<ImagesSERPResponse>

Parameters:

• search: Image search query
• params (optional): Search options
  • lang: Language code
  • location: Location for geo-targeted results
  • ...Additional parameters Example:

const imageResults = await client.searchImages('landscape photography', {
  lang: 'en'
});

console.log(imageResults.data.images);

11. Search Videos

Search for videos.

async searchVideos(
  search: string, 
  params?: Omit<SerpParams, 'search' | 'search_type'>
): Promise<VideosSERPResponse>

Parameters:

• search: Video search query
• params (optional): Search options
  • lang: Language code
  • location: Location for geo-targeted results
  • ...Additional parameters

Example:

const videoResults = await client.searchVideos('cooking tutorials', {
  lang: 'en'
});

console.log(videoResults.data.videos);

12. Search Maps

Search for map locations.

async searchMaps(
  search: string, 
  params?: Omit<SerpParams, 'search' | 'search_type'>
): Promise<MapsSERPResponse>

Parameters:

• search: Location search query
• params (optional): Search options
  • lang: Language code
  • location: Location for geo-targeted results
  • ...Additional parameters

Example:

const mapResults = await client.searchMaps('Coffee shops', {
    location: 'fr'
});

console.log(mapResults.data.maps_results);

13. Get Account Details

Retrieve information about your API account.

async getAccountDetails(): Promise<AccountResponse>

Example:

const response = await client.getAccountDetails();
console.log(`Balance: ${response.data.balance}`);
console.log(`Used: ${response.data.used}/${response.data.quota}`);

Error Handling

All methods can throw errors if the request fails. It's recommended to use try/catch blocks:

try {
  const response = await client.scrape('https://scrape.li');
  // Process response
} catch (error) {
  console.error('Request failed:', error.response?.data || error.message);
}

Response Types

The API methods return different response types:

• ScrapeResponse: Web page content (HTML, PDF, screenshot, etc.)
• ExtractResponse: Article extraction data with metadata
• CardResponse: URL preview card data
• SerpResponse: Search engine results (parent type)
• ResultsSERPResponse: Text search results
• NewsSERPResponse: News search results
• ImagesSERPResponse: Image search results
• VideosSERPResponse: Video search results
• MapsSERPResponse: Maps search results
• AccountResponse: Account details and usage information
• PdfResponse: PDF document data
• ScreenshotResponse: Screenshot image data
• HtmlResponse: HTML content data
• ScrapeResponseJson: Structured data extracted from web pages

Configuration

The client is initialized with your API key and uses the standard Ujeebu API endpoint:

// Read API key from environment variable
const client = new UjeebuClient(process.env.UJEEBU_API_KEY);

Make sure to set your API key as an environment variable:

export UJEEBU_API_KEY="your-api-key-here"

Or use a .env file with a package like dotenv:

# .env file
UJEEBU_API_KEY=your-api-key-here

For more information about the Ujeebu API, visit the official documentation.