Skip to content
instantgeo

Migrating from v1

If you landed here from a _notice field or a 410 response, this page is for you.

The short version

The old endpoint returned geolocation to anyone who asked, with no key. That is being replaced by an endpoint that needs a free API key. Getting one takes about a minute and covers 20,000 requests a month with no card.

Old:

fetch('https://js.instantgeo.info/json')

New:

fetch('https://api.instantgeo.info/v1/geo?key=ig_pk_yourkey')

The field names and shapes are unchanged.

Read this part before you migrate. The old endpoint returned city, region, coordinates and postal code to anyone, with no key. The new free tier is country-level only — country, countryName, continent. If your site uses city, timezone, coordinates or postal code, a free key will not cover you and you need a paid plan. That is a real change, not a technicality, and it is better to find out here than from a broken store locator.

I did not know I was using this

You are probably not imagining it. instantgeo is bundled into at least one widely used Shopify theme as a fetch call, so a lot of stores call it without their owner ever having chosen it.

If your store shows a _notice in a console error, or something regional stopped working:

  1. Check your theme first. Search your theme files for instantgeo. If your theme vendor ships the call, the right fix is for them to update it — tell them, or point them at this page.
  2. If you need it working today, get a free key and replace the URL in your theme. Note that a theme update may overwrite it.
  3. If you are the theme author, get in touch. We would rather work something out with you than break your users’ storefronts.

Timeline

StageWhat happens
Nowv1 works exactly as before
+30 daysResponses gain a _notice field and Deprecation / Sunset headers. Data is unchanged.
+60 daysv1 returns country-level fields only, and is rate limited per IP
+120 daysv1 returns 410 Gone with a pointer here

Each stage is a configuration change we can reverse in seconds, and we will watch what breaks rather than advancing on the calendar alone.

Field differences

Field names and types are unchanged. Two things to know:

  • _notice appears only on the deprecated v1 endpoint. It is never present on the new API.
  • The free tier returns country, countryName and continent. Everything else — city, region, timezone, the caller’s IP, coordinates, postal code, ASN, currency and languages — needs a paid plan. See plans.

If you only used country, the free tier covers you completely. If you used city or coordinates, you need Starter or above.

Once you have a key

Two things worth doing while you are in there, both covered in caching:

  • Cache the result per session, so a visitor browsing several pages makes one request rather than one per page
  • Add <link rel="preconnect" href="https://api.instantgeo.info"> to your <head>

The official client does the caching for you in under 1KB.

Something is broken and this page did not help

Email us. Include the URL of the page making the call. We would much rather hear from you than have your storefront quietly stop working.