SDK Java | Firecrawl

Installation

Pour installer le SDK Java Firecrawl, ajoutez la dépendance à votre projet :

Gradle (Kotlin DSL)
Gradle (Groovy)
Maven

repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.firecrawl:firecrawl-java-sdk:2.0")
}

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.firecrawl:firecrawl-java-sdk:2.0'
}

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.firecrawl</groupId>
    <artifactId>firecrawl-java-sdk</artifactId>
    <version>2.0</version>
</dependency>

Java 17 ou version ultérieure requis.

Utilisation

Obtenez une clé d’API sur firecrawl.dev
Définissez la clé d’API comme variable d’environnement nommée FIRECRAWL_API_KEY ou transmettez-la au constructeur FirecrawlClient.

Voici un exemple d’utilisation du SDK avec gestion des erreurs :

Java

import dev.firecrawl.client.FirecrawlClient;
import dev.firecrawl.exception.ApiException;
import dev.firecrawl.exception.FirecrawlException;
import dev.firecrawl.model.*;
import java.io.IOException;
import java.time.Duration;
import java.util.UUID;

public class Example {
    public static void main(String[] args) {
        FirecrawlClient client = new FirecrawlClient(
            System.getenv("FIRECRAWL_API_KEY"),
            null,
            Duration.ofSeconds(60)
        );

        try {
            // Scraper une URL
            ScrapeParams scrapeParams = new ScrapeParams();
            scrapeParams.setFormats(new String[]{"markdown"});
            FirecrawlDocument doc = client.scrapeURL("https://firecrawl.dev", scrapeParams);
            System.out.println(doc.getMarkdown());

            // Crawler un site web
            CrawlParams crawlParams = new CrawlParams();
            crawlParams.setLimit(5);
            CrawlStatusResponse job = client.crawlURL(
                "https://firecrawl.dev",
                crawlParams,
                UUID.randomUUID().toString(),
                5
            );

            if ("completed".equalsIgnoreCase(job.getStatus()) && job.getData() != null) {
                for (FirecrawlDocument page : job.getData()) {
                    System.out.println(page.getMetadata().get("sourceURL"));
                }
            }
        } catch (ApiException e) {
            System.err.println("API error " + e.getStatusCode() + ": " + e.getResponseBody());
        } catch (FirecrawlException e) {
            System.err.println("Firecrawl error: " + e.getMessage());
        } catch (IOException e) {
            System.err.println("Network error: " + e.getMessage());
        }
    }
}

Scraper une URL

Pour extraire les données d’une seule URL, utilisez la méthode scrapeURL. Elle prend l’URL en paramètre et renvoie les données extraites sous la forme d’un FirecrawlDocument.

Java

ScrapeParams params = new ScrapeParams();
params.setFormats(new String[]{"markdown", "html"});
params.setOnlyMainContent(true);
params.setWaitFor(5000);

FirecrawlDocument doc = client.scrapeURL("https://firecrawl.dev", params);

System.out.println(doc.getMarkdown());
System.out.println(doc.getMetadata().get("title"));

Extraction en JSON

Extrayez des données structurées à l’aide du point de terminaison Extract en spécifiant un schéma JSON et un prompt :

Java

import dev.firecrawl.model.ExtractParams;
import dev.firecrawl.model.ExtractResponse;
import dev.firecrawl.model.ExtractStatusResponse;
import java.util.Map;

ExtractParams extractParams = new ExtractParams(new String[]{"https://firecrawl.dev"});
extractParams.setPrompt("Extract the product name and price");
extractParams.setSchema(Map.of(
    "type", "object",
    "properties", Map.of(
        "name", Map.of("type", "string"),
        "price", Map.of("type", "number")
    )
));

ExtractResponse start = client.extract(extractParams);
ExtractStatusResponse result = client.getExtractStatus(start.getId());

System.out.println(result.getData());

Explorer un site web

Pour explorer un site web, utilisez la méthode crawlURL. Elle prend en argument l’URL de départ ainsi que des paramètres facultatifs. La méthode crawlURL peut effectuer un polling et renvoyer les documents explorés.

Java

CrawlParams crawlParams = new CrawlParams();
crawlParams.setLimit(50);
crawlParams.setMaxDiscoveryDepth(3);

ScrapeParams scrapeParams = new ScrapeParams();
scrapeParams.setFormats(new String[]{"markdown"});

crawlParams.setScrapeOptions(scrapeParams);

CrawlStatusResponse job = client.crawlURL(
    "https://firecrawl.dev",
    crawlParams,
    UUID.randomUUID().toString(),
    10
);

System.out.println("Status: " + job.getStatus());
System.out.println("Pages crawled: " + (job.getData() != null ? job.getData().length : 0));

