Name: GeoIP Location & IP Intelligence REST API
Brand: api-soul
SKU: api-api-soul-geoip
Availability: InStock
Author: API Market

Alejandro Rodríguez

# GeoIP Location & IP Intelligence API

## Overview

The GeoIP Location & IP Intelligence API provides fast, accurate, and reliable IP address lookup services, resolving any IPv4 or IPv6 address to detailed geographic, network, and security metadata. Built for developers, this REST API offers comprehensive IP data without the complexity of managing underlying infrastructure. It utilizes MaxMind GeoLite2 databases to deliver location and network intelligence, making it ideal for a wide range of applications requiring precise IP-based information.

Alongside IP lookup, the API exposes a WHOIS domain lookup endpoint, returning registrar, registration and expiry dates, name servers, and registrant details for any domain. Both capabilities are available on every plan through the same base URL and API key.

## Features

-   **Global Coverage**: Access data for every publicly routable IP address across 200+ countries and territories.
-   **Sub-50ms Response**: Anycast-edge infrastructure ensures rapid data delivery.
-   **Always Fresh Data**: Daily database updates keep country, city, ASN, and ISP mappings current.
-   **Simple Pricing**: Pay per request with transparent billing.
-   **Developer First**: Clean JSON responses, SDKs for popular languages (JavaScript/TypeScript, Python, Go, Ruby), and thorough documentation.
-   **Detailed IP Data**: Resolve IPs to continent, country, region, city, latitude, longitude, postal code, timezone, ISP, organization, ASN, and more.
-   **IP Intelligence**: Includes data like connection details, timezones, and country-specific information.
-   **Security Flags**: Detect VPN, proxy, and Tor exit nodes to enhance security and fraud detection.

## Use Cases

-   **Content Localization & Geo-targeting**: Automatically deliver localized content, currency, or regional offers based on a user's geographic location detected from their IP address. Enhance user experience and relevance for international audiences by ensuring they receive the most relevant information.
-   **Fraud Prevention & Security**: Identify suspicious login attempts, transactions, or user registrations by detecting anomalous geographic origins or known VPN/proxy/Tor exit nodes, bolstering your application's security posture and minimizing fraudulent activities.
-   **Ad Targeting & Personalization**: Enrich customer profiles with accurate geographic data to power more precise and effective advertising campaigns, serving region-specific ads and personalized content that resonates with the user's location.
-   **Compliance & Access Control**: Enforce geo-restrictions and regulatory compliance by controlling access to digital content, services, or features based on the IP address's country or region, ensuring adherence to legal and licensing agreements.
-   **Analytics & Business Intelligence**: Gain deeper insights into your user base by analyzing traffic patterns and user origins at a granular IP level, informing strategic business decisions, market expansion efforts, and resource allocation.
-   **Network Optimization & Routing**: Optimize load balancing and CDN routing by directing user traffic to the closest or most performant edge nodes based on real-time IP geolocation, improving latency, reducing bandwidth costs, and enhancing overall service delivery.

## Pricing

-   1 API unit equals 1 IP address lookup.
-   Different pricing tiers are available based on usage volume.

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/api-soul/geoip`

### Authentication

Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Endpoints

#### `GET /geoip`

This endpoint performs IP geolocation using MaxMind GeoLite2 databases. If no IP address is provided as a query parameter, it defaults to geolocating the caller's IP address.

**Parameters:**

| Param | Type   | Required | Description                              | Example    |
| :---- | :----- | :------- | :--------------------------------------- | :--------- |
| `ip`  | `string` | No       | IPv4 or IPv6 address. Omit to use the caller's IP. | `8.8.8.8` |

**Request Example:**

```bash
curl -X GET "https://prod.api.market/api/v1/api-soul/geoip/geoip?ip=8.8.8.8" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example:**

```json
{
  "ip": "8.8.8.8",
  "success": true,
  "type": "IPv4",
  "continent": "North America",
  "continent_code": "NA",
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "region_code": "CA",
  "city": "Mountain View",
  "latitude": 37.40599,
  "longitude": -122.078514,
  "is_eu": false,
  "postal": "94043",
  "calling_code": "1",
  "capital": "Washington D.C.",
  "borders": "CA,MX",
  "flag": {
    "img": "https://cdn.ipwhois.io/flags/us.svg",
    "emoji": "🇺🇸",
    "emoji_unicode": "U+1F1FA U+1F1F8"
  },
  "connection": {
    "asn": 15169,
    "org": "Google LLC",
    "isp": "Google LLC",
    "domain": "google.com"
  },
  "timezone": {
    "id": "America/Los_Angeles",
    "abbr": "PST",
    "is_dst": false,
    "offset": -28800,
    "utc": "-08:00"
  }
}
```

#### `GET /whois/lookup/{domain}`

Returns WHOIS registration data for a domain, including the registrar, key lifecycle dates, name servers, and registrant contact details where the registry publishes them.

**Parameters:**

| Param | Type | Required | Description | Example |
| :---- | :--- | :------- | :---------- | :------ |
| `domain` | `string` | Yes | Domain name to look up. Provided as a path segment. | `example.com` |

**Request Example:**

