Bulk Convert IP's

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

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.

Bulk convert IPs

Converts up to 5,000 IPv4 or IPv6 addresses in one request and answers one item per address, in the order sent. An invalid address, or a valid one without a geolocation record, comes back with conversion: null. Every address sent counts toward your quota, valid or not.

posthttps://api.ip2geo.dev/convert
curl --request POST \
    --url 'https://api.ip2geo.dev/convert' \
    --header 'x-api-key: i2g_sk_your_secret_key' \
    --header 'content-type: application/json' \
    --data '{"ips":["8.8.4.4","1.1.1.1"]}'

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.

Body

application/json, required

ipsstring[]requiredmax items: 5000
The IPv4 or IPv6 addresses to convert.
Example request body
{
    "ips": [
        "8.8.4.4",
        "1.1.1.1"
    ]
}

Responses

200One item per address, in the order sent.
successbooleanrequired
Whether the request was successful.
messagestringrequired
Response message.
codeintegerrequired
HTTP status code.
dataobject[]required
One item per address, in the order sent.
Show child attributes
ipstringrequired
The address as it was sent.
conversionobject | nullrequired
The address's geolocation data, or null when the address is invalid or has no geolocation record.
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 addresses converted to geo location data successfully.",
    "code": 200,
    "data": [
        {
            "ip": "8.8.4.4",
            "conversion": {
                "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 body is not JSON, ips is missing or not an array, or it holds more than 5,000 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
    }
}
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
    }
}
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.