Convert IP

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

Convert IP

Converts one IPv4 or IPv6 address into its geolocation data. Every address sent counts toward your quota, valid or not. A valid address the datasets hold no record of (private, reserved and unassigned addresses have none) answers 404.

gethttps://api.ip2geo.dev/convert

curl --request GET \
    --url 'https://api.ip2geo.dev/convert?ip=8.8.4.4' \
    --header 'x-api-key: i2g_sk_your_secret_key'

const response = await fetch('https://api.ip2geo.dev/convert?ip=8.8.4.4', {
    method: 'GET',
    headers: {
        'x-api-key': 'i2g_sk_your_secret_key'
    }
})

const { success, message, data } = await response.json()

Authorizations

x-api-keystringrequiredin: header

A secret key (i2g_sk_...) from your server, or a public key (i2g_pk_...) from a browser. A public key only works when the request's Origin header matches the domain it was created for. Browsers set that header themselves, but any other client can set it to anything, so treat a public key as public: it converts addresses on your project's quota and can never read data.

Query parameters

ipstringrequired

The IPv4 or IPv6 address to convert.

Responses

200The address's geolocation data.

successbooleanrequired

Whether the request was successful.

messagestringrequired

Response message.

codeintegerrequired

HTTP status code.

dataobjectrequired

The geolocation data of one address. Every value is null when the datasets do not know it.

Show child attributes

ipstring | null

The address that was converted.

typestring | null

The address family.

Available options:ipv4ipv6null

is_euboolean | null

true when the country is in the European Union (its 27 member states, and the Åland Islands and outermost regions such as Réunion that have a country code of their own), false for any other country, null when the country is unknown.

continentobject

Show child attributes

namestring | null

codestring | null

Two-letter continent code, lowercase: af, an, as, eu, na, oc or sa.

geoname_idinteger | null

GeoNames ID for the continent.

countryobject

Show child attributes

namestring | null

codestring | null

ISO 3166-1 alpha-2 country code, lowercase.

geoname_idinteger | null

GeoNames ID for the country.

phone_codestring | null

The country's international calling code, such as +1, +44 or +7.

capitalstring | null

tldstring | null

The country-code top-level domain.

subdivisionobject

State, province, or region information.

Show child attributes

namestring | null

Name of the state/province/region.

codestring | null

ISO 3166-2 code for the subdivision, as the datasets write it (e.g., 'CA' for California).

cityobject

Show child attributes

namestring | null

geoname_idinteger | null

GeoNames ID for the city.

latitudenumber | null

longitudenumber | null

accuracy_radiusinteger | null

Radius in kilometers around the coordinates where the IP is likely located.

metro_codeinteger | null

Metro area code (US only).

postal_codestring | null

Postal code, lowercase.

timezoneobject

Show child attributes

namestring | null

IANA time zone.

time_nowstring | null

The local time in that time zone when the address was converted, written like 10/10/2026, 1:38:38 AM.

flagobject

Show child attributes

imgstring | null

A 320 px wide PNG of the flag.

emojistring | null

emoji_unicodestring | null

currencyobject

Show child attributes

namestring | null

codestring | null

ISO 4217 currency code.

symbolstring | null

registered_countryobject

The country where the IP address is registered (may differ from location country for VPNs, proxies, etc.).

Show child attributes

namestring | null

Name of the registered country.

codestring | null

ISO 3166-1 alpha-2 code of the registered country, lowercase.

geoname_idinteger | null

GeoNames ID for the registered country.

asnobject

Show child attributes

numberinteger | null

The autonomous system number.

namestring | null

The organization that announces the address.

completion_timeobject

Show child attributes

milisecondsnumber | null

How long the conversion took, in milliseconds.

secondsnumber | null

How long the conversion took, in seconds.

_reqobjectrequired

Show child attributes

reqIdstringrequired

Unique request identifier. Quote it when you contact support.

resTimenumberrequired

Response time in milliseconds.

Example response

