Java SDK

es.neivi:iqx-lookup-java — Java 11+ client for the IQX Lookup API using java.net.http.HttpClient.

Installation

Maven:

<dependency>
    <groupId>es.neivi</groupId>
    <artifactId>iqx-lookup-java</artifactId>
    <version>0.2.1</version>
</dependency>

Gradle:

implementation 'es.neivi:iqx-lookup-java:0.2.1'

Quick Start

import es.neivi.iqx.lookup.IqxLookup;
import es.neivi.iqx.lookup.model.*;

var client = IqxLookup.builder()
    .apiKey("ALk-your-api-key")
    .buildClient();

// Validate an email
var email = client.validateEmail("user@example.com");
System.out.println("Valid format: " + email.isValidFormat());
System.out.println("Disposable: " + email.isDisposableEmail());

// Validate a phone number
var phone = client.validatePhone("+34912345678", "ES");
System.out.println("Valid: " + phone.isValid());
System.out.println("Carrier: " + phone.getCarrier());

// Geolocate an IP
var ip = client.geolocateIp("8.8.8.8");
System.out.println("Country: " + ip.getCountryName());

// Validate a VAT number
var vat = client.validateVat("ES", "B87387775");
System.out.println("Valid: " + vat.isValid());

// Parse a user-agent string
var ua = client.parseUserAgent("Mozilla/5.0...");
System.out.println("Browser: " + ua.getBrowserFamily());

Configuration

import java.time.Duration;

var client = IqxLookup.builder()
    .apiKey("ALk-your-api-key")               // required
    .baseUrl("https://api.iqxlookup.neivi.es")      // optional, default shown
    .timeout(Duration.ofSeconds(15))            // optional, default 10s
    .buildClient();

API Reference

Method	Returns	Description
validateEmail(String address)	EmailValidationResult	Email format, MX, disposable, free provider checks
validatePhone(String number, String countryCode)	PhoneValidationResult	Phone validation (countryCode nullable)
geolocateIp(String ip)	IpGeolocation	IP geolocation + ASN (ip nullable = caller's IP)
validateVat(String countryCode, String number)	VatValidationResult	EU VIES VAT validation
parseUserAgent(String ua)	UserAgentResult	UA parsing — browser, OS, device brand & model
validateIban(String iban)	IbanValidationResult	IBAN structure, checksum, bank info
validateBic(String bic)	BicValidationResult	BIC/SWIFT format, institution info
lookupDns(String domain, String types)	DnsLookupResult	DNS records, SPF/DKIM/DMARC security
checkSsl(String domain)	SslCertificateResult	SSL certificate, chain, grade
analyzePassword(String password)	PasswordStrengthResult	Strength score, crack time, breach check
validateCreditCard(String number)	CreditCardValidationResult	Luhn check, card network, BIN lookup
getLastRateLimitInfo()	RateLimitInfo	Rate limit from last response

Error Handling

import es.neivi.iqx.lookup.exception.*;

try {
    var result = client.validateEmail("user@example.com");
} catch (RateLimitException e) {
    System.out.println("Retry after: " + e.getRetryAfter() + "s");
} catch (UnauthorizedException e) {
    System.out.println("Check your API key");
} catch (IqxLookupException e) {
    System.out.println("Error " + e.getStatusCode() + ": " + e.getErrorMessage());
}

Spring Boot

For Spring Boot applications, use the Spring Boot Starter for automatic configuration.