This service offers a REST API allowing to get a visitor IP address and to query location information from any IP address. It outputs JSON-encoded IP geolocation data, and supports both Cross-origin resource sharing (CORS) and JSONP.

IP (Get IP address in plain text format):

Returns the visitor IP address (IPv4 or IPv6) in plain text, useful for shell scripts or to find the external Internet routable address.

Alternatively, for more granularity when querying from a dual-stack environments, the following endpoints are available:

Usage example (Shell script):
#!/bin/sh

ip=$(curl -s https://api.ip.sb/ip)
echo "My IP address is: $ip"
Output example:
IPv4 address:
192.0.2.2
IPv6 address:
2001:db8::2

JSON IP (Get IP address in JSON format):

Returns the visitor IP address (IPv4 or IPv6) in a JSON object.

Usage example:
<script type="application/javascript">
	function getip(json){
		document.write("My IP address is: ", json.ip);
	}
</script>

<script type="application/javascript" src="https://api.ip.sb/jsonip?callback=getip"></script>
Usage example (jQuery):
<script type="application/javascript">
	$(document).ready(function() {
	$.getJSON("https://api.ip.sb/jsonip?callback=?",
		function(json) {
			document.write("My IP address is: ", json.ip);
		}
	);
});
</script>

GeoIP (Get IP address location in JSON format):

Calling the API endpoint without any parameter will return location information for the visitor IP address:

Appending an IP address as parameter will return location information for this IP address:

Usage example:
<script type="application/javascript">
	function getgeoip(json){
		document.write("Geolocation information for IP address: ", json.ip);
		document.write("Country: ", json.country);
		document.write("Latitude: ", json.latitude);
		document.write("Longitude: ", json.longitude);
	}
</script>

<script type="application/javascript" src="https://api.ip.sb/geoip?callback=getgeoip"></script>
Usage example (jQuery):
<script type="application/javascript">
	$(document).ready(function() {
	$.getJSON("https://api.ip.sb/geoip?callback=?",
		function(json) {
			document.write("Geolocation information for IP address: ", json.ip);
			document.write("Country: ", json.country);
			document.write("Latitude: ", json.latitude);
			document.write("Longitude: ", json.longitude);
		}
	);
});
</script>

JSON Output Schema

The output is a JSON object containing the following elements:

Please note that the IP location database may not contain all information about a given IP. In this case, only the available data is displayed.

  • ip (Visitor IP address, or IP address specified as parameter)
  • country_code (Two-letter ISO 3166-1 alpha-2 country code)
  • country_code3 (Three-letter ISO 3166-1 alpha-3 country code)
  • country (Name of the country)
  • region_code (Two-letter ISO-3166-2 state / region code for US and Canada, FIPS 10-4 region codes otherwise)
  • region (Name of the region)
  • city (Name of the city)
  • postal_code (Postal code / Zip code)
  • continent_code (Two-letter continent code)
  • latitude (Latitude)
  • longitude (Longitude)
  • dma_code (DMA Code)
  • area_code (Area Code)
  • organization (ASN + ISP name)
  • timezone (Time Zone)
  • offset (UTC time offset)
Output example:

The following example use xTom server IP: city, region, and postal code information is not available and thus not present in the output JSON object:

{
	"ip": "45.43.43.43",
	"country_code": "US",
	"country_code3": "USA",
	"country": "United States",
	"continent_code": "NA",
	"latitude": 34.0729,
	"longitude": -118.2606,
	"dma_code": "0",
	"area_code": "0",
	"organization": "AS9312 xTom",
	"timezone": "America/Los_Angeles",
	"offset": "-7"
}

Errors

Client Errors

When incorrect user input is entered, the server returns an HTTP 400 Error (Bad Request), along with a JSON-encoded error message.

HTTP Error Code Message
400 401 Input string is not a valid IP address

Acknowledgment

This service includes GeoLite data created by MaxMind, available from maxmind.com.

Source Code from Telize