The API returns the location of an IP address (country, region, city, zipcode, latitude, longitude) and the associated timezone in XML, JSON or plain text format. You can find the sample codes below with PHP, Javascript, Ruby, Python and ASP.

Sign Up for Free API key


There are two different types of API queries, which are country precision API and city precision API.

Country Precision

Perform IP lookup for country information
Sample Response
  "statusCode" : "OK",
  "statusMessage" : "",
  "ipAddress" : "",
  "countryCode" : "US",
  "countryName" : "United States of America"

City Precision

Perform IP lookup for city information
Sample Response
  "statusCode" : "OK",
  "statusMessage" : "",
  "ipAddress" : "",
  "countryCode" : "US",
  "countryName" : "United States of America",
  "regionName" : "California",
  "cityName" : "Mountain View",
  "zipCode" : "94043",
  "latitude" : "37.406",
  "longitude" : "-122.079",
  "timeZone" : "-07:00"

API Parameters

Parameter Required Default Value
key Yes API key provided with your free account.
ip No Client IP IPv4 or IPv6 address.
format No raw raw, xml, json
callback No Required when using JSON callback.

Note: Please use the appropriate API for your needs. You can help us keep the load low on our servers by making sure that:

  • If you only need the country name, avoid using the city precision API.
  • If you track your visitors, avoid querying our API for all your page views (you can store the geolocation in a cookie, see below for an example).

To remain the stabilities of free service, a rate limit of 2 queries per second applied to our API servers. Any IP querying the API faster than this rate will be temporarily blocked by our firewall. Your IP will be permanently banned if your keep hitting the API server by ignoring this rate limit.
If you are looking for web service with no rate limits and high accuracy, please visit IP2Location Web Service.


Below are the examples using all the features of the class in different languages. You can download the PHP class for our API here.

include 'class.IPInfoDB.php';

// Load the class
$ipinfodb = new IPInfoDB('YOUR_API_KEY');

$results = $ipinfodb->getCity($_SERVER['REMOTE_ADDR']);

// Getting the result
echo "Result
\n"; if (!empty($results) && is_array($results)) { foreach ($results as $key => $value) { echo $key . ' : ' . $value . "
\n"; } }
try (java.util.Scanner s = new java.util.Scanner(new"{YOUR_API_KEY}&ip={IP_ADDRESS}}").openStream(), "UTF-8").useDelimiter("\\A")) {
} catch ( e) {
Dim httpClient As New System.Net.Http.HttpClient
Dim response As String = Await httpClient.GetStringAsync("{YOUR_API_KEY}&ip={IP_ADDRESS}")

	public partial class ipinfodb : System.Web.UI.Page
        protected void Page_Load(object sender, EventArgs e)

	private void WebAPI()
		string myIP = HttpContext.Current.Request.UserHostAddress;
            string strQuery;
            string key = "";
            HttpWebRequest HttpWReq;
            HttpWebResponse HttpWResp;

            strQuery = "" + "ip=" + myIP + "&key=" + key + "&format=json";

            JavaScriptSerializer serializer = new JavaScriptSerializer();

            HttpWReq = (HttpWebRequest)WebRequest.Create(strQuery);
            HttpWReq.Method = "GET";
            HttpWResp = (HttpWebResponse)HttpWReq.GetResponse();

            System.IO.StreamReader reader = new System.IO.StreamReader(HttpWResp.GetResponseStream());
            string content = reader.ReadToEnd();

            dynamic item = serializer.Deserialize<object>(content);
            string city = item["cityName"];
            string countryc = item["countryCode"];
            string countryn = item["countryName"];
            string region = item["regionName"];
            string lat = item["latitude"];
            string longi = item["longitude"];
            string timez = item["timeZone"];
            string zip = item["zipCode"];

            //displaying the result
            Response.Write("Welcome Visitors from " + city + "<br />");
            Response.Write("Your IP address: " + myIP + "<br />");
            Response.Write("Country Code: " + countryc + "<br />");
            Response.Write("Country Name: " + countryn + "<br />");
            Response.Write("Region Name: " + region + "<br />");
            Response.Write("Latitude: " + lat + "<br />");
            Response.Write("Longitude: " + longi + "<br />");
            Response.Write("Time Zone: " + timez + "<br />");
            Response.Write("Zip Code: " + zip + "<br />");


from requests import get

response = get('{YOUR_API_KEY}&ip={IP_ADDRESS}').text
curl -s "{YOUR_API_KEY}&ip={IP_ADDRESS}"
require "net/http"

response = Net::HTTP.get(URI("{YOUR_API_KEY}&ip={IP_ADDRESS}"))
puts response

If you use our API to track your website visitors geolocation, we highly recommend that you put the geolocation data in a cookie (or in a database...). This way, you only query our servers for new visitors, not all page view. To achieve this, here is a quick sample in PHP and ASP how to set the country code in a cookie:

Frequently Asked Questions

Perform IP Geolocation Lookup

Looking for IP geolocation information? Try it for free now!

Register For Free Now

IP2Location IP Geolocation

IP2Location Free Widgets

IP2Location Programming Contest IP Geolocation API

IP Address Map