How to Migrate from ipapi.co to IP Geo API in 2026: A Step-by-Step Drop-In Guide

7-minute read · 2026 code samples · honest rollback plan

This is the practical companion to the ipapi.co alternative comparison → and the head-on review of ipapi.co vs IP Geo API →. Those two pages tell you whether to switch. This page tells you how — including the three field-shape gotchas no other migration guide is honest about.

TL;DR — most ipapi.co → IP Geo API migrations land in half an engineering day. The real work is not the swap itself; it is removing the “Powered by ipapi” attribution from your free-tier code paths, the org-string ASN+name concatenation split, and a rollback path you actually trust.

Who this guide is for

You currently call ipapi.co via https://ipapi.co/{ip}/json/ (or one of the community SDKs), you’ve decided that the free-tier attribution backlink, the per-day-not-per-month rate limit, and USD-billed Stripe invoices cost more than they should, and you want a REST replacement that:

If those four boxes are unchecked — pause and read the vs comparison → first. The tradeoffs are real, especially if you depend on ipapi.co’s global Anycast latency from non-EU clients, the JSONP / XML / CSV response formats, or the Excel-style bulk CSV upload.

The 7-step migration checklist

  1. Inventory every call site that hits ipapi.co or ipapi.com, including any community SDK imports.
  2. Map your fields to the ipapi-compatibility response (?format=ipapi).
  3. Add a feature flag so you can switch any call site between providers.
  4. Wire a 60-second cache in front of the API client (in-memory or Redis).
  5. Deploy in shadow mode — call both, log differences, serve ipapi.co responses.
  6. Cut over gradually — 10% → 50% → 100% of traffic over 48 hours.
  7. Decommission the ipapi.co API key — revoke in the ipapi dashboard, archive billing, remove the attribution backlink.

The rest of this post walks each step with copy-paste code.

Step 1 — Inventory call sites

Run this in the repo root before touching anything:

git grep -nE "ipapi\.co|ipapi\.com|Powered by ipapi" -- ':!*.lock' ':!*.md'

Most teams find 1-4 call sites for ipapi.co. The endpoint is so simple (one HTTP GET, no auth on free tier) that direct requests.get / fetch calls are common — there’s often no SDK to grep. Make a list. Note for each: language, response format (JSON vs JSONP vs XML vs CSV), fields consumed, and whether the result is cached.

Watch-out: ipapi.co has two domains in the wild — the canonical ipapi.co and the older ipapi.com mirror. Both are owned by the same operator but have slightly different default response shapes (ipapi.co/json/ returns flat; ipapi.com/{ip}/json returns nested under geo.*). Audit both. Also grep for any HTML/JSX containing the literal string "Powered by ipapi" — the free-tier ToS requires this attribution and removing it from rendered pages is one of the steps users forget.

Step 2 — Map the fields

ipapi.co returns a flat JSON shape, with a single country.* style prefix expansion (the API flattens the country block into country, country_name, country_code_iso3, country_capital, country_population, country_area_sq_km, country_calling_code, country_currency, country_currency_name, country_languages, country_tld, in_eu):

{
  "ip": "8.8.8.8",
  "version": "IPv4",
  "city": "Mountain View",
  "region": "California",
  "region_code": "CA",
  "country": "US",
  "country_name": "United States",
  "country_code": "US",
  "country_code_iso3": "USA",
  "country_capital": "Washington",
  "country_tld": ".us",
  "continent_code": "NA",
  "in_eu": false,
  "postal": "94043",
  "latitude": 37.4056,
  "longitude": -122.0775,
  "timezone": "America/Los_Angeles",
  "utc_offset": "-0700",
  "country_calling_code": "+1",
  "currency": "USD",
  "currency_name": "Dollar",
  "languages": "en-US,es-US,haw,fr",
  "asn": "AS15169",
  "org": "GOOGLE"
}

IP Geo API ships an ?format=ipapi compatibility shim that returns the same flat shape so most call sites stop noticing the swap. The mapping for the fields ~95% of integrations rely on:

