Java - Firecrawl Docs

Instalación#

El SDK oficial de Java se mantiene en el monorepo de Firecrawl en apps/java-sdk.

Para instalar el SDK de Java de Firecrawl, agrega la dependencia desde Maven Central:

repositories {    mavenCentral()}dependencies {    implementation("com.firecrawl:firecrawl-java:1.1.1")}

repositories {    mavenCentral()}dependencies {    implementation 'com.firecrawl:firecrawl-java:1.1.1'}

<dependency>    <groupId>com.firecrawl</groupId>    <artifactId>firecrawl-java</artifactId>    <version>1.1.1</version></dependency>

Note

Requiere Java 11 o una versión posterior.

Uso#

Obtén una clave de API en firecrawl.dev
Configura la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY, o pásala con FirecrawlClient.builder().apiKey(...)

Aquí tienes un ejemplo rápido con la API actual del SDK:

import com.firecrawl.client.FirecrawlClient;import com.firecrawl.models.CrawlJob;import com.firecrawl.models.CrawlOptions;import com.firecrawl.models.Document;import com.firecrawl.models.ScrapeOptions;import java.util.List;public class Example {    public static void main(String[] args) {        FirecrawlClient client = FirecrawlClient.fromEnv();        Document doc = client.scrape(            "https://firecrawl.dev",            ScrapeOptions.builder()                .formats(List.of((Object) "markdown"))                .build()        );        CrawlJob crawl = client.crawl(            "https://firecrawl.dev",            CrawlOptions.builder().limit(5).build()        );        System.out.println(doc.getMarkdown());        System.out.println("Páginas rastreadas: " + (crawl.getData() != null ? crawl.getData().size() : 0));    }}

Scraping de una URL#

Para hacer scraping de una sola URL, usa el método scrape.

import com.firecrawl.models.Document;import com.firecrawl.models.ScrapeOptions;import java.util.List;Document doc = client.scrape(    "https://firecrawl.dev",    ScrapeOptions.builder()        .formats(List.of((Object) "markdown", "html"))        .onlyMainContent(true)        .waitFor(5000)        .build());System.out.println(doc.getMarkdown());System.out.println(doc.getMetadata().get("title"));

Análisis de archivos cargados#

El paquete más reciente del SDK de Java (com.firecrawl:firecrawl-java) admite la carga directa de archivos a /v2/parse. parse no admite changeTracking ni opciones exclusivas del navegador como screenshot, branding, actions, waitFor, location y mobile.

Java

import com.firecrawl.client.FirecrawlClient;import com.firecrawl.models.Document;import com.firecrawl.models.ParseFile;import com.firecrawl.models.ParseOptions;import java.nio.charset.StandardCharsets;import java.util.List;FirecrawlClient client = FirecrawlClient.fromEnv();ParseFile file = ParseFile.builder()    .filename("upload.html")    .content("<!DOCTYPE html><html><body><h1>Java Parse</h1></body></html>"        .getBytes(StandardCharsets.UTF_8))    .contentType("text/html")    .build();Document parsed = client.parse(    file,    ParseOptions.builder().formats(List.of("markdown")).build());System.out.println(parsed.getMarkdown());

Extracción de JSON#

Extrae JSON estructurado con JsonFormat mediante el endpoint scrape:

import com.firecrawl.models.Document;import com.firecrawl.models.JsonFormat;import com.firecrawl.models.ScrapeOptions;import java.util.List;import java.util.Map;JsonFormat jsonFmt = JsonFormat.builder()    .prompt("Extract the product name and price")    .schema(Map.of(        "type", "object",        "properties", Map.of(            "name", Map.of("type", "string"),            "price", Map.of("type", "number")        )    ))    .build();Document doc = client.scrape(    "https://example.com/product",    ScrapeOptions.builder()        .formats(List.of((Object) jsonFmt))        .build());System.out.println(doc.getJson());

Rastrear un sitio web#

Para rastrear un sitio web y esperar a que finalice, usa crawl.

import com.firecrawl.models.CrawlJob;import com.firecrawl.models.CrawlOptions;import com.firecrawl.models.Document;import com.firecrawl.models.ScrapeOptions;import java.util.List;CrawlJob job = client.crawl(    "https://firecrawl.dev",    CrawlOptions.builder()        .limit(50)        .maxDiscoveryDepth(3)        .scrapeOptions(            ScrapeOptions.builder()                .formats(List.of((Object) "markdown"))                .build()        )        .build());System.out.println("Status: " + job.getStatus());System.out.println("Progress: " + job.getCompleted() + "/" + job.getTotal());if (job.getData() != null) {    for (Document page : job.getData()) {        System.out.println(page.getMetadata().get("sourceURL"));    }}