if (job.getData() != null) {
    for (FirecrawlDocument doc : job.getData()) {
        System.out.println(doc.getMetadata().get("sourceURL"));
    }
}

Démarrer un crawl

Lancez une tâche sans attendre avec startCrawl. Cette méthode renvoie un identifiant de tâche que vous pouvez utiliser pour vérifier son statut.

Java

CrawlParams crawlParams = new CrawlParams();
crawlParams.setLimit(100);

CrawlResponse start = client.startCrawl("https://firecrawl.dev", crawlParams);

System.out.println("Job ID: " + start.getId());

Vérification du statut d’un crawl

Pour vérifier le statut d’une tâche de crawl, utilisez la méthode getCrawlStatus. Elle prend l’ID de la tâche en paramètre et renvoie son statut actuel.

Java

CrawlStatusResponse status = client.getCrawlStatus(start.getId());
System.out.println("Status: " + status.getStatus());
System.out.println("Progress: " + status.getCompleted() + "/" + status.getTotal());

Annuler un crawl

Pour annuler un job de crawl, utilisez la méthode cancelCrawlJob. Elle prend l’identifiant du job en paramètre et renvoie son statut d’annulation.

Java

CancelCrawlJobResponse result = client.cancelCrawlJob(start.getId());
System.out.println(result);

Cartographier un site web

Pour cartographier un site web, utilisez la méthode mapURL. Elle prend l’URL de départ en paramètre et renvoie les URL détectées.

Java

MapParams mapParams = new MapParams();
mapParams.setLimit(100);
mapParams.setSearch("blog");

MapResponse data = client.mapURL("https://firecrawl.dev", mapParams);

if (data.getLinks() != null) {
    for (String link : data.getLinks()) {
        System.out.println(link);
    }
}

Recherche sur le Web

Recherchez sur le Web et, si besoin, scrapez également les résultats à l’aide de la méthode search.

Java

SearchParams searchParams = new SearchParams("firecrawl web scraping");
searchParams.setLimit(10);

SearchResponse results = client.search(searchParams);

if (results.getResults() != null) {
    for (SearchResult result : results.getResults()) {
        System.out.println(result.getTitle() + " — " + result.getUrl());
    }
}

Scraping par lot

Scrapez plusieurs URL en parallèle à l’aide de la méthode batchScrape.

Java

BatchScrapeParams batchParams = new BatchScrapeParams(new String[]{
    "https://firecrawl.dev",
    "https://firecrawl.dev/blog"
});

ScrapeParams batchScrapeOptions = new ScrapeParams();
batchScrapeOptions.setFormats(new String[]{"markdown"});

batchParams.setScrapeOptions(batchScrapeOptions);

BatchScrapeResponse start = client.batchScrape(batchParams);
BatchScrapeStatusResponse status = client.getBatchScrapeStatus(start.getId());

if (status.getData() != null) {
    for (FirecrawlDocument doc : status.getData()) {
        System.out.println(doc.getMarkdown());
    }
}

Agent

Exécutez un agent IA pour rechercher et extraire des données sur le web.

Java

AgentParams params = new AgentParams("Find the pricing plans for Firecrawl and compare them");

AgentResponse start = client.createAgent(params);
AgentStatusResponse result = client.getAgentStatus(start.getId());

System.out.println(result.getData());

Avec un schéma JSON pour obtenir une sortie structurée :

Java

AgentParams params = new AgentParams("Extract pricing plan details");
params.setUrls(new String[]{"https://firecrawl.dev"});
params.setSchema(Map.of(
    "type", "object",
    "properties", Map.of(
        "plans", Map.of(
            "type", "array",
            "items", Map.of(
                "type", "object",
                "properties", Map.of(
                    "name", Map.of("type", "string"),
                    "price", Map.of("type", "string")
                )
            )
        )
    )
));

AgentResponse start = client.createAgent(params);
AgentStatusResponse result = client.getAgentStatus(start.getId());

System.out.println(result.getData());

Utilisation & métriques

Consultez votre consommation de crédits et de jetons :

Java

AccountCreditUsageResponse credits = client.getCreditUsage();
System.out.println("Remaining credits: " + credits.getData().getRemainingCredits());

AccountTokenUsageResponse tokens = client.getTokenUsage();
System.out.println("Remaining tokens: " + tokens.getData().getRemainingTokens());

Prise en charge de l’asynchrone

Le SDK Java fournit des méthodes synchrones. Si vous avez besoin d’un fonctionnement non bloquant, encapsulez les appels dans CompletableFuture ou utilisez votre propre exécuteur :

Java

import java.util.concurrent.CompletableFuture;