Your old code ipapi.co path IP Geo API ?format=ipapi Native ?format=ipgeo
IP ip ip ip
Country code country or country_code country and country_code country.iso_code
Country name country_name country_name country.name
Country ISO3 country_code_iso3 country_code_iso3 country.iso_code_alpha3
EU member flag in_eu in_eu country.in_eu
Country calling code country_calling_code country_calling_code country.calling_code
Region code region_code region_code region.iso_code
Region name region region region.name
City city city location.city
Postal postal postal location.postal_code
Lat latitude latitude location.lat
Lng longitude longitude location.lng
Time zone timezone timezone location.timezone
UTC offset utc_offset utc_offset location.utc_offset
ASN string asn (e.g. "AS15169") asn (string "AS15169") network.asn (integer 15169)
Org / ISP org org network.organization
Currency code currency currency country.currency.iso
VPN / proxy (paid only via /threat) is_proxy (free) threat.is_proxy
Tor (paid only) is_tor (free) threat.is_tor
Datacenter (paid only) is_datacenter (free) threat.is_datacenter
VPN (paid only) is_vpn (free) threat.is_vpn

Fields the shim does not cover (documented gaps): country_capital and country_population and country_area_sq_km (we do not import the world-fact-book enrichment — these are weak signals for almost every product use), languages comma-separated string (use Accept-Language request header parsing instead), country_tld (low signal, statically derivable from country_code if you really need it), and the version field (always "IPv4" or "IPv6" — read it from the input IP itself). If your code reads any of those, list them as blockers and decide per call site whether to drop the dependency or keep ipapi.co for that path only (hybrid pattern — see the comparison page →).

Step 3 — Feature flag, then drop-in client

Python (was raw requests against ipapi.co)

# before
import requests

def lookup_country(ip: str) -> str:
    r = requests.get(f"https://ipapi.co/{ip}/json/", timeout=2.0)
    r.raise_for_status()
    return r.json()["country"]

# after — drop-in via the ipapi-compatibility shim
import os, requests
from functools import lru_cache

API_KEY = os.environ["IPGEO_API_KEY"]
USE_IPGEO = os.environ.get("USE_IPGEO_API", "0") == "1"   # feature flag

@lru_cache(maxsize=10_000)
def _lookup(ip: str) -> dict:
    r = requests.get(
        f"https://api.ipgeo.10b.app/v1/{ip}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={"format": "ipapi"},
        timeout=2.0,
    )
    r.raise_for_status()
    return r.json()

def lookup_country(ip: str) -> str:
    if USE_IPGEO:
        return _lookup(ip)["country"]   # flat shape — no rewrite
    r = requests.get(f"https://ipapi.co/{ip}/json/", timeout=2.0)
    r.raise_for_status()
    return r.json()["country"]

Note the auth shape change: ipapi.co’s free tier is anonymous and rate-limited per source IP; IP Geo API uses a Bearer token in the Authorization header. If you currently pass ?key=... for an ipapi paid plan, that query-param auth is still supported on the new client too (?api_key=...) for environments where headers get stripped at the edge.

Node / TypeScript (was raw fetch against ipapi.co)

// before
const r = await fetch(`https://ipapi.co/${ip}/json/`);
const j = await r.json();

// after — drop-in
const cache = new Map<string, any>();
export async function geoLookup(ip: string) {
  if (process.env.USE_IPGEO_API !== "1") {
    const r = await fetch(`https://ipapi.co/${ip}/json/`);
    return r.json();
  }
  if (cache.has(ip)) return cache.get(ip);
  const r = await fetch(`https://api.ipgeo.10b.app/v1/${ip}?format=ipapi`, {
    headers: { Authorization: `Bearer ${process.env.IPGEO_API_KEY!}` },
  });
  if (!r.ok) throw new Error(`ipgeo ${r.status}`);
  const j = await r.json();
  cache.set(ip, j);
  setTimeout(() => cache.delete(ip), 60_000);   // 60-s TTL
  return j;
}

Go

// after — drop-in via the ipapi-compatibility shim
url := fmt.Sprintf("https://api.ipgeo.10b.app/v1/%s?format=ipapi", ip)
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("IPGEO_API_KEY"))
resp, err := httpClient.Do(req)
// ... unmarshal into your existing ipapi-shaped struct

Step 4 — Cache layer (the step everyone skips)

A naive 1-call-per-request integration will burn through ipapi.co’s free 1.000 req/day in the first hour of any production traffic. ipapi.co’s free-tier rate limit is per-day, not per-month, which fragments quota across the day in a way that surprises teams; IP Geo API’s daily ceiling is the same shape, but the populated threat-flag fields make the cache hit-rate higher (you stop calling out for repeat IPs flagged as bots). The good news: most production traffic is dominated by 1-5% of IPs (your bot crawler, your monitoring, your power users). A 60-second in-memory cache typically deflects 70-90% of calls at zero cost.

