> ## 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.

# 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** (<code>i2g\_sk\_...</code>) when running the SDK on your server. Secret keys are created from the <a href="https://app.ip2geo.dev/keys">Secret Keys</a> section in your dashboard. Always store them in environment variables — never expose them in client-side code.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Init } from '@ip2geo/sdk'

  await Init(process.env.IP2GEO_API_KEY)
  ```

  ```ruby Ruby theme={null}
  require 'ip2geo'

  Ip2Geo.init(ENV['IP2GEO_API_KEY'])
  ```

  ```python Python theme={null}
  import os
  import ip2geo

  ip2geo.init(os.environ['IP2GEO_API_KEY'])
  ```

  ```php PHP theme={null}
  <?php

  use Ip2Geo\Ip2Geo;

  Ip2Geo::init(getenv('IP2GEO_API_KEY'));
  ```
</CodeGroup>

<Warning>
  If you accidentally use a secret key (<code>i2g\_sk\_...</code>) 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.
</Warning>

## Client-Side (Public Key)

Use a **public key** (<code>i2g\_pk\_...</code>) when running the SDK in the browser. Public keys are generated from the <a href="https://app.ip2geo.dev/websites">Websites</a> section in your dashboard — each one is tied to a specific domain.

```typescript theme={null}
import { Init } from '@ip2geo/sdk'

