Name: IP Geolocation API: Country, City, ISP & Timezone Lookup
Brand: viv-data
SKU: api-viv-data-ipgeo
Availability: InStock
Author: API Market

gia ly bui

# IP Geolocation — Country, City, ISP Lookup

## Overview
The IP Geolocation API provides a straightforward solution to instantly look up comprehensive geographic and network information for any given IP address. It accurately returns details such as country, city, region, Internet Service Provider (ISP), and timezone. This powerful tool is essential for developers needing to integrate real-time geolocation data into their applications, enhancing user experience, improving security, and enabling location-aware functionalities. If no IP address is provided in the request, the API automatically detects and returns information for the caller's own IP.

## Features
*   **Comprehensive Geolocation:** Retrieves country, country code, city, region, and timezone data.
*   **ISP Lookup:** Identifies the Internet Service Provider associated with the IP address.
*   **Flexible Input:** Supports looking up specific IP addresses or automatically detecting the caller's IP.
*   **Fast & Reliable:** Built for quick responses, leveraging a robust data source with cached results for efficiency.
*   **Developer-Friendly:** Simple API design with clear request and response formats.
*   **Free Tier Available:** Start with 1,000 requests per month at no cost.

## Use Cases
1.  **Fraud Detection & Prevention:** Enhance security by identifying suspicious login attempts or transactions originating from unexpected geographic locations or known proxy/VPN IP addresses.
2.  **Content Localization & Personalization:** Dynamically tailor website content, language, currency, or product offerings based on a user's geographic location, improving engagement and conversion rates.
3.  **Website Analytics & Traffic Analysis:** Gain insights into your audience's geographical distribution, track visitor origins, and optimize marketing campaigns for specific regions.
4.  **Cybersecurity & Threat Intelligence:** Pinpoint the origin of cyber threats, track malicious activity, and enforce geo-fencing policies to restrict access from high-risk regions.
5.  **Advertising & Marketing Targeting:** Deliver highly relevant advertisements and promotional content to users based on their city, region, or country, maximizing campaign effectiveness.

## Pricing
This API offers flexible pricing tiers based on your usage volume.
*   1 API unit equals 1 IP lookup.
*   **Free:** 1,000 requests per month.
*   **Pro:** $19.99 for 10,000 requests per month.

## API Documentation

### Base URL
All API requests should be made to:
`https://prod.api.market/api/v1/viv-data/ipgeo`

### Authentication
Authentication is handled via an API key. Include your API key in the request header for all API calls:

```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Endpoints

#### `GET /lookup`
Look up the geographic location and ISP details for any IP address.

*   **Summary:** Look up geolocation data for an IP address.
*   **Operation ID:** `lookup_lookup_get`

**Parameters:**

| Name | In    | Type   | Required | Description                               | Default |
| :--- | :---- | :----- | :------- | :---------------------------------------- | :------ |
| `ip` | query | string | false    | IP address. Leave empty for your own IP. | ""      |

**Example Request: Look up your own IP**

```bash
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/ipgeo/lookup" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"
```

**Example Request: Look up a specific IP address (e.g., Google's DNS server)**

```bash
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/ipgeo/lookup?ip=8.8.8.8" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"
```

**Example Response (200 OK):**

```json
{
  "ip": "8.8.8.8",
  "country": "United States",
  "country_code": "US",
  "city": "Mountain View",
  "region": "California",
  "isp": "Google LLC",
  "timezone": "America/Los_Angeles",
  "error": ""
}
```

#### `GET /health`
A simple health check endpoint to verify the API service is operational.

*   **Summary:** Health check.
*   **Operation ID:** `health_health_head`

**Example Request:**

```bash
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/ipgeo/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"
```

**Example Response (200 OK):**

```json
{}
```

#### `GET /`
Root endpoint, typically used for basic service discovery or a minimal response.

*   **Summary:** Root endpoint.
*   **Operation ID:** `root__get`

**Example Request:**

```bash
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/ipgeo/" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"
```

**Example Response (200 OK):**

```json
{}
```

## Status Codes
| Code | Meaning                     | Description                                                                                                                                                                                                                                                                                                          |
| :--- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                          | Request successful. The requested data (e.g., IP geolocation) is returned in the response body.                                                                                                                                                                                                                        |
| 201  | Created                     | Resource successfully created. (Less common for this synchronous API, but included for completeness).                                                                                                                                                                                                                  |
| 400  | Bad Request                 | Invalid input parameters or malformed request. Check your request body, query parameters, or headers for errors. The response body may contain details about the specific validation error.                                                                                                                             |
| 401  | Unauthorized                | Missing or invalid API key. Ensure you include your `x-api-market-key` header with a valid key.                                                                                                                                                                                                                      |
| 403  | Forbidden                   | Valid API key but insufficient permissions to access the resource or perform the action. This can also indicate an API key restricted from this particular API or operation.                                                                                                                                       |
| 404  | Not Found                   | The requested resource (endpoint URL) was not found. Check the endpoint path for typos.                                                                                                                                                                                                                              |
| 422  | Unprocessable Entity        | The request was well-formed but could not be processed due to semantic errors. This often indicates issues with the data provided, such as an invalid IP format. The response typically includes `HTTPValidationError` details.                                                                                        |
| 429  | Too Many Requests           | Rate limit exceeded. You have sent too many requests in a given amount of time. Implement exponential backoff or ensure your usage stays within your plan's limits.                                                                                                                                                |
| 500  | Internal Server Error       | A server-side error occurred. This is typically an unexpected issue on our end. If this persists, please contact support with your request details.                                                                                                                                                                   |
| 503  | Service Unavailable         | The service is temporarily unavailable, often due to maintenance or high load. Retry the request after a short delay.                                                                                                                                                                                              |


## Implementation Guide

### Example Code
These examples demonstrate how to authenticate and make synchronous API requests to the IP Geolocation API.

#### JavaScript

```javascript
// JavaScript example (Synchronous)
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/viv-data/ipgeo";

async function getIpGeolocation(ipAddress = "") {
  try {
    const url = ipAddress ? `${baseUrl}/lookup?ip=${ipAddress}` : `${baseUrl}/lookup`;
    
    console.log(`Fetching geolocation for IP: ${ipAddress || 'your own IP'}`);

    const response = await fetch(url, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey,
        "Accept": "application/json"
      },
      // You might want to add a timeout for production environments
      // For fetch, this requires using AbortController
      // signal: abortController.signal
    });
    
    if (!response.ok) {
      const errorData = await response.json().catch(() => ({ message: response.statusText }));
      throw new Error(`API error: ${response.status} - ${JSON.stringify(errorData)}`);
    }
    
    const result = await response.json();
    console.log("Geolocation Data:", result);
    return result;
  } catch (error) {
    console.error("Error fetching IP geolocation:", error);
    throw error;
  }
}

// Example usage:
// To look up your own IP
console.log("--- Looking up own IP ---");
getIpGeolocation()
  .then(data => console.log("Success (Own IP):", data))
  .catch(err => console.error("Failed (Own IP):", err));

// To look up a specific IP (e.g., Google's DNS server)
console.log("\n--- Looking up 8.8.8.8 ---");
getIpGeolocation("8.8.8.8")
  .then(data => console.log("Success (8.8.8.8):", data))
  .catch(err => console.error("Failed (8.8.8.8):", err));

// Example with an invalid IP for error handling
console.log("\n--- Looking up invalid IP ---");
getIpGeolocation("invalid-ip")
  .then(data => console.log("Success (Invalid IP):", data))
  .catch(err => console.error("Failed (Invalid IP):", err));
```

#### Python

```python
# Python example (Synchronous)
import requests
import json
import os

API_KEY = os.getenv("API_MARKET_KEY", "YOUR_API_MARKET_KEY") # Recommended: load from environment variable
BASE_URL = "https://prod.api.market/api/v1/viv-data/ipgeo"

