Skip to main content

​
IP Lookup API Reference

Get comprehensive geolocation and network information for any IP address. Our IP lookup service provides detailed location data, country information, and network details for both IPv4 and IPv6 addresses.

​
Lookup IP Address

curl -X POST "https://api.mdb.tools/v1/ip/lookup" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "8.8.4.4"
  }'

​
Request Body

​
ip
string
required
The IP address to lookup. Supports both IPv4 and IPv6 formats.

​
Response

{
  "result": {
    "ip": "8.8.4.4",
    "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.3860517,
    "longitude": -122.0838511,
    "is_eu": false,
    "postal": "94039",
    "calling_code": "1"
  },
  "processing_time_ms": 45,
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

​
Response Fields

​
Result Object

​
result
object
Contains the IP lookup data and results.
​
result.ip
string
The IP address that was looked up.
​
result.success
boolean
Whether the IP lookup was successful. false for private IPs, invalid IPs, or when location data is unavailable.
​
result.type
string
The IP address type. Possible values: "IPv4", "IPv6", or null for invalid IPs.

​
Geographic Information

​
result.continent
string
The continent name where the IP is located, or null if unavailable.
​
result.continent_code
string
Two-letter continent code (e.g., “NA” for North America), or null if unavailable.
​
result.country
string
The country name where the IP is located, or null if unavailable.
​
result.country_code
string
Two-letter country code (ISO 3166-1 alpha-2), or null if unavailable.
​
result.region
string
The state/province/region name, or null if unavailable.
​
result.region_code
string
The state/province/region code, or null if unavailable.
​
result.city
string
The city name where the IP is located, or null if unavailable.
​
result.latitude
number
The latitude coordinate of the IP location, or null if unavailable.
​
result.longitude
number
The longitude coordinate of the IP location, or null if unavailable.
​
result.postal
string
The postal/ZIP code for the IP location, or null if unavailable.

​
Regional Information

​
result.is_eu
boolean
Whether the IP is located within the European Union. Always false for unsuccessful lookups.
​
result.calling_code
string
The international calling code for the country, or null if unavailable.

​
Metadata Fields

​
processing_time_ms
number
Time taken to process the request in milliseconds.
​
request_id
string
Unique identifier for this request (ULID format).

​
Common Scenarios

​
Public IP Addresses

Most public IP addresses will return complete geolocation data with success: true.

​
Private IP Addresses

Private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) return success: false with all location fields as null.

​
Invalid IP Addresses

Malformed IP addresses will return a validation error response instead of a result object.

​
IPv6 Support

Both IPv4 and IPv6 addresses are fully supported with the same response structure.

​
Error Responses

When the request fails due to validation or other errors, you’ll receive a standard error response instead of the result structure. For detailed error information, see Common Error Codes.

​
Invalid IP Format

{
  "error": "validation_error",
  "message": "IP address format is invalid",
  "code": "IP_001",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB8",
  "details": {
    "ip": "invalid.ip.address",
    "supported_formats": ["IPv4", "IPv6"]
  }
}

​
Invalid IPv4 Range

{
  "error": "validation_error",
  "message": "IP address format is invalid",
  "code": "IP_001",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB9",
  "details": {
    "ip": "999.999.999.999",
    "supported_formats": ["IPv4", "IPv6"]
  }
}

​
Missing IP Parameter

{
  "error": "bad_request",
  "message": "Missing required parameter",
  "code": "REQ_002",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB9",
  "details": {
    "missing_parameter": "ip",
    "parameter_type": "string"
  }
}
Note: Error responses follow the standard error format and do not include the result object. Only successful responses contain the result structure with IP data.

​
Rate Limits

This endpoint is subject to rate limits. See Rate Limits for detailed information about usage limits and best practices.