Iniciar un rastreo#

Inicia un trabajo de forma asíncrona con startCrawl.

import com.firecrawl.models.CrawlOptions;import com.firecrawl.models.CrawlResponse;CrawlResponse start = client.startCrawl(    "https://firecrawl.dev",    CrawlOptions.builder().limit(100).build());System.out.println("Job ID: " + start.getId());

Comprobar el estado del rastreo#

Consulta el progreso del rastreo con getCrawlStatus.

import com.firecrawl.models.CrawlJob;CrawlJob status = client.getCrawlStatus(start.getId());System.out.println("Status: " + status.getStatus());System.out.println("Progress: " + status.getCompleted() + "/" + status.getTotal());

Cancelar un rastreo#

Cancela un rastreo en ejecución con cancelCrawl.

import java.util.Map;Map<String, Object> result = client.cancelCrawl(start.getId());System.out.println(result);

Mapeo de un sitio web#

Descubre enlaces en un sitio web con map.

import com.firecrawl.models.MapData;import com.firecrawl.models.MapOptions;import java.util.Map;MapData data = client.map(    "https://firecrawl.dev",    MapOptions.builder()        .limit(100)        .search("blog")        .build());if (data.getLinks() != null) {    for (Map<String, Object> link : data.getLinks()) {        System.out.println(link.get("url") + " - " + link.get("title"));    }}

Buscar en la Web#

Busca con configuraciones de búsqueda optional usando search.

import com.firecrawl.models.SearchData;import com.firecrawl.models.SearchOptions;import java.util.Map;SearchData results = client.search(    "firecrawl web scraping",    SearchOptions.builder()        .limit(10)        .build());if (results.getWeb() != null) {    for (Map<String, Object> result : results.getWeb()) {        System.out.println(result.get("title") + " - " + result.get("url"));    }}

Scraping por lotes#

Haz scraping de varias URL en paralelo con batchScrape.

import com.firecrawl.models.BatchScrapeJob;import com.firecrawl.models.BatchScrapeOptions;import com.firecrawl.models.Document;import com.firecrawl.models.ScrapeOptions;import java.util.List;BatchScrapeJob job = client.batchScrape(    List.of("https://firecrawl.dev", "https://firecrawl.dev/blog"),    BatchScrapeOptions.builder()        .options(            ScrapeOptions.builder()                .formats(List.of((Object) "markdown"))                .build()        )        .build());if (job.getData() != null) {    for (Document doc : job.getData()) {        System.out.println(doc.getMarkdown());    }}

Agente#

Ejecuta un agente basado en IA con agent.

import com.firecrawl.models.AgentOptions;import com.firecrawl.models.AgentStatusResponse;AgentStatusResponse result = client.agent(    AgentOptions.builder()        .prompt("Find the pricing plans for Firecrawl and compare them")        .build());System.out.println(result.getData());

Con un esquema JSON para una salida estructurada:

