freegeoip.net: IP Geolocation Web Service

Believe it or not, I offer the system behind freegeoip.net for free as well. Full source code and installation instructions are available within the tarball package.

The system is written in Python, based on the powerful Twisted Matrix framework. It has been tested under Linux and Mac OS X, and the online version is reverse proxied by Nginx.

In order to avoid licensing problems, I decided to not redistribute the database. However, the source code package ships with a tool that easily convert the CSV database from ipinfodb.com into an sqlite3, which is used by this system.

By downloading the source code, you can make use of Geolocation directly in your application or website, without the need to query our web service. If you do so, and if you really like it, please consider making a donation of U$5 by clicking the button below.

Download: geoip-latest.tar.gz

It's pretty simple to use our service. Basically, you choose between one of the supported data formats, then you add an IP address to the end of the URL. However, the IP address part is optional, and you can leave it empty in order to use the visitor's IP address, making it easy to use Geolocation at your web site.

You may write a program to make an HTTP GET request, or just let the visitor's browser do it. Results can be delivered as CSV, XML or JSON.

Here are some examples of how to query our database:

http://freegeoip.net/csv/
http://freegeoip.net/xml/161.148.24.13
http://freegeoip.net/json/67.23.47.116

Data formats

Although the data formats are different, they will provide you a common way to determine the success or failure of a query through the Status, by setting it to either True or False, accordingly.

All results are encoded as UTF-8.

CSV
XML
JSON

The result will always contain 12 columns, separated by commas.

Status,Ip,CountryCode,CountryName,RegionCode,RegionName, CityName,ZipCode,Latitude,Longitude,gmtOffset,dstOffset

Sample:

True,161.148.24.13,BR,Brazil,07,Distrito Federal, Brasília,,-15.7833,-47.9167,-2.0,-3.0

Sample:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>True</Status>
  <Ip>161.148.24.13</Ip>
  <CountryCode>BR</CountryCode>
  <CountryName>Brazil</CountryName>
  <RegionCode>07</RegionCode>
  <RegionName>Distrito Federal</RegionName>
  <City>Brasília</City>
  <ZipCode></ZipCode>
  <Latitude>-15.7833</Latitude>
  <Longitude>-47.9167</Longitude>
  <gmtOffset>-2.0</gmtOffset>
  <dstOffset>-3.0</dstOffset>
</Response>

Sample:

{
  "Status":true,
  "Ip":"161.148.24.13",
  "CountryCode":"BR",
  "CountryName":"Brazil",
  "RegionCode":"07",
  "RegionName":"Distrito Federal",
  "City":"Brasília",
  "ZipCode":"",
  "Latitude":-15.7833,
  "Longitude":-47.9167,
  "gmtOffset":-2.0,
  "dstOffset":-3.0
}

The callback parameter (callback=function) wraps the JSON output text in parentheses and a function name of your choosing.

Example: http://freegeoip.net/json/161.148.24.13?callback=ws_results

Results wrapped in callbacks look like this:

ws_results( ...json output... );

Data formats

freegeoip.net

What is it?

What about the data?