IP Geolocation API

The IP Geolocation API is a powerful tool that allows you to easily detect a user's location by their IP address. By utilizing this API, you can determine which language your visitor speaks and which currency to use in payment forms, among other valuable data.

To see the API in action, you can test it out using the API Playground. :

IP Geolocation Live Demo

Authentication and API key

If you don't have an API key, getting one is quick and easy. Go to our main page and press the "Sign Up" button to create an account. Once you're registered, you can get a Geoapify API key for free! For an overview of our plans, please take a look at our price page.

Getting started

  1. To get started, head over to the Geoapify MyProjects page and create a new project
  2. From there, go to the API Keys section, where you can generate one or multiple API keys for your project. You can also protect your API key by specifying allowed IP addresses, HTTP referrers, origins, and CORS.
  3. To generate the IP Geolocation API programming code sample, select the API key you want to use and choose "IP Geolocation API" from the list of APIs. You'll then be provided with an URL and programming code that you can use to make API calls.
  4. To test out your API call, simply press the "Try" button and get the result object.

API Reference

To use the IP Geolocation API, make an HTTP GET request to the API endpoint:

https://api.geoapify.com/v1/ipinfo?REQUEST_PARAMS

If you leave out the ip parameter, the API uses the IP address of whoever sends the request. Called from a browser, that's your visitor's IP address. Called from a backend, it's your server's IP address, so pass your visitor's IP address in the ip parameter instead.

The location is approximate, usually at city level. An IP address doesn't give a street address or identify a person.

Here are IP Geolocation URL examples (click on a URL to test the API):

Request parameters

Name Description
apiKey Geoapify API key
ip IP address to look up, IPv4 or IPv6. Optional parameter. When it isn't set, the API uses the IP address of whoever sends the request.

Response object

The API returns a JSON object. A field can be missing when there is no data for it.

Name Description
ip The IP address that was looked up
city.name City name
state.name State or region name
subdivisions Array of administrative subdivisions, each with translated names
postal.code Postal code
country.name Country name
country.iso_code Two-letter country code, for example US
country.name_native Country name in its own language
country.phone_code Country calling code without the +, for example 1
country.capital Capital city
country.currency Currency code, for example EUR. It can list several codes, separated by commas.
country.flag Country flag emoji
country.languages Array of languages, each with iso_code, name and name_native
country.is_in_european_union true for countries in the European Union; missing otherwise
country.geoname_id GeoNames ID of the country
continent.code Two-letter continent code, for example NA
continent.name Continent name
continent.geoname_id GeoNames ID of the continent
location.latitude, location.longitude Approximate coordinates
names On city, country, continent and each subdivision: translated names by language code, for example {"en": "Gaithersburg", "ru": "Гейтерсберг"}

Here is a response example for ip=129.6.15.28, a public NIST time server that NIST lists in Gaithersburg, Maryland. It's shortened: the names objects and some country fields are left out.

{
  "ip": "129.6.15.28",
  "city": { "name": "Gaithersburg" },
  "state": { "name": "Maryland" },
  "postal": { "code": "20899" },
  "country": {
    "name": "United States",
    "iso_code": "US",
    "phone_code": "1",
    "capital": "Washington D.C.",
    "flag": "🇺🇸",
    "languages": [
      {
        "iso_code": "en",
        "name": "English",
        "name_native": "English"
      }
    ]
  },
  "continent": { "code": "NA", "name": "North America" },
  "location": { "latitude": 39.1402, "longitude": -77.2185 }
}

Response HTTP status codes

Name Description
200 The request was successful.
400 The ip value isn't a valid IP address. The message field explains the problem.
401 The API key is missing or invalid.
429 Too many requests - rate limit exceeded.
500 Internal server error.

Pricing

At Geoapify, we use a universal unit called a "credit" to calculate the cost of our API calls.

With our IP Geolocation API, each call is priced at just 1 credit:

API name Cost in credits Example
IP Geolocation API 1 request = 1 credit 3 IP Geolocation requests cost 3 credits

Our pricing plans are designed to cater to the needs of any company, and our Free plan includes 3,000 credits per day. To see our pricing plans and find the best option for your business, visit our pricing page.

Learn more