v4

Lookups

View as markdown

Look up IP addresses and domains, and check your account and the API's health.

lookupIp

Returns intelligence for an IPv4 or IPv6 address literal.

public IpInfo lookupIp(String ip)

IpInfo info = client.lookupIp("213.149.183.127");
Location location = info.location();
if (location != null) {
    System.out.println(location.city() + ", " + location.country());
}
Intelligence intelligence = info.intelligence();
if (intelligence != null) {
    for (Provider provider : intelligence.providers()) {
        System.out.println(provider.name() + " " + provider.type() + " " + provider.lastSeen());
    }
}
  • Cost: Each lookup costs one credit, and failed lookups are not billed.
  • Input: A string that is not an address literal throws IllegalArgumentException without sending a request, and host names are never resolved.
  • Errors: Private and reserved addresses return a 422 ApiException.

lookupIps

Looks up as many as 1000 addresses in one request.

public List<IpInfo> lookupIps(Collection<String> ips)

List<IpInfo> results = client.lookupIps(List.of("8.8.8.8", "1.1.1.1"));
for (IpInfo result : results) {
    Intelligence intelligence = result.intelligence();
    if (intelligence == null) {
        System.out.println(result.ip() + " no intelligence available");
        continue;
    }
    System.out.println(result.ip() + " " + intelligence.riskScore());
}
  • Cost: The API bills ceil(n * 0.9) credits for the n distinct addresses it looks up, and bills nothing if the team or key cannot cover the whole batch.
  • Results: Private and reserved addresses are skipped and duplicates are merged, so there can be fewer results than addresses, in a different order. Match results by ip(), which the API canonicalizes, rather than by position.
  • Input: An empty collection returns an empty list without a request. More than 1000 addresses, or an element that is null or not an address literal, throws IllegalArgumentException before anything is sent.
  • Errors: A batch with no address the API can look up returns a 422 ApiException.

lookupDomain

Returns the proxy traffic to a domain that Synthient's honeypots observed over the last 30 days.

public DomainInfo lookupDomain(String domain)
public DomainInfo lookupDomain(String domain, int limit)

DomainInfo domain = client.lookupDomain("example.com", 10);
System.out.println(domain.status() + " " + domain.stats().events24h());
for (DomainEvent event : domain.recentEvents()) {
    System.out.println(event.timestamp() + " " + event.targetSubdomain() + " " + event.port());
}
  • Cost: Each lookup costs one credit.
  • Limit: limit caps the number of recent events, and the API clamps it to 1000. Without it, the API returns its default of 50.
  • Input: Internationalized names must be in Punycode. An empty domain, ".", or "..", or a limit below 1, throws IllegalArgumentException without a request.
  • Results: A domain that has never been observed returns DomainStatus.INACTIVE and zeroed statistics rather than an error.

Account and health

account

Returns the account that owns the API key, including its scopes and remaining lookup credits.

public Account account()

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());
  • Cost: It costs no credits.

health

Returns normally if the API and its dependencies are healthy.

public void health()

try {
    client.health();
} catch (ApiException e) {
    System.err.println("unhealthy: " + e.statusCode());
}
  • Errors: An unhealthy API throws an ApiException with status 503. The API does not check the key, but a malformed key throws a 401 ApiException.
Previous
Next