{ "openapi": "3.1.0", "info": { "title": "ip-api.dev API", "version": "1.3.0", "description": "Stable JSON lookups. v1 uses the existing daily quotas. All v1 endpoints require an API key and hard-stop at the daily per-key plan allowance. Legacy web routes retain keyless lookups and prepaid credit behavior. Lite is reserved for a future release." }, "servers": [ { "url": "https://ip-api.dev" }, { "url": "https://api.ip-api.dev" } ], "paths": { "/v1": { "get": { "operationId": "queryLookup", "summary": "Look up an IP address or AS number", "parameters": [ { "name": "q", "in": "query", "description": "IPv4, IPv6, or AS-prefixed ASN.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8–128 printable ASCII characters without spaces. Reuse the same key and identical request inputs within 24 hours to return the same charged response without additional usage. Changed inputs or an expired retained key return 409. Snapshots are encrypted and limited to 8 MiB. Zero-cost calls do not create snapshots.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" } }, { "name": "key", "in": "query", "description": "Legacy API key. Prefer Authorization: Bearer.", "required": false, "schema": { "type": "string" } } ], "security": [ { "ApiKey": [] }, { "BearerAuth": [] } ], "responses": { "200": { "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } } }, "description": "Successful lookup. Unresolved sections are omitted; unresolved fields within a section are null.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/FullResponse" }, { "$ref": "#/components/schemas/ASNResponse" } ] } } } }, "400": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying after a daily quota rejection.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "bulkLookupAlias", "summary": "Enrich 1 to 1,000 addresses in input order", "security": [ { "ApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8–128 printable ASCII characters without spaces. Reuse the same key and identical request inputs within 24 hours to return the same charged response without additional usage. Changed inputs or an expired retained key return 409. Snapshots are encrypted and limited to 8 MiB. Zero-cost calls do not create snapshots.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" } }, { "name": "key", "in": "query", "description": "Legacy API key. Prefer Authorization: Bearer.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" } }, "text/plain": { "schema": { "type": "string", "description": "One address per line; 1 to 1,000 lines." } } } }, "responses": { "200": { "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } } }, "description": "Successful lookup. Unresolved sections are omitted; unresolved fields within a section are null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResponse" } } } }, "400": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying after a daily quota rejection.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me": { "get": { "operationId": "accountMetadata", "summary": "Inspect plan and per-key usage without consuming quota", "parameters": [ { "name": "key", "in": "query", "description": "Legacy API key. Prefer Authorization: Bearer.", "required": false, "schema": { "type": "string" } } ], "security": [ { "ApiKey": [] }, { "BearerAuth": [] } ], "responses": { "200": { "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } } }, "description": "Successful lookup. Unresolved sections are omitted; unresolved fields within a section are null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMetadata" } } } }, "400": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying after a daily quota rejection.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lookup": { "get": { "operationId": "selfLookup", "summary": "Look up the trusted client connection address", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8–128 printable ASCII characters without spaces. Reuse the same key and identical request inputs within 24 hours to return the same charged response without additional usage. Changed inputs or an expired retained key return 409. Snapshots are encrypted and limited to 8 MiB. Zero-cost calls do not create snapshots.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" } }, { "name": "key", "in": "query", "description": "Legacy API key. Prefer Authorization: Bearer.", "required": false, "schema": { "type": "string" } } ], "security": [ { "ApiKey": [] }, { "BearerAuth": [] } ], "responses": { "200": { "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } } }, "description": "Successful lookup. Unresolved sections are omitted; unresolved fields within a section are null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullResponse" } } } }, "400": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying after a daily quota rejection.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lookup/{ip}": { "get": { "operationId": "ipLookup", "summary": "Look up an IPv4 or IPv6 address", "parameters": [ { "name": "ip", "in": "path", "required": true, "description": "Bare IPv4 or IPv6 address; URL-encode the path segment.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8–128 printable ASCII characters without spaces. Reuse the same key and identical request inputs within 24 hours to return the same charged response without additional usage. Changed inputs or an expired retained key return 409. Snapshots are encrypted and limited to 8 MiB. Zero-cost calls do not create snapshots.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" } }, { "name": "key", "in": "query", "description": "Legacy API key. Prefer Authorization: Bearer.", "required": false, "schema": { "type": "string" } } ], "security": [ { "ApiKey": [] }, { "BearerAuth": [] } ], "responses": { "200": { "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } } }, "description": "Successful lookup. Unresolved sections are omitted; unresolved fields within a section are null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullResponse" } } } }, "400": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying after a daily quota rejection.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/asn/{asn}": { "get": { "operationId": "asnLookup", "summary": "Look up an AS number and its announced prefixes", "parameters": [ { "name": "asn", "in": "path", "required": true, "description": "Decimal ASN from 0 to 4294967295, without the AS prefix.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8–128 printable ASCII characters without spaces. Reuse the same key and identical request inputs within 24 hours to return the same charged response without additional usage. Changed inputs or an expired retained key return 409. Snapshots are encrypted and limited to 8 MiB. Zero-cost calls do not create snapshots.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" } }, { "name": "key", "in": "query", "description": "Legacy API key. Prefer Authorization: Bearer.", "required": false, "schema": { "type": "string" } } ], "security": [ { "ApiKey": [] }, { "BearerAuth": [] } ], "responses": { "200": { "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } } }, "description": "Successful lookup. Unresolved sections are omitted; unresolved fields within a section are null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ASNResponse" } } } }, "400": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying after a daily quota rejection.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bulk": { "post": { "operationId": "bulkLookup", "summary": "Enrich 1 to 1,000 addresses in input order", "security": [ { "ApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8–128 printable ASCII characters without spaces. Reuse the same key and identical request inputs within 24 hours to return the same charged response without additional usage. Changed inputs or an expired retained key return 409. Snapshots are encrypted and limited to 8 MiB. Zero-cost calls do not create snapshots.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" } }, { "name": "key", "in": "query", "description": "Legacy API key. Prefer Authorization: Bearer.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" } }, "text/plain": { "schema": { "type": "string", "description": "One address per line; 1 to 1,000 lines." } } } }, "responses": { "200": { "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } } }, "description": "Successful lookup. Unresolved sections are omitted; unresolved fields within a section are null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResponse" } } } }, "400": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Idempotency-Replayed": { "description": "True when this response reuses a previously charged request snapshot.", "schema": { "type": "boolean" } }, "RateLimit-Limit": { "description": "Daily plan allowance for this key.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Remaining daily allowance, clamped to zero.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until midnight UTC.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC reset as Unix epoch seconds.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying after a daily quota rejection.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Request failed; see error for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "query", "name": "key" }, "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Anonymous": { "type": "object", "properties": { "is_vpn": { "type": "boolean" }, "is_proxy": { "type": "boolean" }, "is_tor": { "type": "boolean" }, "is_relay": { "type": "boolean" }, "is_hosting": { "type": "boolean" }, "provider_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "network_last_seen": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] } }, "required": [ "is_vpn", "is_proxy", "is_tor", "is_relay", "is_hosting", "provider_name", "network_last_seen", "confidence" ], "additionalProperties": false }, "AbuseScore": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 1 }, "level": { "enum": [ "low", "medium", "high" ] } }, "required": [ "score", "level" ], "additionalProperties": false }, "Network": { "type": "object", "properties": { "cidr": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "allocation", "assignment", "reallocation", "reassignment", "legacy" ] }, { "type": "null" } ] }, "rir": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "rdap_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abuse_score": { "anyOf": [ { "$ref": "#/components/schemas/AbuseScore" }, { "type": "null" } ] } }, "required": [ "cidr", "name", "type", "rir", "country_code", "rdap_url", "abuse_score" ], "additionalProperties": false }, "Organization": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "domain" ], "additionalProperties": false }, "ASN": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "route": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rir": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "normalized_type": { "anyOf": [ { "type": "string", "enum": [ "hosting", "isp", "education", "government", "business" ] }, { "type": "null" } ] }, "last_changed": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abuse_score": { "$ref": "#/components/schemas/AbuseScore" } }, "required": [ "number", "name", "domain", "country_code", "route", "rir", "type", "normalized_type", "last_changed", "active", "updated_at", "abuse_score" ], "additionalProperties": false }, "Connection": { "type": "object", "properties": { "isp": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connection_type": { "anyOf": [ { "enum": [ "Cable/DSL", "Cellular", "Corporate", "Satellite" ] }, { "type": "null" } ] }, "user_type": { "anyOf": [ { "enum": [ "business", "cellular", "college", "consumer_privacy_network", "content_delivery_network", "government", "hosting", "library", "military", "residential", "school", "search_engine_spider", "traveler" ] }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mobile_country_code": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{3}$" }, { "type": "null" } ] }, "mobile_network_code": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{2,3}$" }, { "type": "null" } ] } }, "required": [ "isp", "connection_type", "user_type", "domain", "mobile_country_code", "mobile_network_code" ], "additionalProperties": false }, "AbuseContact": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emails": { "type": "array", "items": { "type": "string" } }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phones": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "address", "country_code", "email", "emails", "phone", "phones" ], "additionalProperties": false }, "Datacenter": { "type": "object", "properties": { "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "provider", "domain", "network", "country_code", "region", "city" ], "additionalProperties": false }, "ServiceExit": { "type": "object", "properties": { "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "region", "country_code", "city", "latitude", "longitude" ], "additionalProperties": false }, "Service": { "type": "object", "properties": { "kind": { "enum": [ "vpn", "proxy", "platform_egress" ] }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "type": "string" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exit": { "$ref": "#/components/schemas/ServiceExit" } }, "required": [ "kind", "provider", "url", "role", "confidence", "last_seen", "exit" ], "additionalProperties": false }, "Names": { "type": "object", "properties": { "de": { "type": "string" }, "en": { "type": "string" }, "es": { "type": "string" }, "fr": { "type": "string" }, "ja": { "type": "string" }, "pt-BR": { "type": "string" }, "ru": { "type": "string" }, "zh-CN": { "type": "string" } }, "additionalProperties": false }, "Subdivision": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z0-9]{1,3}$" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "geoname_id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "names": { "$ref": "#/components/schemas/Names" }, "confidence": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] } }, "required": [ "code", "name", "geoname_id", "names", "confidence" ], "additionalProperties": false }, "RegisteredCountry": { "type": "object", "properties": { "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "geoname_id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "is_eu_member": { "type": "boolean" }, "names": { "$ref": "#/components/schemas/Names" } }, "required": [ "country_code", "country", "geoname_id", "is_eu_member", "names" ], "additionalProperties": false }, "Location": { "type": "object", "properties": { "last_changed": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "continent_code": { "anyOf": [ { "enum": [ "AF", "AN", "AS", "EU", "NA", "OC", "SA" ] }, { "type": "null" } ] }, "continent_geoname_id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "continent_names": { "$ref": "#/components/schemas/Names" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "country_geoname_id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "country_names": { "$ref": "#/components/schemas/Names" }, "country_confidence": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region_code_raw": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z0-9]{1,3}$" }, { "type": "null" } ] }, "region_geoname_id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "subdivisions": { "type": "array", "items": { "$ref": "#/components/schemas/Subdivision" } }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city_geoname_id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "city_names": { "$ref": "#/components/schemas/Names" }, "city_confidence": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] }, "accuracy_radius": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000 }, { "type": "null" } ] }, "zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "local_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "local_time_unix": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_dst": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "utcoffset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_eu_member": { "type": "boolean" }, "calling_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "precision": { "enum": [ "street", "city", "region", "country" ] }, "basis": { "enum": [ "operator_geofeed", "active_measurement", "geolocation_database", "registry_allocation" ] } }, "required": [ "last_changed", "continent", "continent_code", "continent_geoname_id", "continent_names", "country", "country_code", "country_geoname_id", "country_names", "country_confidence", "state", "region_code_raw", "region_code", "region_geoname_id", "subdivisions", "city", "city_geoname_id", "city_names", "city_confidence", "latitude", "longitude", "accuracy_radius", "zip", "timezone", "local_time", "local_time_unix", "is_dst", "utcoffset", "is_eu_member", "calling_code", "currency_code", "precision", "basis" ], "additionalProperties": false }, "Crawler": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "FullResponse": { "type": "object", "properties": { "ip": { "type": "string" }, "hostname": { "type": "string" }, "network": { "$ref": "#/components/schemas/Network" }, "organization": { "$ref": "#/components/schemas/Organization" }, "asn": { "$ref": "#/components/schemas/ASN" }, "connection": { "$ref": "#/components/schemas/Connection" }, "abuse_contact": { "$ref": "#/components/schemas/AbuseContact" }, "datacenter": { "$ref": "#/components/schemas/Datacenter" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "location": { "$ref": "#/components/schemas/Location" }, "registered_country": { "$ref": "#/components/schemas/RegisteredCountry" }, "is_bogon": { "type": "boolean" }, "is_datacenter": { "type": "boolean" }, "is_anycast": { "type": "boolean" }, "is_tor": { "type": "boolean" }, "is_proxy": { "type": "boolean" }, "is_vpn": { "type": "boolean" }, "is_abuser": { "type": "boolean" }, "is_mobile": { "type": "boolean" }, "is_satellite": { "type": "boolean" }, "is_crawler": { "type": "boolean" }, "is_relay": { "type": "boolean" }, "is_anonymous": { "type": "boolean" }, "anonymous": { "$ref": "#/components/schemas/Anonymous" }, "ip_risk": { "type": "number", "minimum": 0.01, "maximum": 99 }, "ip_risk_reasons": { "type": "array", "items": { "enum": [ "TOR_EXIT", "ANONYMOUS_VPN", "PUBLIC_PROXY", "PRIVACY_RELAY", "BLOCKLISTED_IP", "ABUSIVE_NETWORK", "ABUSIVE_ASN", "HOSTING_PROVIDER" ] } }, "crawler": { "$ref": "#/components/schemas/Crawler" }, "elapsed_ms": { "type": "number", "minimum": 0 } }, "required": [ "ip", "services", "anonymous", "ip_risk", "ip_risk_reasons", "is_bogon", "is_datacenter", "is_anycast", "is_tor", "is_proxy", "is_vpn", "is_abuser", "is_mobile", "is_satellite", "is_crawler", "is_relay", "is_anonymous" ], "additionalProperties": false }, "ReducedResponse": { "type": "object", "properties": { "ip": { "type": "string" }, "is_bogon": { "type": "boolean" }, "is_datacenter": { "type": "boolean" }, "is_anycast": { "type": "boolean" }, "is_tor": { "type": "boolean" }, "is_proxy": { "type": "boolean" }, "is_vpn": { "type": "boolean" }, "is_abuser": { "type": "boolean" }, "is_mobile": { "type": "boolean" }, "is_satellite": { "type": "boolean" }, "is_crawler": { "type": "boolean" }, "is_relay": { "type": "boolean" }, "is_anonymous": { "type": "boolean" }, "crawler": { "$ref": "#/components/schemas/Crawler" }, "organization": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false }, "asn": { "type": "object", "properties": { "number": { "type": "integer" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "number", "name" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "country_code", "latitude", "longitude" ], "additionalProperties": false }, "elapsed_ms": { "type": "number", "minimum": 0 } }, "required": [ "ip", "is_bogon", "is_datacenter", "is_anycast", "is_tor", "is_proxy", "is_vpn", "is_abuser", "is_mobile", "is_satellite", "is_crawler", "is_relay", "is_anonymous" ], "additionalProperties": false }, "ASNResponse": { "type": "object", "properties": { "asn": { "$ref": "#/components/schemas/ASN" }, "prefixes": { "type": "object", "properties": { "ipv4": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } } }, "required": [ "ipv4", "ipv6" ], "additionalProperties": false }, "elapsed_ms": { "type": "number", "minimum": 0 } }, "required": [ "asn", "prefixes" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "ip": { "type": "string" }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "plan": { "type": "string" }, "elapsed_ms": { "type": "number", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "BulkRequest": { "type": "object", "properties": { "ips": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string", "maxLength": 64 } } }, "required": [ "ips" ], "additionalProperties": false }, "BulkResponse": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "anyOf": [ { "$ref": "#/components/schemas/FullResponse" }, { "$ref": "#/components/schemas/Error" } ] } }, "AccountMetadata": { "type": "object", "properties": { "key_id": { "type": "string", "pattern": "^[a-f0-9]{16}$" }, "plan": { "enum": [ "free", "basic", "medium", "large", "business" ] }, "quota": { "type": "object", "properties": { "scope": { "const": "api_key" }, "limit": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "reset": { "type": "integer", "minimum": 0 } }, "required": [ "scope", "limit", "used", "remaining", "day", "reset" ], "additionalProperties": false }, "metering": { "type": "object", "properties": { "source": { "enum": [ "database", "resident" ] }, "lag_seconds": { "type": "integer", "minimum": 0 } }, "required": [ "source", "lag_seconds" ], "additionalProperties": false } }, "required": [ "key_id", "plan", "quota", "metering" ], "additionalProperties": false }, "LiteResponse": { "type": "object", "properties": { "ip": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "continent_code": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "asn": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "asn_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "asn_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "ip", "country", "country_code", "continent", "continent_code", "asn", "asn_name", "asn_domain" ], "additionalProperties": false, "description": "Reserved schema for the future Lite product (#7). No Lite endpoint is available in this release.", "x-availability": "planned" } } } }