Developer documentation

API version 2 (r3738)


The DB-IP API is exposed via RESTful web services and makes use of the standard JSON encoding.

This 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.



Getting started

PHP with API client

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"
}

Adding an API key

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.

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 (29) {
  ["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"
  ["asNumber"]=>
  int(16591)
  ["asName"]=>
  string(12) "GOOGLE-FIBER"
  ["isp"]=>
  string(17) "Google Fiber Inc."
  ["linkType"]=>
  string(4) "fttx"
  ["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"
  }
}



Using Javascript in the browser

You may use the API directly from a web browser to lookup visitor IP address details. Paid API service users have the option to enable their public API key in the API dashboard.

  JSFiddle Sample jQuery code
$(".my-button").click(function() {
	$.getJSON("http://api.db-ip.com/v2/free/self").then(addrInfo =>
		alert(addrInfo.ipAddress + " is in " + addrInfo.city + ", " + addrInfo.stateProv)
	);
});




Localization


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 :

  •   stateProv
  •   district
  •   city

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

"stateProv": "California",
"district": "Santa Clara County",
"city": "Mountain View",

Accept-Language: fr-FR

"stateProv": "Californie",
"district": "Comté de Santa Clara",
"city": "Mountain View",
Accept-Language: ru-RU

"stateProv": "Калифорния",
"district": "Санта-Клара",
"city": "Маунтин-Вью",

Accept-Language: ja-JP

"stateProv": "カリフォルニア州",
"district": "サンタクララ郡",
"city": "マウンテンビュー",




Batch queries


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 :

apiKey
Your API key
ipAddressList
A comma separated list of IPv4 and/or IPv6 address



Example

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.





Get IP address details


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 :

apiKey
Your API key or the string "free" for the free API
ipAddress
IPv4 / IPv6 address or the string "self" to lookup the calling address
propertyName
[optional] specify a single field name to request instead of the whole address details



Examples

Here are a few examples for fetching IP address information from the command line :

  Try it Fetch address details from free API
~$ 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",
}

Determine whether to apply EU regulations
~$ curl http://api.db-ip.com/v2/a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d/8.8.8.8/isEuMember
false

  Try it Find my own IP address using the free API
~$ curl http://api.db-ip.com/v2/free/self/ipAddress
54.80.183.100



Response details

The server responds with a JSON encoded object with some or all of the following properties :


ipAddress string
Requested IP address
"ipAddress": "123.45.67.89",
continentCode char[2] [AF, AS, EU, NA, OC, SA, AN]
2-letter continent code
"continentCode": "NA",
continentName string
Continent name
"continentName": "North America",
countryCode char[2]
ISO 3166-1 alpha-2 country code (see FAQ)
"countryCode": "US",
countryName string
Country name
"countryName": "United States",
isEuMember bool
True if the country is a member of the European Union
"isEuMember": false,
currencyCode char[3]
ISO 4217 currency code
"currencyCode": "USD",
currencyName string
Currency name
"currencyName": "Dollar",
phonePrefix string | array<string>
International phone prefix (note: in some rare cases, this is an array with two or more prefixes)
"phonePrefix": "1",
languages array<string>
List of ISO 639 language codes
"languages": [
    "en-US",
    "es-US",
    "haw",
    "fr"
],
stateProv string
State or province name
"stateProv": "California",
district string
District or county name
"district": "Santa Clara County",
city string
City name
"city": "Mountain View",
geonameId int
Unique identifier of the location in the GeoNames database
"geonameId": 5375480,
zipCode string
Zip (postal) code
"zipCode": "94043",
latitude float
Decimal latitude
"latitude": 37.3861,
longitude float
Decimal longitude
"longitude": -122.084,
gmtOffset float
Offset from UTC in hours
"gmtOffset": -7,
timeZone string
Name of timezone in the IANA Time Zone Database
"timeZone": "America\/Los_Angeles",
asNumber int
Autonomous System number
"asNumber": 16591,
asName string
Autonomous System name
"asName": "GOOGLE-FIBER",
isp string
Internet Service Provider name
"isp": "Google Fiber Inc.",
linkType string [dialup, isdn, cable, dsl, fttx, wireless]
Connection type
"linkType": "fttx",
organization string
Organization name
"organization": "Google Fiber Inc.",
isCrawler bool
True if this is a web crawler IP address
"isCrawler": true,
crawlerName string
Name of the identified web crawler
"crawlerName": "Googlebot\/2.1",
isProxy bool
True if this is a proxy exit address
"isProxy": true,
proxyType string [http, vpn, tor]
Proxy type
"proxyType": "tor",
threatLevel string [low, medium, high]
Computed threat level for this address
"threatLevel": "high",
threatDetails array<string>
List of threat flags raised by this address
anonymous-proxy
Exit address for anonymizing services such as HTTP/Socks proxies, VPNs or Tor
fake-crawler
Suspicious web scraper impersonating popular and legitimate crawlers
port-scan
Port scanning is a common way to search for exploitable security vulnerabilities in running network services
attack-source
Known source of cyber attacks
attack-target:<type>
[web, mail, ssh, ftp, sip]
Target of attacks originating from this address
bot
The computer using this address is part of a malicous botnet
bot-name:<name>
Name of the identified botnet
bot-type:<type>
[bad, brute-force, scan, spam, referer-spam]
Known activity for this bot
"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"
}




