Developer guides

Crawlora Java SDK

Use the official Maven Central beta SDK from JVM services, Spring applications, backend APIs, and data jobs. Built on java.net.http with no runtime dependencies.

Official beta SDKMaven CentralJava 17+No dependenciesRetries

Open GitHub repo Try Playground

Verified HTTP pattern

GET /bing/search

Normalized JSON

Request

GET https://api.crawlora.net/api/v1/bing/search?q=best+CRM+software&country=us&count=10
x-api-key: $CRAWLORA_API_KEY

Base URL

https://api.crawlora.net/api/v1

Auth header

x-api-key

Example endpoint

GET /bing/search

The Java SDK is published to Maven Central as net.crawlora:crawlora-sdk and developed at https://github.com/Crawlora-org/crawlora-java-sdk. Add the current promoted beta version 1.5.0-sdk.3 and keep API keys in server-side environments. Requires Java 17 or newer.

Developer workflow

Add the dependency

Add the Maven Central artifact to your build. The SDK has no runtime dependencies beyond the JDK.

pom.xml · xml

<dependency>
  <groupId>net.crawlora</groupId>
  <artifactId>crawlora-sdk</artifactId>
  <version>1.5.0-sdk.3</version>
</dependency>

build.gradle · groovy

implementation "net.crawlora:crawlora-sdk:1.5.0-sdk.3"

Developer workflow

Environment variable

.env · bash

export CRAWLORA_API_KEY="your_api_key_here"

Developer workflow

SDK request

Build a client with your API key, then call typed endpoint groups or the dynamic operation interface.

SDK client · java

import net.crawlora.CrawloraClient;
import java.util.List;
import java.util.Map;

// Reads CRAWLORA_API_KEY from the environment if apiKey(...) is omitted.
CrawloraClient client = CrawloraClient.builder()
        .apiKey(System.getenv("CRAWLORA_API_KEY"))
        .build();

@SuppressWarnings("unchecked")
Map<String, Object> result = (Map<String, Object>) client.bing().search(Map.of("q", "coffee shops"));
for (Object item : (List<Object>) result.get("data")) {
    System.out.println(((Map<String, Object>) item).get("title"));
}

Developer workflow

Raw HttpClient fallback

Use java.net.http directly for a zero-dependency path, or to compare behavior with endpoint docs before adding the SDK.

HttpClient request · java

package com.example;

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class CrawloraRequest {
    private static final String API_KEY = System.getenv("CRAWLORA_API_KEY");
    private static final String BASE_URL = "https://api.crawlora.net/api/v1";

    static String request(String pathWithQuery) throws Exception {
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(60))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + pathWithQuery))
                .header("x-api-key", API_KEY)
                .GET()
                .timeout(Duration.ofSeconds(60))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300) {
            throw new RuntimeException("Crawlora request failed: " + response.statusCode() + " " + response.body());
        }
        return response.body();
    }

    public static void main(String[] args) throws Exception {
        String query = URLEncoder.encode("best CRM software", StandardCharsets.UTF_8);
        System.out.println(request("/bing/search?q=" + query + "&country=us"));
    }
}

Developer workflow

Spring Boot REST controller example

Proxy browser requests through a server-side controller so the API key never reaches client-side code.

REST controller · java

import net.crawlora.CrawloraClient;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api/search")
public class SearchController {

    // Reads CRAWLORA_API_KEY from the environment.
    private final CrawloraClient client = CrawloraClient.builder().build();

    @PostMapping
    public Map<String, Object> search(@RequestBody Map<String, String> body) {
        String keyword = body.getOrDefault("keyword", "");
        if (keyword.isBlank()) {
            throw new IllegalArgumentException("keyword is required");
        }
        return client.bing().search(Map.of("q", keyword));
    }
}

Developer workflow

Scheduled batch job example

Loop a keyword list through the typed client for a nightly job or CLI tool, logging per-keyword results and failures separately.

Batch job · java

import net.crawlora.CrawloraClient;
import java.util.List;
import java.util.Map;

public class SearchBatchJob {
    public static void main(String[] args) {
        CrawloraClient client = CrawloraClient.builder().build();
        List<String> keywords = List.of("project management software", "crm for startups", "sales automation");

        for (String keyword : keywords) {
            try {
                @SuppressWarnings("unchecked")
                Map<String, Object> result = (Map<String, Object>) client.bing().search(Map.of("q", keyword));
                @SuppressWarnings("unchecked")
                List<Object> items = (List<Object>) result.get("data");
                System.out.println(keyword + ": " + items.size() + " results");
            } catch (Exception exc) {
                System.err.println(keyword + " failed: " + exc.getMessage());
            }
        }
    }
}

Developer workflow

Error handling

Catch exceptions from the SDK client and inspect the status codes below — Java's typed response wrappers surface these the same way across every endpoint group. 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

Production checklist

Store the key in an environment variable.
Reuse a single CrawloraClient instance.
Handle 429 responses with the built-in retry and backoff.
Bound concurrency for high-throughput jobs.
Log request context where available.
Validate inputs.
Keep API keys out of logs.

Responsible public web data workflows

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 terms

Developer workflow

