IP Geolocation API: Complete Developer Guide

What is IP Geolocation?

IP geolocation is the process of determining the physical location of a device using its IP address. Every device connected to the internet has an IP address, and these addresses are allocated to ISPs and organizations in geographic blocks. By mapping these allocations, an IP geolocation API can determine a visitor's country, region, city, postal code, coordinates, and timezone — all from a single API call.

Unlike GPS or browser-based geolocation (which requires user permission), IP geolocation works server-side with no client interaction. This makes it ideal for use cases where you need location data before the page loads or without prompting the user.

How IP Geolocation Works

IP geolocation databases are built by mapping IP address ranges to geographic locations. Here's how the process works:

1. IP allocation records: Regional Internet Registries (ARIN, RIPE, APNIC, etc.) publish which IP blocks are assigned to which organizations and in which countries.
2. ISP and organization mapping: ISPs are assigned IP ranges for specific service areas. By mapping ISPs to their coverage areas, geolocation databases can narrow down locations to the region or city level.
3. Active probing and crowdsourced data: Network measurements like latency-based triangulation and crowdsourced Wi-Fi/GPS correlations refine city-level accuracy.
4. Continuous updates: IP allocations change as ISPs expand, merge, or reassign blocks. Geolocation databases are updated regularly to maintain accuracy.

When you call an IP geolocation API, it looks up the IP address in its pre-indexed database and returns the associated location data. This is why lookups are extremely fast — typically under 50ms — since there's no real-time network tracing involved.

What Data Does the API Return?

