# Bulk Convert IP's
Source: https://docs.ip2geo.dev/api/bulk-convert-ips

POST /convert
This http method allows you to convert multiple IP addresses into their corresponding geolocation data.

<Warning>
  This method can convert up to 5000 IP addresses in a single request. If you need to convert more than 5000 IPs, consider splitting your requests into smaller batches to avoid exceeding this limit.
</Warning>


# Convert IP
Source: https://docs.ip2geo.dev/api/convert-ip

GET /convert
This http method allows you to convert a single IP address into its corresponding geolocation data.



# Get Conversion
Source: https://docs.ip2geo.dev/api/get-conversion

GET /conversions/get
This http method allows you to retrieve a single conversion by its unique identifier.



# Get Conversions
Source: https://docs.ip2geo.dev/api/get-conversions

POST /conversions/get
This http method allows you to retrieve multiple conversions by their unique identifiers.



# Introduction
Source: https://docs.ip2geo.dev/api/introduction



Our API is a alternative way to access our convertion services directly through HTTP requests. Its recommended to use the SDK unless your environment does not support npm packages.

We have simplified the API to make it easy to use with clear endpoints and consistent request/response structures.

## Authentication

All API requests require the <code>x-api-key</code> header. You can use either key type:

* **Secret key** (<code>i2g\_sk\_...</code>) — for server-side requests. Generated from the <a href="https://app.ip2geo.dev/keys">Secret Keys</a> section in your dashboard.
* **Public key** (<code>i2g\_pk\_...</code>) — for client-side (browser) requests. Generated from the <a href="https://app.ip2geo.dev/websites">Websites</a> section. Must include a valid <code>Origin</code> header matching the registered domain.

```bash theme={null}
# Server-side with secret key
curl --request GET \
    --url https://api.ip2geo.dev/convert?ip=8.8.8.8 \
    --header 'x-api-key: i2g_sk_your_secret_key'

# Client-side with public key (browser sends Origin automatically)
fetch('https://api.ip2geo.dev/convert?ip=8.8.8.8', {
    headers: { 'x-api-key': 'i2g_pk_your_public_key' }
})
```

## When to Use the API Instead of the SDK?

* **Environment Limitations:** If your environment doesn't support npm (e.g., a non-JavaScript runtime).
* **Direct Control:** If you need direct control over HTTP requests for specific use cases that the SDK doesn't cover.
* **Lightweight Needs:** If you want to avoid adding an additional dependency to your project.


# List Conversions
Source: https://docs.ip2geo.dev/api/list-conversions

GET /conversions/list
This http method allows you to list your conversions with pagination, filtering, and field selection.



# SELECT
Source: https://docs.ip2geo.dev/constants/select



