Name: IP Address Lookup API - Get Geo & Network Details
Brand: self-1
SKU: api-self-1-ip-info
Availability: InStock
Author: API Market

Tayyab Kharl

# Query IP Address

## Overview
The Query IP Address API provides a powerful and fast solution for retrieving detailed information about any public IPv4 or IPv6 address. With a single, simple HTTP request, developers can access a wealth of geopolitical, network, and security intelligence associated with an IP address. If no specific IP address is provided, the API intelligently defaults to returning information about the client making the request, making it incredibly versatile for various applications. This API is designed for developers and AI engineers who need reliable and accurate IP address intelligence for a wide range of tasks.

## Features
*   🌍 **Comprehensive IP Data**: Lookup detailed information for any valid IPv4 or IPv6 address.
*   ⚡ **Fast REST API**: Experience rapid response times for efficient data retrieval.
*   ✅ **Built-in IP Validation**: Automatically validates IP addresses, rejecting invalid formats before processing.
*   🔎 **Client IP Detection**: Automatically provides information for the calling client's IP if no address is specified.
*   🔒 **Localhost & Private Network Detection**: Supports identification of localhost and private network addresses for internal use cases (validation dependent).
*   🌐 **Geographical Information**: Includes continent, country, region, city, latitude, and longitude.
*   🏛️ **Network Details**: Provides ASN (Autonomous System Number), organization, route, and type.
*   🏷️ **Currency & Timezone**: Returns currency codes and names, along with the local timezone.
*   🛡️ **Threat Intelligence Flags**: Indicators for anonymity, VPN, Tor, known abusers, attackers, and datacenter presence.

## Use Cases
1.  **Cybersecurity & Fraud Detection**: Enhance security applications by identifying the geographical origin of suspicious login attempts, flagging IP addresses associated with known threats (VPNs, Tor, proxies, attackers), and improving fraud scoring for online transactions. This helps prevent unauthorized access and mitigate financial losses.
2.  **Geo-targeting & Content Localization**: Deliver personalized user experiences by serving region-specific content, advertisements, or services based on the user's IP address. Ideal for e-commerce platforms, streaming services, and publishing houses aiming to comply with regional regulations or optimize conversion rates.
3.  **Network Monitoring & Analytics**: Gain deeper insights into network traffic by associating IP addresses with their geographical and organizational data. This aids in analyzing traffic patterns, troubleshooting connectivity issues, understanding user distribution, and performing network capacity planning.
4.  **Compliance & Data Residency**: Ensure adherence to data residency laws (e.g., GDPR, CCPA) by verifying the physical location of users or data access points. Critical for cloud service providers, financial institutions, and healthcare providers managing sensitive information.
5.  **Threat Intelligence & Research**: Augment threat intelligence platforms by providing rich context for observed IP addresses, enabling faster analysis of attack campaigns, understanding adversary infrastructure, and enriching security incident response data.

## API Documentation

### Base URL
All API requests should be made to the following base URL:
`https://prod.api.market/api/v1/self-1/ip-info`

### Authentication
Authentication is handled via an API key. You must include your API key in the `x-api-market-key` request header for every request. Replace `YOUR_API_MARKET_KEY` with your actual API key.

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


### Endpoints

#### Query by IP Address
`GET /query`

This endpoint allows you to retrieve detailed information for a specified IPv4 or IPv6 address. If the `ip_address` query parameter is omitted, the API will return information about the client making the request.

**Parameters:**

| Name         | In      | Type   | Required | Description                                     | Example    |
| :----------- | :------ | :----- | :------- | :---------------------------------------------- | :--------- |
| `ip_address` | `query` | `string` | `false`  | The IPv4 or IPv6 address to query. If omitted, the client's IP is used. | `8.8.8.8` |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/self-1/ip-info/query?ip_address=8.8.8.8" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{
    "anycast": true,
    "asn": "AS15169",
    "asn_organization": "Google LLC",
    "asn_route": "8.8.8.0/24",
    "asn_type": "hosting",
    "calling_code": "1",
    "city": "Mountain View",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "currency_code": "USD",
    "currency_name": "US Dollar",
    "currency_symbol": "$",
    "flag": "https://flagcdn.com/us.svg",
    "flag_emoji": "\ud83c\uddfa\ud83c\uddf8",
    "flag_emoji_unicode": "U+1F1FA U+1F1F8",
    "hostname": "dns.google",
    "ip": "8.8.8.8",
    "is_anonymous": false,
    "is_bogon": false,
    "is_datacenter": true,
    "is_eu": false,
    "is_icloud_relay": false,
    "is_known_abuser": false,
    "is_known_attacker": false,
    "is_proxy": false,
    "is_threat": false,
    "is_tor": false,
    "is_vpn": false,
    "latitude": "37.4056",
    "longitude": "-122.0775",
    "post_code": "94043",
    "region": "California",
    "timezone": "America/Los_Angeles"
}
```

**Example Error Responses:**

**Invalid IP Address (400 Bad Request):**
```json
{
    "error": "Not a valid IP address."
}
```

**Internal Server Error (500 Internal Server Error):**
```json
{
    "error": "Something went wrong, please try again later."
}
```



## Implementation Guide
This section provides code examples for integrating with the Query IP Address API using common programming languages.

### Example Code

#### JavaScript

```javascript
// JavaScript example for synchronous API call
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/self-1/ip-info";

