node-iplocate/dist/types/index.d.mts

Find geolocation data from IP addresses (e.g. city, country, timezone) using the IPLocate.io API

/** Complete response from the IPLocate API */
interface LookupResponse {
    /** The IP address that was looked up */
    ip: string;
    /** Country name (e.g., "United States") */
    country?: string;
    /** ISO 3166-1 alpha-2 country code (e.g., "US") */
    country_code?: string;
    /** Whether the country is a member of the European Union */
    is_eu: boolean;
    /** City name (e.g., "Mountain View") */
    city?: string;
    /** Continent name (e.g., "North America") */
    continent?: string;
    /** Latitude coordinate */
    latitude?: number;
    /** Longitude coordinate */
    longitude?: number;
    /** Timezone (e.g., "America/Los_Angeles") */
    time_zone?: string;
    /** Postal/ZIP code */
    postal_code?: string;
    /** State/region/subdivision (e.g., "California") */
    subdivision?: string;
    /** ISO 4217 currency code (e.g., "USD") */
    currency_code?: string;
    /** International calling code (e.g., "1") */
    calling_code?: string;
    /** Network CIDR range */
    network?: string;
    /** Autonomous System Number information */
    asn?: ASN;
    /** Privacy and threat detection information */
    privacy: Privacy;
    /** Company information associated with the IP */
    company?: Company;
    /** Hosting provider information */
    hosting?: Hosting;
    /** Abuse contact information */
    abuse?: Abuse;
}
type AsnType = 'isp' | 'hosting' | 'business' | 'education' | 'government' | 'inactive';
/** Autonomous System Number information */
interface ASN {
    /** ASN identifier (e.g., "AS15169") */
    asn: string;
    /** Network route */
    route: string;
    /** Network name */
    netname: string;
    /** ASN organization name */
    name: string;
    /** Country code where ASN is registered */
    country_code: string;
    /** Associated domain */
    domain: string;
    /** ASN type */
    type: AsnType;
    /** Regional Internet Registry */
    rir: string;
}
/** Privacy and threat detection information */
interface Privacy {
    /** Whether the IP is on a known spam/abuse blocklist */
    is_abuser: boolean;
    /** Whether the IP is anonymous */
    is_anonymous: boolean;
    /** Whether the IP is a bogon (unallocated/reserved) address */
    is_bogon: boolean;
    /** Whether the IP belongs to a hosting provider */
    is_hosting: boolean;
    /** Whether the IP is using iCloud Private Relay */
    is_icloud_relay: boolean;
    /** Whether the IP is using a proxy service */
    is_proxy: boolean;
    /** Whether the IP is using Tor */
    is_tor: boolean;
    /** Whether the IP is using a VPN service */
    is_vpn: boolean;
}
type CompanyType = 'isp' | 'hosting' | 'education' | 'government' | 'business' | 'inactive';
/** Company information associated with the IP */
interface Company {
    /** Company name */
    name: string;
    /** Company domain */
    domain: string;
    /** Country code where company network is located */
    country_code: string;
    /** Company type */
    type: CompanyType;
}
/** Hosting provider information */
interface Hosting {
    /** Hosting provider name */
    provider?: string;
    /** Provider domain */
    domain?: string;
    /** Provider network */
    network?: string;
    /** Hosting region */
    region?: string;
    /** Hosting service type */
    service?: string;
}
/** Abuse contact information */
interface Abuse {
    /** Abuse contact address */
    address?: string;
    /** Country code for abuse contact */
    country_code?: string;
    /** Abuse contact email */
    email?: string;
    /** Abuse contact name */
    name?: string;
    /** Associated network */
    network?: string;
    /** Abuse contact phone */
    phone?: string;
}
/** Client configuration options */
interface IPLocateOptions {
    /** Custom base URL for the API (for enterprise customers) */
    baseUrl?: string;
    /** Request timeout in milliseconds (default: 5000) */
    timeout?: number;
    /** Custom HTTP client options */
    httpClientOptions?: RequestInit;
}
/** Error response from the IPLocate API */
interface APIErrorResponse {
    /** Error message */
    error: string;
}

/**
 * IPLocate API client for geolocation and threat intelligence data
 */
declare class IPLocate {
    private readonly apiKey;
    private readonly baseUrl;
    private readonly timeout;
    private readonly httpClientOptions;
    /**
     * Create a new IPLocate client
     * @param apiKey Your IPLocate API key
     * @param options Configuration options
     */
    constructor(apiKey: string, options?: IPLocateOptions);
    /**
     * Look up geolocation and threat intelligence data for an IP address
     * @param ip The IP address to look up
     * @returns Promise resolving to lookup response
     */
    lookup(ip: string): Promise<LookupResponse>;
    /**
     * Look up geolocation and threat intelligence data for the client's current IP address
     * @returns Promise resolving to lookup response
     */
    lookupSelf(): Promise<LookupResponse>;
    /**
     * Make HTTP request to the IPLocate API
     * @param endpoint The API endpoint URL
     * @returns Promise resolving to lookup response
     */
    private makeRequest;
    /**
     * Handle error responses from the API
     * @param response The fetch response object
     */
    private handleErrorResponse;
}

/** Base class for all IPLocate API errors */
declare class IPLocateError extends Error {
    constructor(message: string);
}
/** Error thrown when an invalid IP address is provided */
declare class InvalidIPError extends IPLocateError {
    constructor(ip: string);
}
/** Error thrown when API authentication fails */
declare class AuthenticationError extends IPLocateError {
    constructor(message?: string);
}
/** Error thrown when IP address is not found */
declare class NotFoundError extends IPLocateError {
    constructor(message?: string);
}
/** Error thrown when rate limit is exceeded */
declare class RateLimitError extends IPLocateError {
    constructor(message?: string);
}
/** Error thrown for general API errors */
declare class APIError extends IPLocateError {
    readonly statusCode: number;
    constructor(message: string, statusCode: number);
}

export { APIError, type APIErrorResponse, type ASN, type Abuse, type AsnType, AuthenticationError, type Company, type CompanyType, type Hosting, IPLocate, IPLocateError, type IPLocateOptions, InvalidIPError, type LookupResponse, NotFoundError, type Privacy, RateLimitError, IPLocate as default };