If you want strict cache-miss bounds, add a per-host concurrency limiter so only one in-flight call per IP is ever issued.

Step 5 — Shadow mode (the step that builds trust)

Before flipping any user-facing path: call both APIs and compare.

def lookup_country(ip: str) -> str:
    r = requests.get(f"https://ipapi.co/{ip}/json/", timeout=2.0)
    r.raise_for_status()
    legacy = r.json()["country"]
    if SHADOW_MODE:
        try:
            new = _lookup(ip)["country"]
            if new != legacy:
                logger.warning("ipapi-shadow-mismatch", extra={"ip": ip, "legacy": legacy, "new": new})
        except Exception as e:
            logger.error("ipapi-shadow-error", extra={"ip": ip, "error": str(e)})
    return legacy

Run shadow mode for 24-48 hours. The mismatch rate on country-level data is typically <0.5% (mostly recent IP-block reassignments where one source is fresher). City-level is 1-3%. ASN naming is the noisiest signal — both providers ship the same numeric ASN, but the org field differs in shape: ipapi.co returns the org as a single string (e.g. "GOOGLE"); IP Geo API’s native shape splits this into network.asn (integer) + network.organization (string). The shim re-concatenates so the legacy org field stays a string, but if you parse the org string with a regex that expects ^AS\d+\s+(.+)$ (a few community SDKs do), test it before flipping. The single biggest mismatch class for ipapi.co is the threat-flag block: ipapi.co’s free shadow path does not include is_vpn / is_proxy / is_tor, while IP Geo API returns populated values. Treat absent-vs-populated as a known-good signal, not a mismatch.

For most fraud / analytics rules the numeric ASN is the only field that matters; pin your match logic to that.

Step 6 — Gradual cutover

Once shadow logs are clean, flip a percentage of traffic via your feature-flag system (LaunchDarkly, Unleash, or a hashed-IP rollout):

import hashlib

def use_ipgeo(ip: str, percent: int) -> bool:
    h = int(hashlib.md5(ip.encode()).hexdigest(), 16)
    return (h % 100) < percent

Recommended ladder: 10% → 50% → 100% over 48 hours. Watch your existing fraud-flag dashboards for unexpected spikes; the bundled threat-flag block exposes signals that ipapi.co’s free tier did not, so if you wire is_vpn=true into a soft-block rule you may see a 5-15% bump in flagged sessions. This is not a regression — it is the threat data you were paying for separately on ipapi’s /threat endpoint, now bundled.

Step 7 — Decommission

Once 100% has been on IP Geo API for >7 days with no incidents:

  1. Revoke the ipapi.co API key (paid plan) in the ipapi dashboard, or simply stop calling the anonymous endpoint (free plan).
  2. Cancel the ipapi subscription (Stripe USD invoices stop on the next cycle).
  3. Remove the IPAPI_KEY env var from CI / production / staging (if applicable).
  4. Remove the “Powered by ipapi” attribution backlink from every page, email template, and embed that previously rendered it. This is the step most teams forget — the attribution requirement is in the free-tier ToS and removing it is half the reason you are migrating.
  5. Delete the legacy fallback branch from your code (keep the feature-flag scaffold for the next migration).
  6. Update your DPIA / Article 30 record — processor change from ipapi (US) to corem6 BV (NL/EU).

