Get Conversions

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

Get conversions

Retrieves up to 100 of your project's conversions by their uniqueId. Ids that are unknown, another project's, or older than the current month and the twelve before it are left out of the answer rather than failing it, and the rows are not in the order asked, so match them by uniqueId. Secret keys only: a public key gets 403.

posthttps://api.ip2geo.dev/conversions/get
curl --request POST \
    --url 'https://api.ip2geo.dev/conversions/get' \
    --header 'x-api-key: i2g_sk_your_secret_key' \
    --header 'content-type: application/json' \
    --data '{"conversionIds":["01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9","01a121d4-6ad4-71c2-9e3f-4a5b6c7d8e9f"]}'

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

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.

Body

application/json, required

conversionIdsstring[]requiredformat: uuidmin items: 1max items: 100
The conversions' uniqueId values, each a UUIDv7.
Example request body
{
    "conversionIds": [
        "01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9",
        "01a121d4-6ad4-71c2-9e3f-4a5b6c7d8e9f"
    ]
}

Responses

200The conversions found, trimmed to select when it is given.
successbooleanrequired
Whether the request was successful.
messagestringrequired
Response message.
codeintegerrequired
HTTP status code.
dataobjectrequired
Show child attributes
conversionsobject[]required
The conversions found. Ids that were not found are left out.
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": "Conversions retrieved successfully.",
    "code": 200,
    "data": {
        "conversions": [
            {
                "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
    }
}
400The body is not JSON, or conversionIds is missing, empty, longer than 100 or holds an id that is not a UUIDv7 (listed in data.invalidIds).
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
    }
}
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 Started

Convert IPs into accurate location data in milliseconds.

Sign up today and get 1,000 free monthly conversions, and discover why developers trust us for fast, reliable, and affordable IP conversions.