Get AS details


The AS API lets you request details about an AS number, it is included with Core and Extended API plans.

By IP address

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 :

apiKey
Your API key
ipAddress
The IP address you want AS details for
propertyName
[optional] specify a single field name to request instead of the whole AS details



By AS number

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 :

apiKey
Your API key
asNumber
The AS number you want details for
propertyName
[optional] specify a single field name to request instead of the whole AS details



Examples

Here are sample command lines for fetching AS number details :

Get full AS 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
    }
}


Get AS name
~$ curl http://api.db-ip.com/v2/a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d/as/8.8.8.8/name
GOOGLE - Google LLC



Response details

The server responds with a JSON encoded object with some or all of the following properties :

number int
AS number
name string
AS name
organization string
Organization name
registry string [ ripe, arin, apnic, lacnic, afrinic ]
Regional internet registry
continentCode char[2] [AF, AS, EU, NA, OC, SA, AN]
2-letter continent code
continentName string
Continent name
countryCode char[2]
ISO 3166-1 alpha-2 country code (see FAQ)
countryName string
Country name
prefixCount int
Total number of prefixes announced by this AS
ipv4 struct
AS details for IPv4 addresses
addressCount int
Total number of IPv4 addresses announced by this AS
prefixCount int
Total number of IPv4 prefixes announced by this AS
ipv6 struct
AS details for IPv6 addresses - see above




Get API key information


In 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 :

apiKey
Your API key or the string "free" for free API



Examples

Here are sample command lines for fetching API service information :

  Try it Free API
~$ curl http://api.db-ip.com/v2/free
{
    "queriesLeft": 969
}

API key
~$ curl http://api.db-ip.com/v2/a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d
{
    "apiKey": "a05p3c1m3n79875p3c1m3nd26cd0n07u5307ac5d",
	"queriesPerDay": 10000,
    "queriesLeft": 9353,
    "status": "active"
}



Response details

The server responds with a JSON encoded object with some or all of the following properties :

apiKey string
Your API key
queriesPerDay int
Quota of daily IP address queries
queriesLeft int
Number of IP address queries left for the day
status string
The status of your API service (trial/active/canceled)
expires string
[deprecated] Your API key expiration date and time (format is YYYY-MM-DD HH:MM:SS and timezone is UTC)




Error handling


When 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 :

INVALID_KEY
The API key is not valid, double-check your code or URL
INVALID_ADDRESS
The IP address is malformed or invalid
HTTPS_NOT_ALLOWED
Only applies to free API service
You are trying to use the free API over HTTPS, encrypted API is only supported for paid service
TEMPORARY_BLOCKED
Only applies to free API service
Our systems have detected unusual or malicious activity and the key has been temporarily blocked
TOO_MANY_ADDRESSES
Your are making a batch query with too many addresses, check your code so you do not go over your plan limits
OVER_QUERY_LIMIT
Your key has exceeded its daily quota. A batch query that would go over the quota will also raise this error
RESTRICTED
You are trying to use an API that is not available with your service (ie. calling the AS API with a Basic API key)
EXPIRED
The API key has expired
UNAVAILABLE
The server may be overloaded or undergoing maintenance, retry your query after a short delay




Upgrading from version 1.x


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 :

  • Additional information
    • Continent code and name
    • Country name
    • Currency code and name
    • Phone prefix
    • ISO 639 language codes
    • Autonomous System number and name
    • District name
    • Zip code
    • GeoNames identifier
    • Crawler and proxy detection, threat level assessment
  • Batch queries
    • Free users can batch 32 queries per API request
    • Paid keys can batch 256 queries per API request
  • Localized place names
    • New York, Moscow, Beijing, ...
    • Нью-Йорк, Москва, Пекин, ...
    • 纽约, 莫斯科, 北京, ...
    • न्यूयॉर्क, मास्को, बीजिंग, ...
    • マンハッタン, モスクワ, 北京市, ...