IP.SB Free API

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 -A Mozilla)
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 (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)
  • organization (ASN + ISP name)
  • timezone (Time Zone)
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": "185.255.55.55",
    "country_code": "NL",
    "country": "Netherlands",
    "continent_code": "EU",
    "latitude": 52.3824,
    "longitude": 4.8995,
    "asn": "3214",
    "organization": "xTom GmbH",
    "timezone": "Europe/Amsterdam",
}

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 modified from Telize