A typical IP geolocation API response includes a rich set of location and network data. Here's what Sthan.io's IP Geolocation API returns:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "result": {
        "ipAddress": "8.8.8.8",
        "country": "United States",
        "countryCode": "US",
        "region": "California",
        "city": "Mountain View",
        "postalCode": "94043",
        "latitude": 37.386,
        "longitude": -122.0838,
        "timezone": "America/Los_Angeles",
        "continent": "North America"
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Response Fields Explained

Getting Started

Before making your first API call, you need:

• A Sthan.io account (sign up for free — no credit card required)
• Your Profile Name and Profile Password from the Sthan.io Dashboard

The free tier includes 50,000 IP lookups per month, which is more than enough for development, testing, and many production applications.

Authentication

Sthan.io uses a 2-step JWT authentication flow. First, get a token, then use it for API calls.

Step 1: Get a JWT Token

Send a GET request to /Auth/Token with your credentials in the headers:

curl -X GET "https://api.sthan.io/Auth/Token" \
  -H "profileName: YOUR_PROFILE_NAME" \
  -H "profilePassword: YOUR_PROFILE_PASSWORD"

Response:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "result": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "expiration": "2026-03-08T21:00:00Z"
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Step 2: Use the Token

Include the token as a Bearer token in the Authorization header for all subsequent API calls. Tokens expire after a set period, so your code should handle token refresh.

Your First IP Lookup

With your token in hand, you can look up any IP address. The endpoint is:

GET /IpGeolocation/{ip}

Replace {ip} with an IPv4 or IPv6 address. Here are complete examples in four languages.

cURL

# Step 1: Get token
TOKEN=$(curl -s "https://api.sthan.io/Auth/Token" \
  -H "profileName: YOUR_PROFILE_NAME" \
  -H "profilePassword: YOUR_PROFILE_PASSWORD" \
  | jq -r '.result.access_token')

# Step 2: Look up an IP address
curl -s "https://api.sthan.io/IpGeolocation/8.8.8.8" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.result'

JavaScript (Node.js)

const API_BASE = "https://api.sthan.io";

async function getToken(profileName, profilePassword) {
    const response = await fetch(`${API_BASE}/Auth/Token`, {
        headers: {
            profileName,
            profilePassword
        }
    });
    const data = await response.json();
    return data.result.access_token;
}

async function lookupIp(token, ip) {
    const response = await fetch(`${API_BASE}/IpGeolocation/${ip}`, {
        headers: {
            Authorization: `Bearer ${token}`
        }
    });
    const data = await response.json();
    return data.result;
}

// Usage
const token = await getToken("YOUR_PROFILE_NAME", "YOUR_PROFILE_PASSWORD");
const location = await lookupIp(token, "8.8.8.8");

console.log(`${location.city}, ${location.region}, ${location.country}`);
// Output: Mountain View, California, United States

Python

import requests

API_BASE = "https://api.sthan.io"

# Step 1: Authenticate
auth_response = requests.get(
    f"{API_BASE}/Auth/Token",
    headers={
        "profileName": "YOUR_PROFILE_NAME",
        "profilePassword": "YOUR_PROFILE_PASSWORD",
    },
    timeout=10,
)
auth_response.raise_for_status()
token = auth_response.json()["result"]["access_token"]

# Step 2: Look up an IP address
geo_response = requests.get(
    f"{API_BASE}/IpGeolocation/8.8.8.8",
    headers={"Authorization": f"Bearer {token}"},
    timeout=10,
)
geo_response.raise_for_status()
location = geo_response.json()["result"]

print(f"{location['city']}, {location['region']}, {location['country']}")
# Output: Mountain View, California, United States

C# (.NET)

using System.Net.Http.Json;
using System.Text.Json;

var client = new HttpClient();
var apiBase = "https://api.sthan.io";

// Step 1: Authenticate
var authRequest = new HttpRequestMessage(HttpMethod.Get, $"{apiBase}/Auth/Token");
authRequest.Headers.Add("profileName", "YOUR_PROFILE_NAME");
authRequest.Headers.Add("profilePassword", "YOUR_PROFILE_PASSWORD");

var authResponse = await client.SendAsync(authRequest);
authResponse.EnsureSuccessStatusCode();

var authData = await authResponse.Content.ReadFromJsonAsync<JsonDocument>();
var token = authData.RootElement
    .GetProperty("result")
    .GetProperty("access_token")
    .GetString();

// Step 2: Look up an IP address
var geoRequest = new HttpRequestMessage(HttpMethod.Get, $"{apiBase}/IpGeolocation/8.8.8.8");
geoRequest.Headers.Add("Authorization", $"Bearer {token}");

var geoResponse = await client.SendAsync(geoRequest);
geoResponse.EnsureSuccessStatusCode();

var geoData = await geoResponse.Content.ReadFromJsonAsync<JsonDocument>();
var result = geoData.RootElement.GetProperty("result");

Console.WriteLine($"{result.GetProperty("city")}, {result.GetProperty("region")}, {result.GetProperty("country")}");
// Output: Mountain View, California, United States

Real-World Use Cases

IP geolocation powers a wide range of features across industries. Here are the most impactful use cases with implementation guidance.

1. Content Personalization

Automatically adapt your application based on where visitors are located. This creates a more relevant experience without requiring users to manually set their preferences.

• Currency & pricing: Show prices in the visitor's local currency. An e-commerce site can display USD for US visitors and EUR for European visitors.
• Language: Pre-select the user's language based on their country code. Use the countryCode field to map to your supported languages.
• Region-specific content: Show local promotions, store locations, or shipping estimates based on the visitor's region.
• Timezone-aware scheduling: Use the timezone field to display dates, times, and deadlines in the visitor's local timezone.

// Example: Auto-select currency based on visitor location
async function getVisitorCurrency(token, visitorIp) {
    const location = await lookupIp(token, visitorIp);

    const currencyMap = {
        US: "USD", GB: "GBP", DE: "EUR", FR: "EUR",
        JP: "JPY", IN: "INR", CA: "CAD", AU: "AUD"
    };

    return currencyMap[location.countryCode] || "USD";
}

2. Fraud Prevention

IP geolocation is one of the most effective signals for detecting fraudulent activity. Use it to add a location-based risk layer to your security.

• Login anomaly detection: Compare the login IP's location with the user's known locations. Flag logins from unexpected countries or regions.
• Billing address mismatch: Compare the IP's country with the billing address country at checkout. A mismatch is a common fraud signal.
• Impossible travel: If a user logs in from New York and then from Tokyo 30 minutes later, flag the second session for review.

# Example: Detect suspicious login location
def check_login_risk(token, login_ip, user_country):
    """Compare login IP location with the user's registered country."""
    location = lookup_ip(token, login_ip)

    if location["countryCode"] != user_country:
        return {
            "risk": "high",
            "reason": f"Login from {location['country']} "
                       f"(expected: {user_country})",
            "ip": login_ip,
            "city": location["city"],
        }

    return {"risk": "low"}

3. Geo-Restrictions & Compliance

Some content and services need to be restricted by geography due to licensing agreements, regulations, or sanctions compliance.

• Content licensing: Streaming services restrict content libraries by region. Use the countryCode to enforce access rules.
• Regulatory compliance: Financial services, gambling platforms, and healthcare applications may need to restrict access based on jurisdiction.
• Export controls: Block access from sanctioned countries or regions as required by your legal obligations.

// Example: Geo-restriction middleware in ASP.NET Core
public class GeoRestrictionMiddleware
{
    private static readonly HashSet<string> BlockedCountries = new()
    {
        "KP", "IR", "SY"  // Example sanctioned country codes
    };

    public async Task InvokeAsync(HttpContext context, IIpGeolocationService geoService)
    {
        var ip = context.Connection.RemoteIpAddress?.ToString();
        if (ip != null)
        {
            var location = await geoService.LookupAsync(ip);
            if (BlockedCountries.Contains(location.CountryCode))
            {
                context.Response.StatusCode = 403;
                await context.Response.WriteAsync("Service not available in your region.");
                return;
            }
        }

        await _next(context);
    }
}

4. Analytics & Reporting

Enrich your analytics with geographic context to understand where your users are and how usage varies by region.

• Traffic origin dashboards: Visualize where your traffic comes from on a map using latitude/longitude coordinates.
• Regional conversion rates: Break down sign-ups, purchases, and engagement by country or region to identify growth opportunities.
• Timezone distribution: Understand when your users are most active by mapping their timezones, helping you schedule releases, maintenance, and campaigns.

Understanding Accuracy Levels

IP geolocation accuracy isn't uniform — it varies by the level of detail you need and the type of IP address.

Factors That Affect Accuracy

• IP type: Fixed broadband IPs (home/office) are the most accurate. Mobile IPs shift as users move. VPN and proxy IPs reflect the server location, not the user.
• ISP centralization: Some ISPs route traffic through a single point-of-presence, making all their users appear to be in one city.
• CGNAT (Carrier-Grade NAT): Many mobile carriers and some ISPs share a single public IP among thousands of users, reducing location precision.
• Regional coverage: Accuracy tends to be highest in North America and Western Europe, and lower in regions with less IP allocation data.

Best Practices

1. Cache Results

IP geolocation data doesn't change frequently. Cache results for at least 24 hours to reduce API calls and latency. Use the IP address as the cache key.

# Example: Simple in-memory cache with TTL
from functools import lru_cache
from datetime import datetime, timedelta

_cache = {}
CACHE_TTL = timedelta(hours=24)

def lookup_ip_cached(token, ip):
    """Look up IP with 24-hour cache."""
    now = datetime.utcnow()

    if ip in _cache:
        result, cached_at = _cache[ip]
        if now - cached_at < CACHE_TTL:
            return result

    result = lookup_ip(token, ip)
    _cache[ip] = (result, now)
    return result

2. Handle Errors Gracefully

Don't let a geolocation API failure break your application. Always have a fallback.

• If the API is unavailable, default to a sensible fallback (e.g., US/English).
• If an IP can't be located (private IPs, localhost), handle it as "unknown" rather than erroring out.
• Set reasonable timeouts (5–10 seconds) so a slow response doesn't block your page load.

3. Respect User Preferences

IP geolocation provides a smart default, but always let users override it. Common patterns:

• Auto-detect country/language, but show a dropdown to change it.
• Store the user's explicit preference in a cookie or profile — once they choose, stop relying on IP.
• For logged-in users, prefer their profile settings over IP geolocation.

4. Don't Over-Rely on IP for Security

IP geolocation is a useful signal, not a definitive answer. For security-critical decisions:

• Combine IP location with device fingerprinting, user behavior, and authentication factors.
• Be aware that VPNs, proxies, and Tor can mask true locations.
• Use IP geolocation to flag suspicious activity for review, not to automatically block users.

5. Consider Privacy

IP geolocation processes personal data (IP addresses). Follow these privacy guidelines:

• Document your legal basis for processing (legitimate interest for fraud prevention, consent for analytics).
• Mention IP geolocation in your privacy policy.
• Don't store raw IP addresses longer than necessary — store the derived location data instead where possible.
• For EU visitors (GDPR), ensure your data processing agreements cover the IP geolocation provider.