Documentation for IP Geolocation API version 2 (r5578)
The DB-IP API is exposed via RESTful web services and makes use of the standard JSON encoding.
This geolocation API developer documentation will show you how to query the API using either the officially supported PHP client library or direct API calls over HTTP or HTTPs, and how to use the information in your application.
You can start using the API with just two lines of code, first include the API client library :
require "dbip-client.class.php";... and use it to lookup visitor IP address information :
$addrInfo = DBIP\Address::lookup($_SERVER["REMOTE_ADDR"]);The $addrInfo variable is now populated with an object like this one :
var_dump($addrInfo);
object(stdClass)#2 (7) {
["ipAddress"]=>
string(7) "8.8.8.8"
["continentCode"]=>
string(2) "NA"
["continentName"]=>
string(13) "North America"
["countryCode"]=>
string(2) "US"
["countryName"]=>
string(13) "United States"
["stateProv"]=>
string(10) "California"
["city"]=>
string(13) "Mountain View"
}Now this was only the free API, let's use an API key so we can get much more useful data in the API response. At this point in the IP location API developer documentation, we’ll go over how to add the API key.
In order to do this we just call DBIP\APIKey::set() after loading the client library and before making address requests :
require "dbip-client.class.php";
// Replace the sample key below with your private API key
DBIP\APIKey::set("a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d");
$addrInfo = DBIP\Address::lookup($_SERVER["REMOTE_ADDR"]);The response object now has all the Extended API information, it worked !
object(stdClass)#1 (30) {
["ipAddress"]=>
string(12) "123.45.67.89"
["continentCode"]=>
string(2) "NA"
["continentName"]=>
string(13) "North America"
["countryCode"]=>
string(2) "US"
["countryName"]=>
string(13) "United States"
["isEuMember"]=>
bool(false)
["currencyCode"]=>
string(3) "USD"
["currencyName"]=>
string(6) "Dollar"
["phonePrefix"]=>
string(1) "1"
["languages"]=>
array(4) {
[0]=>
string(5) "en-US"
[1]=>
string(5) "es-US"
[2]=>
string(3) "haw"
[3]=>
string(2) "fr"
}
["stateProv"]=>
string(10) "California"
["district"]=>
string(18) "Santa Clara County"
["city"]=>
string(13) "Mountain View"
["geonameId"]=>
int(5375480)
["zipCode"]=>
string(5) "94043"
["latitude"]=>
float(37.3861)
["longitude"]=>
float(-122.084)
["gmtOffset"]=>
int(-7)
["timeZone"]=>
string(19) "America/Los_Angeles"
["weatherCode"]=>
string(8) "USCA0746"
["asNumber"]=>
int(16591)
["asName"]=>
string(12) "GOOGLE-FIBER"
["isp"]=>
string(17) "Google Fiber Inc."
["linkType"]=>
string(4) "fttx"
["usageType"]=>
string(4) "consumer"
["organization"]=>
string(17) "Google Fiber Inc."
["isCrawler"]=>
bool(false)
["isProxy"]=>
bool(true)
["proxyType"]=>
string(3) "vpn"
["threatLevel"]=>
string(4) "high"
["threatDetails"]=>
array(5) {
[0]=>
string(15) "anonymous-proxy"
[1]=>
string(13) "attack-source"
[2]=>
string(17) "attack-target:web"
[3]=>
string(16) "bot-name:gherran"
[4]=>
string(13) "bot-type:spam"
}
}In order to use the API in a web browser you have to use your public key. Paid API service users have the option to enable their public key in the API dashboard.
dbip.js is the easiest way to write location-aware client side applications, it provides easy access to the following features :
You may also call the API directly using the standard Javascript XMLHttpRequest or its jQuery helper :
$(".my-button").click(function() {
$.getJSON("http://api.db-ip.com/v2/free/self").then(addrInfo =>
alert(addrInfo.ipAddress + " is in " + addrInfo.city + ", " + addrInfo.stateProv)
);
});The place names are localized using the language information present in the standard Accept-Language HTTP request header. This header is automatically passed from the client browser to the API if you are using the official PHP client or making calls directly from Javascript in the browser.
Localized names are available with paid API keys only, and are provided for most medium and big cities in the world, and several small ones.
We have plans to add more localization options in the future, at the moment this is available for the following data fields :
You will find below a few samples of localized responses for the above example query, along with their respective Accept-Language request header :
Accept-Language: en-US
"countryName": "United States",
"stateProv": "California",
"district": "Santa Clara County",
"city": "Mountain View",Accept-Language: fr-FR
"countryName": "États-Unis",
"stateProv": "Californie",
"district": "Comté de Santa Clara",
"city": "Mountain View",Accept-Language: ru-RU
"countryName": "США",
"stateProv": "Калифорния",
"district": "Санта-Клара",
"city": "Маунтин-Вью",Accept-Language: ja-JP
"countryName": "アメリカ合衆国",
"stateProv": "カリフォルニア州",
"district": "サンタクララ郡",
"city": "マウンテンビュー",If this is compatible with your usage pattern, you may significantly improve query performance by making multiple IP address lookups in a single API query.
Furthermore, batch queries are given a 10% bonus regarding daily quotas, it means that your quota will only be decremented by 9 for a batch query of 10 addresses, by 45 for 50 addresses, etc ...
In order to fetch information about multiple IP addresses at once, you need to build a request URL of the following form :
http://api.db-ip.com/v2/{apiKey}/{ipAddressList}The two parameters are defined as follows :
Sample command line for fetching information about multiple IP address in a single API call with the resulting JSON response :
Try it~$ curl http://api.db-ip.com/v2/free/111.111.111.111,222.222.222.222,333.333.333.333
{
"111.111.111.111": {
"continentCode": "AS",
"continentName": "Asia",
"countryCode": "JP",
"countryName": "Japan",
"stateProv": "Tokyo",
"city": "Chiyoda"
},
"222.222.222.222": {
"continentCode": "AS",
"continentName": "Asia",
"countryCode": "CN",
"countryName": "China",
"stateProv": "Hebei",
"city": "Shijiazhuang"
},
"333.333.333.333": {
"errorCode": "INVALID_ADDRESS",
"error": "invalid address '333.333.333.333'"
}
}The server responds with JSON encoded set of key-value pairs where the key is an IP address and the value either an object of the format described above for single address queries or an error object.
In order to fetch information about an IP address, you need to build a request URL of the following form :
http://api.db-ip.com/v2/{apiKey}/{ipAddress}/{propertyName}The three parameters are defined as follows :
Here are a few examples for fetching IP address information from the command line :
~$ curl http://api.db-ip.com/v2/free/8.8.8.8
{
"ipAddress": "8.8.8.8",
"continentCode": "NA",
"continentName": "North America",
"countryCode": "US",
"countryName": "United States",
"stateProv": "California",
"city": "Mountain View",
}~$ curl http://api.db-ip.com/v2/a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d/8.8.8.8/isEuMember
false~$ curl http://api.db-ip.com/v2/free/self/ipAddress
18.191.195.110The server responds with a JSON encoded object with some or all of the following properties :
string
"ipAddress": "123.45.67.89",char[2]
[AF, AS, EU, NA, OC, SA, AN]
"continentCode": "NA",string
"continentName": "North America",char[2]
"countryCode": "US",string
"countryName": "United States",bool
"isEuMember": false,char[3]
"currencyCode": "USD",string
"currencyName": "Dollar",string | array<string>
"phonePrefix": "1",array<string>
"languages": [
"en-US",
"es-US",
"haw",
"fr"
],string
"stateProvCode": "CA",string
"stateProv": "California",string
"district": "Santa Clara County",string
"city": "Mountain View",int
"geonameId": 5375480,string
"zipCode": "94043",float
"latitude": 37.3861,float
"longitude": -122.084,float
"gmtOffset": -7,string
"timeZone": "America\/Los_Angeles",string
"weatherCode": "USCA0746",int
"asNumber": 16591,string
"asName": "GOOGLE-FIBER",string
"isp": "Google Fiber Inc.",string
[dialup, isdn, cable, dsl, fttx, wireless]
"linkType": "fttx",string
[hosting, corporate, consumer]
"usageType": "consumer",string
"organization": "Google Fiber Inc.",bool
"isCrawler": true,string
"crawlerName": "Googlebot\/2.1",bool
"isProxy": true,string
[http, vpn, tor]
"proxyType": "tor",string
[low, medium, high]
"threatLevel": "high",array<string>
"threatDetails": [
"anonymous-proxy",
"attack-source",
"attack-target:web",
"bot-name:gherran",
"bot-type:spam"
],If an error occurs, the server responds with an object containing only errorCode and error properties, the different error codes are listed in the error handling section :
{
"errorCode": "INVALID_KEY",
"error": "invalid API key"
}The AS API lets you request details about an AS number, it is included with Core and Extended API plans.
In order to fetch details for an IP address, you need to build a request URL of the following form :
http://api.db-ip.com/v2/{apiKey}/as/{ipAddress}/{propertyName}The parameters are defined as follows :
In order to fetch details for an AS number, you need to build a request URL of the following form :
http://api.db-ip.com/v2/{apiKey}/as/{asNumber}/{propertyName}The parameters are defined as follows :
Here are sample command lines for fetching AS number details :
~$ curl http://api.db-ip.com/v2/a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d/as/16591
{
"number": 16591,
"name": "GOOGLE-FIBER - Google Fiber Inc.",
"organization": "Google Fiber Inc.",
"registry": "arin",
"continentCode": "NA",
"continentName": "North America",
"countryCode": "US",
"countryName": "United States",
"prefixCount": 20,
"ipv4": {
"addressCount": 2244608,
"prefixCount": 18
},
"ipv6": {
"addressCount": 8589934592,
"prefixCount": 2
}
}~$ curl http://api.db-ip.com/v2/a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d/as/8.8.8.8/name
GOOGLE - Google LLCThe server responds with a JSON encoded object with some or all of the following properties :
intstringstringstring [ ripe, arin, apnic, lacnic, afrinic ]char[2] [AF, AS, EU, NA, OC, SA, AN]stringchar[2]stringintstructintintstructIn order to fetch information about your API service, you need to build a request URL of the following form :
http://api.db-ip.com/v2/{apiKey}The parameter is defined as follows :
Here are sample command lines for fetching API service information :
~$ curl http://api.db-ip.com/v2/free
{
"queriesLeft": 969
}~$ curl http://api.db-ip.com/v2/a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d
{
"apiKey": "a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d",
"queriesPerDay": 10000,
"queriesLeft": 9353,
"status": "active"
}The server responds with a JSON encoded object with some or all of the following properties :
stringintintstringstringWhen the server cannot answer a query it will answer with an error object consisting of two properties, errorCode and error :
{
"errorCode": "INVALID_KEY",
"error": "invalid API key"
}The error property contains the error message and errorCode can be one of the following :
This version of the API adds several features and breaks compatibility with the previous version in a number of ways and altough we will still support v1 queries for as long as necessary, it is now considered as deprecated and we strongly recommend that you target the latest version for new projects and port legacy code to be able to use the new features in v2.
If you are already using version 1.x of our official query library, you will be able to safely upgrade to a newest version and enjoy the new features without breaking legacy code.
The new features in version 2 include :
If you would like more information about our API that isn’t available in our IP geolocation API developer documentation, simply contact us at any time and we’ll be able to help you find what you need.