SDK de Java | Firecrawl

Instalación

Para instalar el SDK de Firecrawl para Java, agrega la dependencia a tu proyecto:

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>

Requiere Java 17 o posterior.

Uso

Obtén una clave API de firecrawl.dev
Configura la clave API como una variable de entorno llamada FIRECRAWL_API_KEY o pásala al constructor de FirecrawlClient.

Aquí tienes un ejemplo de cómo usar el SDK con control de errores:

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 {
            // Hacer scrape de una URL
            ScrapeParams scrapeParams = new ScrapeParams();
            scrapeParams.setFormats(new String[]{"markdown"});
            FirecrawlDocument doc = client.scrapeURL("https://firecrawl.dev", scrapeParams);
            System.out.println(doc.getMarkdown());

            // Rastrear un sitio 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());
        }
    }
}

Extraer datos de una URL

Para extraer los datos de una sola URL, usa el método scrapeURL. Toma la URL como parámetro y devuelve los datos extraídos como 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"));

Extracción de JSON

Extrae datos estructurados mediante el endpoint Extract especificando un esquema JSON y 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());

Rastrear un sitio web

Para rastrear un sitio web, usa el método crawlURL. Este método recibe la URL inicial y parámetros opcionales como argumentos. crawlURL puede consultar periódicamente y devolver los documentos rastreados.

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"));
    }
}

Iniciar un rastreo

Inicia un trabajo de forma asíncrona con startCrawl. Devuelve un ID de trabajo que puedes usar para consultar su estado.

Java

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

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

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

Comprobar el estado del rastreo

Para comprobar el estado de un trabajo de rastreo, usa el método getCrawlStatus. Recibe el ID del trabajo como parámetro y devuelve el estado actual del trabajo de rastreo.

Java

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

Cancelar un rastreo

Para cancelar un trabajo de rastreo, utiliza el método cancelCrawlJob. Recibe el ID del trabajo como parámetro y devuelve el estado de la cancelación.

Java

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

Mapear un sitio web

Para mapear un sitio web, utiliza el método mapURL. Toma la URL inicial como parámetro y devuelve las URL encontradas.

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);
    }
}

Buscar en la web

Busca en la web y, si lo deseas, extrae los resultados con el método 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());
    }
}

Extracción por lotes

Extrae varias URL en paralelo con el método 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());
    }
}

Agente

Ejecuta un agente con IA para investigar y extraer datos de la 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());

Con un esquema JSON para una salida estructurada:

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());

Uso y métricas

Consulta el uso de tus créditos y tokens:

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());

Compatibilidad asíncrona

El SDK de Java proporciona métodos síncronos. Si necesitas un comportamiento sin bloqueo, encapsula las llamadas en CompletableFuture o usa tu propio executor:

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()));

Navegador

Browser Sandbox está disponible a través de la API REST. En Java, puedes llamar directamente a los endpoints del navegador con el HttpClient estándar.

Crear una sesión

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()); // contiene el id de sesión, cdpUrl, liveViewUrl

Ejecutar código

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());

Listar y cerrar sesiones

Java

// Listar sesiones activas
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());

// Cerrar una sesión
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());

Configuración

El constructor de FirecrawlClient admite las siguientes opciones:

Opción	Tipo	Predeterminado	Descripción
`apiKey`	`String`	variable de entorno `FIRECRAWL_API_KEY`	Tu clave de API de Firecrawl
`apiUrl`	`String`	`https://api.firecrawl.dev`	URL base de la API (o la variable de entorno `FIRECRAWL_API_URL`)
`timeout`	`Duration`	`null`	Tiempo de espera de la solicitud HTTP

Java

import java.time.Duration;

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

Gestión de errores

El SDK lanza ApiException para errores HTTP y FirecrawlException para otros errores del 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());
}

General

Oficial

Comunidad

Java

Instalación

Uso

Extraer datos de una URL

Extracción de JSON

Rastrear un sitio web

Iniciar un rastreo

Comprobar el estado del rastreo

Cancelar un rastreo

Mapear un sitio web

Buscar en la web

Extracción por lotes

Agente

Uso y métricas

Compatibilidad asíncrona

Navegador

Crear una sesión

Ejecutar código

Listar y cerrar sesiones

Configuración

Gestión de errores

General

Oficial

Comunidad

​Instalación

​Uso

​Extraer datos de una URL

​Extracción de JSON

​Rastrear un sitio web

​Iniciar un rastreo

​Comprobar el estado del rastreo

​Cancelar un rastreo

​Mapear un sitio web

​Buscar en la web

​Extracción por lotes

​Agente

​Uso y métricas

​Compatibilidad asíncrona

​Navegador

​Crear una sesión

​Ejecutar código

​Listar y cerrar sesiones

​Configuración

​Gestión de errores

Instalación

Uso

Extraer datos de una URL

Extracción de JSON

Rastrear un sitio web

Iniciar un rastreo

Comprobar el estado del rastreo

Cancelar un rastreo

Mapear un sitio web

Buscar en la web

Extracción por lotes

Agente

Uso y métricas

Compatibilidad asíncrona

Navegador

Crear una sesión

Ejecutar código

Listar y cerrar sesiones

Configuración

Gestión de errores