def get_ip_geolocation(ip_address=""):
    """
    Fetches geolocation data for a given IP address.
    If ip_address is empty, it looks up the caller's own IP.
    """
    headers = {
        "x-api-market-key": API_KEY,
        "Accept": "application/json"
    }
    
    params = {}
    if ip_address:
        params["ip"] = ip_address

    try:
        print(f"Fetching geolocation for IP: {ip_address or 'your own IP'}")
        response = requests.get(
            f"{BASE_URL}/lookup",
            headers=headers,
            params=params,
            timeout=30 # Recommended timeout for synchronous requests
        )
        
        response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
        
        result = response.json()
        print("Geolocation Data:", json.dumps(result, indent=2))
        return result
    except requests.exceptions.HTTPError as e:
        print(f"HTTP error occurred: {e.response.status_code} - {e.response.text}")
        raise
    except requests.exceptions.ConnectionError as e:
        print(f"Connection error occurred: {e}")
        raise
    except requests.exceptions.Timeout:
        print("The request timed out after 30 seconds.")
        raise
    except requests.exceptions.RequestException as e:
        print(f"An unexpected error occurred: {e}")
        raise

# Example usage:
# To look up your own IP
print("--- Looking up own IP ---")
try:
    get_ip_geolocation()
except Exception as e:
    print(f"Failed (Own IP): {e}")

# To look up a specific IP (e.g., Google's DNS server)
print("\n--- Looking up 8.8.8.8 ---")
try:
    get_ip_geolocation("8.8.8.8")
except Exception as e:
    print(f"Failed (8.8.8.8): {e}")

# Example with an invalid IP for error handling
print("\n--- Looking up invalid IP ---")
try:
    get_ip_geolocation("invalid-ip")
except Exception as e:
    print(f"Failed (Invalid IP): {e}")
```

#### cURL

```bash
# cURL example (Synchronous)

# Look up your own IP address
echo "--- Looking up own IP ---"
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/ipgeo/lookup" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"
echo "" # For a newline

# Look up a specific IP address (e.g., Google's DNS server)
echo "--- Looking up 8.8.8.8 ---"
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/ipgeo/lookup?ip=8.8.8.8" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"
echo ""

# Example with an invalid IP for error handling
echo "--- Looking up invalid IP ---"
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/ipgeo/lookup?ip=invalid-ip" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"
echo ""
```

### Performance Optimization
*   **Client-Side Caching:** If you frequently look up the same IP addresses, implement client-side caching to store results. Since the underlying data source caches results for an hour, you can safely cache results on your end for a similar duration to reduce API calls and latency.
*   **Batching (if applicable):** While this API is designed for single IP lookups, if you have a list of IPs, consider parallelizing your requests (within rate limits) rather than sequential processing to speed up overall execution.
*   **Error Handling and Retries:** Implement robust error handling and retry mechanisms with exponential backoff for transient errors (`429`, `503`) to ensure your application remains resilient without overwhelming the API.
*   **Choose the Right Plan:** Monitor your usage and select an API plan that aligns with your anticipated request volume to avoid rate limiting and ensure cost-effectiveness.

## FAQ
**Q: What data does the API return?**

A: The API returns the IP address, country, country code, city, region, ISP, and timezone for a given IP address.

**Q: Do I need an API key to use this service?**

A: Yes, all requests require an API key passed in the `x-api-market-key` header for authentication.

**Q: What happens if I don't provide an IP address?**

A: If the `ip` query parameter is left empty, the API will automatically detect and return the geolocation data for the IP address of the client making the request.

**Q: Is there a free tier?**

A: Yes, there is a free tier that allows up to 1,000 requests per month.

**Q: How accurate is the geolocation data?**

A: The data is sourced from `ipapi.co`, which provides generally reliable geolocation data. However, IP geolocation is not always 100% precise and can vary depending on the IP address type (e.g., mobile vs. fixed broadband) and how ISPs manage their IP ranges.

**Q: What does "ISP" stand for?**

A: ISP stands for Internet Service Provider, which is the organization that provides internet access to the given IP address.

**Q: How often is the data updated?**

A: The underlying data source `ipapi.co` frequently updates its database. Results from our API are cached for 1 hour to improve performance.

**Q: What should I do if I get a "429 Too Many Requests" error?**

A: This means you've exceeded your rate limit. You should implement a retry mechanism with exponential backoff or consider upgrading your API plan if you need higher request volumes.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Use the IP Geolocation API to accurately lookup geographic location data for any IP address. Get country, city, region, ISP, and timezone with a free tier.