Know where your visitor is, with one tag
Show a visitor their country, pick a currency, or change a shipping notice without writing the request yourself. The script asks our API once per visit, keeps the answer in the visitor’s own browser, and fills in your page.
- Free, no key
- One request per visit
- No cookies
- About 3 KB
<script src="https://ipaddress.to/embed/v1/" async crossorigin data-fields="location.country,location.currency"> </script> Shipping to <b data-ipa="location.country">your country</b>, prices in <span data-ipa="location.currency.code">USD</span>.
Quick start
Put the script anywhere on the page, then mark the elements that should receive a value with data-ipa. Whatever you write inside the element is the fallback: it stays if the value is unknown, the request fails, or the visitor blocks scripts.
<script src="https://ipaddress.to/embed/v1/" async crossorigin
data-fields="location.country,location.country_code,location.currency"></script>
<p>
Shipping to <b data-ipa="location.country">your country</b>,
prices in <span data-ipa="location.currency.code">USD</span>.
</p>That is the whole integration. A visitor in Canada sees “Shipping to Canada, prices in CAD.” Everyone else sees their own country, and anyone the lookup cannot place sees the text you wrote.
Script tag options
All optional. Set them as attributes on the script tag.
location.country_code,location.currency. The API then returns only those, which makes the response a few hundred bytes instead of about 1 KB. Leave it out to get everything. See the field list.session (default) remembers the answer until the tab is closed. local remembers it across visits. off asks every time.1800 (30 minutes). A visitor who switches networks gets a fresh answer once it expires.4000.data-ipa elements. Use it when you only want the CSS classes or the event.Without data-auto and without any data-ipa element, the script loads and does nothing until you call it from JavaScript. No request is made.
Filling the page from HTML
location.city, location.currency.code, asn.org. The element’s text is replaced with the value.{value}, only that token is replaced (and URL-encoded). Event-handler attributes are refused.<!-- a link that carries the visitor's country -->
<a data-ipa="location.country_code" data-ipa-attr="href"
href="/stores?country={value}">Find a store near you</a>
<!-- a notice for some countries only -->
<p data-ipa="location.country_code" data-ipa-show="CA,US" hidden>
Free shipping across North America.
</p>
<!-- and one for everyone else -->
<p data-ipa="location.country_code" data-ipa-hide="CA,US">
International shipping from $12.
</p>Start elements that should be hidden by default with the hidden attribute, as in the first notice above, so nothing flashes before the answer arrives.
CSS classes
After a successful lookup the script adds classes to the <html> element, so simple cases need no JavaScript at all.
ipa-cc-us, ipa-cc-de. Needs location.country_code in your field list.location.is_eu_member.is_vpn, is_proxy, is_tor..vat-notice { display: none; }
.ipa-eu .vat-notice { display: block; }
.price-gbp { display: none; }
.ipa-cc-gb .price-gbp { display: inline; }
.ipa-cc-gb .price-usd { display: none; }JavaScript API
The script defines one global, IPAddressTo. Because the tag is async, wait for it before calling: either put your code in the tag’s onload, or listen for the event described below.
locate() and fills every data-ipa element under root (default: the whole document). Call it again after you add elements to the page, for example in a single-page app. It costs no extra request.IPAddressTo.get(data, "location.currency.code"). Returns undefined instead of throwing when part of the path is missing.1.0.1.options takes the same settings as the tag, in camel case: fields (string or array), cache ("session", "local" or false), maxAge, timeout, key. Options passed to a call override the attributes on the tag.
<script src="https://ipaddress.to/embed/v1/" async crossorigin onload="pickCurrency()"></script>
<script>
function pickCurrency() {
IPAddressTo.locate({ fields: ['location.country_code', 'location.currency.code'] })
.then(function (data) {
var currency = data.location.currency ? data.location.currency.code : 'USD';
document.querySelector('#currency').value = currency;
})
.catch(function () {
// Lookup failed or timed out. Keep your default and carry on.
});
}
</script>Events
In automatic mode the script reports the outcome on document, so code elsewhere on the page can react without knowing when the script loaded.
event.detail is the lookup result.event.detail.message says why: timeout, a network error, or the API’s error text.document.addEventListener('ipaddressto:ready', function (event) {
var where = event.detail.location;
analytics.track('visitor_country', { country: where.country_code });
});Fields
Ask only for what the page uses. Name a single value (location.country_code) or a whole group (location). The ones storefronts use most:
Canada.CA.America/Toronto.code (CAD) and name (Canadian Dollar).The complete response is shown under IP Lookup. Every field there can be requested the same way.
Without the script
If you would rather make the request yourself, the same fields option works on the plain endpoint. Please remember the answer for the rest of the visit: a visitor’s country does not change between your product page and your cart, and one request per visit is faster for them than one per page.
async function visitorCountry() {
const saved = sessionStorage.getItem('visitor-country');
if (saved) return JSON.parse(saved);
const res = await fetch(
'https://ipaddress.to/api/lookup/my?fields=location.country_code,location.currency'
);
const data = await res.json();
if (!data.success) throw new Error(data.error);
sessionStorage.setItem('visitor-country', JSON.stringify(data));
return data;
}{
"success": true,
"location": {
"country_code": "CA",
"currency": { "code": "CAD", "name": "Canadian Dollar" }
}
}How it behaves
async, the script never blocks rendering. If our service is slow or down, the visitor sees your fallback text after the timeout and nothing else on the page is affected.crossorigin attribute on the tag. With it, the browser makes the lookup over the connection it opened to fetch the script; without it, it opens a second connection first, which costs two extra round trips. Asking for only the fields you use also skips work on our side: a country-and-currency lookup is answered in a few milliseconds. To shave the first visit further, add <link rel="preconnect" href="https://ipaddress.to" crossorigin> to your <head>.ipaddressto:error event and the ipa-failed class.sessionStorage (or localStorage if you choose it) under keys starting ipa:v1:. No cookies are set. If storage is blocked, the script still works and simply asks again on the next page.fetch and Promise, which is every browser released since 2017. Older ones keep the fallback text./embed/v1/ will keep working as documented here. Fixes are published to the same address and reach browsers within a few hours. Incompatible changes would ship as /embed/v2/. Because the file can receive fixes, do not pin it with a Subresource Integrity hash.https://ipaddress.to in both script-src and connect-src.Credit
The embed is free and a link back is not required. If it is useful to you, a small credit in your footer or on your about page helps other people find the service, and we are grateful for it.
<a href="https://ipaddress.to/">IP geolocation by IPAddress.to</a>
Running this on a busy site? Tell us. We would rather make room for your traffic than be surprised by it, and we can let you know before anything changes.