The 7 gotchas teams hit in week one

  1. Attribution backlink left in HTML. ipapi.co’s free tier ToS requires “Powered by ipapi” linking to https://ipapi.co. Teams switch the API call but forget the rendered backlink lives on a footer template, an email signature, or a status-page embed. Grep your templates, not just your call sites. Removing the backlink is half the reason you are migrating.
  2. asn string vs integer. ipapi.co returns "AS15169" (string with AS prefix). IP Geo API native returns 15169 (integer, no prefix); the shim preserves the "AS..." string format on the asn field but exposes the integer at network.asn. Code that does int(asn[2:]) on the legacy field continues to work; code that reads network.asn as a string will break. Pin a unit test on the type before flipping.
  3. org string concatenation. ipapi.co’s org is a single string like "GOOGLE" or "GOOGLE LLC". IP Geo API native splits ASN-org into network.asn (integer) + network.organization (string). The shim re-concatenates so the legacy org field stays a single string, but the org-name suffix shape can differ slightly between providers ("GOOGLE" vs "Google LLC"). If your fraud rules string-match on the org name, test against a sample of 50+ IPs before the 50% cutover.
  4. No cache layer. Quota burn in 4-6 hours on the free tier. Add the cache before flipping the flag — the per-day ceiling on ipapi.co is small enough that an unflagged production deploy can exhaust it before lunch.
  5. Outbound HTTPS blocked. Production VPC egress rules deny api.ipgeo.10b.app. Get firewall change scheduled before cutover. ipapi.co’s hostname (ipapi.co) was likely already allowlisted; the new hostname is not.
  6. Authorization header stripped at the edge. ipapi.co’s free tier is anonymous; IP Geo API uses a Bearer token in the Authorization header. Some CDNs / WAFs strip Authorization on calls to non-allowlisted hostnames. Test from prod before flipping >10%. (Workaround: pass the key as ?api_key=... query param instead — supported on every tier.)
  7. GDPR DPIA refresh. Switching processor classes (ipapi US → corem6 NL-only) usually triggers a one-page Article 30 update. Boring, but should be on the cutover checklist; it’s also the reason most teams started this migration in the first place.

What you’ll see in week two

Pairing pages

FAQ

How long does a real ipapi.co migration take? For a single-stack web app with 1-4 call sites and a working CI: half an engineering day end-to-end. Multi-stack monorepos with 10+ call sites: 1-2 days, mostly in shadow-mode tuning. The attribution-backlink scrub is the time sink, not the field-shape diff — grep your templates first.

Will my ipapi.co-shaped tests still pass? Yes — the compatibility shim returns the same flat JSON shape for the supported field set. For fields outside the shim (country_capital, country_population, country_area_sq_km, languages comma-separated string, country_tld), mock the new client path or move that logic to a dedicated reference-data source.

What about the SDK ergonomics? ipapi.co does not ship a first-party SDK; the SDKs in npm / PyPI under names like ipapi, ipapi-python, ipapicom-client are all community-maintained. Most callers are raw requests.get / fetch against the simple endpoint. We do not ship language SDKs in 2026 either — the API is small enough that a 10-line client is faster than a SDK.

What’s the rollback story if something goes wrong? The feature flag gives you a 1-second flip back to ipapi.co. Keep the (free or paid) ipapi.co integration working for at least 30 days post-cutover. Most teams keep the attribution backlink in a feature-flagged template branch until the 30-day mark for instant fallback.

Can I migrate one service at a time? Yes — and it’s the recommended approach. Each call site is independent. Migrate the lowest-risk one first (often a dashboard analytics path or a server-side log enrichment job), measure for a week, then move to the next. There is no all-or-nothing requirement.

What about ipapi.co’s JSONP / XML / CSV response formats? Those are formats ipapi.co inherited from a 2014-era web stack. We support JSON only (REST and JSON:API content-types). If your code reads JSONP from a <script> tag or parses the XML response, refactor to JSON fetch first — this is a one-hour cleanup that pays back independently of which provider you end up on.

What if I was on the free tier with the attribution backlink? Then this migration is also a brand-cleanup for you — IP Geo API’s free tier has no attribution requirement, so any white-label embed, footer, or email template that previously rendered “Powered by ipapi” can be cleaned up. This is the single most common reason side-project teams in the first hour of evaluation hit this guide.

What about ipapi.co’s Excel-style bulk CSV upload? ipapi.co’s /bulk/ endpoint accepts a CSV of IPs and returns a CSV of results. We support the same workflow via a JSON POST to /v1/bulk with up to 100 IPs per call (paginate for larger batches). For one-off CSV-in-CSV-out workflows, a 20-line Python script using the JSON endpoint is shorter than the original CSV upload code.

Related migration & comparison reading

Industry deep-dives


Last reviewed 2026-05-09 · IP Geo API team · Comments / corrections: hello@ipgeo.10b.app

Pairs with the full ipapi.co alternative comparison page and the head-on IP Geo API vs ipapi.co review.


Get early access — 50% off for 12 months

First 100 signups lock in 50% off any paid plan for the first year. No credit card required — we’ll email you at launch.