Init
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)require 'ip2geo'
Ip2Geo.init(ENV['IP2GEO_API_KEY'])import os
import ip2geo
ip2geo.init(os.environ['IP2GEO_API_KEY'])<?php
use Ip2Geo\Ip2Geo;
Ip2Geo::init(getenv('IP2GEO_API_KEY'));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.
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
})require 'ip2geo'
Ip2Geo.init(ENV['IP2GEO_API_KEY'], version_update_message: false)import os
import ip2geo
ip2geo.init(os.environ['IP2GEO_API_KEY'], version_update_message=False)<?php
use Ip2Geo\Ip2Geo;
Ip2Geo::init(getenv('IP2GEO_API_KEY'), [
'version_update_message' => 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 is 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
})require 'ip2geo'
Ip2Geo.init(ENV['IP2GEO_API_KEY'],
cache_max_size: 500,
cache_ttl: 60
)import os
import ip2geo
ip2geo.init(os.environ['IP2GEO_API_KEY'],
cache_max_size=500,
cache_ttl=60
)<?php
use Ip2Geo\Ip2Geo;
Ip2Geo::init(getenv('IP2GEO_API_KEY'), [
'cache_max_size' => 500,
'cache_ttl' => 60,
]);Parameters
keystringrequiredThe 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.clientRuntimeMessagebooleanWhether to display client runtime warning when using a secret key in the browser. Automatically disabled when using a public key. Defaults to true.
options.versionUpdateMessagebooleanWhether to display version update messages. Defaults to true.
options.cachebooleanWhether to enable caching for successful conversions. Defaults to true.
options.cacheMaxSizenumberMaximum number of cached entries. Must be between 10 and 50000. Defaults to 1000.
options.cacheTTLnumberCache 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).
Parameters
keyStringrequiredThe secret key used to authenticate with the Ip2Geo service.
version_update_messageBooleanWhether to display version update messages. Defaults to true.
cacheBooleanWhether to enable caching for successful conversions. Defaults to true.
cache_max_sizeIntegerMaximum number of cached entries. Must be between 10 and 50000. Defaults to 1000.
cache_ttlIntegerCache time-to-live in seconds. After this duration, cached entries expire and the next request will wait for a fresh response. Must be between 30 (30 seconds) and 86400 (1 day). Defaults to 300 (5 minutes).
Parameters
keystrrequiredThe secret key used to authenticate with the Ip2Geo service.
version_update_messageboolWhether to display version update messages. Defaults to True.
cacheboolWhether to enable caching for successful conversions. Defaults to True.
cache_max_sizeintMaximum number of cached entries. Must be between 10 and 50000. Defaults to 1000.
cache_ttlintCache time-to-live in seconds. After this duration, cached entries expire and the next request will wait for a fresh response. Must be between 30 (30 seconds) and 86400 (1 day). Defaults to 300 (5 minutes).
Parameters
keystringrequiredThe secret key used to authenticate with the Ip2Geo service.
version_update_messageboolWhether to display version update messages. Defaults to true.
cacheboolWhether to enable caching for successful conversions. Defaults to true.
cache_max_sizeintMaximum number of cached entries. Must be between 10 and 50000. Defaults to 1000.
cache_ttlintCache time-to-live in seconds. After this duration, cached entries expire and the next request will wait for a fresh response. Must be between 30 (30 seconds) and 86400 (1 day). Defaults to 300 (5 minutes).