{"openapi":"3.1.0","info":{"title":"IP Address Details — IP Geolocation API","version":"1.0.0","summary":"IP geolocation, ASN, timezone and reverse DNS for IPv4 and IPv6.","description":"JSON lookups for any public IP address. Anonymous use is allowed at a low per-IP rate; a free API key raises the quota (Free: 1,000 req/day; Starter: 30,000 req/day ($9/mo); Pro: 150,000 req/day ($29/mo); Enterprise: 1,000,000 req/day). Data: DB-IP Lite (CC BY 4.0) refreshed monthly, with reverse-DNS resolved live. Docs and keys: https://www.ipaddressdetails.com/developers","termsOfService":"https://www.ipaddressdetails.com/pages/terms.html","contact":{"name":"IP Address Details","url":"https://www.ipaddressdetails.com/pages/contact.html"},"license":{"name":"Data: CC BY 4.0 (DB-IP)","url":"https://db-ip.com"}},"servers":[{"url":"https://www.ipaddressdetails.com/api/v1"}],"externalDocs":{"url":"https://www.ipaddressdetails.com/developers","description":"Developer documentation and pricing"},"tags":[{"name":"Lookup"},{"name":"Keys"}],"paths":{"/ip":{"get":{"tags":["Lookup"],"operationId":"lookupSelf","summary":"Look up the caller's own IP address","security":[{},{"apiKeyHeader":[]},{"apiKeyQuery":[]}],"responses":{"200":{"description":"Geolocation for the requesting IP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoResult"}}}},"429":{"$ref":"#/components/responses/Quota"}}}},"/ip/{ip}":{"get":{"tags":["Lookup"],"operationId":"lookupIp","summary":"Look up any IPv4 or IPv6 address","parameters":[{"name":"ip","in":"path","required":true,"schema":{"type":"string"},"example":"1.1.1.1"}],"security":[{},{"apiKeyHeader":[]},{"apiKeyQuery":[]}],"responses":{"200":{"description":"Geolocation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoResult"}}}},"400":{"description":"invalid_ip","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/Quota"}}}},"/ip/{ip}/{field}":{"get":{"tags":["Lookup"],"operationId":"lookupField","summary":"Return a single field as plain text","description":"Handy for shell scripts: `curl https://www.ipaddressdetails.com/api/v1/ip/8.8.8.8/country_code`","parameters":[{"name":"ip","in":"path","required":true,"schema":{"type":"string"}},{"name":"field","in":"path","required":true,"schema":{"type":"string","enum":["ip","version","is_private","city","region","country","country_code","continent","continent_code","latitude","longitude","timezone","postal","is_eu","asn","org","hostname"]}}],"security":[{},{"apiKeyHeader":[]},{"apiKeyQuery":[]}],"responses":{"200":{"description":"Field value (empty string when null)","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"unknown_field"},"429":{"$ref":"#/components/responses/Quota"}}}},"/bulk":{"post":{"tags":["Lookup"],"operationId":"lookupBulk","summary":"Look up many IP addresses in one request","description":"Each IP costs one request from the daily quota. Batch size limit by plan: anonymous 25, free 100, starter 1,000, pro 5,000, enterprise 10,000. Duplicates and invalid entries are dropped (invalid ones are echoed back). UI at https://www.ipaddressdetails.com/bulk.","security":[{},{"apiKeyHeader":[]},{"apiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ips"],"properties":{"ips":{"type":"array","items":{"type":"string"},"maxItems":10000,"example":["8.8.8.8","1.1.1.1","2606:4700:4700::1111"]}}}},"text/plain":{"schema":{"type":"string","description":"One IP per line"}}}},"responses":{"200":{"description":"Results in input order","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"invalid":{"type":"array","items":{"type":"string"}},"results":{"type":"array","items":{"$ref":"#/components/schemas/GeoResult"}}}}}}},"400":{"description":"no_valid_ips","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"batch_too_large — the plan's per-request limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/Quota"}}}},"/keys":{"post":{"tags":["Keys"],"operationId":"createKey","summary":"Create a free API key (no credit card)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Key created","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string"},"plan":{"type":"string"},"daily_limit":{"type":"integer"},"docs":{"type":"string"}}}}}},"400":{"description":"invalid_email"},"429":{"description":"too_many_keys / rate_limited"}}}},"/keys/me":{"get":{"tags":["Keys"],"operationId":"keyUsage","summary":"Usage and quota for the calling key","security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]}],"responses":{"200":{"description":"Plan, limit and today's usage"},"401":{"description":"invalid_key"}}}}},"components":{"securitySchemes":{"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"key"}},"responses":{"Quota":{"description":"quota_exceeded or rate_limited — see X-RateLimit-* headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"GeoResult":{"type":"object","properties":{"ip":{"type":"string","example":"8.8.8.8"},"version":{"type":"integer","enum":[4,6]},"is_private":{"type":"boolean","description":"RFC 1918 / loopback / link-local / documentation ranges"},"city":{"type":["string","null"],"example":"Mountain View"},"region":{"type":["string","null"],"example":"California"},"country":{"type":["string","null"],"example":"United States"},"country_code":{"type":["string","null"],"example":"US"},"continent":{"type":["string","null"],"example":"North America"},"continent_code":{"type":["string","null"],"example":"NA"},"latitude":{"type":["number","null"],"example":37.422},"longitude":{"type":["number","null"],"example":-122.085},"timezone":{"type":["string","null"],"example":"America/Los_Angeles","description":"IANA zone; approximated from country + longitude when the database has none"},"postal":{"type":["string","null"]},"is_eu":{"type":"boolean"},"asn":{"type":["string","null"],"example":"AS15169"},"org":{"type":["string","null"],"example":"Google LLC"},"hostname":{"type":["string","null"],"example":"dns.google","description":"Reverse DNS (PTR) if present"}},"required":["ip","version","is_private"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}