import com.firecrawl.models.AgentOptions;import com.firecrawl.models.AgentStatusResponse;import java.util.List;import java.util.Map;AgentStatusResponse result = client.agent(    AgentOptions.builder()        .prompt("Extract pricing plan details")        .urls(List.of("https://firecrawl.dev"))        .schema(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")                        )                    )                )            )        ))        .build());System.out.println(result.getData());

Uso y métricas#

Consulta la concurrencia y los créditos restantes:

import com.firecrawl.models.ConcurrencyCheck;import com.firecrawl.models.CreditUsage;ConcurrencyCheck concurrency = client.getConcurrency();System.out.println("Concurrency: " + concurrency.getConcurrency() + "/" + concurrency.getMaxConcurrency());CreditUsage credits = client.getCreditUsage();System.out.println("Remaining credits: " + credits.getRemainingCredits());

Soporte asíncrono#

Se incluyen variantes asíncronas que devuelven CompletableFuture.

import com.firecrawl.models.Document;import com.firecrawl.models.ScrapeOptions;import java.util.List;import java.util.concurrent.CompletableFuture;CompletableFuture<Document> future = client.scrapeAsync(    "https://example.com",    ScrapeOptions.builder()        .formats(List.of((Object) "markdown"))        .build());future.thenAccept(doc -> System.out.println(doc.getMarkdown()));

Navegador#

El SDK de Java incluye utilidades de Browser Sandbox.

Crear una sesión#

import com.firecrawl.models.BrowserCreateResponse;BrowserCreateResponse session = client.browser(120, 60, true);System.out.println(session.getId());System.out.println(session.getCdpUrl());System.out.println(session.getLiveViewUrl());

Ejecutar código#

import com.firecrawl.models.BrowserExecuteResponse;BrowserExecuteResponse run = client.browserExecute(    session.getId(),    "await page.goto(\"https://example.com\"); console.log(await page.title());",    "node",    60);System.out.println(run.getStdout());System.out.println(run.getExitCode());

Sesión interactiva vinculada al scraping#

Usa un ID de trabajo de scraping para ejecutar código posterior en el mismo contexto reproducido del navegador:

interact(...) ejecuta código en la sesión del navegador vinculada al scraping (y la inicializa en el primer uso).
stopInteraction(...) detiene explícitamente la sesión interactiva cuando hayas terminado.

import com.firecrawl.models.BrowserDeleteResponse;import com.firecrawl.models.BrowserExecuteResponse;String scrapeJobId = "550e8400-e29b-41d4-a716-446655440000";BrowserExecuteResponse scrapeRun = client.interact(    scrapeJobId,    "console.log(page.url());",    "node",    60);System.out.println(scrapeRun.getStdout());BrowserDeleteResponse deleted = client.stopInteraction(scrapeJobId);System.out.println("Deleted: " + deleted.isSuccess());

Listar & cerrar sesiones#

import com.firecrawl.models.BrowserDeleteResponse;import com.firecrawl.models.BrowserListResponse;import com.firecrawl.models.BrowserSession;BrowserListResponse active = client.listBrowsers("active");if (active.getSessions() != null) {    for (BrowserSession s : active.getSessions()) {        System.out.println(s.getId() + " - " + s.getStatus());    }}BrowserDeleteResponse closed = client.deleteBrowser(session.getId());System.out.println("Closed: " + closed.isSuccess());

Configuración#

FirecrawlClient.builder() admite las siguientes opciones:

Opción	Tipo	Predeterminado	Descripción
`apiKey`	`String`	variable de entorno `FIRECRAWL_API_KEY` o propiedad del sistema `firecrawl.apiKey`	Tu API key de Firecrawl
`apiUrl`	`String`	`https://api.firecrawl.dev` (o `FIRECRAWL_API_URL`)	URL base de la API
`timeoutMs`	`long`	`300000`	Tiempo de espera de la request HTTP en ms
`maxRetries`	`int`	`3`	Reintentos automáticos para fallos transitorios
`backoffFactor`	`double`	`0.5`	Factor de retroceso exponencial en segundos
`asyncExecutor`	`Executor`	`ForkJoinPool.commonPool()`	Ejecutor personalizado para métodos asíncronos
`httpClient`	`OkHttpClient`	Construido a partir de `timeoutMs`	Instancia de OkHttpClient preconfigurada

import com.firecrawl.client.FirecrawlClient;FirecrawlClient client = FirecrawlClient.builder()    .apiKey("fc-your-api-key")    .apiUrl("https://api.firecrawl.dev")    .timeoutMs(300_000)    .maxRetries(3)    .backoffFactor(0.5)    .build();

Cliente HTTP personalizado#

Puedes pasar un OkHttpClient preconfigurado para controlar el pool de conexiones, los interceptores, la configuración de SSL, la configuración del proxy y cualquier otra funcionalidad de OkHttp. Cuando se proporciona, la configuración timeoutMs se ignora y se usa la propia configuración del cliente.

import com.firecrawl.client.FirecrawlClient;import okhttp3.OkHttpClient;import java.net.InetSocketAddress;import java.net.Proxy;import java.util.concurrent.TimeUnit;OkHttpClient custom = new OkHttpClient.Builder()    .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.example.com", 8080)))    .addInterceptor(chain -> {        System.out.println("Request: " + chain.request().url());        return chain.proceed(chain.request());    })    .connectTimeout(10, TimeUnit.SECONDS)    .readTimeout(60, TimeUnit.SECONDS)    .build();FirecrawlClient client = FirecrawlClient.builder()    .apiKey("fc-your-api-key")    .httpClient(custom)    .build();

Manejo de errores#

El SDK lanza excepciones en tiempo de ejecución en com.firecrawl.errors.

import com.firecrawl.errors.AuthenticationException;import com.firecrawl.errors.FirecrawlException;import com.firecrawl.errors.JobTimeoutException;import com.firecrawl.errors.RateLimitException;import com.firecrawl.models.Document;try {    Document doc = client.scrape("https://example.com");} catch (AuthenticationException e) {    System.err.println("Auth failed: " + e.getMessage());} catch (RateLimitException e) {    System.err.println("Rate limited: " + e.getMessage());} catch (JobTimeoutException e) {    System.err.println("Job " + e.getJobId() + " timed out after " + e.getTimeoutSeconds() + "s");} catch (FirecrawlException e) {    System.err.println("Error " + e.getStatusCode() + ": " + e.getMessage());}

¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para ver las instrucciones de incorporación automática.