The <code>SELECT</code> constants allow you to retrieve only the data fields you need instead of the full conversion, reducing payload size and improving performance. They work with both the SDK's and the API.

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

  const { data } = await GetConversion({
      conversionId: 'your-conversion-uuid',
      select: [
          SELECT.COUNTRY_NAME,
          SELECT.COUNTRY_CODE,
          SELECT.ASN_NAME
      ]
  })
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.get_conversion(
      conversion_id: 'your-conversion-uuid',
      select: [
          Ip2Geo.select[:COUNTRY_NAME],
          Ip2Geo.select[:COUNTRY_CODE],
          Ip2Geo.select[:ASN_NAME]
      ]
  )
  ```

  ```python Python theme={null}
  result = ip2geo.get_conversion(
      conversion_id='your-conversion-uuid',
      select=[
          ip2geo.SELECT['COUNTRY_NAME'],
          ip2geo.SELECT['COUNTRY_CODE'],
          ip2geo.SELECT['ASN_NAME']
      ]
  )
  ```

  ```php PHP theme={null}
  $result = Ip2Geo::getConversion(
      conversionId: 'your-conversion-uuid',
      select: [
          Ip2Geo::SELECT['COUNTRY_NAME'],
          Ip2Geo::SELECT['COUNTRY_CODE'],
          Ip2Geo::SELECT['ASN_NAME']
      ]
  );
  ```
</CodeGroup>

<Tabs>
  <Tab title="TypeScript">
    The full list of <code>SELECT</code> constant you can import and use when retrieving data:

    | Constant                               | Value                                        |
    | -------------------------------------- | -------------------------------------------- |
    | `SELECT.IP`                            | `'ip'`                                       |
    | `SELECT.TYPE`                          | `'type'`                                     |
    | `SELECT.IS_EU`                         | `'is_eu'`                                    |
    | `SELECT.CONTINENT_NAME`                | `'continent.name'`                           |
    | `SELECT.CONTINENT_CODE`                | `'continent.code'`                           |
    | `SELECT.CONTINENT_GEONAME_ID`          | `'continent.geoname_id'`                     |
    | `SELECT.COUNTRY_NAME`                  | `'continent.country.name'`                   |
    | `SELECT.COUNTRY_CODE`                  | `'continent.country.code'`                   |
    | `SELECT.COUNTRY_GEONAME_ID`            | `'continent.country.geoname_id'`             |
    | `SELECT.COUNTRY_PHONE_CODE`            | `'continent.country.phone_code'`             |
    | `SELECT.COUNTRY_CAPITAL`               | `'continent.country.capital'`                |
    | `SELECT.COUNTRY_TLD`                   | `'continent.country.tld'`                    |
    | `SELECT.SUBDIVISION_NAME`              | `'continent.country.subdivision.name'`       |
    | `SELECT.SUBDIVISION_CODE`              | `'continent.country.subdivision.code'`       |
    | `SELECT.CITY_NAME`                     | `'continent.country.city.name'`              |
    | `SELECT.CITY_GEONAME_ID`               | `'continent.country.city.geoname_id'`        |
    | `SELECT.CITY_LATITUDE`                 | `'continent.country.city.latitude'`          |
    | `SELECT.CITY_LONGITUDE`                | `'continent.country.city.longitude'`         |
    | `SELECT.CITY_ACCURACY_RADIUS`          | `'continent.country.city.accuracy_radius'`   |
    | `SELECT.CITY_METRO_CODE`               | `'continent.country.city.metro_code'`        |
    | `SELECT.CITY_POSTAL_CODE`              | `'continent.country.city.postal_code'`       |
    | `SELECT.TIMEZONE_NAME`                 | `'continent.country.city.timezone.name'`     |
    | `SELECT.TIMEZONE_TIME_NOW`             | `'continent.country.city.timezone.time_now'` |
    | `SELECT.FLAG_IMG`                      | `'continent.country.flag.img'`               |
    | `SELECT.FLAG_EMOJI`                    | `'continent.country.flag.emoji'`             |
    | `SELECT.FLAG_EMOJI_UNICODE`            | `'continent.country.flag.emoji_unicode'`     |
    | `SELECT.CURRENCY_NAME`                 | `'continent.country.currency.name'`          |
    | `SELECT.CURRENCY_CODE`                 | `'continent.country.currency.code'`          |
    | `SELECT.CURRENCY_SYMBOL`               | `'continent.country.currency.symbol'`        |
    | `SELECT.REGISTERED_COUNTRY_NAME`       | `'registered_country.name'`                  |
    | `SELECT.REGISTERED_COUNTRY_CODE`       | `'registered_country.code'`                  |
    | `SELECT.REGISTERED_COUNTRY_GEONAME_ID` | `'registered_country.geoname_id'`            |
    | `SELECT.ASN_NUMBER`                    | `'asn.number'`                               |
    | `SELECT.ASN_NAME`                      | `'asn.name'`                                 |
    | `SELECT.COMPLETION_TIME_MILISECONDS`   | `'completion_time.miliseconds'`              |
    | `SELECT.COMPLETION_TIME_SECONDS`       | `'completion_time.seconds'`                  |
  </Tab>

  <Tab title="Ruby">
    The full list of <code>Ip2Geo.select</code> constant you can use when retrieving data:

    | Constant                                        | Value                                        |
    | ----------------------------------------------- | -------------------------------------------- |
    | `Ip2Geo.select[:IP]`                            | `'ip'`                                       |
    | `Ip2Geo.select[:TYPE]`                          | `'type'`                                     |
    | `Ip2Geo.select[:IS_EU]`                         | `'is_eu'`                                    |
    | `Ip2Geo.select[:CONTINENT_NAME]`                | `'continent.name'`                           |
    | `Ip2Geo.select[:CONTINENT_CODE]`                | `'continent.code'`                           |
    | `Ip2Geo.select[:CONTINENT_GEONAME_ID]`          | `'continent.geoname_id'`                     |
    | `Ip2Geo.select[:COUNTRY_NAME]`                  | `'continent.country.name'`                   |
    | `Ip2Geo.select[:COUNTRY_CODE]`                  | `'continent.country.code'`                   |
    | `Ip2Geo.select[:COUNTRY_GEONAME_ID]`            | `'continent.country.geoname_id'`             |
    | `Ip2Geo.select[:COUNTRY_PHONE_CODE]`            | `'continent.country.phone_code'`             |
    | `Ip2Geo.select[:COUNTRY_CAPITAL]`               | `'continent.country.capital'`                |
    | `Ip2Geo.select[:COUNTRY_TLD]`                   | `'continent.country.tld'`                    |
    | `Ip2Geo.select[:SUBDIVISION_NAME]`              | `'continent.country.subdivision.name'`       |
    | `Ip2Geo.select[:SUBDIVISION_CODE]`              | `'continent.country.subdivision.code'`       |
    | `Ip2Geo.select[:CITY_NAME]`                     | `'continent.country.city.name'`              |
    | `Ip2Geo.select[:CITY_GEONAME_ID]`               | `'continent.country.city.geoname_id'`        |
    | `Ip2Geo.select[:CITY_LATITUDE]`                 | `'continent.country.city.latitude'`          |
    | `Ip2Geo.select[:CITY_LONGITUDE]`                | `'continent.country.city.longitude'`         |
    | `Ip2Geo.select[:CITY_ACCURACY_RADIUS]`          | `'continent.country.city.accuracy_radius'`   |
    | `Ip2Geo.select[:CITY_METRO_CODE]`               | `'continent.country.city.metro_code'`        |
    | `Ip2Geo.select[:CITY_POSTAL_CODE]`              | `'continent.country.city.postal_code'`       |
    | `Ip2Geo.select[:TIMEZONE_NAME]`                 | `'continent.country.city.timezone.name'`     |
    | `Ip2Geo.select[:TIMEZONE_TIME_NOW]`             | `'continent.country.city.timezone.time_now'` |
    | `Ip2Geo.select[:FLAG_IMG]`                      | `'continent.country.flag.img'`               |
    | `Ip2Geo.select[:FLAG_EMOJI]`                    | `'continent.country.flag.emoji'`             |
    | `Ip2Geo.select[:FLAG_EMOJI_UNICODE]`            | `'continent.country.flag.emoji_unicode'`     |
    | `Ip2Geo.select[:CURRENCY_NAME]`                 | `'continent.country.currency.name'`          |
    | `Ip2Geo.select[:CURRENCY_CODE]`                 | `'continent.country.currency.code'`          |
    | `Ip2Geo.select[:CURRENCY_SYMBOL]`               | `'continent.country.currency.symbol'`        |
    | `Ip2Geo.select[:REGISTERED_COUNTRY_NAME]`       | `'registered_country.name'`                  |
    | `Ip2Geo.select[:REGISTERED_COUNTRY_CODE]`       | `'registered_country.code'`                  |
    | `Ip2Geo.select[:REGISTERED_COUNTRY_GEONAME_ID]` | `'registered_country.geoname_id'`            |
    | `Ip2Geo.select[:ASN_NUMBER]`                    | `'asn.number'`                               |
    | `Ip2Geo.select[:ASN_NAME]`                      | `'asn.name'`                                 |
    | `Ip2Geo.select[:COMPLETION_TIME_MILISECONDS]`   | `'completion_time.miliseconds'`              |
    | `Ip2Geo.select[:COMPLETION_TIME_SECONDS]`       | `'completion_time.seconds'`                  |
  </Tab>

  <Tab title="Python">
    The full list of <code>ip2geo.SELECT</code> constant you can use when retrieving data:

    | Constant                                         | Value                                        |
    | ------------------------------------------------ | -------------------------------------------- |
    | `ip2geo.SELECT['IP']`                            | `'ip'`                                       |
    | `ip2geo.SELECT['TYPE']`                          | `'type'`                                     |
    | `ip2geo.SELECT['IS_EU']`                         | `'is_eu'`                                    |
    | `ip2geo.SELECT['CONTINENT_NAME']`                | `'continent.name'`                           |
    | `ip2geo.SELECT['CONTINENT_CODE']`                | `'continent.code'`                           |
    | `ip2geo.SELECT['CONTINENT_GEONAME_ID']`          | `'continent.geoname_id'`                     |
    | `ip2geo.SELECT['COUNTRY_NAME']`                  | `'continent.country.name'`                   |
    | `ip2geo.SELECT['COUNTRY_CODE']`                  | `'continent.country.code'`                   |
    | `ip2geo.SELECT['COUNTRY_GEONAME_ID']`            | `'continent.country.geoname_id'`             |
    | `ip2geo.SELECT['COUNTRY_PHONE_CODE']`            | `'continent.country.phone_code'`             |
    | `ip2geo.SELECT['COUNTRY_CAPITAL']`               | `'continent.country.capital'`                |
    | `ip2geo.SELECT['COUNTRY_TLD']`                   | `'continent.country.tld'`                    |
    | `ip2geo.SELECT['SUBDIVISION_NAME']`              | `'continent.country.subdivision.name'`       |
    | `ip2geo.SELECT['SUBDIVISION_CODE']`              | `'continent.country.subdivision.code'`       |
    | `ip2geo.SELECT['CITY_NAME']`                     | `'continent.country.city.name'`              |
    | `ip2geo.SELECT['CITY_GEONAME_ID']`               | `'continent.country.city.geoname_id'`        |
    | `ip2geo.SELECT['CITY_LATITUDE']`                 | `'continent.country.city.latitude'`          |
    | `ip2geo.SELECT['CITY_LONGITUDE']`                | `'continent.country.city.longitude'`         |
    | `ip2geo.SELECT['CITY_ACCURACY_RADIUS']`          | `'continent.country.city.accuracy_radius'`   |
    | `ip2geo.SELECT['CITY_METRO_CODE']`               | `'continent.country.city.metro_code'`        |
    | `ip2geo.SELECT['CITY_POSTAL_CODE']`              | `'continent.country.city.postal_code'`       |
    | `ip2geo.SELECT['TIMEZONE_NAME']`                 | `'continent.country.city.timezone.name'`     |
    | `ip2geo.SELECT['TIMEZONE_TIME_NOW']`             | `'continent.country.city.timezone.time_now'` |
    | `ip2geo.SELECT['FLAG_IMG']`                      | `'continent.country.flag.img'`               |
    | `ip2geo.SELECT['FLAG_EMOJI']`                    | `'continent.country.flag.emoji'`             |
    | `ip2geo.SELECT['FLAG_EMOJI_UNICODE']`            | `'continent.country.flag.emoji_unicode'`     |
    | `ip2geo.SELECT['CURRENCY_NAME']`                 | `'continent.country.currency.name'`          |
    | `ip2geo.SELECT['CURRENCY_CODE']`                 | `'continent.country.currency.code'`          |
    | `ip2geo.SELECT['CURRENCY_SYMBOL']`               | `'continent.country.currency.symbol'`        |
    | `ip2geo.SELECT['REGISTERED_COUNTRY_NAME']`       | `'registered_country.name'`                  |
    | `ip2geo.SELECT['REGISTERED_COUNTRY_CODE']`       | `'registered_country.code'`                  |
    | `ip2geo.SELECT['REGISTERED_COUNTRY_GEONAME_ID']` | `'registered_country.geoname_id'`            |
    | `ip2geo.SELECT['ASN_NUMBER']`                    | `'asn.number'`                               |
    | `ip2geo.SELECT['ASN_NAME']`                      | `'asn.name'`                                 |
    | `ip2geo.SELECT['COMPLETION_TIME_MILISECONDS']`   | `'completion_time.miliseconds'`              |
    | `ip2geo.SELECT['COMPLETION_TIME_SECONDS']`       | `'completion_time.seconds'`                  |
  </Tab>

  <Tab title="PHP">
    The full list of <code>Ip2Geo::SELECT</code> constant you can use when retrieving data:

    | Constant                                          | Value                                        |
    | ------------------------------------------------- | -------------------------------------------- |
    | `Ip2Geo::SELECT['IP']`                            | `'ip'`                                       |
    | `Ip2Geo::SELECT['TYPE']`                          | `'type'`                                     |
    | `Ip2Geo::SELECT['IS_EU']`                         | `'is_eu'`                                    |
    | `Ip2Geo::SELECT['CONTINENT_NAME']`                | `'continent.name'`                           |
    | `Ip2Geo::SELECT['CONTINENT_CODE']`                | `'continent.code'`                           |
    | `Ip2Geo::SELECT['CONTINENT_GEONAME_ID']`          | `'continent.geoname_id'`                     |
    | `Ip2Geo::SELECT['COUNTRY_NAME']`                  | `'continent.country.name'`                   |
    | `Ip2Geo::SELECT['COUNTRY_CODE']`                  | `'continent.country.code'`                   |
    | `Ip2Geo::SELECT['COUNTRY_GEONAME_ID']`            | `'continent.country.geoname_id'`             |
    | `Ip2Geo::SELECT['COUNTRY_PHONE_CODE']`            | `'continent.country.phone_code'`             |
    | `Ip2Geo::SELECT['COUNTRY_CAPITAL']`               | `'continent.country.capital'`                |
    | `Ip2Geo::SELECT['COUNTRY_TLD']`                   | `'continent.country.tld'`                    |
    | `Ip2Geo::SELECT['SUBDIVISION_NAME']`              | `'continent.country.subdivision.name'`       |
    | `Ip2Geo::SELECT['SUBDIVISION_CODE']`              | `'continent.country.subdivision.code'`       |
    | `Ip2Geo::SELECT['CITY_NAME']`                     | `'continent.country.city.name'`              |
    | `Ip2Geo::SELECT['CITY_GEONAME_ID']`               | `'continent.country.city.geoname_id'`        |
    | `Ip2Geo::SELECT['CITY_LATITUDE']`                 | `'continent.country.city.latitude'`          |
    | `Ip2Geo::SELECT['CITY_LONGITUDE']`                | `'continent.country.city.longitude'`         |
    | `Ip2Geo::SELECT['CITY_ACCURACY_RADIUS']`          | `'continent.country.city.accuracy_radius'`   |
    | `Ip2Geo::SELECT['CITY_METRO_CODE']`               | `'continent.country.city.metro_code'`        |
    | `Ip2Geo::SELECT['CITY_POSTAL_CODE']`              | `'continent.country.city.postal_code'`       |
    | `Ip2Geo::SELECT['TIMEZONE_NAME']`                 | `'continent.country.city.timezone.name'`     |
    | `Ip2Geo::SELECT['TIMEZONE_TIME_NOW']`             | `'continent.country.city.timezone.time_now'` |
    | `Ip2Geo::SELECT['FLAG_IMG']`                      | `'continent.country.flag.img'`               |
    | `Ip2Geo::SELECT['FLAG_EMOJI']`                    | `'continent.country.flag.emoji'`             |
    | `Ip2Geo::SELECT['FLAG_EMOJI_UNICODE']`            | `'continent.country.flag.emoji_unicode'`     |
    | `Ip2Geo::SELECT['CURRENCY_NAME']`                 | `'continent.country.currency.name'`          |
    | `Ip2Geo::SELECT['CURRENCY_CODE']`                 | `'continent.country.currency.code'`          |
    | `Ip2Geo::SELECT['CURRENCY_SYMBOL']`               | `'continent.country.currency.symbol'`        |
    | `Ip2Geo::SELECT['REGISTERED_COUNTRY_NAME']`       | `'registered_country.name'`                  |
    | `Ip2Geo::SELECT['REGISTERED_COUNTRY_CODE']`       | `'registered_country.code'`                  |
    | `Ip2Geo::SELECT['REGISTERED_COUNTRY_GEONAME_ID']` | `'registered_country.geoname_id'`            |
    | `Ip2Geo::SELECT['ASN_NUMBER']`                    | `'asn.number'`                               |
    | `Ip2Geo::SELECT['ASN_NAME']`                      | `'asn.name'`                                 |
    | `Ip2Geo::SELECT['COMPLETION_TIME_MILISECONDS']`   | `'completion_time.miliseconds'`              |
    | `Ip2Geo::SELECT['COMPLETION_TIME_SECONDS']`       | `'completion_time.seconds'`                  |
  </Tab>
</Tabs>

### Raw Values

In case you are using the API instead of our SDKs to call it, here are the raw constants you can use for reference.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const SELECT = {
      IP: 'ip',
      TYPE: 'type',
      IS_EU: 'is_eu',
      CONTINENT_NAME: 'continent.name',
      CONTINENT_CODE: 'continent.code',
      CONTINENT_GEONAME_ID: 'continent.geoname_id',
      COUNTRY_NAME: 'continent.country.name',
      COUNTRY_CODE: 'continent.country.code',
      COUNTRY_GEONAME_ID: 'continent.country.geoname_id',
      COUNTRY_PHONE_CODE: 'continent.country.phone_code',
      COUNTRY_CAPITAL: 'continent.country.capital',
      COUNTRY_TLD: 'continent.country.tld',
      SUBDIVISION_NAME: 'continent.country.subdivision.name',
      SUBDIVISION_CODE: 'continent.country.subdivision.code',
      CITY_NAME: 'continent.country.city.name',
      CITY_GEONAME_ID: 'continent.country.city.geoname_id',
      CITY_LATITUDE: 'continent.country.city.latitude',
      CITY_LONGITUDE: 'continent.country.city.longitude',
      CITY_ACCURACY_RADIUS: 'continent.country.city.accuracy_radius',
      CITY_METRO_CODE: 'continent.country.city.metro_code',
      CITY_POSTAL_CODE: 'continent.country.city.postal_code',
      TIMEZONE_NAME: 'continent.country.city.timezone.name',
      TIMEZONE_TIME_NOW: 'continent.country.city.timezone.time_now',
      FLAG_IMG: 'continent.country.flag.img',
      FLAG_EMOJI: 'continent.country.flag.emoji',
      FLAG_EMOJI_UNICODE: 'continent.country.flag.emoji_unicode',
      CURRENCY_NAME: 'continent.country.currency.name',
      CURRENCY_CODE: 'continent.country.currency.code',
      CURRENCY_SYMBOL: 'continent.country.currency.symbol',
      REGISTERED_COUNTRY_NAME: 'registered_country.name',
      REGISTERED_COUNTRY_CODE: 'registered_country.code',
      REGISTERED_COUNTRY_GEONAME_ID: 'registered_country.geoname_id',
      ASN_NUMBER: 'asn.number',
      ASN_NAME: 'asn.name',
      COMPLETION_TIME_MILISECONDS: 'completion_time.miliseconds',
      COMPLETION_TIME_SECONDS: 'completion_time.seconds'
  }
  ```

  ```ruby Ruby theme={null}
  SELECT = {
      IP: 'ip',
      TYPE: 'type',
      IS_EU: 'is_eu',
      CONTINENT_NAME: 'continent.name',
      CONTINENT_CODE: 'continent.code',
      CONTINENT_GEONAME_ID: 'continent.geoname_id',
      COUNTRY_NAME: 'continent.country.name',
      COUNTRY_CODE: 'continent.country.code',
      COUNTRY_GEONAME_ID: 'continent.country.geoname_id',
      COUNTRY_PHONE_CODE: 'continent.country.phone_code',
      COUNTRY_CAPITAL: 'continent.country.capital',
      COUNTRY_TLD: 'continent.country.tld',
      SUBDIVISION_NAME: 'continent.country.subdivision.name',
      SUBDIVISION_CODE: 'continent.country.subdivision.code',
      CITY_NAME: 'continent.country.city.name',
      CITY_GEONAME_ID: 'continent.country.city.geoname_id',
      CITY_LATITUDE: 'continent.country.city.latitude',
      CITY_LONGITUDE: 'continent.country.city.longitude',
      CITY_ACCURACY_RADIUS: 'continent.country.city.accuracy_radius',
      CITY_METRO_CODE: 'continent.country.city.metro_code',
      CITY_POSTAL_CODE: 'continent.country.city.postal_code',
      TIMEZONE_NAME: 'continent.country.city.timezone.name',
      TIMEZONE_TIME_NOW: 'continent.country.city.timezone.time_now',
      FLAG_IMG: 'continent.country.flag.img',
      FLAG_EMOJI: 'continent.country.flag.emoji',
      FLAG_EMOJI_UNICODE: 'continent.country.flag.emoji_unicode',
      CURRENCY_NAME: 'continent.country.currency.name',
      CURRENCY_CODE: 'continent.country.currency.code',
      CURRENCY_SYMBOL: 'continent.country.currency.symbol',
      REGISTERED_COUNTRY_NAME: 'registered_country.name',
      REGISTERED_COUNTRY_CODE: 'registered_country.code',
      REGISTERED_COUNTRY_GEONAME_ID: 'registered_country.geoname_id',
      ASN_NUMBER: 'asn.number',
      ASN_NAME: 'asn.name',
      COMPLETION_TIME_MILISECONDS: 'completion_time.miliseconds',
      COMPLETION_TIME_SECONDS: 'completion_time.seconds'
  }
  ```
