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

``bash
npm install @ujeebu-org/ujeebu-sdk
`

Usage

`typescript
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

$3

Retrieve web page content with various options for processing.

`typescript
async scrape(
url: string,
params?: ScrapeParams,
forwardHeaders?: Record
): Promise
`

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:
`typescript
// 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);
`

$3

Parse and extract structured content from web articles.

`typescript
async extract(
url: string,
params?: Record,
forwardHeaders?: Record
): Promise
`

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

Example:
`typescript
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

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

`typescript
async preview(
url: string,
forwardHeaders?: Record
): Promise
`

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

Example:
`typescript
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);
`

$3

Retrieve a PDF version of a web page.

`typescript
async getPdf(
url: string,
params?: Omit,
forwardHeaders?: Record
): Promise
`

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

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

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

$3

Capture a screenshot of a web page.

`typescript
async getScreenshot(
url: string,
params?: Omit,
forwardHeaders?: Record
): Promise
`

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

Example:
`typescript
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);
`

$3

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

`typescript
async scrapeWithRules(
url: string,
extractRules: Record,
params?: Omit,
forwardHeaders?: Record
): Promise
`

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:
`typescript
const response = await client.scrapeWithRules('https://scrape.li/quotes', {
"quote": {
"selector": ".quote-card .description",
"type": "text",
"multiple": true
}
});

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


$3

Perform search engine queries and get structured results.

`typescript
async serp(
params: SerpParams,
forwardHeaders?: Record
): Promise
`

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:
`typescript
const response = await client.serp({
search: 'Bitcoin',
search_type: 'search',
lang: 'en'
});

console.log(response.data.organic_results);
`

$3

Convenience method for performing a text search.

`typescript
async searchText(
search: string,
params?: Omit
): Promise
`

Parameters:
- search: The search query
- params (optional): Additional parameters

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

console.log(response.data.organic_results);
`




$3

Search for news articles.

`typescript
async searchNews(
search: string,
params?: Omit
): Promise
`

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

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

console.log(response.data.news);
`

$3

Search for images.

`typescript
async searchImages(
search: string,
params?: Omit
): Promise
`

Parameters:
- search: Image search query
- params (optional): Search options
- lang: Language code
- location: Location for geo-targeted results
- ...Additional parameters
Example:
`typescript
const imageResults = await client.searchImages('landscape photography', {
lang: 'en'
});

console.log(imageResults.data.images);
`

$3

Search for videos.

`typescript
async searchVideos(
search: string,
params?: Omit
): Promise
`

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

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

console.log(videoResults.data.videos);
`

$3

Search for map locations.

`typescript
async searchMaps(
search: string,
params?: Omit
): Promise
`

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

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

console.log(mapResults.data.maps_results);
`




$3

Retrieve information about your API account.

`typescript
async getAccountDetails(): Promise
`

Example:
`typescript
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:

`typescript
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:

`typescript
// 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:
`bash
export UJEEBU_API_KEY="your-api-key-here"
`

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


.env file


UJEEBU_API_KEY=your-api-key-here
``

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