{ "openapi": "3.1.0", "info": { "title": "Network Data Labs API", "version": "0.1.0", "summary": "Honest IP intelligence \u2014 geo with transparent accuracy, ASN/network, hosting/Tor/VPN flags", "description": "Developer-first IP intelligence API from Network Data Labs.\n\nEvery geo response includes `accuracy_radius_km` and `confidence` \u2014 we do not publish\nsingle-number \"99% city accuracy\" claims. Country/ASN/hosting flags ship day one;\ndownloadable MMDB/CSV databases come later.\n\n**Base URL:** `https://api.networkdatalabs.com`\n\n**Auth:** `Authorization: Bearer ` or `?api_key=`\n\n**Languages:** Docs and support in Spanish and English.\n", "contact": { "name": "Network Data Labs", "email": "hello@networkdatalabs.com", "url": "https://networkdatalabs.com" }, "license": { "name": "Proprietary", "url": "https://networkdatalabs.com" } }, "servers": [ { "url": "https://api.networkdatalabs.com", "description": "Production" } ], "security": [ { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "tags": [ { "name": "IP Lookup", "description": "Geolocation, network, and traits for a single IP" }, { "name": "ASN", "description": "Autonomous System details" }, { "name": "Bulk", "description": "Batch lookups (up to 100 IPs in v0)" }, { "name": "Account", "description": "Caller identity and quota" } ], "paths": { "/v0/ip/{ip}": { "get": { "tags": [ "IP Lookup" ], "operationId": "getIpLookup", "summary": "Full IP intelligence lookup", "description": "Primary endpoint. Returns location (with accuracy radius + confidence),\nnetwork/ASN, traits (hosting/Tor/VPN/proxy/etc.), and meta.\n", "parameters": [ { "$ref": "#/components/parameters/IpPath" }, { "$ref": "#/components/parameters/ApiKeyQueryOptional" } ], "responses": { "200": { "description": "Successful lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpLookup" }, "examples": { "google_dns": { "summary": "8.8.8.8 (Google Public DNS)", "value": { "ip": "8.8.8.8", "version": "v0", "location": { "continent_code": "NA", "country_code": "US", "country": "United States", "is_eu": false, "region": "California", "region_code": "CA", "city": "Mountain View", "postal": "94043", "latitude": 37.4056, "longitude": -122.0775, "timezone": "America/Los_Angeles", "accuracy_radius_km": 1000, "confidence": "low" }, "network": { "asn": 15169, "as_org": "Google LLC", "isp": "Google LLC", "organization": "Google LLC", "network": "8.8.8.0/24" }, "traits": { "is_anycast": true, "is_hosting": true, "is_mobile": false, "is_satellite": false, "is_bogon": false, "is_proxy": false, "is_vpn": false, "is_tor": false, "is_relay": false }, "meta": { "data_version": "2026-09-20", "sources": [ "rir", "licensed_geo", "public_blocklists" ], "cached": false } } }, "latam_ip": { "summary": "200.32.0.1 (LATAM example)", "value": { "ip": "200.32.0.1", "version": "v0", "location": { "continent_code": "SA", "country_code": "AR", "country": "Argentina", "is_eu": false, "region": "Buenos Aires", "region_code": "B", "city": "Buenos Aires", "postal": null, "latitude": -34.6037, "longitude": -58.3816, "timezone": "America/Argentina/Buenos_Aires", "accuracy_radius_km": 50, "confidence": "medium" }, "network": { "asn": 10481, "as_org": "Telecom Argentina S.A.", "isp": "Telecom Argentina", "organization": "Telecom Argentina S.A.", "network": "200.32.0.0/19" }, "traits": { "is_anycast": false, "is_hosting": false, "is_mobile": false, "is_satellite": false, "is_bogon": false, "is_proxy": false, "is_vpn": false, "is_tor": false, "is_relay": false }, "meta": { "data_version": "2026-09-20", "sources": [ "rir", "licensed_geo", "public_blocklists" ], "cached": false } } } } } } }, "400": { "$ref": "#/components/responses/InvalidIp" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v0/ip/{ip}/geo": { "get": { "tags": [ "IP Lookup" ], "operationId": "getIpGeo", "summary": "Geo-only lookup", "description": "Smaller payload for CDN/edge \u2014 `location` + `ip` + `meta` only.", "parameters": [ { "$ref": "#/components/parameters/IpPath" }, { "$ref": "#/components/parameters/ApiKeyQueryOptional" } ], "responses": { "200": { "description": "Geo-only result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpGeo" }, "examples": { "google_dns": { "summary": "8.8.8.8 geo", "value": { "ip": "8.8.8.8", "location": { "continent_code": "NA", "country_code": "US", "country": "United States", "is_eu": false, "region": "California", "region_code": "CA", "city": "Mountain View", "postal": "94043", "latitude": 37.4056, "longitude": -122.0775, "timezone": "America/Los_Angeles", "accuracy_radius_km": 1000, "confidence": "low" }, "meta": { "data_version": "2026-09-20", "sources": [ "rir", "licensed_geo" ], "cached": false } } }, "latam_ip": { "summary": "200.32.0.1 geo (LATAM)", "value": { "ip": "200.32.0.1", "location": { "continent_code": "SA", "country_code": "AR", "country": "Argentina", "is_eu": false, "region": "Buenos Aires", "region_code": "B", "city": "Buenos Aires", "postal": null, "latitude": -34.6037, "longitude": -58.3816, "timezone": "America/Argentina/Buenos_Aires", "accuracy_radius_km": 50, "confidence": "medium" }, "meta": { "data_version": "2026-09-20", "sources": [ "rir", "licensed_geo" ], "cached": false } } } } } } }, "400": { "$ref": "#/components/responses/InvalidIp" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v0/ip/{ip}/network": { "get": { "tags": [ "IP Lookup" ], "operationId": "getIpNetwork", "summary": "Network / ASN lookup", "description": "ASN, org, ISP, and prefix for an IP \u2014 no geo payload.", "parameters": [ { "$ref": "#/components/parameters/IpPath" }, { "$ref": "#/components/parameters/ApiKeyQueryOptional" } ], "responses": { "200": { "description": "Network-only result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpNetwork" }, "examples": { "google_dns": { "summary": "8.8.8.8 network", "value": { "ip": "8.8.8.8", "network": { "asn": 15169, "as_org": "Google LLC", "isp": "Google LLC", "organization": "Google LLC", "network": "8.8.8.0/24", "rir": "ARIN" }, "meta": { "data_version": "2026-09-20" } } }, "latam_ip": { "summary": "200.32.0.1 network (LATAM)", "value": { "ip": "200.32.0.1", "network": { "asn": 10481, "as_org": "Telecom Argentina S.A.", "isp": "Telecom Argentina", "organization": "Telecom Argentina S.A.", "network": "200.32.0.0/19", "rir": "LACNIC" }, "meta": { "data_version": "2026-09-20" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidIp" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v0/asn/{asn}": { "get": { "tags": [ "ASN" ], "operationId": "getAsn", "summary": "ASN detail", "description": "Autonomous System name, org, type, RIR, and sample prefixes.", "parameters": [ { "name": "asn", "in": "path", "required": true, "description": "ASN number (with or without `AS` prefix)", "schema": { "oneOf": [ { "type": "integer", "minimum": 0, "example": 15169 }, { "type": "string", "pattern": "^(AS|as)?[0-9]+$", "example": "AS15169" } ] }, "examples": { "numeric": { "value": 15169 }, "prefixed": { "value": "AS15169" } } }, { "$ref": "#/components/parameters/ApiKeyQueryOptional" } ], "responses": { "200": { "description": "ASN details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnDetail" }, "examples": { "google": { "summary": "AS15169 Google", "value": { "asn": 15169, "name": "GOOGLE", "org": "Google LLC", "domain": "google.com", "type": "hosting", "country_code": "US", "rir": "ARIN", "prefixes_sample": [ "8.8.8.0/24", "8.8.4.0/24" ], "meta": { "data_version": "2026-09-20" } } }, "telecom_ar": { "summary": "AS10481 Telecom Argentina", "value": { "asn": 10481, "name": "TELECOM-ARGENTINA", "org": "Telecom Argentina S.A.", "domain": "telecom.com.ar", "type": "isp", "country_code": "AR", "rir": "LACNIC", "prefixes_sample": [ "200.32.0.0/19", "200.42.0.0/16" ], "meta": { "data_version": "2026-09-20" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v0/bulk": { "post": { "tags": [ "Bulk" ], "operationId": "postBulk", "summary": "Bulk IP lookup", "description": "Batch lookup up to **100 IPs** per request in v0.\nReturns a map of results keyed by IP; per-IP failures appear under `errors`\n(partial success \u2014 one bad IP does not fail the whole batch).\n\n**Quota:** counts as **1** request toward the per-minute rate limit, but **N**\n(number of IPs in the body) toward the daily UTC quota.\n", "parameters": [ { "$ref": "#/components/parameters/ApiKeyQueryOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" }, "examples": { "mixed": { "summary": "Google DNS + Cloudflare + LATAM", "value": { "ips": [ "8.8.8.8", "1.1.1.1", "200.32.0.1" ] } } } } } }, "responses": { "200": { "description": "Bulk results (partial success possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResponse" }, "examples": { "success": { "summary": "Three successful lookups", "value": { "results": { "8.8.8.8": { "ip": "8.8.8.8", "version": "v0", "location": { "continent_code": "NA", "country_code": "US", "country": "United States", "is_eu": false, "region": "California", "region_code": "CA", "city": "Mountain View", "postal": "94043", "latitude": 37.4056, "longitude": -122.0775, "timezone": "America/Los_Angeles", "accuracy_radius_km": 1000, "confidence": "low" }, "network": { "asn": 15169, "as_org": "Google LLC", "isp": "Google LLC", "organization": "Google LLC", "network": "8.8.8.0/24" }, "traits": { "is_anycast": true, "is_hosting": true, "is_mobile": false, "is_satellite": false, "is_bogon": false, "is_proxy": false, "is_vpn": false, "is_tor": false, "is_relay": false }, "meta": { "data_version": "2026-09-20", "sources": [ "rir", "licensed_geo", "public_blocklists" ], "cached": false } }, "1.1.1.1": { "ip": "1.1.1.1", "version": "v0", "location": { "continent_code": "OC", "country_code": "AU", "country": "Australia", "is_eu": false, "region": null, "region_code": null, "city": null, "postal": null, "latitude": -33.494, "longitude": 143.2104, "timezone": "Australia/Sydney", "accuracy_radius_km": 1000, "confidence": "low" }, "network": { "asn": 13335, "as_org": "Cloudflare, Inc.", "isp": "Cloudflare", "organization": "APNIC and Cloudflare DNS Resolver Project", "network": "1.1.1.0/24" }, "traits": { "is_anycast": true, "is_hosting": true, "is_mobile": false, "is_satellite": false, "is_bogon": false, "is_proxy": false, "is_vpn": false, "is_tor": false, "is_relay": false }, "meta": { "data_version": "2026-09-20", "sources": [ "rir", "licensed_geo", "public_blocklists" ], "cached": false } }, "200.32.0.1": { "ip": "200.32.0.1", "version": "v0", "location": { "continent_code": "SA", "country_code": "AR", "country": "Argentina", "is_eu": false, "region": "Buenos Aires", "region_code": "B", "city": "Buenos Aires", "postal": null, "latitude": -34.6037, "longitude": -58.3816, "timezone": "America/Argentina/Buenos_Aires", "accuracy_radius_km": 50, "confidence": "medium" }, "network": { "asn": 10481, "as_org": "Telecom Argentina S.A.", "isp": "Telecom Argentina", "organization": "Telecom Argentina S.A.", "network": "200.32.0.0/19" }, "traits": { "is_anycast": false, "is_hosting": false, "is_mobile": false, "is_satellite": false, "is_bogon": false, "is_proxy": false, "is_vpn": false, "is_tor": false, "is_relay": false }, "meta": { "data_version": "2026-09-20", "sources": [ "rir", "licensed_geo", "public_blocklists" ], "cached": false } } }, "errors": {} } } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_IP", "message": "Request must include an 'ips' array with 1\u2013100 IP addresses" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v0/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Caller IP and account info", "description": "Returns the caller's apparent IP (from the request) plus plan/quota hints\nwhen authenticated. Useful for \"what's my IP\" and key validation.\n", "parameters": [ { "$ref": "#/components/parameters/ApiKeyQueryOptional" } ], "responses": { "200": { "description": "Caller context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "examples": { "authenticated": { "summary": "Authenticated caller", "value": { "ip": "200.32.0.1", "plan": "free", "requests_remaining_today": 847, "meta": { "data_version": "2026-09-20" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Prefer `Authorization: Bearer ndl_live_xxx`.\nKeys look like `ndl_live_*` (production) or `ndl_test_*` (sandbox).\n" }, "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Optional alternative to Bearer \u2014 useful for quick curl tests. Prefer header in production." } }, "parameters": { "IpPath": { "name": "ip", "in": "path", "required": true, "description": "IPv4 or IPv6 address", "schema": { "type": "string", "examples": [ "8.8.8.8", "200.32.0.1", "2001:4860:4860::8888" ] } }, "ApiKeyQueryOptional": { "name": "api_key", "in": "query", "required": false, "description": "Optional API key (if not using Bearer header)", "schema": { "type": "string", "example": "ndl_live_xxx" } } }, "responses": { "InvalidIp": { "description": "Malformed or unsupported IP address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_IP", "message": "Malformed IP address" } } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key" } } } } }, "RateLimited": { "description": "Burst (per-minute) or daily quota exceeded.\nPer-minute \u2192 `RATE_LIMITED`; daily UTC quota \u2192 `QUOTA_EXCEEDED`.\n", "headers": { "Retry-After": { "description": "Seconds until quota resets (when known)", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Per-minute request limit", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in the current minute window", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Daily quota (calendar UTC day)", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Remaining daily quota units", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-minute burst exceeded", "value": { "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded (60 requests per minute). Retry after 12s." } } }, "quota_exceeded": { "summary": "Daily UTC quota exceeded", "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded (1000 requests per UTC calendar day). Resets in 3600s (UTC midnight)." } } } } } } }, "NotFound": { "description": "Resource not found (e.g. unknown ASN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "ASN not found" } } } } }, "Internal": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL", "message": "Internal server error" } } } } } }, "schemas": { "Location": { "type": "object", "required": [ "continent_code", "country_code", "country", "accuracy_radius_km", "confidence" ], "properties": { "continent_code": { "type": "string", "description": "Continent code (e.g. NA, SA, EU)", "examples": [ "NA", "SA" ] }, "country_code": { "type": [ "string", "null" ], "description": "ISO-3166-1 alpha-2", "examples": [ "US", "AR" ] }, "country": { "type": [ "string", "null" ], "examples": [ "United States", "Argentina" ] }, "is_eu": { "type": "boolean", "description": "Whether the country is in the European Union" }, "region": { "type": [ "string", "null" ], "examples": [ "California", "Buenos Aires" ] }, "region_code": { "type": [ "string", "null" ], "examples": [ "CA", "B" ] }, "city": { "type": [ "string", "null" ], "examples": [ "Mountain View", "Buenos Aires" ] }, "postal": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ], "format": "double" }, "longitude": { "type": [ "number", "null" ], "format": "double" }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone", "examples": [ "America/Los_Angeles", "America/Argentina/Buenos_Aires" ] }, "accuracy_radius_km": { "type": [ "number", "null" ], "description": "Estimated accuracy radius in kilometers. Always present when geo is returned \u2014\nthis is our honesty signal. Wide radii (e.g. 1000) mean city is a best-effort guess.\n", "examples": [ 50, 1000 ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low", "unknown" ], "description": "Qualitative confidence in the geo estimate" } } }, "Network": { "type": "object", "properties": { "asn": { "type": [ "integer", "null" ], "examples": [ 15169, 10481 ] }, "as_org": { "type": [ "string", "null" ], "examples": [ "Google LLC", "Telecom Argentina S.A." ] }, "isp": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ], "description": "Containing prefix (CIDR)", "examples": [ "8.8.8.0/24", "200.32.0.0/19" ] }, "rir": { "type": [ "string", "null" ], "description": "Regional Internet Registry (present on /network endpoint)", "examples": [ "ARIN", "LACNIC", "RIPE", "APNIC", "AFRINIC" ] } } }, "Traits": { "type": "object", "required": [ "is_hosting", "is_proxy", "is_vpn", "is_tor", "is_bogon" ], "properties": { "is_anycast": { "type": "boolean" }, "is_hosting": { "type": "boolean", "description": "Likely datacenter / hosting ASN or range" }, "is_mobile": { "type": "boolean" }, "is_satellite": { "type": "boolean" }, "is_bogon": { "type": "boolean", "description": "Unallocated / reserved / bogon space" }, "is_proxy": { "type": "boolean" }, "is_vpn": { "type": "boolean", "description": "Known public VPN exit (best-effort; may have false negatives)" }, "is_tor": { "type": "boolean" }, "is_relay": { "type": "boolean", "description": "Known privacy relay (e.g. iCloud Private Relay style)" } } }, "Meta": { "type": "object", "required": [ "data_version" ], "properties": { "data_version": { "type": "string", "description": "Dataset build date (YYYY-MM-DD)", "examples": [ "2026-09-20" ] }, "sources": { "type": "array", "items": { "type": "string" }, "examples": [ [ "rir", "licensed_geo", "public_blocklists" ] ] }, "cached": { "type": "boolean", "description": "Whether this response was served from cache" } } }, "IpLookup": { "type": "object", "required": [ "ip", "version", "location", "network", "traits", "meta" ], "properties": { "ip": { "type": "string" }, "version": { "type": "string", "const": "v0" }, "location": { "$ref": "#/components/schemas/Location" }, "network": { "$ref": "#/components/schemas/Network" }, "traits": { "$ref": "#/components/schemas/Traits" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "IpGeo": { "type": "object", "required": [ "ip", "location", "meta" ], "properties": { "ip": { "type": "string" }, "location": { "$ref": "#/components/schemas/Location" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "IpNetwork": { "type": "object", "required": [ "ip", "network", "meta" ], "properties": { "ip": { "type": "string" }, "network": { "$ref": "#/components/schemas/Network" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AsnDetail": { "type": "object", "required": [ "asn", "name", "org", "meta" ], "properties": { "asn": { "type": "integer" }, "name": { "type": "string", "examples": [ "GOOGLE" ] }, "org": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "Coarse ASN category", "enum": [ "hosting", "isp", "education", "government", "business", "unknown", null ] }, "country_code": { "type": [ "string", "null" ] }, "rir": { "type": [ "string", "null" ] }, "prefixes_sample": { "type": "array", "items": { "type": "string" }, "description": "Sample of announced prefixes (not exhaustive)" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "BulkRequest": { "type": "object", "required": [ "ips" ], "properties": { "ips": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "description": "IPv4/IPv6 addresses to look up (max 100 in v0)", "examples": [ [ "8.8.8.8", "1.1.1.1", "200.32.0.1" ] ] } } }, "BulkResponse": { "type": "object", "required": [ "results", "errors" ], "properties": { "results": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/IpLookup" }, "description": "Map of IP \u2192 full lookup result" }, "errors": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ErrorBody" }, "description": "Map of IP \u2192 error for failed lookups (empty object if all succeeded)" } } }, "Me": { "type": "object", "required": [ "ip", "meta" ], "properties": { "ip": { "type": "string", "description": "Apparent client IP" }, "plan": { "type": "string", "examples": [ "free", "starter", "growth", "scale" ] }, "requests_remaining_today": { "type": [ "integer", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ErrorBody": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "INVALID_IP", "UNAUTHORIZED", "RATE_LIMITED", "QUOTA_EXCEEDED", "NOT_FOUND", "INTERNAL" ] }, "message": { "type": "string" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } } } } } }