# Java SDK

The official Java client for the Synthient API: IP and domain lookups, account details, real-time feed streams, and Parquet exports.

> **Note**: The generated reference for every package, class, and method is in the [Javadoc](https://javadoc.io/doc/com.synthient/synthient-java), and the gRPC schema artifact has [its own](https://javadoc.io/doc/com.synthient/synthient-java-grpcschema). These pages cover the same surface with examples. The source and runnable programs, in `examples/`, are at [github.com/synthient/synthient-java](https://github.com/synthient/synthient-java).

## Getting started

### 1. Install

**Install**

```kotlin title="Gradle"
implementation("com.synthient:synthient-java:1.0.0")
```

```xml title="Maven"
<dependency>
  <groupId>com.synthient</groupId>
  <artifactId>synthient-java</artifactId>
  <version>1.0.0</version>
</dependency>
```

Requires Java 21 or later. The client is in the `com.synthient` package and the response models are in `com.synthient.model`. The SDK is built on OkHttp, whose `OkHttpClient` and `Headers` types appear in its API. Its packages are `@NullMarked` with JSpecify, so every type is non-null unless it is annotated `@Nullable`. The jar's automatic module name is `com.synthient`. The [gRPC schema](https://docs.synthient.com/sdks/java/grpc-schema) fetcher is a separate artifact, `com.synthient:synthient-java-grpcschema`.

### 2. Make your first lookup

This program creates a client with the API key in `SYNTHIENT_API_KEY` and looks up one address. Each lookup costs one credit.

```java
import com.synthient.SynthientClient;
import com.synthient.model.Intelligence;
import com.synthient.model.IpInfo;
import com.synthient.model.Network;

public final class Quickstart {
    public static void main(String[] args) {
        try (SynthientClient client = new SynthientClient()) {
            IpInfo info = client.lookupIp("8.8.8.8");
            Network network = info.network();
            if (network != null) {
                System.out.println(network.isp() + " " + network.type());
            }
            Intelligence intelligence = info.intelligence();
            if (intelligence != null) {
                System.out.println(intelligence.riskScore() + " " + intelligence.categories());
            }
        }
    }
}
```

The no-argument constructor reads the API key from the `SYNTHIENT_API_KEY` environment variable. `IpInfo.network()`, `IpInfo.location()`, and `IpInfo.intelligence()` return `null` when the API has no data for that section, so check them before reading their fields.

A `SynthientClient` holds a connection pool, so close it when you are done, for example with try-with-resources.

### 3. Check your credits

`account()` returns the account that owns the API key, including its scopes and remaining lookup credits. It costs no credits.

```java
Account account = client.account();
System.out.println(account.email() + " " + account.organization().name() + " " + account.scopes());
LookupQuota quota = account.lookupQuota();
System.out.println(quota.credits() + " credits, resetting in " + quota.resetsIn());
```

### 4. Handle errors

Every exception the SDK throws for a failed call is unchecked and extends `SynthientException`.

```java
try {
    IpInfo info = client.lookupIp("8.8.8.8");
    System.out.println(info.ip());
} catch (ApiException e) {
    switch (e.statusCode()) {
        case 402 -> System.out.println("out of lookup credits");
        case 429 -> System.out.println(
                e.retryAfter() == null ? "monthly request budget spent" : "rate limited, retry after " + e.retryAfter());
        default -> System.out.println(
                "request " + e.requestId() + " failed: " + (e.detail().isEmpty() ? e.title() : e.detail()));
    }
} catch (ApiConnectionException e) {
    System.out.println("no response: " + e.getMessage());
}
```

### 5. Keep going

- [Client](https://docs.synthient.com/sdks/java/client): create and configure the client, and read the metadata of every API response.
- [Lookups](https://docs.synthient.com/sdks/java/lookups): look up IP addresses and domains, and check your account and the API's health.
- [Feeds](https://docs.synthient.com/sdks/java/feeds): stream each feed's real-time events and download its hourly and daily Parquet exports.
- [Errors and retries](https://docs.synthient.com/sdks/java/errors): how failed requests are reported, and which requests are retried.
- [Types](https://docs.synthient.com/sdks/java/types): the fields of every response and event type, and the enumerations they use.
- [gRPC schema](https://docs.synthient.com/sdks/java/grpc-schema): fetch the protobuf schema of the Synthient gRPC API.