iqx-lookup-go

Go client for the IQX Lookup validation and geolocation API. Zero external dependencies.

Installation

go get github.com/Neivi-IT/iqx-lookup-go

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	iqx "github.com/Neivi-IT/iqx-lookup-go"
)

func main() {
	client := iqx.New("your-api-key")
	ctx := context.Background()

	// --- Example 1: Validate an email address ---
	email, err := client.ValidateEmail(ctx, "user@example.com")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Valid format: %v, MX: %v, Disposable: %v\n",
		email.ValidFormat, email.MxRecord, email.DisposableEmail)

	// --- Example 2: Geolocate an IP address ---
	geo, err := client.GeolocateIP(ctx, "8.8.8.8")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Country: %s, City: %s\n", geo.CountryName, geo.CityName)

	// --- Example 3: Check an SSL certificate ---
	ssl, err := client.CheckSsl(ctx, "example.com")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Valid: %v, Grade: %s, Days until expiry: %d\n",
		ssl.Valid, ssl.Grade, ssl.DaysUntilExpiry)
}

API Reference

All methods accept a context.Context as the first parameter and return a typed result pointer plus an error.

Method	Signature	Description
ValidateEmail	(ctx, address string)	Validate email format, MX/A records, disposable and role-based detection
ValidatePhone	(ctx, number, countryCode string)	Validate and parse a phone number (pass "" for countryCode to omit)
GeolocateIP	(ctx, ip string)	Geolocate an IP address (pass "" to geolocate the caller)
ValidateVat	(ctx, countryCode, number string)	Validate a European VAT number via the VIES service
ParseUserAgent	(ctx, ua string)	Parse a user-agent string into browser, OS, and device components
ValidateIban	(ctx, iban string)	Validate an IBAN and return bank name and BIC
ValidateBic	(ctx, bic string)	Validate a BIC/SWIFT code and return bank details
LookupDns	(ctx, domain, types string)	Look up DNS records (pass "" for types to query all)
CheckSsl	(ctx, domain string)	Check SSL/TLS certificate validity, grade, and expiry
AnalyzePassword	(ctx, password string)	Analyze password strength, crack time, and breach status
ValidateCreditCard	(ctx, cardNumber string)	Validate a credit card number (Luhn algorithm, card type, issuer)
LastRateLimitInfo	()	Returns *RateLimitInfo from the most recent API response (nil if none)

Configuration

client := iqx.New("your-api-key")

The API key is the only required parameter. For advanced use cases, functional options are available:

Option	Default	Description
WithBaseURL(url)	https://api.iqxlookup.neivi.es	Override the API base URL
WithTimeout(d)	10s	HTTP client timeout

The base URL is resolved with priority: WithBaseURL() option > LOOKUP_BASE_URL env var > default. Useful for local development:

export LOOKUP_BASE_URL=http://localhost:8081

Error Handling

All API errors are returned as typed values. Use errors.As to inspect specific error types:

import "errors"

result, err := client.ValidateEmail(ctx, "test@example.com")
if err != nil {
	var rateLimitErr *iqx.RateLimitError
	if errors.As(err, &rateLimitErr) {
		fmt.Printf("Rate limited. Retry after %d seconds\n", rateLimitErr.RetryAfter)
		return
	}

	var unauthorizedErr *iqx.UnauthorizedError
	if errors.As(err, &unauthorizedErr) {
		fmt.Println("Invalid API key")
		return
	}

	// Generic API error fallback
	var apiErr *iqx.IqxLookupError
	if errors.As(err, &apiErr) {
		fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Message)
		return
	}

	log.Fatal(err) // network or other error
}

Available error types: UnauthorizedError (401), ForbiddenError (403), NotFoundError (404), RateLimitError (429), ServiceUnavailableError (503). All embed *IqxLookupError.

Requirements

• Go 1.21+
• Zero external dependencies (stdlib only)

License

Apache-2.0