Developer guides
Use the official GitHub Packages beta SDK from Node.js, Next.js, serverless functions, backend services, and AI workflows.
Verified HTTP pattern
POST /google/search
Request
POST https://api.crawlora.net/api/v1/google/search
x-api-key: $CRAWLORA_API_KEY
Content-Type: application/json
{
"country": "us",
"keyword": "best CRM software",
"language": "en",
"limit": 10,
"page": 1
}Base URL
https://api.crawlora.net/api/v1
Auth header
x-api-key
Example endpoint
POST /google/search
The TypeScript and JavaScript SDK is published from https://github.com/Crawlora-org/crawlora-typescript-sdk. Install the current promoted beta version 1.5.0-sdk.3 and keep API keys in server-side environments.
Developer workflow
The package is published through GitHub Packages. Configure the scoped registry and authenticate with a GitHub token that can read packages.
npm config set @crawlora-org:registry https://npm.pkg.github.com npm install @crawlora-org/sdk@1.5.0-sdk.3
Developer workflow
CRAWLORA_API_KEY=your_api_key_here
Developer workflow
Use the generated endpoint groups and typed declarations from the SDK package.
import { CrawloraClient } from "@crawlora-org/sdk";
const crawlora = new CrawloraClient({
apiKey: process.env.CRAWLORA_API_KEY,
});
const result = await crawlora.bing.search({
q: "coffee shops",
count: 10,
});
console.log(result);Developer workflow
Use direct HTTP calls when you need a minimal dependency path or want to compare behavior with endpoint docs.
const CRAWLORA_API_KEY = process.env.CRAWLORA_API_KEY;
const CRAWLORA_BASE_URL = "https://api.crawlora.net/api/v1";
if (!CRAWLORA_API_KEY) {
throw new Error("Missing CRAWLORA_API_KEY");
}
async function crawloraRequest<TResponse>(
path: string,
body: Record<string, unknown>,
): Promise<TResponse> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 60_000);
try {
const response = await fetch(`${CRAWLORA_BASE_URL}${path}`, {
method: "POST",
headers: {
"x-api-key": CRAWLORA_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(body),
signal: controller.signal,
});
if (!response.ok) {
const errorText = await response.text();
throw new Error(`Crawlora request failed: ${response.status} ${errorText}`);
}
return response.json() as Promise<TResponse>;
} finally {
clearTimeout(timeout);
}
}
type GoogleSearchItem = {
position?: number;
title?: string;
website_name?: string;
link?: string;
Snippet?: string;
};
type GoogleSearchResponse = {
code: number;
msg: string;
data?: {
result?: GoogleSearchItem[];
};
};
async function main() {
const data = await crawloraRequest<GoogleSearchResponse>("/google/search", {
country: "us",
keyword: "best CRM software",
language: "en",
limit: 10,
page: 1,
});
console.log(data.data?.result);
}
main().catch(console.error);Developer workflow
Proxy browser requests through a server-side route so the API key never reaches client-side code.
// app/api/search/route.ts
import { NextResponse } from "next/server";
const CRAWLORA_API_KEY = process.env.CRAWLORA_API_KEY;
const CRAWLORA_BASE_URL = "https://api.crawlora.net/api/v1";
export async function POST(request: Request) {
if (!CRAWLORA_API_KEY) {
return NextResponse.json({ error: "Server API key is not configured" }, { status: 500 });
}
const { keyword, country = "us", language = "en" } = await request.json();
if (typeof keyword !== "string" || keyword.trim().length < 2) {
return NextResponse.json({ error: "Keyword is required" }, { status: 400 });
}
const response = await fetch(`${CRAWLORA_BASE_URL}/google/search`, {
method: "POST",
headers: {
"x-api-key": CRAWLORA_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ keyword, country, language, limit: 10, page: 1 }),
});
const payload = await response.json().catch(() => null);
if (!response.ok) {
return NextResponse.json({ error: "Crawlora request failed", details: payload }, { status: response.status });
}
return NextResponse.json(payload);
}Developer workflow
The status codes below are common integration patterns. Endpoint detail pages list documented failure responses where available.
| Status / code | Meaning | How to handle |
|---|---|---|
| 400 | Invalid request or missing required input. | Validate request bodies before calling Crawlora and surface useful messages to users. |
| 401 | Missing or invalid API key. | Check the `x-api-key` header and rotate the key from the console if needed. |
| 402/403 | Plan, permission, or billing issue where applicable. | Check plan access, credit state, and endpoint availability. |
| 429 | Rate limit exceeded. | Back off with jitter and reduce concurrency. |
| 5xx | Temporary execution or upstream failure. | Retry safe jobs with exponential backoff and keep the failure visible. |
Developer workflow
Set reasonable timeouts, retry only safe jobs, back off on 429 or temporary 5xx responses, and avoid aggressive loops.
async function fetchWithTimeout(input: RequestInfo, init: RequestInit, timeoutMs = 60_000) {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), timeoutMs);
try {
return await fetch(input, { ...init, signal: controller.signal });
} finally {
clearTimeout(timeout);
}
}Developer workflow
Use Crawlora for structured public web data workflows. Customers are responsible for compliance with applicable laws, third-party rights, platform rules, and Crawlora terms. Keep API keys server-side, validate inputs, and avoid collecting or storing unnecessary sensitive data.
Read Crawlora termsDeveloper workflow
Use these pages to move between endpoint discovery, examples, pricing, and responsible-use guidance.
Developer workflow
Common questions for this Crawlora developer integration path.
Yes. The official TypeScript and JavaScript beta SDK is published at https://github.com/Crawlora-org/crawlora-typescript-sdk and installed as @crawlora-org/sdk from GitHub Packages.
Prefer server-side calls so API keys are not exposed. Browser code should call your own backend or Next.js route handler.
Check for 429 responses, reduce concurrency, and retry with exponential backoff and jitter.
Yes. Use route handlers, server actions, or backend services to call Crawlora with a server-side API key.
Yes. Add timeouts and keep function limits in mind for longer browser-backed endpoints.
Use the SDK's generated declarations for operation ids, endpoint groups, parameter objects, enum values, request options, and response aliases. Keep defensive handling for optional fields.
Open the endpoint detail page from the docs catalog to inspect request parameters, examples, and schema references.
Configure the GitHub Packages registry, pin the current SDK version, and keep Crawlora calls in server-side code.