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.
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. 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 keyDBIP\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" }}
Using Javascript in the browser
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
dbip.js is the easiest way to write location-aware client side applications, it provides easy access to the following features :
- Visitor IP address lookup
- Form elements autofill
- Live conversions into visitor currency
- Augmented browser geolocation
Javascript API documentation
Direct calls with jQuery
You may also call the API directly using the standard Javascript XMLHttpRequest or its jQuery helper :
JSFiddleSample 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 :
- countryName
- 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"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": "マウンテンビュー",
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 itFetch 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/isEuMemberfalse
Try itFind my own IP address using the free API
~$ curl http://api.db-ip.com/v2/free/self/ipAddress132.145.215.147
Response details
The server responds with a JSON encoded object with some or all of the following properties :
- Free API
- Basic API
- Core API
- Extended API
- 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"],
- stateProvCode
string
- State or province ISO 3166-2 code
"stateProvCode": "CA",
- 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",
- weatherCode
string
- Nearest international weather station code. These are as used by AOL Weather, The Weather Channel (weather.com), Yahoo! Weather and many more.
"weatherCode": "USCA0746",
- 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",
- usageType
string
[hosting, corporate, consumer] - Usage type
"usageType": "consumer",
- 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/nameGOOGLE - 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 itFree 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, ...
- Нью-Йорк, Москва, Пекин, ...
- 纽约, 莫斯科, 北京, ...
- न्यूयॉर्क, मास्को, बीजिंग, ...
- マンハッタン, モスクワ, 北京市, ...
Contact Us With Additional Questions About Our IP Address Location API Developer Documentation
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.