IP Geolocation API

Login Sign Up
About API docs Pricing IP Geo Database

API docs

"Country" API type features

  • Credits cost per request: 1
  • "Country" output fields: ip, country, timezone, isp, as, domains

Making requests

GET https://geo.ipify.org/api/v2/country?apiKey=YOUR_API_KEY&ipAddress=8.8.8.8
It takes up to 2 minutes to activate your account after Sign Up.

Input parameters

apiKey Required. Get your personal API KEY on My subscriptions page.
ipAddress Optional. IPv4 or IPv6 to search location by.

If the parameter is not specified, then it defaults to client request's public IP address.
domain Optional. Domain name to search location by.

If the parameter is not specified, then 'ipAddress' will be used.
email Optional. Email address or domain name to search location by it's MX servers.

If the parameter is not specified, then 'ipAddress' will be used.
escapedUnicode

Optional.

1 - allows you to receive unescaped Unicode characters in the API response (default is to escape as \uXXXX).

Acceptable values: 0 | 1

Default: 0

Output format

{
    "ip": "8.8.8.8",
    "location": {
        "country": "US",
        "region": "California",
        "timezone": "-07:00",
    },
    "domains": [
        "0d2.net",
        "003725.com",
        "0f6.b0094c.cn",
        "007515.com",
        "0guhi.jocose.cn"
    ],
    "as": {
        "asn": 15169,
        "name": "Google LLC",
        "route": "8.8.8.0/24",
        "domain": "https://about.google/intl/en/",
        "type": "Content"
    },
    "isp": "Google LLC"
}
ip Requested (for search by 'ipAddress') or resolved (for search by 'domain' or 'email') IP address.
location.country Two letters country code from ISO 3166.
location.region Region
location.timezone Timezone in the format "+10:00"
as {} Autonomous System. It works for IPv4 only. The field is omitted if the record is not found.
as.asn Autonomous System Number
as.name Autonomous System Name
as.route Autonomous System Route
as.domain Autonomous System Website's URL
as.type Autonomous System type, one of the following: "Cable/DSL/ISP", "Content", "Educational/Research", "Enterprise", "Non-Profit", "Not Disclosed", "NSP", "Route Server". Empty when unknown.
isp Internet Service Provider
domains Array of domains associated with the IP. The field is omitted if the record is not found. This array is limited to 5 domains.

Free access

After Sign Up you automatically get a free subscription plan limited to 1,000 credits.

Account balance information

GET https://geo.ipify.org/service/account-balance?apiKey=YOUR_API_KEY
- You can always check your account balance on the My subscriptions page.

Usage limits and requests throttling

The maximum number of requests per second is 100. In case that the limit is exceeded, the server will respond with the 429 Too Many Requests status code and subsequent requests will be rejected until the next second.

Error codes

IP Geolocation API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, account balance is 0, etc.), and codes in the 5xx range indicate an error with IP Geolocation's servers.

400 Bad Request Some required fields are missing from the request's body or have invalid values.
401 Unauthorized The required 'apiKey' field value is missing or invalid.
403 Forbidden Access restricted. Check credits balance or enter the correct API key.
422 Unprocessable Entity Input correct request parameters or search term.
429 Too Many Requests Too Many Requests. Try your call again later.
5XX Internal server error, please contact our support team.
Try our IP Geolocation API free of charge
Get started
Have questions?

Or shoot us an email to