Java SDK · ipscope Docs

# Install

Dependency

<dependency>
  <groupId>io.ipscope</groupId>
  <artifactId>ipscope-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

# Quickstart: single, batch & prefix lookups

Pass your API key explicitly or set IPSCOPE_KEY in your environment. Every lookup returns the canonical response schema with geo, network, connection, security and security_extensions.

Java

import io.ipscope.sdk.IpScopeClient;
import io.ipscope.sdk.IpScopeConfig;
import io.ipscope.sdk.model.BatchLookupResponse;
import io.ipscope.sdk.model.IpLookupResponse;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        IpScopeConfig config = IpScopeConfig.builder()
            .apiKey(System.getenv("IPSCOPE_KEY"))
            .build();

        try (IpScopeClient client = new IpScopeClient(config)) {
            // 1. Single IPv4 or IPv6 lookup
            IpLookupResponse info = client.lookupIp("198.51.100.7");
            System.out.println(info.ip() + " " + info.geo().countryCode()
                + " VPN=" + info.security().isVpn());

            // 2. Async lookup via CompletableFuture
            client.lookupIpAsync("1.1.1.1")
                .thenAccept(res -> System.out.println("Async: " + res.network().organization()));

            // 3. Batch lookup (up to 100 IPs)
            BatchLookupResponse batch = client.lookupBatch(List.of("198.51.100.7", "1.1.1.1"));
            System.out.println("Resolved: " + batch.count());

            // 4. Network CIDR prefix lookup
            var prefix = client.lookupNetwork("198.51.100.0/24");
            System.out.println(prefix.queriedCidr() + " -> AS" + prefix.record().asn());
        }
    }
}

Responses

application/json

1. Single IPv4/IPv6 lookup response (GET /v1/ip/{ip})

{
  "ip": "198.51.100.7",
  "ip_version": 4,
  "matched_network": "198.51.100.0/24",
  "geo": {
    "country_code": "US",
    "declared_country_code": "US",
    "physical_country_code": "US",
    "is_virtual_location": false,
    "location_type": "physical",
    "confidence": 0.94,
    "subdivision": "Virginia",
    "city": "Ashburn",
    "postal_code": "20147",
    "latitude": 39.0438,
    "longitude": -77.4874,
    "accuracy_radius_km": 10,
    "timezone": "America/New_York"
  },
  "network": {
    "asn": 64501,
    "organization": "Example Cloud LLC"
  },
  "connection": {
    "connection_type": "hosting",
    "is_hosting": true,
    "is_residential": false,
    "is_mobile": false,
    "is_business": false
  },
  "security": {
    "is_vpn": true,
    "is_hosting": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "anonymizer_type": "vpn",
    "confidence": 0.96,
    "reason_codes": [
      "vpn_handshake_confirmed",
      "datacenter_asn_range"
    ]
  },
  "security_extensions": {
    "abuse_velocity_score": 18,
    "is_known_scanner": false,
    "observation_recency_hours": 12,
    "anonymizer_reason": "vpn_handshake_confirmed",
    "threat_level": "medium",
    "abuse_velocity": "low",
    "confidence": 0.96
  },
  "dataset_version": "2026-10-27T00:00:00Z.crawl-1793088000000",
  "updated_at": "2026-10-27T00:00:00Z"
}

application/json

4. Network CIDR prefix lookup response (GET /v1/networks/{prefix}/{length})

{
  "queried_cidr": "198.51.100.0/24",
  "family": 4,
  "dataset_version": "2026-10-27T00:00:00Z.crawl-1793088000000",
  "record": {
    "prefix": "198.51.100.0/24",
    "family": 4,
    "asn": 64501,
    "organization": "Example Cloud LLC",
    "countryCode": "US",
    "city": "Ashburn",
    "locationType": "physical",
    "isVpn": true,
    "isHosting": true,
    "isTorExit": false,
    "isProxy": false,
    "anonymizerType": "vpn"
  }
}

# Architecture & runtime guarantees

Built on standard java.net.http.HttpClient with both synchronous methods and non-blocking CompletableFuture methods (lookupIpAsync, lookupBatchAsync).
Immutable Java 17 record models (IpLookupResponse, GeoInfo, NetworkInfo, ConnectionInfo, SecurityInfo).
Implements AutoCloseable with a bounded thread-safe LRU cache and streaming Consumer<BatchLookupResponse> batch chunking.

# Reading local MMDB files

If you subscribe to a downloadable database, our .mmdb snapshots open directly in standard MaxMind DB readers with sub-microsecond in-memory lookups:

Java (MMDB)

import com.maxmind.db.Reader;
import java.io.File;
import java.net.InetAddress;
import java.util.Map;

try (Reader reader = new Reader(new File("/var/lib/ipscope/ipscope-complete.mmdb"))) {
    Map<?, ?> record = reader.get(InetAddress.getByName("198.51.100.7"), Map.class);
}

# Plain HTTP fallback

Need to call the REST API without installing a package? Use Java’s standard HTTP client directly:

Java (HTTP)

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.ipscope.io/v1/ip/198.51.100.7"))
    .header("Authorization", "Bearer " + System.getenv("IPSCOPE_KEY"))
    .build();

HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());