TypeScript SDK

The TypeScript/JavaScript SDK provides a simple and type-safe way to interact with our GeoIP API.

Installation

Install the SDK using npm or yarn:

npm install @geoipapi/sdk
# or
yarn add @geoipapi/sdk

Quick Start

import { GeoIp } from "geoipapi";

const client = new GeoIp();

// Get your current IP address
const ip = await client.geoIPEndpoints.getIp();
console.log("Your IP:", ip);

// Get detailed geolocation data
const geoData = await client.geoIPEndpoints.getIpData();
console.log("Location data:", geoData);

Configuration

The client accepts various configuration options:

const client = new GeoIp({
  serverURL: "https://api.geoipapi.com",
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1000,
      maxInterval: 30000,
      exponent: 1.5,
    },
  },
});

Response Types

The SDK includes full TypeScript definitions for all response types:

interface GeoIPResponse {
  ip: string;
  type: "IPv4" | "IPv6";
  country: {
    is_eu_member: boolean;
    currency_code: string;
    continent: string;
    name: string;
    country_code: string;
    state: string;
    city: string;
    zip: string;
    timezone: string;
  };
  location: {
    latitude: number;
    longitude: number;
  };
  asn: {
    number: number;
    name: string;
    network: string;
    type: string;
  };
}

Available Methods

getIp()

Get your current public IP address:

const ip = await client.geoIPEndpoints.getIp();
console.log("Current IP:", ip);

getIpData()

Get comprehensive geolocation data:

const result = await client.geoIPEndpoints.getIpData();
console.log("Location:", result.country.city, result.country.name);
console.log("Coordinates:", result.location.latitude, result.location.longitude);

Error Handling

Handle API errors gracefully:

import * as errors from "geoipapi/models/errors";

try {
  const result = await client.geoIPEndpoints.getIpData();
  console.log(result);
} catch (error) {
  if (error instanceof errors.HTTPValidationError) {
    console.log("Validation error:", error.data$.detail);
  } else {
    console.error("API error:", error);
  }
}

Tree-Shaking Support

Use standalone functions for optimal bundle size:

import { GeoIpCore } from "geoipapi/core.js";
import { geoIPEndpointsGetIP, geoIPEndpointsGetIPData } from "geoipapi/funcs";

const client = new GeoIpCore();

const ipResult = await geoIPEndpointsGetIP(client);
const dataResult = await geoIPEndpointsGetIPData(client);

if (ipResult.ok) {
  console.log("IP:", ipResult.value);
}