;

SmartIP API documentation

Important!
In order to achieve better performances and scalability we updated our infrastructure! As a result, we had to change our main API endpoint to:

https://api.smartip.io

Please update your services accordingly.
Any request incoming to the old hostname will return with an error code: 301 Permanently Moved

Introduction

SmartIP.io offers a powerful and yet extremely simple API to gather information from any IP address. Using our API you will have access to GeoLocation data, Security data, Crypto data, Currency data, Timezone and ASN data all returned in simple JSON format. With SmartIP you will be able to locate your website visitors and potentially tailor the user experience based on their needs.

In order to use our API you just need to Sign up and get your free API key.

Sign up now

Authentication

Once you signed up and created a new account, you will be given a new API key. In order to use this API, you will need to append the api_key parameter to every single GET request you send to our service endpoints.

HTTPS / SSL

All endpoints of our API work over a secure HTTPS connection for all users, even for Free tier. Just make sure to use https:// in your API requests URL.

Get IP endpoint

Request URL

This is how a request URL would look like looking for info about IP address: 8.8.8.8:

https://api.smartip.io/8.8.8.8?api_key=[YOUR_API_KEY]
Input parameters
Parameter Required Description
IP address Yes It is specified as part of the URL. This can be either a ipv4 or ipv6 address. If the address is not specified, the lookup will be made against the IP requesting the API call (your own IP address).
api_key Yes Your personal API Key.
hostname No
If true, the API response will contain the current hostname of the requested IP address, otherwise it will be set the requested IP address value.
Remark
By default the Hostname lookup is disabled to improve performances. Enabling it, may impact on the overall API response time.
useragent No
If true, the API response will contain a JSON representation of the caller's user agent, otherwise it will be null.
Remark
By default the User-Agent lookup is disabled to improve performances.

Get ASN data endpoint

Request URL

This is how a request URL would look like looking for info about the ASN: AS3443:

https://api.smartip.io/AS3443?api_key=[YOUR_API_KEY]
Input parameters
Parameter Required Description
ASN name Yes It is specified as part of the URL. The ASN name must start with "AS".
api_key Yes Your personal API Key.

Sample code

This is a sample code which shows how easy it is to request an IP address data using the SmartIP.io API:

C#
using( var httpClient = new HttpClient()) 
{
    var apiEndpoint = "https://api.smartip.io/112.126.34.5/?api_key=[YOUR_API_KEY]";
    var response = await httpClient.GetAsync(apiEndpoint);
    return await response.Content.ReadAsStringAsync();  
}
Javascript
$.ajax ({
  type: "GET",
  url: "https://api.smartip.io/112.126.34.5/?api_key=[YOUR_API_KEY]",
  success: function(response) { alert(response); }
});

Error codes

Whenever an API request fails, Errors always get returned with the error code and the description in the JSON response.


Code Type Description
401user_not_authorizedUnable to find an user for the provided api_key.
403monthly_quota_reachedThe monthly quota has been reach for the current subscription tier. Need to upgrade the subscription to keep using the API.
400invalid_ip_addressThe provided IP address is invalid.
417missing_api_keyThe api_key parameter is mandatory.

Full IP API Response

SmartIP returns the IP data in simple JSON format.

This is a full JSON API Response which includes security, crypto, asn, timezone, currency and location data.


