Java SDK

The official Java SDK for the Screenshot Scout screenshot API. It is distributed on Maven Central as com.screenshotscout:screenshotscout and developed in the screenshotscout-java repository.

Installation

Add the dependency to your Maven project:

<dependency>
  <groupId>com.screenshotscout</groupId>
  <artifactId>screenshotscout</artifactId>
  <version>0.1.0</version>
</dependency>

The SDK requires Java 17 or newer, and works with Maven, Gradle, or any other build tool that resolves Maven Central.

Sign up for Screenshot Scout or sign in. We automatically create a default API key for you when you sign up. Open the API Keys page, copy the access key and secret key, and store them in a safe place.

Capture a screenshot

Create a client with your access key and call capture() with the URL of the page you would like to take a screenshot of:

import com.screenshotscout.BinaryCaptureResponse;
import com.screenshotscout.CaptureOptions;
import com.screenshotscout.CaptureResponse;
import com.screenshotscout.ScreenshotScoutClient;
import java.nio.file.Files;
import java.nio.file.Path;

public class Example {
  public static void main(String[] args) throws Exception {
    ScreenshotScoutClient client =
        ScreenshotScoutClient.builder()
            .accessKey("YOUR_ACCESS_KEY")
            .build();

    CaptureResponse response =
        client.capture(
            "https://example.com",
            CaptureOptions.builder().fullPage(true).build());

    if (response instanceof BinaryCaptureResponse binary) {
      Files.write(Path.of("screenshot.png"), binary.bytes());
      binary.screenshotUrl().ifPresent(System.out::println);
    }
  }
}

capture() sends a POST request by default. The responseType option on CaptureOptions selects the response format. When you leave it unset, the call returns a BinaryCaptureResponse: the image data is in bytes(), and the exact screenshot URL is in screenshotUrl() when available.

Request a JSON result

Set responseType to CaptureResponseType.JSON to receive a JSON object with the screenshot URL instead of the image bytes:

import com.screenshotscout.CaptureOptions;
import com.screenshotscout.CaptureResponseType;
import com.screenshotscout.JsonCaptureResponse;
import com.screenshotscout.ScreenshotScoutClient;

public class Example {
  public static void main(String[] args) throws Exception {
    ScreenshotScoutClient client =
        ScreenshotScoutClient.builder()
            .accessKey("YOUR_ACCESS_KEY")
            .build();

    CaptureOptions options =
        CaptureOptions.builder()
            .responseType(CaptureResponseType.JSON)
            .build();

    JsonCaptureResponse response =
        (JsonCaptureResponse) client.capture("https://example.com", options);

    response.result().screenshotUrl().ifPresent(System.out::println);
  }
}

The parsed JSON body is in result().

Non-blocking client

Use ScreenshotScoutAsyncClient when your application needs non-blocking I/O. Its capture() methods return a CompletableFuture that completes with the final capture response; it does not create a background job:

import com.screenshotscout.BinaryCaptureResponse;
import com.screenshotscout.ScreenshotScoutAsyncClient;
import java.util.concurrent.CompletableFuture;

public class Example {
  public static void main(String[] args) {
    ScreenshotScoutAsyncClient asyncClient =
        ScreenshotScoutAsyncClient.builder()
            .accessKey("YOUR_ACCESS_KEY")
            .buildAsync();

    CompletableFuture<Void> finished =
        asyncClient
            .capture("https://example.com")
            .thenAccept(
                response -> {
                  BinaryCaptureResponse binary = (BinaryCaptureResponse) response;
                  System.out.println(binary.bytes().length);
                });

    finished.join();
  }
}

Cancel the returned future to cancel an in-flight request.

Set capture options

Configure the screenshot with CaptureOptions.builder(), which covers every option in the screenshot option reference through camelCase builder methods: full_page becomes fullPage(...), block_cookie_banners becomes blockCookieBanners(...), and so on. Options with a fixed set of documented values have constants, such as CaptureFormat.WEBP and CaptureWaitUntil.LOAD. For a value the constants do not cover yet, use the value type's fromString method.

Build a capture URL

Use buildCaptureUrl() when a browser, an HTML <img> element, or another application needs to load the screenshot directly. It creates a GET capture URL without making an API request:

import com.screenshotscout.CaptureOptions;
import com.screenshotscout.ScreenshotScoutClient;

public class Example {
  public static void main(String[] args) {
    ScreenshotScoutClient client =
        ScreenshotScoutClient.builder()
            .accessKey("YOUR_ACCESS_KEY")
            .build();

    String captureUrl =
        client.buildCaptureUrl(
            "https://example.com",
            CaptureOptions.builder()
                .fullPage(true)
                .blockAds(true)
                .build());

    System.out.println(captureUrl);
  }
}

The generated URL contains the access key. When a secret key is configured (see Signed requests), the SDK signs the URL automatically; otherwise it is unsigned. Treat generated URLs as sensitive. Before exposing one to browsers or users, configure a secret key and enable Require signed requests on the API Keys page.

Signed requests

Pass the API key's secret key to the client builder:

import com.screenshotscout.ScreenshotScoutClient;

public class Example {
  public static void main(String[] args) {
    ScreenshotScoutClient client =
        ScreenshotScoutClient.builder()
            .accessKey("YOUR_ACCESS_KEY")
            .secretKey("YOUR_SECRET_KEY")
            .build();
  }
}

The secret is used locally and is never transmitted. The client signs capture requests and generated capture URLs automatically. See the signed requests guide for details.

Errors

When the API returns a non-2xx response, the SDK throws ScreenshotScoutApiException, with the HTTP status in statusCode() and the machine-readable error code and descriptive message in errorCode() and errorMessage(). All SDK exceptions extend ScreenshotScoutException, and failed requests are not retried automatically. The repository README documents all exception types.

Full reference

This page covers installation and your first captures. For everything else, see:

The repository README: GET requests, timeouts and cancellation, a custom JDK HttpClient, raw responses, and all exception types.
The standalone examples in the repository.
The screenshot option reference: service behavior and allowed values for every option.