Developer documentation

Javascript API with dbip.js

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.

Using dbip.js is the easiest way to write location-aware client side applications. You simply start by enabling the Javascript API with the following addition to your HTML code :

<script src=""

Get visitor info

In order to fetch information about the visitor IP address you just make a call to dbip.getVisitorInfo()

The function returns a Promise object that resolves to the visitor information :

Autofill form fields

Make signup or order forms quicker and easier for your visitors and autofill the country field with their originating country.

When you add a data-auto-select-country attribute to dbip.js script tag, it will automatically fill visitor country for select elements that have a dbip-auto-select-country class :

Alternatively you can use the dbip.autoSelectCountry() method to autofill dynamically loaded forms :

dbip.autoSelectCountry() can optionally take a DOM selector as parameter and returns a Promise object :

Convert currencies

The Core and Extended APIs provide automatic price conversions into your visitors currencies.

When you add a data-auto-convert-currencies attribute to the dbip.js script tag, it will automatically convert currencies for elements that have a dbip-convert-currency class :

Alternatively you can use the dbip.convertCurrencies() method to convert dynamically loaded amounts or provide on-demand conversion to your visitors :

dbip.convertCurrencies() can optionally take a DOM selector as parameter and returns a Promise object.

Advanced conversion options

When an amount has been converted, a converted class is added so you can use CSS to show or hide it as you see fit. The example below shows how to always display the base currency and only show the converted amount when necessary.

data-format attributes if present are used to customize the format of the displayed amount. The {amount} is replaced by the actual converted amount.

The data-currency-display attribute may be added to either the global dbip.js script tag or individial elements. It specifies how the currency is to be displayed and can be symbol ($), code (USD), or name (dollar).

The code example below is using a combination of those conversion options :

Browser geolocation

Browser geolocation is a useful feature that can provide more accurate results than IP address based geolocation. The drawback is that you cannot use it as a reliable source because it is often unavailable for various reasons such as browser support or user permissions.

dbip.getCurrentPosition is a drop-in replacement for the standard navigator.geolocation.getCurrentPosition method.

It takes the same parameters and returns the same values as its standard couterpart, the difference is that it never fails.

If the visitor has browser geolocation turned off or doesn't allow it before the specified timeout, the coordinates are looked up using their IP address :