FAQ

Common questions for this Crawlora developer integration path.

Is there an official Crawlora Java SDK?

Yes. The official Java beta SDK is published to Maven Central as net.crawlora:crawlora-sdk and developed at https://github.com/Crawlora-org/crawlora-java-sdk. Pin the current version 1.5.0-sdk.3.

Which Java version is required?

Java 17 or newer. The client is built on the JDK's java.net.http.HttpClient and has no runtime dependencies.

How do I authenticate?

Pass your API key to CrawloraClient.builder().apiKey(...), or omit it to read CRAWLORA_API_KEY from the environment. JWT authorization is also supported.

Does the SDK handle retries and rate limits?

Yes. It includes automatic retries with exponential backoff and Retry-After handling, plus client-side rate limiting and before/after middleware hooks.

Can I use it with Maven and Gradle?

Yes. Add the net.crawlora:crawlora-sdk coordinate to your pom.xml dependencies or your Gradle implementation configuration.

How do I call Crawlora from a Spring Boot service?

Build a CrawloraClient once (reading CRAWLORA_API_KEY from the environment) and inject or reuse it inside a @RestController, calling typed endpoint groups from your handler methods — see the Spring Boot REST controller example above.

Where do I find endpoint schemas?

Open the endpoint detail page from the docs catalog to inspect request parameters, examples, and schema references.

Install the Java SDK

Add the Maven Central artifact, pin the current version, set CRAWLORA_API_KEY, then inspect endpoint docs for platform-specific schemas.

Open GitHub repo Browse APIs

import net.crawlora.CrawloraClient; import java.util.List; import java.util.Map; // Reads CRAWLORA_API_KEY from the environment if apiKey(...) is omitted. CrawloraClient client = CrawloraClient.builder() .apiKey(System.getenv("CRAWLORA_API_KEY")) .build(); @SuppressWarnings("unchecked") Map<String, Object> result = (Map<String, Object>) client.bing().search(Map.of("q", "coffee shops")); for (Object item : (List<Object>) result.get("data")) { System.out.println(((Map<String, Object>) item).get("title")); }

package com.example; import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; public class CrawloraRequest { private static final String API_KEY = System.getenv("CRAWLORA_API_KEY"); private static final String BASE_URL = "https://api.crawlora.net/api/v1"; static String request(String pathWithQuery) throws Exception { HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(60)) .build(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(BASE_URL + pathWithQuery)) .header("x-api-key", API_KEY) .GET() .timeout(Duration.ofSeconds(60)) .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() >= 300) { throw new RuntimeException("Crawlora request failed: " + response.statusCode() + " " + response.body()); } return response.body(); } public static void main(String[] args) throws Exception { String query = URLEncoder.encode("best CRM software", StandardCharsets.UTF_8); System.out.println(request("/bing/search?q=" + query + "&country=us")); } }

import net.crawlora.CrawloraClient; import org.springframework.web.bind.annotation.*; import java.util.Map; @RestController @RequestMapping("/api/search") public class SearchController { // Reads CRAWLORA_API_KEY from the environment. private final CrawloraClient client = CrawloraClient.builder().build(); @PostMapping public Map<String, Object> search(@RequestBody Map<String, String> body) { String keyword = body.getOrDefault("keyword", ""); if (keyword.isBlank()) { throw new IllegalArgumentException("keyword is required"); } return client.bing().search(Map.of("q", keyword)); } }

import net.crawlora.CrawloraClient; import java.util.List; import java.util.Map; public class SearchBatchJob { public static void main(String[] args) { CrawloraClient client = CrawloraClient.builder().build(); List<String> keywords = List.of("project management software", "crm for startups", "sales automation"); for (String keyword : keywords) { try { @SuppressWarnings("unchecked") Map<String, Object> result = (Map<String, Object>) client.bing().search(Map.of("q", keyword)); @SuppressWarnings("unchecked") List<Object> items = (List<Object>) result.get("data"); System.out.println(keyword + ": " + items.size() + " results"); } catch (Exception exc) { System.err.println(keyword + " failed: " + exc.getMessage()); } } } }

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.

Crawlora Java SDK

Add the dependency

pom.xml · xml

build.gradle · groovy

Environment variable

.env · bash

SDK request

SDK client · java

Raw HttpClient fallback

HttpClient request · java

Spring Boot REST controller example

REST controller · java

Scheduled batch job example

Batch job · java

Error handling

Production checklist

Responsible public web data workflows

Related developer links

Java SDK repo

Crawlora GitHub org

Docs

Playground

Go guide

PHP guide

Ruby guide

cURL examples

FAQ

Install the Java SDK

Crawlora Java SDK

Add the dependency

pom.xml · xml

build.gradle · groovy

Environment variable

.env · bash

SDK request

SDK client · java

Raw HttpClient fallback

HttpClient request · java

Spring Boot REST controller example

REST controller · java

Scheduled batch job example

Batch job · java

Error handling

Production checklist

Responsible public web data workflows

Related developer links

Java SDK repo

Crawlora GitHub org

Docs

Playground

Go guide

PHP guide

Ruby guide

cURL examples

FAQ

Install the Java SDK