{
    "ip": "72.229.28.185",
    "ip-type": "ipv4",
    "hostname": "cpe-72-229-28-185.nyc.res.rr.com",
    "country": {
        "country-iso-code": "US",
        "country-two-letter-iso-code": "US",
        "country-name": "United States",
        "capital": "Washington",
        "is-in-europe": false,
        "is-metric": false,
        "country-geo-id": 6252001,
        "continent-name": "North America",
        "continent-code": "NA",
        "continent-geo-id": 6255149,
        "region-name": "New York",
        "region-code": "NY",
        "region-geo-id": 5128638
    },
    "location": {
        "city": "New York",
        "zip-code": "10009",
        "latitude": "40.7263",
        "longitude": "-73.9818",
        "timezone": "America/New_York",
        "metro-code": 501
    },
    "asn": {         
        "type": "isp",
        "domain": "charter.com",
        "organization": "Charter Communications Inc",
        "asn": "AS12271"    
    },
    "currency": {
        "symbol": "$",
        "name": "US Dollar",
        "code": "USD",
        "native-name": "US Dollar"
    },
    "timezone": {
        "iana-name": "America/New_York",
        "microsoft-name": "Eastern Standard Time",
        "date-time": "2019-07-05T20:54:23-05:00",
        "is-daylight-saving": true,
        "gmt-offset": -18000
    },
    "security": {
        "is-tor": false,
        "tor-insights": null,
        "is-proxy": false,
        "proxy-insights": null,
        "is-crawler": false,
        "crawler-insights": null
    },
    "crypto": {
        "is-crypto-node": false,
        "crypto-insights": null
    },
    "user-agent": {
        "os": {
            "name": "iOS",
            "platform": "",
            "version": "5.1.1",
            "family": "iOS"
        },
        "device": {
            "brand": "AP",
            "model": "iPhone",
            "family": "smartphone"
        },
        "engine-version": "534.46",
        "engine": "WebKit",
        "name": "Mobile Safari",
        "type": "browser",
        "header": "Mozilla/5.0 (iPhone; CPU iPhone OS 5_1_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B206 Safari/7534.48.3",
        "version": "5.1",
        "family": "Safari"
    },
    "error": null,
    "status-code": 200
}

Security Data API Response

SmartIP API exposes useful security information related to a given IP address, you can identify if a given IP is either or not a Tor exit node, a Crawler IP, a Proxy IP. On top of this, we will surface some additional security insights based on its type.

The security data are available across all of our API tiers, including the Free Tier.

"security": {
    "is-tor": false,
    "tor-insights": null,
    "is-proxy": false,
    "proxy-insights": null,
    "is-crawler": false,
    "crawler-insights": null
}

Crawler Data

If the IP specified in the request has been categorized as a Crawler, our API will return some additional insights about its nature such as its type and its name.

"security": {   
    "is-crawler": true,
    "crawler-insights": {
        "type": "crawler_search_engine",
        "name": "alexa_bot",
        "domain": null
    }
}

TOR Data

If the IP specified in the request is a well known TOR exit node, our API will return some additional insights about its nature such as its Exit Node identifier exit-node, when the node has been published on the network published-on and when its information has been updated last last-status-on.

"security": {
    "is-tor": true,
    "tor-insights": {
        "exit-node": "92E82B6D71C8073C748BA74E818C478B4B5C793B",
        "published-on": "7/7/2019 12:00:00 AM",
        "last-status-on": "7/7/2019 12:00:00 AM"
    },
    "is-proxy": true,
    "proxy-insights": {
        "type": "proxy_anonymizer"
    }
}

Proxy Data

If the IP specified in the request has been categorized as a proxy, we specify the proxy type in the response. Currently supported types are:proxy_anonymizer, proxy_abuser

"security": {   
    "is-proxy": true,
    "proxy-insights": {
        "type": "proxy_anonymizer"
    }
}

Crypto Data API Response

SmartIP API crypto data exposes information about if a given IP address is an active blockchain node. The response will include, the blockchain coin in which the IP is a full node and the port used to connect to the blockchain.

The crypto data are available across all of our API tiers, including the Free Tier.

"crypto": {
    "is-crypto-node": true,
    "crypto-insights": {
        "port": 8333,
        "coin": "btc"
    }
}

ASN Data API Response

SmartIP API asn data point exposes useful information about any ASN. The response will include:

type: Possible values: isp, hosting, edutation and enterprise.

name: The ASN name as shown on the related Whois record.

domain: The domain associated to the ASN.

organization: The organization name which owns the ASN.

asn: The ASN number.

The ASN data are available across all of our API tiers, including the Free Tier.

 "asn": {
        "name": "DIGITALOCEAN-ASN",
        "type": "hosting",
        "domain": "digitalocean.com",
        "organization": "DigitalOcean, LLC",
        "asn": "AS14061"
    }}