{
    "success": true,
    "message": "IP address converted to geo location data successfully.",
    "code": 200,
    "data": {
        "ip": "8.8.4.4",
        "type": "ipv4",
        "is_eu": false,
        "continent": {
            "name": "North America",
            "code": "na",
            "geoname_id": 6255149,
            "country": {
                "name": "United States",
                "code": "us",
                "geoname_id": 6252001,
                "phone_code": "+1",
                "capital": "Washington D.C.",
                "tld": ".us",
                "subdivision": {
                    "name": "Massachusetts",
                    "code": "MA"
                },
                "city": {
                    "name": "Westfield",
                    "geoname_id": 4955190,
                    "latitude": 42.1293,
                    "longitude": -72.7522,
                    "accuracy_radius": 10,
                    "metro_code": 543,
                    "postal_code": "01085",
                    "timezone": {
                        "name": "America/New_York",
                        "time_now": "10/10/2026, 1:38:38 AM"
                    }
                },
                "flag": {
                    "img": "https://flagcdn.com/w320/us.png",
                    "emoji": "🇺🇸",
                    "emoji_unicode": "U+1F1FA U+1F1F8"
                },
                "currency": {
                    "name": "United States Dollar",
                    "code": "USD",
                    "symbol": "$"
                }
            }
        },
        "registered_country": {
            "name": "United States",
            "code": "us",
            "geoname_id": 6252001
        },
        "asn": {
            "number": 15169,
            "name": "Google Llc"
        },
        "completion_time": {
            "miliseconds": 3,
            "seconds": 0.003
        }
    },
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}

400The ip parameter is missing or is not an IPv4 or IPv6 address. The request still counts toward your quota.

successbooleanrequired

Always false for an error.

messagestringrequired

What went wrong, in a sentence you can show.

codeintegerrequired

HTTP status code.

dataobject | nullrequired

Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.

_reqobjectrequired

Show child attributes

reqIdstringrequired

Unique request identifier. Quote it when you contact support.

resTimenumberrequired

Response time in milliseconds.

Example response

{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}

401The x-api-key header is missing, malformed, unknown or disabled, or a public key was sent with an Origin that does not match its domain.

successbooleanrequired

Always false for an error.

messagestringrequired

What went wrong, in a sentence you can show.

codeintegerrequired

HTTP status code.

dataobject | nullrequired

Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.

_reqobjectrequired

Show child attributes

reqIdstringrequired

Unique request identifier. Quote it when you contact support.

resTimenumberrequired

Response time in milliseconds.

Example response

{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}

404The address is valid but has no geolocation record: private, reserved and unassigned addresses have none. It still counts toward your quota.

successbooleanrequired

Always false for an error.

messagestringrequired

What went wrong, in a sentence you can show.

codeintegerrequired

HTTP status code.

dataobject | nullrequired

Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.

_reqobjectrequired

Show child attributes

reqIdstringrequired

Unique request identifier. Quote it when you contact support.

resTimenumberrequired

Response time in milliseconds.

Example response

{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}

429The project has used its plan's conversions for this period. data carries currentUsage, planLimit and plan.

successbooleanrequired

Always false for an error.

messagestringrequired

What went wrong, in a sentence you can show.

codeintegerrequired

HTTP status code.

dataobject | nullrequired

Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.

_reqobjectrequired

Show child attributes

reqIdstringrequired

Unique request identifier. Quote it when you contact support.

resTimenumberrequired

Response time in milliseconds.

Example response

{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}

500Something failed on our side. Reads are safe to retry; a conversion may already have been counted.

successbooleanrequired

Always false for an error.

messagestringrequired

What went wrong, in a sentence you can show.

codeintegerrequired

HTTP status code.

dataobject | nullrequired

Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.

_reqobjectrequired

Show child attributes

reqIdstringrequired

Unique request identifier. Quote it when you contact support.

resTimenumberrequired

Response time in milliseconds.

Example response

{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}

503The API is under maintenance. Retry later: https://api.ip2geo.dev/maintenance/status says when it is over.

successbooleanrequired

Always false for an error.

messagestringrequired

What went wrong, in a sentence you can show.

codeintegerrequired

HTTP status code.

dataobject | nullrequired

Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.

_reqobjectrequired

Show child attributes

reqIdstringrequired

Unique request identifier. Quote it when you contact support.

resTimenumberrequired

Response time in milliseconds.

Example response

{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}

Convert IP

Authorizations

Query parameters

Responses

Convert IPs into accurate location data in milliseconds.