</CodeGroup>


# External Apps
Source: https://docs.ip2geo.dev/external-apps

Explore Ip2Geo integrations, GPTs, and third-party connections.

<CardGroup>
  <Card title="Ip2Geo GPT" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/chat-bot-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=30a891cd520fc4daf3cf5166b0472151" href="https://chatgpt.com/g/g-69d0b690b57c8191a6c1c4b7289a2c36-ip2geo">
    IP to Geolocation via ChatGPT.
  </Card>
</CardGroup>

<Info>
  Have you built something with Ip2Geo? <a href="https://ip2geo.dev/contact">Let us know</a> and we'll feature it here.
</Info>


# Getting Started
Source: https://docs.ip2geo.dev/getting-started

A quick introduction to getting started with the Ip2Geo platform for converting IP's to geolocation data from a technical perspective.

## Introduction

To convert IPs to geolocation data, you will need to have an account and a project set up. By default, every account comes with a default project. Then, create a secret key for server-side usage or add a website for client-side usage — and you're ready to start converting.

## What's next?

See below for some helpful links to get you started.

<CardGroup>
  <Card title="Secret Keys" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/key-01-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=5f71533d3b12dec2a27e5dee7b9ecefd" href="/secret-keys">
    Learn about secret and public keys.
  </Card>

  <Card title="Websites" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/internet-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=8405d2c3791ad600be00f3943d81a640" href="/websites">
    Register domains for client-side usage.
  </Card>

  <Card title="Rate Limiting" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/clock-01-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=146f53c36c6b6bfa4d9a823770ffe21d" href="/rate-limiting">
    Read more about rate limiting.
  </Card>

  <Card title="SDK" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/package-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=bb5f9c8982865be89b26734b3bdc8ad1" href="/sdk">
    Getting started with our SDK.
  </Card>

  <Card title="API" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/server-stack-01-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=bf387f4592d3305685233db511ed75bc" href="/api">
    Getting started with our API.
  </Card>

  <Card title="Interfaces" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/text-font-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=13a9cf334bfe676ac419a42f5ca675a5" href="/interfaces">
    Learn about our data Interfaces.
  </Card>

  <Card title="Constants" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/code-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=b8bb873223a65b5801671645a95bdea8" href="/constants">
    Explore available constants.
  </Card>

  <Card title="External Apps" icon="https://mintcdn.com/ip2geo/VeORnUxG0phG2rcP/icons/puzzle-stroke-rounded.svg?fit=max&auto=format&n=VeORnUxG0phG2rcP&q=85&s=b4caa0c5913beb4b7aa7d0aae96ded19" href="/external-apps">
    GPTs, connectors, and integrations.
  </Card>
