Get Conversion

This http method allows you to retrieve a single conversion by its unique identifier.

Get conversion

Retrieves one of your project's conversions by its uniqueId. Conversions are kept for the current month and the twelve before it, so an older id answers 404, as does an unknown id or another project's. Secret keys only: a public key gets 403.

gethttps://api.ip2geo.dev/conversions/get

curl --request GET \
    --url 'https://api.ip2geo.dev/conversions/get?conversionId=01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9' \
    --header 'x-api-key: i2g_sk_your_secret_key'

const response = await fetch('https://api.ip2geo.dev/conversions/get?conversionId=01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9', {
    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_...). Keep it on your server: it reads every conversion your project made. A public key gets 403 here.

Query parameters

conversionIdstringrequiredformat: uuid

The conversion's uniqueId, a UUIDv7.

selectstring[]

Return only these fields, comma-separated: select=data.continent.country.code,status. Repeating the parameter (select=data.asn.name&select=status) works too. Name a stored field as it is (id, uniqueId, data, status, startedAt, completedAt, createdAt) and a geolocation field by its path under data, such as data.continent.country.name (the data. prefix may be left out). uniqueId is always included, so every row can be matched to its conversion. The SELECT constants list every path.

Responses

200The conversion, trimmed to select when it is given.

successbooleanrequired

Whether the request was successful.

messagestringrequired

Response message.

codeintegerrequired

HTTP status code.

dataobjectrequired

A stored conversion. With select, only the requested fields and uniqueId.

Show child attributes

idinteger

Sequential conversion number.

uniqueIdstringformat: uuid

The conversion's id, a UUIDv7 that carries the time it was made. Always included.

dataobject

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.

statusstring

success, failed (a valid address without a geolocation record, or a lookup that failed) or invalid-ip-address.

Available options:successfailedinvalid-ip-address

startedAtstringformat: date-time

When the conversion started.

completedAtstring | nullformat: date-time

When the conversion completed.

createdAtstringformat: date-time

When the conversion was created.

_reqobjectrequired

Show child attributes

reqIdstringrequired

Unique request identifier. Quote it when you contact support.

resTimenumberrequired

Response time in milliseconds.

Example response

{
    "success": true,
    "message": "Conversion retrieved successfully.",
    "code": 200,
    "data": {
        "id": 4825913,
        "uniqueId": "01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9",
        "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
            }
        },
        "status": "success",
        "startedAt": "2026-10-10T05:38:38.112Z",
        "completedAt": "2026-10-10T05:38:38.112Z",
        "createdAt": "2026-10-10T05:38:38.112Z"
    },
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}

400conversionId is missing or is not a UUIDv7.

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

403A public key was sent. Reading conversions takes a secret key: public keys can only convert addresses.

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

404No conversion of your project has this id: it is unknown, another project's, or older than the current month and the twelve before it.

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

Get Conversion

Authorizations

Query parameters

Responses

Convert IPs into accurate location data in milliseconds.