CheckHost4J

A lightweight, lightning-fast, and feature-complete Java 17+ wrapper for the Check-Host.cc API. Full API reference: check-host.cc/docs. A bundled OpenAPI 3.0.3 / Swagger spec ships at swagger.yaml for codegen / offline browsing.

Seamlessly integrate global network diagnostics into your backend. Perform remote Ping, MTR, DNS, HTTP, TCP and UDP checks from multiple worldwide locations—straight from your Java application. Checks from 60+ locations worldwide.

Features

• Minimal Dependencies: Built purely on the native java.net.http.HttpClient (Java 11+). Only requires Jackson for robust JSON parsing.
• Bulletproof Payloads: Strictly utilizes POST requests for all active monitoring endpoints. This completely eliminates nasty URL-encoding issues with complex hostnames or custom UDP payloads.
• Modern & Clean: Written for Java 17+ with full record classes to eliminate boilerplate, ensuring a beautifully typed structure.
• Smart Authentication: API Key auto-injection. Configure your key once during initialization, and the core SDK seamlessly handles all authentication payloads under the hood.

Requirements

• Java: 17 or higher
• Maven: 3.6+ (for building)

Installation

Add the following dependency to your pom.xml:

<dependency>
    <groupId>cc.checkhost</groupId>
    <artifactId>checkhost4j</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Quickstart

A comprehensive, ready-to-run demonstration containing every available method and option is included in the project under src/main/java/cc/checkhost/Example.java.

Basic Usage

package cc.checkhost;

import cc.checkhost.models.CheckCreated;
    public static void main(String[] args) {
        // Initialize the client. The API Key is optional.
        // Without an API key, standard public rate limits apply.
        // CheckHost checkHost = new CheckHost("YOUR_API_KEY_HERE");
        CheckHost checkHost = new CheckHost();

        // Example: Retrieve the public IP of your server
        System.out.println("My IP: " + checkHost.myip());
        
        // Example: Ping exactly one location
        CheckCreated pingNode = checkHost.ping("1.1.1.1");
        System.out.println("Task UUID: " + pingNode.uuid());
    }
}

---

Complete API Reference & Examples

This library supports both minimal invocations and detailed, options-rich requests for every endpoint using the Builder pattern. All failures (network issues, API errors, rate limits) throw a CheckHostException.

Common Options Used in Examples

• region: List of Node names (e.g., List.of("us1.node.check-host.cc")) or ISO Country Codes (e.g., List.of("DE", "NL")) or Continents (e.g., List.of("EU")).
• repeatchecks: Number of repeated probes to perform per node for higher accuracy (Live Check).
• timeout: Connection timeout threshold in seconds.

---

Information & Utilities

Get My IP

Returns the requesting client's public IPv4 or IPv6 address.

String ip = checkHost.myip();

Get Locations

Fetches a dynamic list of all currently active monitoring nodes across the globe.

JsonNode nodes = checkHost.locations();

Host Info (GeoIP/ASN)

Retrieves detailed geolocation data, ISP information, and ASN details.

MinResponseINFO info = checkHost.info("check-host.cc");
System.out.println(info.country());

WHOIS Lookup

Performs a WHOIS registry lookup.

JsonNode whois = checkHost.whois("check-host.cc");

---

Active Monitoring (POST Tasks)

Monitoring endpoints initiate tasks asynchronously and return a CheckCreated record containing an uuid. Use the report() method to fetch the actual results.

Ping

Dispatches ICMP echo requests to the target from global nodes.

// Minimal Example
CheckCreated pingMin = checkHost.ping("8.8.8.8");

// Max Example (With options)
PingOptions options = PingOptions.builder()
        .region(List.of("DE", "NL"))
        .repeatchecks(5)
        .timeout(5)
        .build();
CheckCreated pingMax = checkHost.ping("8.8.8.8", options);

DNS

Queries global nameservers for specific DNS records.

// Minimal Example
CheckCreated dnsMin = checkHost.dns("check-host.cc");

// Max Example (TXT Record)
DnsOptions options = DnsOptions.builder()
        .querymethod("TXT")
        .region(List.of("US", "DE"))
        .build();
CheckCreated dnsMax = checkHost.dns("check-host.cc", options);

TCP

Attempts to establish a 3-way TCP handshake on a specific destination port.

// Minimal Example (Target, Port)
CheckCreated tcpMin = checkHost.tcp("1.1.1.1", 443);

// Max Example
TcpOptions options = TcpOptions.builder()
        .region(List.of("DE", "NL"))
        .repeatchecks(3)
        .build();
CheckCreated tcpMax = checkHost.tcp("1.1.1.1", 443, options);

UDP

Sends UDP packets to a specified target and port.

// Minimal Example (Target, Port)
CheckCreated udpMin = checkHost.udp("1.1.1.1", 53);

// Max Example (With hex payload)
UdpOptions options = UdpOptions.builder()
        .payload("0b")
        .region(List.of("EU"))
        .build();
CheckCreated udpMax = checkHost.udp("1.1.1.1", 123, options);

HTTP

Executes an HTTP/HTTPS request to the target to measure latency.

// Minimal Example
CheckCreated httpMin = checkHost.http("https://check-host.cc");

// Max Example
HttpOptions options = HttpOptions.builder()
        .region(List.of("US", "DE"))
        .repeatchecks(3)
        .build();
CheckCreated httpMax = checkHost.http("https://check-host.cc", options);

MTR

Initiates an MTR (My Traceroute) diagnostic.

// Minimal Example
CheckCreated mtrMin = checkHost.mtr("1.1.1.1");

// Max Example
MtrOptions options = MtrOptions.builder()
        .repeatchecks(15)
        .forceIPversion(4)
        .forceProtocol("TCP")
        .region(List.of("DE"))
        .build();
CheckCreated mtrMax = checkHost.mtr("1.1.1.1", options);

---

Fetching Results

Report

Fetches the compiled report and real-time statuses from a previously initiated monitoring check.

// The check UUID is returned by any monitoring method above
String taskUuid = "c0b4b0e3-aed7-4ae2-9f53-7bac879697cb";

// Fetch the result payload (JsonNode)
JsonNode report = checkHost.report(taskUuid);
System.out.println(report.toPrettyString());

License

MIT License