CompletableFuture<FirecrawlDocument> future = CompletableFuture.supplyAsync(() -> {
    try {
        ScrapeParams params = new ScrapeParams();
        params.setFormats(new String[]{"markdown"});
        return client.scrapeURL("https://firecrawl.dev", params);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
});

future.thenAccept(doc -> System.out.println(doc.getMarkdown()));

Browser

Browser Sandbox est disponible via l’API REST. En Java, vous pouvez appeler directement les points de terminaison du navigateur à l’aide du HttpClient standard.

Créer une session

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient http = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.firecrawl.dev/v2/browser"))
    .header("Authorization", "Bearer " + System.getenv("FIRECRAWL_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"ttl\":120,\"activityTtl\":60}"))
    .build();

HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body()); // contient l'identifiant de session, cdpUrl, liveViewUrl

Exécuter du code

Java

String sessionId = "YOUR_SESSION_ID";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.firecrawl.dev/v2/browser/" + sessionId + "/execute"))
    .header("Authorization", "Bearer " + System.getenv("FIRECRAWL_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"code\":\"await page.goto(\\\\\"https://example.com\\\\\"); const t = await page.title(); console.log(t);\",\"language\":\"node\"}"
    ))
    .build();

HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Lister & fermer les sessions

Java

// Lister les sessions actives
HttpRequest list = HttpRequest.newBuilder()
    .uri(URI.create("https://api.firecrawl.dev/v2/browser?status=active"))
    .header("Authorization", "Bearer " + System.getenv("FIRECRAWL_API_KEY"))
    .GET()
    .build();

HttpResponse<String> listResponse = http.send(list, HttpResponse.BodyHandlers.ofString());
System.out.println(listResponse.body());

// Fermer une session
HttpRequest close = HttpRequest.newBuilder()
    .uri(URI.create("https://api.firecrawl.dev/v2/browser"))
    .header("Authorization", "Bearer " + System.getenv("FIRECRAWL_API_KEY"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString("{\"id\":\"" + sessionId + "\"}"))
    .build();

HttpResponse<String> closeResponse = http.send(close, HttpResponse.BodyHandlers.ofString());
System.out.println(closeResponse.body());

Configuration

Le constructeur FirecrawlClient prend en charge les options suivantes :

Option	Type	Par défaut	Description
`apiKey`	`String`	variable d’environnement `FIRECRAWL_API_KEY`	Votre clé API Firecrawl
`apiUrl`	`String`	`https://api.firecrawl.dev`	URL de base de l’API (ou variable d’environnement `FIRECRAWL_API_URL`)
`timeout`	`Duration`	`null`	Délai d’expiration de la requête HTTP

Java

import java.time.Duration;

FirecrawlClient client = new FirecrawlClient(
    System.getenv("FIRECRAWL_API_KEY"),
    "https://api.firecrawl.dev",
    Duration.ofSeconds(300)
);

Gestion des erreurs

Le SDK lève une ApiException en cas d’erreur HTTP et une FirecrawlException pour les autres erreurs du SDK.

Java

import dev.firecrawl.exception.ApiException;
import dev.firecrawl.exception.FirecrawlException;

try {
    ScrapeParams params = new ScrapeParams();
    params.setFormats(new String[]{"markdown"});
    FirecrawlDocument doc = client.scrapeURL("https://firecrawl.dev", params);
} catch (ApiException e) {
    System.err.println("API error " + e.getStatusCode() + ": " + e.getResponseBody());
} catch (FirecrawlException e) {
    System.err.println("Firecrawl error: " + e.getMessage());
} catch (IOException e) {
    System.err.println("Network error: " + e.getMessage());
}

Global

Officiel

Communauté

Java

Installation

Utilisation

Scraper une URL

Extraction en JSON

Explorer un site web

Démarrer un crawl

Vérification du statut d’un crawl

Annuler un crawl

Cartographier un site web

Recherche sur le Web

Scraping par lot

Agent

Utilisation & métriques

Prise en charge de l’asynchrone

Browser

Créer une session

Exécuter du code

Lister & fermer les sessions

Configuration

Gestion des erreurs

Global

Officiel

Communauté

​Installation

​Utilisation

​Scraper une URL

​Extraction en JSON

​Explorer un site web

​Démarrer un crawl

​Vérification du statut d’un crawl

​Annuler un crawl

​Cartographier un site web

​Recherche sur le Web

​Scraping par lot

​Agent

​Utilisation & métriques

​Prise en charge de l’asynchrone

​Browser

​Créer une session

​Exécuter du code

​Lister & fermer les sessions

​Configuration

​Gestion des erreurs

Installation

Utilisation

Scraper une URL

Extraction en JSON

Explorer un site web

Démarrer un crawl

Vérification du statut d’un crawl

Annuler un crawl

Cartographier un site web

Recherche sur le Web

Scraping par lot

Agent

Utilisation & métriques

Prise en charge de l’asynchrone

Browser

Créer une session

Exécuter du code

Lister & fermer les sessions

Configuration

Gestion des erreurs