Skip to content
instantgeo

Quickstart

1. Get a key

Create a free account — 20,000 requests a month, no card. Make a project, then a publishable key, and add the site you will call from to its allowlist.

You do not need to add localhost. It is always allowed on any port, so local development works immediately.

2. Call it

<script>
  fetch('https://api.instantgeo.info/v1/geo?key=ig_pk_yourkey')
    .then((r) => r.json())
    .then((geo) => {
      console.log(geo.country, geo.city, geo.timezone);
    });
</script>

That is it. No SDK required, no build step, no npm install.

3. Make it fast

Two lines, both worth more than they look:

<link rel="preconnect" href="https://api.instantgeo.info" />

in your <head> opens the connection while the rest of the page loads, taking the TLS handshake off the critical path.

And cache the result so a visitor browsing eight pages makes one request rather than eight. Caching is a few lines and the single biggest thing you can do for both latency and quota.

What you get back

On the free tier:

{
  "country": "GB",
  "countryName": "United Kingdom",
  "continent": "EU"
}

Paid plans add city, region, timezone, the caller’s IP, coordinates, postal code, ASN, and derived currency and language fields. See the API reference for the full list and plans for what each tier includes.

Trim the payload

Ask for only what you use:

?key=ig_pk_yourkey&fields=country,timezone
{ "country": "GB", "timezone": "Europe/London" }

?fields only ever narrows what your plan already allows — asking for a paid field on the free tier returns nothing, not an upgrade.

When it does not work

The error body always says what went wrong and what to do about it, and links to a page here. The one you are most likely to hit first is 403 origin_not_allowed — it means the site you called from is not on the key’s allowlist yet, and the message names the exact origin to add.