IP Geolocation API | JuheAPI Document

As developers, we're often tasked with creating personalized experiences for our users. One of the most effective ways to do this is by understanding their geographic location. Whether it's to display local content, pre-fill a form, or assess security risks, getting a user's location from their IP address is a foundational skill.

This tutorial will walk you through the entire process of integrating IP geolocation into your app with a single, simple API call. We'll be using the [IP Geolocation API], which is known for its fast response times, rich data fields, and developer-friendly JSON format, making it perfect for any project.

Step 1: Prerequisites - Get Your API Key

Before we start writing code, you need an API key to authenticate your requests.

Navigate to our API Marketplace and create a free account.
Go to your user dashboard and find the "API Keys" section.
Generate a new key for your project.

Copy this key and keep it safe. We'll need it in a moment.

Step 2: Understanding the API Endpoint & Data Structure

Let's quickly review the API's structure.

API Endpoint: All requests will be made to a simple GET endpoint: https://api.juheapi.com/ip2location/v1/query
Request Parameters: You'll pass two main parameters in the query string:
- key: Required. Your unique API key.
- ip: Required. The IP address you want to look up.

The JSON Response: A successful API call returns a clean JSON object packed with useful information. Here’s an example:

{
  "code": "OK",
  "msg": "Success",
  "data": {
    "ip": "8.8.8.8",
    "ip_version": 4,
    "country_name": "United States",
    "country_code": "US",
    "city_name": "Mountain View",
    "region_name": "California",
    "zip_code": "94043",
    "time_zone": "-07:00",
    "lat": 37.4229,
    "lon": -122.085
  }
}

Key fields include country_name and city_name for localization, lat and lon for mapping, and time_zone for displaying local times.

Step 3: Implementation Walkthrough - Code Examples

Now, let's bring this to life with code.

Python Example (Backend)

On your server, you can get the visitor's IP from the request headers and look up its location. This is ideal for logging, fraud detection, or server-side rendering.

import requests
import json

def get_geolocation_from_ip(api_key, ip_address):
    """
    Fetches geolocation data for a given IP address using the API.

    :param api_key: Your API key.
    :param ip_address: The IP address to look up.
    :return: A dictionary with geolocation data or None on error.
    """
    api_url = "https://api.juheapi.com/ip2location/v1/query"
    params = {
        'key': api_key,
        'ip': ip_address
    }

    try:
        response = requests.get(api_url, params=params, timeout=5)
        # Raise an HTTPError for bad responses (4xx or 5xx)
        response.raise_for_status()

        # Return the 'data' object from the JSON response
        return response.json().get("data")

    except requests.exceptions.RequestException as e:
        print(f"API request failed: {e}")
        return None

# --- Example Usage ---
API_KEY = "YOUR_API_KEY"  # Replace with your key
visitor_ip = "8.8.8.8"  # In a real app, get this from request headers

location_data = get_geolocation_from_ip(API_KEY, visitor_ip)

if location_data:
    print("Geolocation Data:")
    print(json.dumps(location_data, indent=2))
    city = location_data.get("city_name")
    if city:
        print(f"\nWelcome, visitor from {city}!")

JavaScript Example (Frontend)

In the browser, you can use the API to create a dynamic user experience, like personalizing a welcome message. Note: To get the user's IP on the client-side, you typically need a service or can pass it from your backend. For simplicity, we'll use a placeholder.

<!-- HTML Structure -->
<h1>Welcome, valued visitor!</h1>
<p id="location-greeting"></p>

<script>
    // In a real application, you would need a way to get the user's IP.
    // For this demo, we'll use a sample IP.
    const userIp = "208.67.222.222";
    const apiKey = "YOUR_API_KEY"; // Replace with your key

    async function fetchLocationAndGreet(ip) {
        const greetingElement = document.getElementById('location-greeting');
        const apiUrl = `https://api.juheapi.com/ip2location/v1/query?key=${apiKey}&ip=${ip}`;

        greetingElement.textContent = "Customizing your experience...";

        try {
            const response = await fetch(apiUrl);
            const result = await response.json();

            if (response.ok && result.data) {
                const city = result.data.city_name;
                const country = result.data.country_name;
                if (city && country) {
                    greetingElement.textContent = `We see you're visiting from ${city}, ${country}. Enjoy your stay!`;
                } else {
                    greetingElement.textContent = "Enjoy your stay!";
                }
            } else {
                greetingElement.textContent = "Could not customize your experience.";
            }
        } catch (error) {
            console.error("Geolocation fetch failed:", error);
            greetingElement.textContent = "Could not retrieve location information.";
        }
    }

    // Call the function on page load
    fetchLocationAndGreet(userIp);
</script>

Step 4: A Quick Use Case & Error Handling

A great "quick win" is to use the time_zone data. You could parse the UTC offset to determine if it's morning, afternoon, or evening for the user and display a context-aware greeting.

Always remember to handle errors. Check the HTTP status code and the code or msg fields in the JSON response to gracefully manage situations like an invalid API key or a private IP address lookup.

Conclusion

It's that easy! With a single API call, you can now access a wealth of geographic information to build smarter, more personalized, and more secure applications.

Ready to build something amazing? Dive into the full API Documentation to see all available data points, or share your creations with fellow developers in our Developer Community!