</CardGroup>


# Conversion Interface
Source: https://docs.ip2geo.dev/interfaces/conversion



When you retrieve conversions using the SDK or API, the conversion data is returned as a structured object.

```typescript theme={null}
interface Conversion {
    id: number
    uniqueId: string
    data: Ip
    status: string
    startedAt: string
    completedAt: string | null
    createdAt: string
}
```


# Ip Interface
Source: https://docs.ip2geo.dev/interfaces/ip



When you interact with our SDK or API, the geolocation data for an IP address is returned as a structured object containing details like country, region, city, coordinates, and similar information.

```typescript theme={null}
interface Ip {
    ip: string | null
    type: 'ipv4' | 'ipv6' | null
    is_eu: boolean | null
    continent: {
        name: string | null
        code: string | null
        geoname_id: number | null
        country: {
            name: string | null
            code: string | null
            geoname_id: number | null
            phone_code: string | null
            capital: string | null
            tld: string | null
            subdivision: {
                name: string | null
                code: string | null
            }
            city: {
                name: string | null
                geoname_id: number | null
                latitude: number | null
                longitude: number | null
                accuracy_radius: number | null
                metro_code: number | null
                postal_code: string | null
                timezone: {
                    name: string | null
                    time_now: string | null
                }
            }
            flag: {
                img: string | null
                emoji: string | null
                emoji_unicode: string | null
            }
            currency: {
                name: string | null
                code: string | null
                symbol: string | null
            }
        }
    }
    registered_country: {
        name: string | null
        code: string | null
        geoname_id: number | null
    }
    asn: {
        number: number | null
        name: string | null
    }
    completion_time: {
        miliseconds: number | null
        seconds: number | null
    }
}
```


# Rate Limiting
Source: https://docs.ip2geo.dev/rate-limiting



Currently, we don't enforce strict rate limits on our API or SDK usage. If you can handle the traffic, we won't stand in your way. Our infrastructure is built to process millions of requests efficiently, ensuring reliability, performance, and availability for all users worldwide.

<Info>
  While we don't impose hard rate limits, we continuously monitor usage patterns to maintain fair access. If we detect unusual activity that could affect service quality, we may reach out to discuss appropriate usage.
</Info>


# Bulk Convert IP's
Source: https://docs.ip2geo.dev/sdk/bulk-convert-ips



This function allows you to convert multiple IP addresses in a single request, making it efficient for batch processing. You can provide an array of IP addresses, and the function will return their corresponding geolocation data.

<Warning>
  You should authenticate/initialize <a href="/sdk/init">Ip2Geo</a> before using this method.
</Warning>

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

  const ipAddresses = [
      '8.8.8.8',
      '8.8.4.4',
      '1.1.1.1',
      '9.9.9.9',
      '4.4.4.4',
      '3.3.3.3'
  ]

  const { data, success, message } = await ConvertIPs({
      ips: ipAddresses
  })
  ```

  ```ruby Ruby theme={null}
  ip_addresses = [
      '8.8.8.8',
      '8.8.4.4',
      '1.1.1.1',
      '9.9.9.9',
      '4.4.4.4',
      '3.3.3.3'
  ]

  result = Ip2Geo.convert_ips(ips: ip_addresses)

  # {
  #     'success' => true,
  #     'code' => 200,
  #     'message' => 'Success',
  #     'data' => [
  #         { 'ip' => '8.8.8.8', 'conversion' => { ... } },
  #         { 'ip' => '8.8.4.4', 'conversion' => { ... } },
  #         ...
  #     ],
  #     '_req' => { 'reqId' => '...', 'resTime' => 123 }
  # }
  ```

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

  ip_addresses = [
      '8.8.8.8',
      '8.8.4.4',
      '1.1.1.1',
      '9.9.9.9',
      '4.4.4.4',
      '3.3.3.3',
  ]

  result = ip2geo.convert_ips(ips=ip_addresses)

  # {
  #     'success': True,
  #     'code': 200,
  #     'message': 'Success',
  #     'data': [
  #         { 'ip': '8.8.8.8', 'conversion': { ... } },
  #         { 'ip': '8.8.4.4', 'conversion': { ... } },
  #         ...
  #     ],
  #     '_req': { 'reqId': '...', 'resTime': 123 }
  # }
  ```

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

  use Ip2Geo\Ip2Geo;

  $ipAddresses = [
      '8.8.8.8',
      '8.8.4.4',
      '1.1.1.1',
      '9.9.9.9',
      '4.4.4.4',
      '3.3.3.3',
  ];

  $result = Ip2Geo::convertIps(ips: $ipAddresses);

  // [
  //     'success' => true,
  //     'code' => 200,
  //     'message' => 'Success',
  //     'data' => [
  //         ['ip' => '8.8.8.8', 'conversion' => [ ... ]],
  //         ['ip' => '8.8.4.4', 'conversion' => [ ... ]],
  //         ...
  //     ],
  //     '_req' => ['reqId' => '...', 'resTime' => 123],
  // ]
  ```
</CodeGroup>

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

    <ParamField type="Array<string>">
      An array of IPv4 or IPv6 addresses to convert. Maximum 5000 IPs per request.
    </ParamField>

    ### Response

    <ResponseField name="success" type="boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="number">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="Array<{ ip: string, conversion: Ip | null }>">
      An array of conversion results. Each item contains:

      * <code>ip</code>: The IP address that was converted.
      * <code>conversion</code>: The geolocation data for the IP (see <a href="/interfaces/ip">Ip Interface</a>). Returns <code>null</code> if the conversion failed for that IP <a href="/interfaces/conversion">Response Interface</a>.
    </ResponseField>

    <ResponseField name="_req" type="object">
      Request metadata containing:

      * <code>reqId</code>: Unique request identifier.
      * <code>resTime</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="Array<String>">
      An array of IPv4 or IPv6 addresses to convert. Maximum 5000 IPs per request.
    </ParamField>

    ### Response

    <ResponseField name="success" type="Boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="String">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="Integer">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="Array<Hash>">
      An array of conversion results. Each item contains:

      * <code>'ip'</code>: The IP address that was converted.
      * <code>'conversion'</code>: The geolocation data for the IP (see <a href="/interfaces/ip">Ip Interface</a>). Returns <code>nil</code> if the conversion failed for that IP <a href="/interfaces/conversion">Response Interface</a>.
    </ResponseField>

    <ResponseField name="_req" type="Hash">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="list[str]">
      A list of IPv4 or IPv6 addresses to convert. Maximum 5000 IPs per request.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="str">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="list[dict]">
      A list of conversion results. Each item contains:

      * <code>'ip'</code>: The IP address that was converted.
      * <code>'conversion'</code>: The geolocation data for the IP (see <a href="/interfaces/ip">Ip Interface</a>). Returns <code>None</code> if the conversion failed for that IP <a href="/interfaces/conversion">Response Interface</a>.
    </ResponseField>

    <ResponseField name="_req" type="dict">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="array">
      An array of IPv4 or IPv6 addresses to convert. Maximum 5000 IPs per request.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="array">
      An array of conversion results. Each item contains:

      * <code>'ip'</code>: The IP address that was converted.
      * <code>'conversion'</code>: The geolocation data for the IP (see <a href="/interfaces/ip">Ip Interface</a>). Returns <code>null</code> if the conversion failed for that IP <a href="/interfaces/conversion">Response Interface</a>.
    </ResponseField>

    <ResponseField name="_req" type="array">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>
</Tabs>


# Changelogs
Source: https://docs.ip2geo.dev/sdk/changelogs



This page documents version history and updates for our SDKs. We strongly recommend keeping your SDK up to date to benefit from the latest features, security patches, and performance improvements.

<Tabs>
  <Tab title="TypeScript">
    <Update label="18 Apr - 2026" description="v0.0.3">
      * Client-side support — use the SDK directly in the browser with public keys (<code>i2g\_pk\_...</code>) tied to your domains
      * Built-in smart caching layer for successful conversions with stale-while-revalidate (SWR) pattern, LRU eviction, and configurable <code>cache</code>, <code>cacheMaxSize</code>, <code>cacheTTL</code> options on <code>Init</code>
    </Update>

    <Update label="28 Jan - 2026" description="v0.0.2">
      * <code>IpValidation</code> helper function to validate IP addresses
      * <code>GetConversion</code> to retrieve a single conversion by ID
      * <code>GetConversions</code> to retrieve multiple conversions by IDs
      * <code>ListConversions</code> with pagination and IP search filtering
      * New SELECT constants: <code>geoname\_id</code>, <code>subdivision</code>, <code>accuracy\_radius</code>, <code>metro\_code</code>, <code>registered\_country</code>
      * General improvements and fixes from the previous version
    </Update>

    <Update label="05 Jan - 2026" description="v0.0.1">
      * Initial release and base functionality
      * <code>Init</code> function for SDK configuration
      * <code>ConvertIP</code> method for single IP address conversion
      * <code>ConvertIPs</code> method for bulk IP address conversion
      * Full TypeScript support with type definitions
      * Built-in client & server side safety and update notifications
    </Update>
  </Tab>

  <Tab title="Ruby">
    <Update label="19 Apr - 2026" description="v0.0.2">
      * Built-in smart caching layer for successful conversions with stale-while-revalidate (SWR) pattern, LRU eviction, and configurable <code>cache</code>, <code>cache\_max\_size</code>, <code>cache\_ttl</code> options on <code>init</code>
    </Update>

    <Update label="28 Jan - 2026" description="v0.0.1">
      * Initial public release
      * <code>init</code> method for SDK configuration
      * <code>convert\_ip</code> method for single IP address conversion
      * <code>convert\_ips</code> method for bulk IP address conversion
      * <code>get\_conversion</code> retrieve a single conversion by ID
      * <code>get\_conversions</code> method to retrieve multiple conversions by IDs
      * <code>list\_conversions</code> method with pagination and IP search filtering
      * <code>ip\_validation</code> helper function to validate IP addresses
      * <code>SELECT</code> constants for field selection including <code>geoname\_id</code>, <code>subdivision</code>, <code>accuracy\_radius</code>, <code>metro\_code</code>, <code>registered\_country</code>
      * Version update notifications
    </Update>
  </Tab>

  <Tab title="Python">
    <Update label="19 Apr - 2026" description="v0.0.1">
      * Initial public release
      * <code>init</code> function for SDK configuration
      * <code>convert\_ip</code> function for single IP address conversion
      * <code>convert\_ips</code> function for bulk IP address conversion
      * <code>get\_conversion</code> function to retrieve a single conversion by ID
      * <code>get\_conversions</code> function to retrieve multiple conversions by IDs
      * <code>list\_conversions</code> function with pagination and IP search filtering
      * <code>ip\_validation</code> helper function to validate IP addresses
      * <code>SELECT</code> constants for field selection including <code>geoname\_id</code>, <code>subdivision</code>, <code>accuracy\_radius</code>, <code>metro\_code</code>, <code>registered\_country</code>
      * Built-in smart caching layer for successful conversions with stale-while-revalidate (SWR) pattern, LRU eviction, and configurable <code>cache</code>, <code>cache\_max\_size</code>, <code>cache\_ttl</code> options on <code>init</code>
      * Version update notifications
    </Update>
  </Tab>

  <Tab title="PHP">
    <Update label="19 Apr - 2026" description="v0.0.1">
      * Initial public release
      * <code>init</code> method for SDK configuration
      * <code>convertIp</code> for single IP address conversion
      * <code>convertIps</code> for bulk IP address conversion
      * <code>getConversion</code> to retrieve a single conversion by ID
      * <code>getConversions</code> to retrieve multiple conversions by IDs
      * <code>listConversions</code> method with pagination and IP search filtering
      * <code>ipValidation</code> helper function to validate IP addresses
      * <code>SELECT</code> constants for field selection including <code>geoname\_id</code>, <code>subdivision</code>, <code>accuracy\_radius</code>, <code>metro\_code</code>, <code>registered\_country</code>
      * Built-in smart caching layer for successful conversions with stale-while-revalidate (SWR) pattern, LRU eviction, and configurable <code>cache</code>, <code>cache\_max\_size</code>, <code>cache\_ttl</code> options on <code>init</code>
      * Version update notifications
    </Update>
  </Tab>
</Tabs>


# Convert IP
Source: https://docs.ip2geo.dev/sdk/convert-ip



This function allows you to convert a single IP address into its corresponding geolocation data using, see an example below:

<Warning>
  You should authenticate/initialize <a href="/sdk/init">Ip2Geo</a> before using this method.
</Warning>

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

  const ipAddress = '8.8.8.8'

  const { data, success, message } = await ConvertIP({
      ip: ipAddress
  })
  ```

  ```ruby Ruby theme={null}
  converted = Ip2Geo.convert_ip(ip: '8.8.8.8')

  # {
  #     'success' => true,
  #     'code' => 200,
  #     'message' => 'Success',
  #     'data' => { ... },
  #     '_req' => { 'reqId' => '...', 'resTime' => 123 }
  # }
  ```

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

  result = ip2geo.convert_ip(ip='8.8.8.8')

  # {
  #     'success': True,
  #     'code': 200,
  #     'message': 'Success',
  #     'data': { ... },
  #     '_req': { 'reqId': '...', 'resTime': 123 }
  # }
  ```

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

  use Ip2Geo\Ip2Geo;

  $result = Ip2Geo::convertIp(ip: '8.8.8.8');

  // [
  //     'success' => true,
  //     'code' => 200,
  //     'message' => 'Success',
  //     'data' => [ ... ],
  //     '_req' => ['reqId' => '...', 'resTime' => 123],
  // ]
  ```