await Init(process.env.IP2GEO_PUBLIC_KEY)
```

The SDK automatically detects the <code>i2g\_pk\_</code> prefix and suppresses the client runtime warning — no need to set <code>clientRuntimeMessage: false</code>.

Browsers automatically send the <code>Origin</code> header on cross-origin requests, which is how we verify the request comes from your allowed domain.

<Warning>
  Public keys only work from the browser. Server-side environments (Node.js, Bun, Deno) do not send the <code>Origin</code> header by default, so public key requests from the server will be rejected. Use a secret key for server-side usage.
</Warning>

<Info>
  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.
</Info>

<Tip>
  Once initialized, the SDK works the same way regardless of which key type you used. All methods like <code>ConvertIP</code>, <code>ConvertIPs</code>, <code>GetConversion</code>, and others work identically on both client and server — the only difference is how you authenticate.
</Tip>

## Options

You can customize the initialization with optional parameters:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Init } from '@ip2geo/sdk'

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

  ```ruby Ruby theme={null}
  require 'ip2geo'

  Ip2Geo.init(ENV['IP2GEO_API_KEY'], version_update_message: false)
  ```

  ```python Python theme={null}
  import os
  import ip2geo

  ip2geo.init(os.environ['IP2GEO_API_KEY'], version_update_message=False)
  ```

  ```php PHP theme={null}
  <?php

  use Ip2Geo\Ip2Geo;

  Ip2Geo::init(getenv('IP2GEO_API_KEY'), [
      'version_update_message' => false,
  ]);
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Init } from '@ip2geo/sdk'

  await Init(process.env.IP2GEO_API_KEY, {
      cacheMaxSize: 500,
      cacheTTL: 60000
  })
  ```

  ```ruby Ruby theme={null}
  require 'ip2geo'

  Ip2Geo.init(ENV['IP2GEO_API_KEY'],
      cache_max_size: 500,
      cache_ttl: 60
  )
  ```

  ```python Python theme={null}
  import os
  import ip2geo

  ip2geo.init(os.environ['IP2GEO_API_KEY'],
      cache_max_size=500,
      cache_ttl=60
  )
  ```

  ```php PHP theme={null}
  <?php

  use Ip2Geo\Ip2Geo;

  Ip2Geo::init(getenv('IP2GEO_API_KEY'), [
      'cache_max_size' => 500,
      'cache_ttl' => 60,
  ]);
  ```
</CodeGroup>

<Note>
  To disable caching entirely, set <code>cache</code> to <code>false</code>. When disabled, every conversion will make a fresh API request.
</Note>

<Tabs>
  <Tab title="TypeScript">
    ### Parameters

    <ParamField path="key" type="string" required>
      The secret key used to authenticate with the Ip2Geo service. Can be a secret key (<code>i2g\_sk\_...</code>) for server-side or a public key (<code>i2g\_pk\_...</code>) for client-side usage.
    </ParamField>

    <ParamField path="options.clientRuntimeMessage" type="boolean">
      Whether to display client runtime warning when using a secret key in the browser. Automatically disabled when using a public key. Defaults to <code>true</code>.
    </ParamField>

    <ParamField path="options.versionUpdateMessage" type="boolean">
      Whether to display version update messages. Defaults to <code>true</code>.
    </ParamField>

    <ParamField path="options.cache" type="boolean">
      Whether to enable caching for successful conversions. Defaults to <code>true</code>.
    </ParamField>

    <ParamField path="options.cacheMaxSize" type="number">
      Maximum number of cached entries. Must be between <code>10</code> and <code>50000</code>. Defaults to <code>1000</code>.
    </ParamField>

    <ParamField path="options.cacheTTL" type="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 <code>30000</code> (30 seconds) and <code>86400000</code> (1 day). Defaults to <code>300000</code> (5 minutes).
    </ParamField>
  </Tab>

  <Tab title="Ruby">
    ### Parameters

    <ParamField path="key" type="String" required>
      The secret key used to authenticate with the Ip2Geo service.
    </ParamField>

    <ParamField path="version_update_message" type="Boolean">
      Whether to display version update messages. Defaults to <code>true</code>.
    </ParamField>

    <ParamField path="cache" type="Boolean">
      Whether to enable caching for successful conversions. Defaults to <code>true</code>.
    </ParamField>

    <ParamField path="cache_max_size" type="Integer">
      Maximum number of cached entries. Must be between <code>10</code> and <code>50000</code>. Defaults to <code>1000</code>.
    </ParamField>

    <ParamField path="cache_ttl" type="Integer">
      Cache time-to-live in seconds. After this duration, cached entries expire and the next request will wait for a fresh response. Must be between <code>30</code> (30 seconds) and <code>86400</code> (1 day). Defaults to <code>300</code> (5 minutes).
    </ParamField>

    <Note>
      Ruby does not have <code>client\_runtime\_message</code> option since Ruby only runs server-side.
    </Note>
  </Tab>

  <Tab title="Python">
    ### Parameters

    <ParamField path="key" type="str" required>
      The secret key used to authenticate with the Ip2Geo service.
    </ParamField>

    <ParamField path="version_update_message" type="bool">
      Whether to display version update messages. Defaults to <code>True</code>.
    </ParamField>

    <ParamField path="cache" type="bool">
      Whether to enable caching for successful conversions. Defaults to <code>True</code>.
    </ParamField>

    <ParamField path="cache_max_size" type="int">
      Maximum number of cached entries. Must be between <code>10</code> and <code>50000</code>. Defaults to <code>1000</code>.
    </ParamField>

    <ParamField path="cache_ttl" type="int">
      Cache time-to-live in seconds. After this duration, cached entries expire and the next request will wait for a fresh response. Must be between <code>30</code> (30 seconds) and <code>86400</code> (1 day). Defaults to <code>300</code> (5 minutes).
    </ParamField>

    <Note>
      Python does not have <code>client\_runtime\_message</code> option since Python only runs server-side.
    </Note>
  </Tab>

  <Tab title="PHP">
    ### Parameters

    <ParamField path="key" type="string" required>
      The secret key used to authenticate with the Ip2Geo service.
    </ParamField>

    <ParamField path="version_update_message" type="bool">
      Whether to display version update messages. Defaults to <code>true</code>.
    </ParamField>

    <ParamField path="cache" type="bool">
      Whether to enable caching for successful conversions. Defaults to <code>true</code>.
    </ParamField>

    <ParamField path="cache_max_size" type="int">
      Maximum number of cached entries. Must be between <code>10</code> and <code>50000</code>. Defaults to <code>1000</code>.
    </ParamField>

    <ParamField path="cache_ttl" type="int">
      Cache time-to-live in seconds. After this duration, cached entries expire and the next request will wait for a fresh response. Must be between <code>30</code> (30 seconds) and <code>86400</code> (1 day). Defaults to <code>300</code> (5 minutes).
    </ParamField>

    <Note>
      PHP does not have <code>client\_runtime\_message</code> option since PHP only runs server-side.
    </Note>
  </Tab>
</Tabs>