User Agent detection

Our user-agent data-point exposes all the information included in the User Agent HTTP Header.

The user-agent data-point is available across all of our API tiers, including the Free Tier.

To surface this data point, the request URL must be enriched with the additional input parameter: useragent=true.

 "user-agent": {
    "os": {
        "name": "iOS",
        "platform": "",
        "version": "5.1.1",
        "family": "iOS"
    },
    "device": {
        "brand": "AP",
        "model": "iPhone",
        "family": "smartphone"
    },
    "engine-version": "534.46",
    "engine": "WebKit",
    "name": "Mobile Safari",
    "type": "browser",
    "header": "Mozilla/5.0 (iPhone; CPU iPhone OS 5_1_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B206 Safari/7534.48.3",
    "version": "5.1",
    "family": "Safari"
}

Full ASN API Response

SmartIP returns the ASN data in simple JSON format.


{
    "total-blocks-v4": 118,
    "status-code": 200,
    "ip-blocks-v4": [
        "103.253.144.0/22",
        "104.131.0.0/16",
        "104.236.0.0/16",
        "104.248.0.0/16",
        "107.170.0.0/16",
        "128.199.128.0/17",
        "128.199.32.0/19",
        "128.199.64.0/18",
        "134.209.0.0/17",
        "134.209.128.0/22",
        "134.209.144.0/20",
        "134.209.160.0/19",
        "134.209.192.0/18",
        "138.197.0.0/17",
        "138.197.128.0/18",
       ... ... ...
    ],
    "abuse": {
        "address": "101 Ave of the Americas 10th Floor New York NY 10013 US",
        "email": "[email protected]"
    },
    "registry": "ARIN",
    "country-iso-code": "US",
    "name": "DIGITALOCEAN-ASN",
    "type": "hosting",
    "domain": "digitalocean.com",
    "error": null,
    "organization": "DigitalOcean, LLC",
    "asn": "AS14061"
}

Code samples

The following code samples do not take into account any error handling, so keep in mind they are shown for demo purposes only.

Please replace [YOUR_API_KEY] with your own API key in the following code samples to get them working.

Redirect traffic by country

The following Javascript code (using JQuery) identifies from which country your users are visiting using smartip.io API and then redirects them to a country-specific URL.

var urls = {
    US: "https://test.com/us",
    FR: "https://test.com/fr",
    CH: "http://test.com/ch"
};

$.get("https://api.smartip.io/[client_ip]?api_key=[YOUR_API_KEY]", function(response) {
    var countryCode = response["country"]["country-iso-code"];
    var redirect = url[countryCode];
    window.location.href = redirect;
});

Something similar could be implemented to show different welcome messages in different languages or even to show different ads to user from different countries.

Detect Bot traffic

Once way to reduce the number of API calls to our API, could be to avoid hitting the API locally detecting knows search bots like Google, Bing, Yandex. They all expose well defined User Agent strings that can be inspected:

Bot name User Agent
Google Bot Googlebot/2.1 (+http://www.googlebot.com/bot.html)
Bing Bot Mozilla/5.0 (compatible; bingbot/2.0 +http://www.bing.com/bingbot.htm)
Yandex Bot Mozilla/5.0 (compatible; YandexBot/3.0; +http://yandex.com/bots)
if (navigator.userAgent.match(/bot|spider/i)) {
    // It is a bot, probably keep it going to crawl your site
} else {
    // It's not a bot, hit the API:
    $.get("https://api.smartip.io/[client_ip]?api_key=[YOUR_API_KEY]", function(response) {
        console.log("response");
    });
}

Blocking TOR connections

The following Javascript snippet (using JQuery) detects if an incoming IP is a TOR node and take action.

$.get("https://api.smartip.io/[client_ip]?api_key=[YOUR_API_KEY]", function(response) {
    var isTor = response["security"]["is-tor"];

    if (isTor) {
        // this user connection is not allowed: redirect to an error page
    } else {
        // all good!
    }
});