Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ip2geo.dev/llms.txt

Use this file to discover all available pages before exploring further.

Before you can start converting IP addresses, you need to authenticate your project with a secret key. The initialization function should always be called once at the start of your application — we’ll handle everything else automatically afterward.

​
Server-Side (Secret Key)

Use a secret key (i2g_sk_…) when running the SDK on your server. Secret keys are created from the Secret Keys section in your dashboard. Always store them in environment variables — never expose them in client-side code. 
import { Init } from '@ip2geo/sdk'

await Init(process.env.IP2GEO_API_KEY)
If you accidentally use a secret key (i2g_sk_…) in the browser, the SDK will show a Client Runtime Detected warning to let you know your key is exposed. Use a public key instead for client-side usage.

​
Client-Side (Public Key)

Use a public key (i2g_pk_…) when running the SDK in the browser. Public keys are generated from the Websites section in your dashboard — each one is tied to a specific domain. 
import { Init } from '@ip2geo/sdk'

await Init(process.env.IP2GEO_PUBLIC_KEY)
The SDK automatically detects the i2g_pk_ prefix and suppresses the client runtime warning — no need to set clientRuntimeMessage: false. Browsers automatically send the Origin header on cross-origin requests, which is how we verify the request comes from your allowed domain.
Public keys only work from the browser. Server-side environments (Node.js, Bun, Deno) do not send the Origin header by default, so public key requests from the server will be rejected. Use a secret key for server-side usage.
Public keys are safe to include in your frontend code. Even if someone copies your public key, it won’t work from a different domain.
Once initialized, the SDK works the same way regardless of which key type you used. All methods like ConvertIP, ConvertIPs, GetConversion, and others work identically on both client and server — the only difference is how you authenticate.

​
Options

You can customize the initialization with optional parameters: 
import { Init } from '@ip2geo/sdk'

await Init(process.env.IP2GEO_API_KEY, {
    clientRuntimeMessage: false,
    versionUpdateMessage: false
})

​
Caching

By default, the SDK caches successful conversions in memory. When you convert an IP that has been converted before, the SDK returns the cached result instantly while refreshing the data in the background. This means your subsequent requests for the same IP are significantly faster, while the data stays up to date. The API request still happens in the background on every call, so your usage and billing are not affected by caching in any way. You can customize or disable caching through the init options: 
import { Init } from '@ip2geo/sdk'

await Init(process.env.IP2GEO_API_KEY, {
    cacheMaxSize: 500,
    cacheTTL: 60000
})
To disable caching entirely, set cache to false. When disabled, every conversion will make a fresh API request.

​
Parameters

​
key
string
required
The secret key used to authenticate with the Ip2Geo service. Can be a secret key (i2g_sk_…) for server-side or a public key (i2g_pk_…) for client-side usage.
​
options.clientRuntimeMessage
boolean
Whether to display client runtime warning when using a secret key in the browser. Automatically disabled when using a public key. Defaults to true.
​
options.versionUpdateMessage
boolean
Whether to display version update messages. Defaults to true.
​
options.cache
boolean
Whether to enable caching for successful conversions. Defaults to true.
​
options.cacheMaxSize
number
Maximum number of cached entries. Must be between 10 and 50000. Defaults to 1000.
​
options.cacheTTL
number
Cache time-to-live in milliseconds. After this duration, cached entries expire and the next request will wait for a fresh response. Must be between 30000 (30 seconds) and 86400000 (1 day). Defaults to 300000 (5 minutes).