async function queryIpAddress(ipAddress = "") {
  try {
    const url = new URL(`${baseUrl}/query`);
    if (ipAddress) {
      url.searchParams.append("ip_address", ipAddress);
    }

    const response = await fetch(url.toString(), {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey
      },
      // Set a timeout for the request (e.g., 30 seconds)
      signal: AbortSignal.timeout(30000) 
    });
    
    const data = await response.json();

    if (!response.ok) {
      // API returned an error (e.g., 400, 401, 500)
      const errorMessage = data.error || `API error: ${response.status} ${response.statusText}`;
      throw new Error(errorMessage);
    }
    
    return data; // Returns the detailed IP information
  } catch (error) {
    console.error("Error querying IP address:", error);
    throw error; // Re-throw for further handling
  }
}

// Example usage:
// Query a specific IP
queryIpAddress("8.8.8.8")
  .then(data => console.log("Google DNS IP Info:", data))
  .catch(err => console.error("Failed to query IP:", err));

// Query client's own IP (no ipAddress parameter)
queryIpAddress()
  .then(data => console.log("Client IP Info:", data))
  .catch(err => console.error("Failed to query client IP:", err));
```

#### Python

```python
# Python example for synchronous API call
import requests
import json

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/self-1/ip-info"

def query_ip_address(ip_address=None):
    headers = {
        "x-api-market-key": API_KEY
    }
    params = {}
    if ip_address:
        params["ip_address"] = ip_address
    
    try:
        # Set a timeout for the request (e.g., 30 seconds)
        response = requests.get(
            f"{BASE_URL}/query",
            headers=headers,
            params=params,
            timeout=30 # seconds
        )
        response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)
        
        return response.json()
        
    except requests.exceptions.HTTPError as http_err:
        error_data = response.json()
        error_msg = error_data.get("error", f"HTTP error occurred: {http_err}")
        print(f"Error querying IP address: {error_msg}")
        raise
    except requests.exceptions.ConnectionError as conn_err:
        print(f"Connection error occurred: {conn_err}")
        raise
    except requests.exceptions.Timeout as timeout_err:
        print(f"Request timed out: {timeout_err}")
        raise
    except requests.exceptions.RequestException as req_err:
        print(f"An unexpected error occurred: {req_err}")
        raise

# Example usage:
# Query a specific IP
try:
    google_dns_info = query_ip_address("8.8.8.8")
    print("Google DNS IP Info:", json.dumps(google_dns_info, indent=4))
except Exception:
    pass # Error handled within the function

# Query client's own IP (no ip_address parameter)
try:
    client_ip_info = query_ip_address()
    print("Client IP Info:", json.dumps(client_ip_info, indent=4))
except Exception:
    pass # Error handled within the function
```

## cURL

```bash
# cURL example for querying a specific IP address
curl -X GET "https://prod.api.market/api/v1/self-1/ip-info/query?ip_address=8.8.8.8" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"

# cURL example for querying the client's own IP address
# (Omit the ip_address query parameter)
curl -X GET "https://prod.api.market/api/v1/self-1/ip-info/query" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## FAQ

**Q: What is an IP address and why would I need to query its details?**

A: An IP (Internet Protocol) address is a unique numerical label assigned to every device connected to a computer network that uses the Internet Protocol for communication. Querying its details provides information like geographical location, network ownership (ASN), and potential threat indicators, useful for cybersecurity, geo-targeting, and network analysis.

**Q: Does the API support both IPv4 and IPv6 addresses?**

A: Yes, the API fully supports both IPv4 (e.g., `8.8.8.8`) and IPv6 (e.g., `2001:4860:4860::8888`) address formats.

**Q: What happens if I don't provide an `ip_address` in the request?**

A: If the `ip_address` query parameter is omitted, the API will automatically detect and return detailed information about the client making the API request.

**Q: How accurate is the geographical location data?**

A: Geographical location data for IP addresses is based on various databases and heuristics. While generally accurate, especially at the country and region level, city-level accuracy can vary and should be considered an approximation rather than a precise GPS location.

**Q: What are "anycast" IPs and why is it important to know?**

A: An anycast IP address is shared by multiple servers in different locations. When you query an anycast IP, the response will indicate `"anycast": true`. This is important for understanding network routing, as requests to an anycast IP are routed to the nearest server, not a single, fixed location.

**Q: What do the `is_threat`, `is_vpn`, `is_tor`, etc. fields mean?**

A: These boolean fields are indicators derived from threat intelligence databases and network analysis. They help identify if an IP address is associated with known malicious activity, anonymization services (VPN, Tor), or other suspicious behaviors. They are valuable for security and fraud detection.

**Q: How can I identify if an IP address belongs to a data center?**

A: The `is_datacenter` field will be `true` if the IP address is identified as belonging to a data center or cloud provider, which is useful for filtering traffic or identifying server-side requests.

## 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.

Access comprehensive details for any IPv4 or IPv6 address, including geolocation, ASN, and network info. Automatically detect client IP. Fast & reliable IP data