ipflare/dist/index.d.ts

IP Geolocation API, our API enables you to effortlessly obtain precise geolocation data for any IP address through a single endpoint. Benefit from ultra-fast responses—typically between 50-100ms—and enjoy reliable performance with 99.9% uptime.

export interface IPGeolocationResponse {
    ip: string;
    version?: string;
    city?: string;
    region?: string;
    region_code?: string;
    country_code?: string;
    country_code_iso3?: string;
    country_fifa_code?: string;
    country_fips_code?: string;
    country_name?: string;
    country_capital?: string;
    country_tld?: string;
    country_emoji?: string;
    continent_code?: string;
    in_eu: boolean;
    land_locked: boolean;
    postal?: string;
    latitude?: number;
    longitude?: number;
    timezone?: string;
    utc_offset?: string;
    country_calling_code?: string;
    currency?: string;
    currency_name?: string;
    languages?: string;
    country_area?: number;
    asn?: string;
    isp?: string;
}
export interface IPGeolocationError {
    error_message: string;
    ip: string;
    status: "error";
}
export interface IPGeolocationSuccess {
    ip: string;
    status: "success";
    data: IPGeolocationResponse;
}
export type BulkLookupResponse = (IPGeolocationSuccess | IPGeolocationError)[];
export type ErrorType = "INVALID_IP_ADDRESS" | "RESERVED_IP_ADDRESS" | "GEOLOCATION_NOT_FOUND" | "INTERNAL_SERVER_ERROR" | "INVALID_INPUT" | "UNAUTHORIZED" | "QUOTA_EXCEEDED" | "NO_API_KEY_PROVIDED" | "NETWORK_ERROR" | "VALIDATION_ERROR" | "UNKNOWN_ERROR";
export interface ResultError {
    type: ErrorType;
    message: string;
    details?: unknown;
}
export interface SuccessResult<T> {
    ok: true;
    data: T;
}
export interface ErrorResult {
    ok: false;
    error: ResultError;
}
export type Result<T> = SuccessResult<T> | ErrorResult;
export declare function isSuccess<T>(result: Result<T>): result is SuccessResult<T>;
export declare function isError<T>(result: Result<T>): result is ErrorResult;
export interface IPGeolocationOptions {
    apiKey: string;
    baseURL?: string;
    timeout?: number;
}
export interface LookupOptions {
    /**
     * Include additional fields in the response
     */
    include?: {
        asn?: boolean;
        isp?: boolean;
    };
}
export interface BulkLookupOptions extends LookupOptions {
    /**
     * Array of IP addresses to lookup (max 500)
     */
    ips: string[];
}
export declare function isIPGeolocationError(response: IPGeolocationSuccess | IPGeolocationError): response is IPGeolocationError;
export declare function isIPGeolocationSuccess(response: IPGeolocationSuccess | IPGeolocationError): response is IPGeolocationSuccess;
export declare class IPFlare {
    private client;
    private readonly apiKey;
    constructor(options: IPGeolocationOptions);
    /**
     * Validates if a string is a valid IP address (IPv4 or IPv6)
     * @param ip - IP address to validate
     * @returns true if valid IP address
     */
    private isValidIP;
    /**
     * Get geolocation data for a single IP address
     * @param ip - IP address to lookup
     * @param options - Additional options for the lookup
     * @returns Promise with Result containing geolocation data or error
     */
    lookup(ip: string, options?: LookupOptions): Promise<Result<IPGeolocationResponse>>;
    /**
     * Get geolocation data for multiple IP addresses
     * @param options - Options for bulk lookup including IPs array and additional fields
     * @returns Promise with Result containing array of geolocation data or error
     */
    bulkLookup(options: BulkLookupOptions): Promise<Result<BulkLookupResponse>>;
}