</CodeGroup>

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

    <ParamField type="string">
      The IPv4 or IPv6 address to convert.
    </ParamField>

    ### Response

    <ResponseField name="success" type="boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="number">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="Ip | null">
      The geolocation data for the IP address. See <a href="/interfaces/ip">Ip Interface</a> for details. Returns <code>null</code> if the conversion failed, read more about <a href="/interfaces/conversion">IP Response Interface</a>.
    </ResponseField>

    <ResponseField name="_req" type="object">
      Request metadata containing:

      * <code>reqId</code>: Unique request identifier.
      * <code>resTime</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="String">
      The IPv4 or IPv6 address to convert.
    </ParamField>

    ### Response

    <ResponseField name="success" type="Boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="String">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="Integer">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="Hash | nil">
      The geolocation data for the IP address. See <a href="/interfaces/ip">Ip Interface</a> for details. Returns <code>nil</code> if the conversion failed, read more about <a href="/interfaces/conversion">IP Response Interface</a>.
    </ResponseField>

    <ResponseField name="_req" type="Hash">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="str">
      The IPv4 or IPv6 address to convert.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="str">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="dict | None">
      The geolocation data for the IP address. See <a href="/interfaces/ip">Ip Interface</a> for details. Returns <code>None</code> if the conversion failed, read more about <a href="/interfaces/conversion">IP Response Interface</a>.
    </ResponseField>

    <ResponseField name="_req" type="dict">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="string">
      The IPv4 or IPv6 address to convert.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="array | null">
      The geolocation data for the IP address. See <a href="/interfaces/ip">Ip Interface</a> for details. Returns <code>null</code> if the conversion failed, read more about <a href="/interfaces/conversion">IP Response Interface</a>.
    </ResponseField>

    <ResponseField name="_req" type="array">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>
</Tabs>


# Get Conversion
Source: https://docs.ip2geo.dev/sdk/get-conversion



This function allows you to retrieve a single conversion by its unique identifier, see an example below:

<Warning>
  You should authenticate/initialize <a href="/sdk/init">Ip2Geo</a> before using this method.
</Warning>

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

  const conversionId = 'your-conversion-uuid'

  const { data, success, message } = await GetConversion({
      conversionId: conversionId
  })
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.get_conversion(conversion_id: 'your-conversion-uuid')

  # {
  #     'success' => true,
  #     'code' => 200,
  #     'message' => 'Success',
  #     'data' => { ... },
  #     '_req' => { 'reqId' => '...', 'resTime' => 123 }
  # }
  ```

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

  result = ip2geo.get_conversion(conversion_id='your-conversion-uuid')

  # {
  #     'success': True,
  #     'code': 200,
  #     'message': 'Success',
  #     'data': { ... },
  #     '_req': { 'reqId': '...', 'resTime': 123 }
  # }
  ```

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

  use Ip2Geo\Ip2Geo;

  $result = Ip2Geo::getConversion(conversionId: 'your-conversion-uuid');

  // [
  //     'success' => true,
  //     'code' => 200,
  //     'message' => 'Success',
  //     'data' => [ ... ],
  //     '_req' => ['reqId' => '...', 'resTime' => 123],
  // ]
  ```
</CodeGroup>

### With Select Fields

You can select specific fields from the conversion <code>data</code> object using the <code>select</code> parameter:

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

  const { data, success, message } = await GetConversion({
      conversionId: 'your-conversion-uuid',
      select: [
          SELECT.COUNTRY_NAME,
          SELECT.COUNTRY_CODE,
          SELECT.ASN_NAME
      ]
  })

  // Response data structure:
  // {
  //     data: {
  //         continent: {
  //             country: {
  //                 name: 'United States',
  //                 code: 'US'
  //             }
  //         },
  //         asn: {
  //             name: 'Cloudflare'
  //         }
  //     }
  // }
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.get_conversion(
      conversion_id: 'your-conversion-uuid',
      select: [
          Ip2Geo.select[:COUNTRY_NAME],
          Ip2Geo.select[:COUNTRY_CODE],
          Ip2Geo.select[:ASN_NAME]
      ]
  )

  # Response data structure:
  # {
  #     'data' => {
  #         'continent' => {
  #             'country' => {
  #                 'name' => 'United States',
  #                 'code' => 'US'
  #             }
  #         },
  #         'asn' => {
  #             'name' => 'Cloudflare'
  #         }
  #     }
  # }
  ```

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

  result = ip2geo.get_conversion(
      conversion_id='your-conversion-uuid',
      select=[
          ip2geo.SELECT['COUNTRY_NAME'],
          ip2geo.SELECT['COUNTRY_CODE'],
          ip2geo.SELECT['ASN_NAME'],
      ]
  )

  # Response data structure:
  # {
  #     'data': {
  #         'continent': {
  #             'country': {
  #                 'name': 'United States',
  #                 'code': 'US'
  #             }
  #         },
  #         'asn': {
  #             'name': 'Cloudflare'
  #         }
  #     }
  # }
  ```

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

  use Ip2Geo\Ip2Geo;

  $result = Ip2Geo::getConversion(
      conversionId: 'your-conversion-uuid',
      select: [
          Ip2Geo::SELECT['COUNTRY_NAME'],
          Ip2Geo::SELECT['COUNTRY_CODE'],
          Ip2Geo::SELECT['ASN_NAME'],
      ],
  );

  // Response data structure:
  // [
  //     'data' => [
  //         'continent' => [
  //             'country' => [
  //                 'name' => 'United States',
  //                 'code' => 'US',
  //             ],
  //         ],
  //         'asn' => [
  //             'name' => 'Cloudflare',
  //         ],
  //     ],
  // ]
  ```
