API Version 2.3 Documentation

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

Over the lifetime of our first API version, we have received a lot of useful feedback from our users, we have listened and decided to improve our service and implement the most requested features and additional information.


Changes

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 the 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 keys can batch 32 queries per API request
    • Lite and Pro keys can batch 256 queries per API request
  • Localized place names
    • New York, Moscow, Beijing, ...
    • Нью-Йорк, Москва, Пекин, ...
    • 纽约, 莫斯科, 北京, ...
    • न्यूयॉर्क, मास्को, बीजिंग, ...
    • マンハッタン, モスクワ, 北京市, ...

Get IP address information

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>

The two parameters are defined as follows :

apiKey
Your API key
ipAddress
IPv4 or IPv6 address

Here is a sample URL for fetching IP address information :

http://api.db-ip.com/v2/ec6220f579879ce10da9d26caec11dc707ac5d34/23.255.240.0

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

ipAddress
Requested IP address
continentCode
2-letter continent code
continentName
Continent name
countryCode
ISO 3166-1 alpha-2 country code
countryName
Country name
currencyCode
ISO 4217 currency code
currencyName
Currency name
phonePrefix
International phone prefix (note: in some rare cases, this is an array with two or more prefixes)
languages
List of ISO 639 language codes
stateProv
State or province name
district
District or county name
city
City name
geonameId
Unique identifier of the location in the GeoNames database
zipCode
Zip (postal) code
latitude
Decimal latitude
longitude
Decimal longitude
gmtOffset
Offset from UTC in hours
timeZone
Name of timezone
asNumber
Autonomous System number
asName
Autonomous System name
isp
Internet Service Provider name
linkType
Connection type
organization
Organization name
isCrawler
True if this is a web crawler IP address
crawlerName
Name of the identified web crawler
isProxy
True if this this is a proxy exit address
proxyType
Proxy type (http/vpn/tor)
threatLevel
Computed threat level for this address (low/medium/high)
threatDetails
List of threat flags raised by this address

Sample response using a Lite API Key :

{
    "ipAddress": "23.255.240.0",
    "continentCode": "NA",
    "continentName": "North America",
    "countryCode": "US",
    "countryName": "United States",
    "currencyCode": "USD",
    "currencyName": "Dollar",
    "phonePrefix": "1",
    "languages": [
        "en-US",
        "es-US",
        "haw",
        "fr"
    ],
    "stateProv": "California",
    "district": "Santa Clara County",
    "city": "Mountain View",
    "geonameId": 5375480,
    "zipCode": "94043",
    "latitude": 37.3861,
    "longitude": -122.084,
    "gmtOffset": -7,
    "timeZone": "America\/Los_Angeles"
}

Sample response using a Pro API Key :

{
    "ipAddress": "23.255.240.0",
    "continentCode": "NA",
    "continentName": "North America",
    "countryCode": "US",
    "countryName": "United States",
    "currencyCode": "USD",
    "currencyName": "Dollar",
    "phonePrefix": "1",
    "languages": [
        "en-US",
        "es-US",
        "haw",
        "fr"
    ],
    "stateProv": "California",
    "district": "Santa Clara County",
    "city": "Mountain View",
    "geonameId": 5375480,
    "zipCode": "94043",
    "latitude": 37.3861,
    "longitude": -122.084,
    "gmtOffset": -7,
    "timeZone": "America\/Los_Angeles",
    "asNumber": 16591,
    "asName": "GOOGLE-FIBER - Google Fiber Inc.",
    "isp": "Google Fiber Inc.",
    "linkType": "fttx",
    "organization": "Google Fiber Inc.",
    "isCrawler": false,
    "isProxy": false,
    "threatLevel": "low"
}

If an error occurs, the server responds with an object containing only an error property with the actual error text :

{ "error": "invalid API key" }

Localization

The place names are localized using the language information present in the standard Accept-Language HTTP request header.

Localized names are available with Lite and Pro 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

Here is a sample URL for fetching IP address information :

http://api.db-ip.com/v2/ec6220f579879ce10da9d26caec11dc707ac5d34/111.111.111.111,222.222.222.222

The server responds with a set of JSON encoded key-value pairs where the key is an IP address and the value an object of the format described above for single address queries.

Sample response using a Free API Key :

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

Get API key information

In order to fetch information about your API key, 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

Here is a sample URL for fetching API key information :

http://api.db-ip.com/v2/ec6220f579879ce10da9d26caec11dc707ac5d34

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

apiKey
Your API key
queriesPerDay
Quota of daily IP address queries
queriesLeft
Number of IP address queries left for the day
expires
You API key expiration date and time (format is YYYY-MM-DD HH:MM:SS and timezone is UTC)

Sample response :

{
    "apiKey": "ec6220f579879ce10da9d26caec11dc707ac5d34",
    "queriesPerDay": 10000,
    "queriesLeft": 2863,
    "expires": "2018-11-22 23:20:15"
}