Veille

Java

Install the Veille Java SDK and make your first API call.

The official Java SDK for Veille, with one typed method per endpoint and a generic request() for anything else.

Requirements

  • Java 17+

Install

The Java SDK is not on Maven Central. Build it from source to install it in your local Maven repository, then add it to your project.

git clone https://github.com/veilleio/veille-java.git
cd veille-java
mvn -q install -DskipTests
Maven
<dependency>
  <groupId>io.veille</groupId>
  <artifactId>veille</artifactId>
  <version>0.1.0</version>
</dependency>
Gradle
implementation("io.veille:veille:0.1.0")

Get your API key

Copy your API key from the Veille dashboard and set it in the VEILLE_API_KEY environment variable, which the SDK reads by default. Keep it out of source control.

Quick start

import io.veille.ApiResponse;
import io.veille.VeilleClient;
import io.veille.params.IntelligenceEmailParams;

VeilleClient client = VeilleClient.fromEnv();
ApiResponse response = client.intelligenceEmail(IntelligenceEmailParams.builder().query("jane.doe@example.com").build());
System.out.println(response.json().toPrettyString());

Async jobs

Any call accepts is_async, which is useful past the 60-second server limit. The response is then a job_id, and the SDK can wait for the job to finish.

ApiResponse submitted = client.intelligenceEmail(IntelligenceEmailParams.builder().query("jane.doe@example.com").isAsync(true).build());
ApiResponse job = client.waitForJob(
    submitted.json().get("job_id").asText(),
    Duration.ofSeconds(3),
    Duration.ofHours(12),
    progress -> System.out.println(progress.path("status").asText() + " " + progress.path("progress").asInt()));

Errors

A non-2xx response raises an API error with its status and message. See Status codes for the full list.

try {
  client.intelligenceEmail(IntelligenceEmailParams.builder().query("jane.doe@example.com").build());
} catch (VeilleApiException e) {
  System.err.println(e.status() + ": " + e.getMessage());
}

Retries

Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a plan rate limit. Per-key quota errors and client-side timeouts are not retried. The delay starts at 1 second and grows 1.5× per retry, and a Retry-After header wins.

VeilleClient client = VeilleClient.builder().maxRetries(5).retryDelay(Duration.ofMillis(500)).build();
client.intelligenceEmail(IntelligenceEmailParams.builder().query("jane.doe@example.com").build(), RequestOptions.builder().maxRetries(0).build()); // one request without retries

Batch requests

Run many calls at once, 10 at a time by default. One failure does not stop the others.

List<String> inputs = List.of("jane.doe@example.com", "john@mailinator.com", "contact@veille.io");
List<BatchResult<ApiResponse>> results = client.batch(inputs, 5, value ->
    client.intelligenceEmail(IntelligenceEmailParams.builder().query(value).build()));
for (BatchResult<ApiResponse> result : results) {
  if (result.ok()) {
    System.out.println(result.value().json());
  } else {
    System.err.println(inputs.get(result.index()) + ": " + result.error().getMessage());
  }
}

Any endpoint

request() reaches any path, including endpoints released after your SDK version.

ApiResponse response = client.request("GET", "/v1/usage", Map.of());

Common mistakes

  • Putting the API key in front-end code. Anyone could read it. Call the API from your server.
  • Treating every 401 as a bad key. A 401 can also be a rate limit: read the message. The SDK retries plan rate limits for you.
  • Retrying a 402. It means there are no credits or quota left, so a retry cannot succeed. See Credits.
  • Waiting on long requests. Past 60 seconds, use async mode as shown above rather than raising your timeout. See Timeout.

On this page

RequirementsInstallGet your API keyQuick startAsync jobsErrorsRetriesBatch requestsAny endpointCommon mistakesLinks