IP Lookup API

Geolocate any IPv4 or IPv6 address to country, region, city, and postal code. Includes ISP, ASN, proxy detection, VPN/Tor flags, and currency data.

IP Lookup API

The IP Lookup API geolocates an IPv4 or IPv6 address to its approximate geographic location, network provider, and associated metadata. Proxy, VPN, Tor exit node, and data-centre hosting detection are included in standard responses.

Note: You can use this endpoint in anonymous mode until the free 500 requests/day allowance is exhausted.

Endpoint

GET https://api.mapzena.com/v1/ip

Parameters

Parameter	Type	Required	Description
`key`	string	optional	Optional in free mode. Required for usage above the free daily allowance.
`ip`	string	required	The IPv4 or IPv6 address to look up. Pass `self` to look up the IP making the API request.
`fields`	string	optional	Comma-separated list of field groups to include: `geo`, `network`, `security`, `currency`. Default: all fields.

Example request

bash - curl

curl "https://api.mapzena.com/v1/ip?ip=8.8.8.8&key=YOUR_KEY"

Example response

json

{
  "status":      "ok",
  "ip":          "8.8.8.8",
  "type":        "IPv4",
  "is_private":  false,
  "continent":   "North America",
  "continent_code": "NA",
  "country":     "United States",
  "country_code": "US",
  "region":      "California",
  "region_code": "CA",
  "city":        "Mountain View",
  "postal":      "94043",
  "lat":         37.4056,
  "lon":         -122.0775,
  "accuracy_km": 5,
  "timezone":    "America/Los_Angeles",
  "isp":         "Google LLC",
  "org":         "GOOGLE",
  "asn":         "AS15169",
  "security": {
    "is_proxy":   false,
    "is_vpn":     false,
    "is_tor":     false,
    "is_hosting": true,
    "threat_score": 10
  },
  "currency": {
    "code":   "USD",
    "name":   "US Dollar",
    "symbol": "$"
  }
}

Security fields

Field	Type	Description
`is_proxy`	boolean	Known open or commercial proxy.
`is_vpn`	boolean	Known VPN exit node.
`is_tor`	boolean	Tor exit node.
`is_hosting`	boolean	IP belongs to a cloud/hosting provider (AWS, GCP, Azure, etc.).
`threat_score`	integer 0-100	Aggregate risk score. 0 = clean, 100 = high risk.

Private IP handling

Private and reserved IP ranges (RFC 1918, loopback, link-local, etc.) return a successful response with is_private: true and geographic fields set to null.

Looking up the caller's IP

http

GET https://api.mapzena.com/v1/ip?ip=self&key=YOUR_KEY

This returns geolocation for the IP address making the API request. Useful for server-side "detect my location" features.

Error codes

HTTP	Code	Description
400	missing_ip	The `ip` parameter is absent.
400	invalid_ip	The value is not a valid IPv4 or IPv6 address.
402	insufficient_credit	API key has insufficient account credit.
404	not_found	No geolocation data for this IP (unallocated ranges).
429	anonymous_quota_exceeded	Free anonymous quota reached.
429	rate_limit_exceeded	Burst limit reached.

Code examples

PHP

php

<?php
$key = 'YOUR_KEY';
$ip  = filter_var($_SERVER['REMOTE_ADDR'], FILTER_VALIDATE_IP);
$url = "https://api.mapzena.com/v1/ip?ip={$ip}&key={$key}";
$geo = json_decode(file_get_contents($url), true);

echo $geo['city'] . ', ' . $geo['country'];

Python

python

import urllib.request, json

key = "YOUR_KEY"
ip  = "1.1.1.1"
url = f"https://api.mapzena.com/v1/ip?ip={ip}&key={key}"

with urllib.request.urlopen(url) as r:
    geo = json.load(r)

print(geo["city"], geo["country_code"])

Dataset coverage: For a full breakdown of IPv4 and IPv6 scope, connection type classification, VPN detection methodology, and update frequency, see the IP Address Coverage page.