Geo-IP API

General Information

Geo-IP service has interfaces to get data in XML or JSON via both HTTP and HTTPS connections, which allows developers to integrate the service with other web sites.

In general, the integration can take place both on the client-side (browser) and server-side. It should be taken into account that client-side or server-side integration both have different limits, which are described below.

Limitations

We limit the number of requests per IP-address to our service in the 5,000 queries per day.

Thus, when it is used client-side integration (on the browser side), end-user of geo-IP-data will be visitors to the site and restrictions will be imposed on them. When the server integration is used, the end-user of data will be third-party server. Please, note, that it will significantly reduce data access for the end-visitors of this third-party web-site.

In other words, the client-side integration allows 5,000 queries for each visitor and server-side integration will give only 5,000 queries per day for all visitors.

However, what you may need is integration on a server-side. If it is, but you also need a greater number of requests per day - contact us.

IMPORTANT! Please, read The Best Ways to Get Banned for Geo-IP API Improper Usage.

Data Structure

Data supplied by the service are given in UTF-8 encoding. If successful, the query will return the service data, which contains of the following fields:

Example of XML-response

<?xml version="1.0" encoding="UTF-8"?>
<geoip>
    <source>smart-ip.net</source>
    <host>193.178.146.17</host>
    <lang>en</lang>
    <countryName>Ukraine</countryName>
    <countryCode>UA</countryCode>
    <city>Kiev</city>
    <region>Kyyivs'ka Oblast'</region>
    <latitude>50.4333</latitude>
    <longitude>30.5167</longitude>
    <timezone>Europe/Kiev</timezone>
</geoip>

Example of JSON-response

{
    "source":"smart-ip.net"
    "host":"193.178.146.17",
    "lang":"en",
    "countryName":"Ukraine",
    "countryCode":"UA",
    "city":"Kiev",
    "region":"Kyyivs'ka Oblast'",
    "latitude":50.4333,
    "longitude":30.5167,
    "timezone":"Europe/Kiev"
}

Errors

In case of errors the service will return an error in XML or JSON format in the language of the request. For example:

Example of XML-response with error

<?xml version="1.0" encoding="UTF-8"?>
<geoip><error>Cannot resolve host name!</error></geoip>

Example of JSON-response with error

{
    "error":"Cannot resolve host name!"
}

Building Queries

All queries to Geo-IP service are implemented over HTTP using a GET requests. Addresses of basic services are:

Geo-IP service accepts the following parameters within the queries:

There could be used a short form to pass "host" and "type" parameters via URL. Examples:

Where after "geoip-xml" the first one parameter is treated as "host", and the second one - as "type".

"lang" parameter can be passed only via QERY_STRING, e.g.: http://smart-ip.net/geoip-xml/google.com/auto?lang=ru

NOTE: JSON version of API also supports JSONP. The name of the parameter which identifies a function to call has name "callback". So, to make JSONP request the call will look like:

http://smart-ip.net/geoip-json/11.22.33.44?callback=_function_name_

NOTE XML version of API supports cross-domain requests for Flash and Silverlight with standard crossdomain.xml

Examples of Usage

Here we will collect some interesting examples of our Geo-IP API usage.

Do you have an example of using our API somewhere on a web and want to share it at this page? Please, send it to us.

Please, keep in mind that we reserve the right to decide which examples to be published here and give absolutely no promise that your example will be shared.

7-Days Statistics of Geo-IP API Usage

Last modified: Jan 9, 2013 4:12:36 PM