</CodeGroup>

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

    <ParamField type="string">
      The unique identifier (UUID) of the conversion to retrieve.
    </ParamField>

    <ParamField type="Array<SelectField>">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    ### Response

    <ResponseField name="success" type="boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="number">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="Conversion | Partial<Conversion> | null">
      The conversion data. If <code>select</code> was specified, only the selected fields are returned. Returns <code>null</code> if the conversion was not found.
    </ResponseField>

    <ResponseField name="_req" type="object">
      Request metadata containing:

      * <code>reqId</code>: Unique request identifier.
      * <code>resTime</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="String">
      The unique identifier (UUID) of the conversion to retrieve.
    </ParamField>

    <ParamField type="Array<String>">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    ### Response

    <ResponseField name="success" type="Boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="String">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="Integer">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="Hash | nil">
      The conversion data. If <code>select</code> was specified, only the selected data fields are returned. Returns <code>nil</code> if the conversion was not found.
    </ResponseField>

    <ResponseField name="_req" type="Hash">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="str">
      The unique identifier (UUID) of the conversion to retrieve.
    </ParamField>

    <ParamField type="list[str]">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="str">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="dict | None">
      The conversion data. If <code>select</code> was specified, only the selected data fields are returned. Returns <code>None</code> if the conversion was not found.
    </ResponseField>

    <ResponseField name="_req" type="dict">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="string">
      The unique identifier (UUID) of the conversion to retrieve.
    </ParamField>

    <ParamField type="array">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="array | null">
      The conversion data. If <code>select</code> was specified, only the selected data fields are returned. Returns <code>null</code> if the conversion was not found.
    </ResponseField>

    <ResponseField name="_req" type="array">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>
</Tabs>

For all available <code>SELECT</code> constants and their values, see the <a href="/constants/select">SELECT Constants</a> reference.


# Get Conversions
Source: https://docs.ip2geo.dev/sdk/get-conversions



This function allows you to retrieve multiple conversions by their unique identifiers in a single request, see an example below:

<Warning>
  You should authenticate/initialize <a href="/sdk/init">Ip2Geo</a> before using this method.
</Warning>

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

  const conversionIds = ['uuid-1', 'uuid-2', 'uuid-3']

  const { data, success, message } = await GetConversions({
      conversionIds: conversionIds
  })

  // Access the conversions
  console.log(data.conversions) // Array of conversion objects
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.get_conversions(
      conversion_ids: ['uuid-1', 'uuid-2', 'uuid-3']
  )

  # Access the conversions
  puts result['data']['conversions'] # Array of conversion objects

  # {
  #     'success' => true,
  #     'code' => 200,
  #     'message' => 'Success',
  #     'data' => { 'conversions' => [...] },
  #     '_req' => { 'reqId' => '...', 'resTime' => 123 }
  # }
  ```

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

  result = ip2geo.get_conversions(
      conversion_ids=['uuid-1', 'uuid-2', 'uuid-3']
  )

  # Access the conversions
  print(result['data']['conversions'])  # List of conversion objects

  # {
  #     'success': True,
  #     'code': 200,
  #     'message': 'Success',
  #     'data': { 'conversions': [...] },
  #     '_req': { 'reqId': '...', 'resTime': 123 }
  # }
  ```

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

  use Ip2Geo\Ip2Geo;

  $result = Ip2Geo::getConversions(
      conversionIds: ['uuid-1', 'uuid-2', 'uuid-3'],
  );

  // Access the conversions
  print_r($result['data']['conversions']); // Array of conversion arrays

  // [
  //     'success' => true,
  //     'code' => 200,
  //     'message' => 'Success',
  //     'data' => ['conversions' => [...]],
  //     '_req' => ['reqId' => '...', 'resTime' => 123],
  // ]
  ```
</CodeGroup>

### With Select Fields

You can select specific fields from the conversion <code>data</code> object using the <code>select</code> parameter:

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

  const { data, success, message } = await GetConversions({
      conversionIds: ['uuid-1', 'uuid-2'],
      select: [
          SELECT.COUNTRY_NAME,
          SELECT.COUNTRY_CODE,
          SELECT.ASN_NAME
      ]
  })

  // Response data structure:
  // {
  //     conversions: [
  //         {
  //             data: {
  //                 continent: {
  //                     country: { name: 'United States', code: 'US' }
  //                 },
  //                 asn: { name: 'Cloudflare' }
  //             }
  //         },
  //         ...
  //     ]
  // }
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.get_conversions(
      conversion_ids: ['uuid-1', 'uuid-2'],
      select: [
          Ip2Geo.select[:COUNTRY_NAME],
          Ip2Geo.select[:COUNTRY_CODE],
          Ip2Geo.select[:ASN_NAME]
      ]
  )

  # Response data structure:
  # {
  #     'conversions' => [
  #         {
  #             'data' => {
  #                 'continent' => {
  #                     'country' => { 'name' => 'United States', 'code' => 'US' }
  #                 },
  #                 'asn' => { 'name' => 'Cloudflare' }
  #             }
  #         },
  #         ...
  #     ]
  # }
  ```

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

  result = ip2geo.get_conversions(
      conversion_ids=['uuid-1', 'uuid-2'],
      select=[
          ip2geo.SELECT['COUNTRY_NAME'],
          ip2geo.SELECT['COUNTRY_CODE'],
          ip2geo.SELECT['ASN_NAME'],
      ]
  )

  # Response data structure:
  # {
  #     'conversions': [
  #         {
  #             'data': {
  #                 'continent': {
  #                     'country': { 'name': 'United States', 'code': 'US' }
  #                 },
  #                 'asn': { 'name': 'Cloudflare' }
  #             }
  #         },
  #         ...
  #     ]
  # }
  ```

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

  use Ip2Geo\Ip2Geo;

  $result = Ip2Geo::getConversions(
      conversionIds: ['uuid-1', 'uuid-2'],
      select: [
          Ip2Geo::SELECT['COUNTRY_NAME'],
          Ip2Geo::SELECT['COUNTRY_CODE'],
          Ip2Geo::SELECT['ASN_NAME'],
      ],
  );

  // Response data structure:
  // [
  //     'conversions' => [
  //         [
  //             'data' => [
  //                 'continent' => [
  //                     'country' => ['name' => 'United States', 'code' => 'US'],
  //                 ],
  //                 'asn' => ['name' => 'Cloudflare'],
  //             ],
  //         ],
  //         ...
  //     ],
  // ]
  ```
</CodeGroup>

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

    <ParamField type="Array<string>">
      An array of unique identifiers (UUIDs) of the conversions to retrieve. Maximum 100 IDs per request.
    </ParamField>

    <ParamField type="Array<SelectField>">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    ### Response

    <ResponseField name="success" type="boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="number">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="object | null">
      The response data containing:

      * <code>conversions</code>: Array of conversion objects (or partial objects if <code>select</code> was used)
    </ResponseField>

    <ResponseField name="_req" type="object">
      Request metadata containing:

      * <code>reqId</code>: Unique request identifier.
      * <code>resTime</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="Array<String>">
      An array of unique identifiers (UUIDs) of the conversions to retrieve. Maximum 100 IDs per request.
    </ParamField>

    <ParamField type="Array<String>">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    ### Response

    <ResponseField name="success" type="Boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="String">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="Integer">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="Hash | nil">
      The response data containing:

      * <code>'conversions'</code>: Array of conversion hashes (or partial hashes if <code>select</code> was used)
    </ResponseField>

    <ResponseField name="_req" type="Hash">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="list[str]">
      A list of unique identifiers (UUIDs) of the conversions to retrieve. Maximum 100 IDs per request.
    </ParamField>

    <ParamField type="list[str]">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="str">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="dict | None">
      The response data containing:

      * <code>'conversions'</code>: List of conversion dicts (or partial dicts if <code>select</code> was used)
    </ResponseField>

    <ResponseField name="_req" type="dict">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="array">
      An array of unique identifiers (UUIDs) of the conversions to retrieve. Maximum 100 IDs per request.
    </ParamField>

    <ParamField type="array">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="array | null">
      The response data containing:

      * <code>'conversions'</code>: Array of conversion arrays (or partial arrays if <code>select</code> was used)
    </ResponseField>

    <ResponseField name="_req" type="array">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>