```bash
curl -X GET "https://prod.api.market/api/v1/api-soul/geoip/whois/lookup/example.com" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example:**

```json
{
  "domain": "example.com",
  "registrar": "RESERVED-Internet Assigned Numbers Authority",
  "creation_date": "1995-08-14T04:00:00",
  "expiration_date": "2026-08-13T04:00:00",
  "updated_date": "2025-08-14T07:01:44",
  "status": ["clientDeleteProhibited", "clientTransferProhibited"],
  "name_servers": ["a.iana-servers.net", "b.iana-servers.net"],
  "emails": null,
  "org": null,
  "country": null
}
```

Fields that the registry does not publish are returned as `null`. `status` and `name_servers` are arrays; `emails` may be a string or an array depending on the registry.

A failed upstream lookup returns `500 WHOIS lookup error`.

## Status Codes

A comprehensive list of HTTP status codes and their meanings for the GeoIP Location & IP Intelligence API:

-   **200 OK**: The request was successful, and the API returned the expected data.
-   **400 Bad Request**: The request was malformed, or invalid input parameters were provided (e.g., an invalid IP address format).
  -   *Specific to GeoIP:* "Unable to determine IP" if no IP is provided and the caller's IP cannot be determined.
-   **401 Unauthorized**: The API key is missing or invalid. Ensure your `x-api-market-key` header is correctly set.
-   **403 Forbidden**: Your API key is valid, but you do not have sufficient permissions to access the requested resource or perform the action.
-   **404 Not Found**: The requested resource could not be found. This typically indicates an incorrect endpoint path.
-   **429 Too Many Requests**: You have exceeded your API rate limit. Refer to the Rate Limits section for more details.
-   **500 Internal Server Error**: A server-side error occurred while processing your request. This indicates an issue on the API provider's end. Retry after a backoff period.
-   **503 Service Unavailable**: The service is temporarily unavailable, possibly due to maintenance or overload. Retry after a backoff period.
  -   *Specific to GeoIP:* "GeoIP database not configured" indicates an internal service issue.

## Rate Limits

The GeoIP Location & IP Intelligence API implements rate limits to ensure fair usage and service stability. The limits vary by your subscribed plan:

| Plan      | Requests/minute |
| :-------- | :-------------- |
| Free      | 60              |
| Starter   | 600             |
| Business  | 6,000           |
| Enterprise| Custom          |

Rate limit information is included in the response headers of every request:
-   `X-RateLimit-Limit`: The maximum number of requests you can make in the current time window.
-   `X-RateLimit-Remaining`: The number of requests remaining in the current time window.
-   `X-RateLimit-Reset`: The Unix timestamp when the current rate limit window will reset.

## Error Handling

Effective error handling is crucial for building robust applications. The GeoIP Location & IP Intelligence API provides clear error responses to help you debug and respond appropriately.

**Interpreting Error Responses:**
When an error occurs, the API will return a non-200 HTTP status code and a JSON body containing details about the error.

**Error Response Example:**

```json
{
  "error": {
    "code": "INVALID_IP",
    "message": "The provided value is not a valid IPv4 or IPv6 address.",
    "status": 400
  }
}
```

**Common Errors and Resolution:**
-   **400 Bad Request (`INVALID_IP`)**: Occurs when the `ip` parameter is malformed or invalid.
  -   **Resolution**: Ensure the IP address provided is a valid IPv4 or IPv6 format.
-   **401 Unauthorized**: Returned if the `x-api-market-key` header is missing or incorrect.
  -   **Resolution**: Verify that your API key is correctly included in the `x-api-market-key` header for all requests. Generate a new key from your dashboard if needed.
-   **429 Too Many Requests**: You have exceeded your plan's rate limit.
  -   **Resolution**: Implement exponential backoff for retries and monitor `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. Consider upgrading your plan for higher limits.
-   **500 Internal Server Error / 503 Service Unavailable**: These indicate transient issues on the server side.
  -   **Resolution**: Implement a retry strategy with exponential backoff. If the issue persists, check the [Status Page](https://status.api.market) for service announcements or contact support.

**Recommended Retry Strategies:**
For `429`, `500`, and `503` errors, implementing an exponential backoff strategy is recommended. This involves waiting a short period before retrying, and increasing the wait time with each subsequent failed attempt. This prevents overwhelming the API and allows the service to recover.

## FAQ

**What kind of IP addresses can I lookup?**

The API supports both IPv4 and IPv6 addresses.

**How up-to-date is the GeoIP data?**

Our database is updated daily at 00:00 UTC to ensure the most current country, city, ASN, and ISP mappings.

**Do I need to provide an API key?**

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

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

If the `ip` parameter is omitted, the API will attempt to geolocate the IP address of the caller making the request.

**Can I use this API for commercial projects?**

Yes, the API is designed for various applications, including commercial use cases, subject to the api.market Terms of Service.

**What data sources are used for geolocation?**

Our database is built from a combination of Regional Internet Registry (RIR) data (ARIN, RIPE, APNIC, LACNIC, AFRINIC), BGP routing tables, network measurement data, and ISP-reported allocations.

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

Resolve any IP address to country, city, timezone, ISP, and ASN in under 50ms. Global coverage, simple pricing, clean JSON. Try free today.