</Tabs>

For all available <code>SELECT</code> constants and their values, see the <a href="/constants/select">SELECT Constants</a> reference.

### Error Handling

If any of the provided conversion IDs are invalid (not valid UUIDs), the request will fail and return the list of invalid IDs:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { data, success, message } = await GetConversions({
      conversionIds: ['valid-uuid', 'invalid-id', 'another-bad-id']
  })

  // Response:
  // {
  //     success: false,
  //     message: 'conversions.invalid-conversion-ids',
  //     data: { invalidIds: ['invalid-id', 'another-bad-id'] }
  // }
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.get_conversions(
      conversion_ids: ['valid-uuid', 'invalid-id', 'another-bad-id']
  )

  # Response:
  # {
  #     'success' => false,
  #     'message' => 'conversions.invalid-conversion-ids',
  #     'data' => { 'invalidIds' => ['invalid-id', 'another-bad-id'] }
  # }
  ```

  ```python Python theme={null}
  result = ip2geo.get_conversions(
      conversion_ids=['valid-uuid', 'invalid-id', 'another-bad-id']
  )

  # Response:
  # {
  #     'success': False,
  #     'message': 'conversions.invalid-conversion-ids',
  #     'data': { 'invalidIds': ['invalid-id', 'another-bad-id'] }
  # }
  ```

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

  $result = Ip2Geo::getConversions(
      conversionIds: ['valid-uuid', 'invalid-id', 'another-bad-id'],
  );

  // Response:
  // [
  //     'success' => false,
  //     'message' => 'conversions.invalid-conversion-ids',
  //     'data' => ['invalidIds' => ['invalid-id', 'another-bad-id']],
  // ]
  ```
</CodeGroup>


# Init
Source: https://docs.ip2geo.dev/sdk/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 type="string">
      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 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 type="boolean">
      Whether to display version update messages. Defaults to <code>true</code>.
    </ParamField>

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

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

    <ParamField 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 type="String">
      The secret key used to authenticate with the Ip2Geo service.
    </ParamField>

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

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

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

    <ParamField 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 type="str">
      The secret key used to authenticate with the Ip2Geo service.
    </ParamField>

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

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

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

    <ParamField 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 type="string">
      The secret key used to authenticate with the Ip2Geo service.
    </ParamField>

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

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

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

    <ParamField 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>


# Introduction
Source: https://docs.ip2geo.dev/sdk/introduction



Our SDKs provide a type-safe way to use our conversion services directly through installable packages.
In essence, they're lightweight wrappers around our REST API — but with type safety, auto-completion, and an enhanced developer experience (DX).

## Available SDKs

We offer official SDKs for the following languages:

| Language              | Package                                                         |
| --------------------- | --------------------------------------------------------------- |
| TypeScript/JavaScript | [@ip2geo/sdk](https://npmjs.com/package/@ip2geo/sdk)            |
| Ruby                  | [ip2geo](https://rubygems.org/gems/ip2geo)                      |
| Python                | [ip2geo-sdk](https://pypi.org/project/ip2geo-sdk/)              |
| PHP                   | [ip2geo-dev/sdk](https://packagist.org/packages/ip2geo-dev/sdk) |

## Why Use the SDK Instead of the REST API?

* **Type Safety:** Get full TypeScript/Ruby/Python support to catch issues early and reduce runtime errors.
* **Simplified Integration:** Includes pre-built functions for requests, authentication, and response handling — no need to manually set up HTTP calls.
* **Faster Development:** Focus on your app's logic while the SDK handles the boilerplate.
* **Better Documentation:** Clear examples and typings make it easy to discover and use available methods.
* **Automatic Updates:** The SDKs stay in sync with the API, giving you access to the latest endpoints and improvements.

<Warning>
  The only reason not to use the SDK is if your environment doesn't support npm, RubyGems, or PyPI, or if your use case requires direct REST API calls.
</Warning>

## Installation

<Tabs>
  <Tab title="TypeScript">
    The TypeScript SDK works with all major JavaScript runtimes that support npm, including Node.js, Deno, Bun, and the browser (with public keys).

    <Tabs>
      <Tab title="npm">
        ```bash theme={null}
        npm install @ip2geo/sdk@latest
        ```
      </Tab>

      <Tab title="bun">
        ```bash theme={null}
        bun add @ip2geo/sdk@latest
        ```
      </Tab>

      <Tab title="deno">
        ```bash theme={null}
        deno install @ip2geo/sdk@latest
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={null}
        yarn add @ip2geo/sdk@latest
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm add @ip2geo/sdk@latest
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Ruby">
    The Ruby SDK works with Ruby 2.7 and above. Install via Bundler or directly with gem.

    <Tabs>
      <Tab title="Bundler">
        Add to your Gemfile:

        ```ruby theme={null}
        gem 'ip2geo'
        ```

        Then run:

        ```bash theme={null}
        bundle install
        ```
      </Tab>

      <Tab title="gem">
        ```bash theme={null}
        gem install ip2geo
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Python">
    The Python SDK works with Python 3.8 and above. Install via pip.

    <Tabs>
      <Tab title="pip">
        ```bash theme={null}
        pip install ip2geo-sdk
        ```
      </Tab>

      <Tab title="pip (requirements.txt)">
        Add to your requirements.txt:

        ```
        ip2geo-sdk
        ```

        Then run:

        ```bash theme={null}
        pip install -r requirements.txt
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="PHP">
    The PHP SDK works with PHP 8.0 and above. Install via Composer.

    <Tabs>
      <Tab title="composer">
        ```bash theme={null}
        composer require ip2geo-dev/sdk
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Ip Validation
Source: https://docs.ip2geo.dev/sdk/ip-validation



This function allows you to validate an IP address and check if it is valid and supported by our conversion services.

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

  const ipAddress = '8.8.8.8'

  const { ip4, ip6 } = await IpValidation(ipAddress)
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.ip_validation('8.8.8.8')

  # { ip4: true, ip6: false }
  ```

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

  result = ip2geo.ip_validation('8.8.8.8')

  # { 'ip4': True, 'ip6': False }
  ```

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

  use Ip2Geo\Ip2Geo;

  $result = Ip2Geo::ipValidation('8.8.8.8');

  // ['ip4' => true, 'ip6' => false]
  ```
</CodeGroup>

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

    <ParamField type="string">
      The IPv4 or IPv6 address to validate.
    </ParamField>

    ### Response

    <ResponseField name="IpValidationResult" type="object">
      An object containing validation results:

      * <code>ip4</code>: <code>boolean</code> - Whether the IP address is a valid IPv4 address.
      * <code>ip6</code>: <code>boolean</code> - Whether the IP address is a valid IPv6 address.
    </ResponseField>
  </Tab>

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

    <ParamField type="String">
      The IPv4 or IPv6 address to validate.
    </ParamField>

    ### Response

    <ResponseField name="Hash" type="object">
      A hash containing validation results:

      * <code>:ip4</code>: <code>Boolean</code> - Whether the IP address is a valid IPv4 address.
      * <code>:ip6</code>: <code>Boolean</code> - Whether the IP address is a valid IPv6 address.
    </ResponseField>
  </Tab>

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

    <ParamField type="str">
      The IPv4 or IPv6 address to validate.
    </ParamField>

    ### Response

    <ResponseField name="dict" type="object">
      A dict containing validation results:

      * <code>'ip4'</code>: <code>bool</code> - Whether the IP address is a valid IPv4 address.
      * <code>'ip6'</code>: <code>bool</code> - Whether the IP address is a valid IPv6 address.
    </ResponseField>
  </Tab>

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

    <ParamField type="string">
      The IPv4 or IPv6 address to validate.
    </ParamField>

    ### Response

    <ResponseField name="array" type="object">
      An array containing validation results:

      * <code>'ip4'</code>: <code>bool</code> - Whether the IP address is a valid IPv4 address.
      * <code>'ip6'</code>: <code>bool</code> - Whether the IP address is a valid IPv6 address.
    </ResponseField>
  </Tab>
</Tabs>


# List Conversions
Source: https://docs.ip2geo.dev/sdk/list-conversions



This function allows you to list your conversions with pagination, filtering, and field selection, see an example below:

<Warning>
  You should authenticate/initialize <a href="/sdk/init">Ip2Geo</a> before using this method.
</Warning>

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

  const { data, success, message } = await ListConversions()
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.list_conversions

  # {
  #     'success' => true,
  #     'code' => 200,
  #     'message' => 'Success',
  #     'data' => {
  #         'conversions' => [...],
  #         'hasMore' => true,
  #         'totalCount' => 100
  #     },
  #     '_req' => { 'reqId' => '...', 'resTime' => 123 }
  # }
  ```

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

  result = ip2geo.list_conversions()

  # {
  #     'success': True,
  #     'code': 200,
  #     'message': 'Success',
  #     'data': {
  #         'conversions': [...],
  #         'hasMore': True,
  #         'totalCount': 100
  #     },
  #     '_req': { 'reqId': '...', 'resTime': 123 }
  # }
  ```

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

  use Ip2Geo\Ip2Geo;

  $result = Ip2Geo::listConversions();

  // [
  //     'success' => true,
  //     'code' => 200,
  //     'message' => 'Success',
  //     'data' => [
  //         'conversions' => [...],
  //         'hasMore' => true,
  //         'totalCount' => 100,
  //     ],
  //     '_req' => ['reqId' => '...', 'resTime' => 123],
  // ]
  ```
</CodeGroup>

### With Pagination

You can paginate through conversions using <code>offset</code> and <code>limit</code>:

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

  const { data, success, message } = await ListConversions({
      offset: 0,
      limit: 20
  })

  // Access pagination info
  console.log(data.conversions)   // Array of conversions
  console.log(data.hasMore)       // true if there are more conversions
  console.log(data.totalCount)    // Total number of conversions
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.list_conversions(offset: 0, limit: 20)

  # Access pagination info
  puts result['data']['conversions']   # Array of conversions
  puts result['data']['hasMore']       # true if there are more conversions
  puts result['data']['totalCount']    # Total number of conversions
  ```

  ```python Python theme={null}
  result = ip2geo.list_conversions(offset=0, limit=20)

  # Access pagination info
  print(result['data']['conversions'])   # List of conversions
  print(result['data']['hasMore'])       # True if there are more conversions
  print(result['data']['totalCount'])    # Total number of conversions
  ```

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

  $result = Ip2Geo::listConversions(offset: 0, limit: 20);

  // Access pagination info
  print_r($result['data']['conversions']);   // Array of conversions
  var_dump($result['data']['hasMore']);      // true if there are more conversions
  echo $result['data']['totalCount'];        // Total number of conversions
  ```
</CodeGroup>

### With IP Search

Filter conversions by IP address:

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

  const { data, success, message } = await ListConversions({
      ipSearch: '8.8.8.8'
  })
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.list_conversions(ip_search: '8.8.8.8')
  ```

  ```python Python theme={null}
  result = ip2geo.list_conversions(ip_search='8.8.8.8')
  ```

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

  $result = Ip2Geo::listConversions(ipSearch: '8.8.8.8');
  ```
</CodeGroup>

### With Select Fields

Select specific fields from the conversion <code>data</code> object:

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

  const { data, success, message } = await ListConversions({
      select: [
          SELECT.COUNTRY_NAME,
          SELECT.COUNTRY_CODE,
          SELECT.ASN_NAME
      ]
  })
  ```

  ```ruby Ruby theme={null}
  result = Ip2Geo.list_conversions(
      select: [
          Ip2Geo.select[:COUNTRY_NAME],
          Ip2Geo.select[:COUNTRY_CODE],
          Ip2Geo.select[:ASN_NAME]
      ]
  )
  ```

  ```python Python theme={null}
  result = ip2geo.list_conversions(
      select=[
          ip2geo.SELECT['COUNTRY_NAME'],
          ip2geo.SELECT['COUNTRY_CODE'],
          ip2geo.SELECT['ASN_NAME'],
      ]
  )
  ```

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

  $result = Ip2Geo::listConversions(
      select: [
          Ip2Geo::SELECT['COUNTRY_NAME'],
          Ip2Geo::SELECT['COUNTRY_CODE'],
          Ip2Geo::SELECT['ASN_NAME'],
      ],
  );
  ```
</CodeGroup>

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

    <ParamField type="number">
      The number of conversions to skip for pagination.
    </ParamField>

    <ParamField type="number">
      The maximum number of conversions to return. Maximum value is 50.
    </ParamField>

    <ParamField type="Array<SelectField>">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    <ParamField type="string">
      Filter conversions by IP address.
    </ParamField>

    ### Response

    <ResponseField name="success" type="boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="number">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="object | null">
      The response data containing:

      * <code>conversions</code>: Array of conversion objects (or partial objects if <code>select</code> was used)
      * <code>hasMore</code>: Boolean indicating if there are more conversions to fetch
      * <code>totalCount</code>: Total number of conversions matching the query
    </ResponseField>

    <ResponseField name="_req" type="object">
      Request metadata containing:

      * <code>reqId</code>: Unique request identifier.
      * <code>resTime</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="Integer">
      The number of conversions to skip for pagination.
    </ParamField>

    <ParamField type="Integer">
      The maximum number of conversions to return. Maximum value is 50.
    </ParamField>

    <ParamField type="Array<String>">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    <ParamField type="String">
      Filter conversions by IP address.
    </ParamField>

    ### Response

    <ResponseField name="success" type="Boolean">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="String">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="Integer">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="Hash | nil">
      The response data containing:

      * <code>'conversions'</code>: Array of conversion hashes (or partial hashes if <code>select</code> was used)
      * <code>'hasMore'</code>: Boolean indicating if there are more conversions to fetch
      * <code>'totalCount'</code>: Total number of conversions matching the query
    </ResponseField>

    <ResponseField name="_req" type="Hash">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="int">
      The number of conversions to skip for pagination.
    </ParamField>

    <ParamField type="int">
      The maximum number of conversions to return. Maximum value is 50.
    </ParamField>

    <ParamField type="list[str]">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    <ParamField type="str">
      Filter conversions by IP address.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="str">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="dict | None">
      The response data containing:

      * <code>'conversions'</code>: List of conversion dicts (or partial dicts if <code>select</code> was used)
      * <code>'hasMore'</code>: Boolean indicating if there are more conversions to fetch
      * <code>'totalCount'</code>: Total number of conversions matching the query
    </ResponseField>

    <ResponseField name="_req" type="dict">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>

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

    <ParamField type="int">
      The number of conversions to skip for pagination.
    </ParamField>

    <ParamField type="int">
      The maximum number of conversions to return. Maximum value is 50.
    </ParamField>

    <ParamField type="array">
      Select specific data fields to return. If not specified, all data fields are returned. See <a href="/constants/select">SELECT Constants</a> for all available fields.
    </ParamField>

    <ParamField type="string">
      Filter conversions by IP address.
    </ParamField>

    ### Response

    <ResponseField name="success" type="bool">
      Whether the request was successful.
    </ResponseField>

    <ResponseField name="message" type="string">
      Response message describing the result.
    </ResponseField>

    <ResponseField name="code" type="int">
      HTTP status code.
    </ResponseField>

    <ResponseField name="data" type="array | null">
      The response data containing:

      * <code>'conversions'</code>: Array of conversion arrays (or partial arrays if <code>select</code> was used)
      * <code>'hasMore'</code>: Boolean indicating if there are more conversions to fetch
      * <code>'totalCount'</code>: Total number of conversions matching the query
    </ResponseField>

    <ResponseField name="_req" type="array">
      Request metadata containing:

      * <code>'reqId'</code>: Unique request identifier.
      * <code>'resTime'</code>: Response time in milliseconds.
    </ResponseField>
  </Tab>
</Tabs>

For all available <code>SELECT</code> constants and their values, see the <a href="/constants/select">SELECT Constants</a> reference.


# Secret Keys
Source: https://docs.ip2geo.dev/secret-keys



Secret keys authenticate your project from server-side environments (Node.js, Python, Ruby, etc.). Each key you create in your dashboard is assigned to a project.

<Steps>
  <Step title="Have an Account">
    Create your Ip2Geo account or login to your existing account if you haven't already. You can do that by visiting the <a href="https://app.ip2geo.dev">Ip2Geo Dashboard</a>. Once logged in, select the project you want to generate a secret key for from your dashboard.
  </Step>

  <Step title="Create a Secret Key">
    Navigate to the <a href="https://app.ip2geo.dev/keys">Keys</a> section within your project. Click on "Create Key", provide a name for your key, and click "Generate Key" to create your secret key.
  </Step>

  <Step title="Authenticate Your Project">
    Use the secret key to authenticate your project when using the SDK or making direct API calls from your server.
  </Step>
</Steps>

<Warning>
  Keep your secret keys secure and do not share them publicly. If you believe your key has been compromised, you can re-roll it from the dashboard to generate a new one.
</Warning>


# Websites
Source: https://docs.ip2geo.dev/websites



Websites let you use the Ip2Geo SDK and API directly from the browser. When you add a website, a public key is generated and tied to that domain — only requests originating from that domain will be accepted.

<Steps>
  <Step title="Have an Account">
    Create your Ip2Geo account or login to your existing account if you haven't already. You can do that by visiting the <a href="https://app.ip2geo.dev">Ip2Geo Dashboard</a>. Once logged in, select the project you want to add a website to from your dashboard.
  </Step>

  <Step title="Add a Website">
    Navigate to the <a href="https://app.ip2geo.dev/websites">Websites</a> section within your project. Click on "Add Website", enter your domain (e.g. <code>myapp.com</code>), and confirm. A public key (<code>i2g\_pk\_...</code>) will be generated automatically.
  </Step>

  <Step title="Authenticate Your Project">
    Use the public key to authenticate your project when using the SDK or making direct API calls from your frontend.
  </Step>
</Steps>

<Info>
  Public keys are safe to expose in client-side code. They only work from the domain they are registered to, so even if someone copies the key, it won't work from a different origin.
</Info>