openapi: 3.2.0 info: description: 'Official OpenAPI Specification for IPinfo''s comprehensive IP intelligence API. This specification defines all endpoints for IP geolocation, ASN data, company information, privacy detection, and specialized data services. ## Authentication All endpoints support three authentication methods: - **HTTP Basic Auth**: Use your token as the username with empty password - **Bearer Token**: Include token in Authorization header - **Query Parameter**: Pass token as `?token=YOUR_TOKEN` Learn more about authentication ## IPinfo API Tiers IPinfo offers four main API tiers with different feature sets: ### IPinfo Lite Lightweight IP geolocation with essential information including ASN details, country, and continent data. Perfect for basic geolocation needs with fast response times. Unlimited requests on paid plans. - Endpoints: `/lite/me`, `/lite/{ip}`, `/lite/{ip}/{field}` - Base URL: `https://api.ipinfo.io/` - Documentation ### IPinfo Core Comprehensive IP information with detailed geolocation data (city, region, coordinates, postal code, timezone), ASN information, and classification boolean flags (anycast, hosting, mobile, satellite). - Endpoints: `/lookup/me`, `/lookup/{ip}`, `/lookup/{ip}/{field}` - Base URL: `https://api.ipinfo.io/` - Documentation ### IPinfo Plus All Core features plus mobile/carrier detection, anonymity analysis (VPN, proxy, Tor, relay detection), service identification, and extended geographic metadata. Ideal for security, fraud prevention, and advanced analytics. - Endpoints: `/lookup/me`, `/lookup/{ip}`, `/lookup/{ip}/{field}` (shared with Core — response shape depends on your token''s plan) - Base URL: `https://api.ipinfo.io/` - Documentation ### IPinfo Max Our most comprehensive IP intelligence tier, building on all Plus features with full anonymization coverage including residential proxy behavioral signals, in addition to geolocation, ASN, and carrier data. Ideal for advanced threat analysis and bot detection. - Endpoints: `/lookup/me`, `/lookup/{ip}`, `/lookup/{ip}/{field}` (shared with Core and Plus — response shape depends on your token''s plan) - Base URL: `https://api.ipinfo.io/` - Documentation ## Specialized Detection APIs ### Residential Proxy Detection Detect residential, mobile, and datacenter proxy IPs with activity insights, last seen dates, and proxy service identification. - Endpoints: `/resproxy/{ip}` - Documentation ### Privacy Detection Standard Detect VPNs, proxies, Tor exit nodes, relays, and hosting providers associated with an IP address. Returns core privacy signals including service provider identification. - Endpoints: `/{ip}/privacy` - Documentation ### Privacy Detection Extended Advanced anonymous IP detection with detailed methodologies, confidence metrics, and metadata for VPNs, proxies, Tor, hosting providers, and relays.' version: 1.0.0 title: IPinfo.io OpenAPI Specification privacy detection extended… contact: name: IPinfo email: support@ipinfo.io url: https://ipinfo.io/ servers: - url: https://ipinfo.io/ - url: https://v6.ipinfo.io/ - url: https://api.ipinfo.io/ tags: - name: privacy detection extended description: Privacy Detection Extended API with detailed methodologies. externalDocs: description: Find more info here url: https://ipinfo.io/developers/privacy-extended-api paths: /{ip}/privacy_extended: get: tags: - privacy detection extended summary: Returns extended privacy detection information with detailed methodologies description: 'The Privacy Detection Extended API provides detection methodology metadata to support risk scoring, confidence metrics, and IP reputation aspects. Uses multi-modal detection methods including internet measurement, IP behavior analysis, and internet records metadata. Includes detailed flags for VPN, proxy, Tor, relay, hosting, and service identification with confidence metrics.' operationId: getPrivacyExtendedByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/PrivacyExtended' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: schemas: Error429: type: object required: - title - message properties: title: type: string example: Rate limit exceeded message: type: string example: Upgrade to increase your usage limits at https://ipinfo.io/pricing, or contact us via https://ipinfo.io/support PrivacyExtendedResponse: type: object required: - vpn - proxy - tor - relay - hosting - service properties: vpn: type: boolean description: Indicates Virtual Private Network (VPN) service exit node IP address example: true proxy: type: boolean description: Indicates an open web proxy IP address example: false tor: type: boolean description: Indicates a Tor (The Onion Router) exit node IP address example: false relay: type: boolean description: Indicates a location-preserving anonymous relay service example: false hosting: type: boolean description: Indicates a hosting/cloud service/data center IP address example: true service: type: string description: Name of the privacy service provider - includes VPN, Proxy, and Relay service provider names example: NordVPN confidence: type: integer minimum: 1 maximum: 3 description: The level of confidence attributed to the best source associated with this range. Level 3 - Direct observation of commercial use (vpn_config). Level 2 - Direct observation of VPN software running on the range (census) + registrar information associated with VPNs or specific providers OR highly convincing device activity. Level 1 - Direct observation of VPN software running on the range (census) without known association to specific providers or VPNs in general OR suspicious device data not associated with hosting ranges example: 3 coverage: type: number minimum: 0 maximum: 1 description: For inferred ranges, represents the proportion of the range (in IP count) that we saw direct evidence of VPN activity on. For IPs/ranges we've fully directly observed VPN evidence on, this value is 1.0 example: 1.0 census: type: boolean description: Ranges where we've observed VPN software/ports on; we run scans on ports and protocols commonly associated with VPN software. Ranges with the census flag are those where these scans obtained positive results example: false census_ports: type: array items: type: integer description: The ports we've gotten positive results for when running our VPN detection census example: [] device_activity: type: boolean description: Ranges on which we've observed device activity compatible with VPN usage (outside of known infrastructure area; simultaneous use around a large area; pingable and/or associated with hosting providers) example: false inferred: type: boolean description: Whether the range associated with the record is the result of direct observation or inference based on neighboring IPs example: false vpn_config: type: boolean description: Ranges where we confirmed VPN activity by directly running VPN software from almost 200 different providers and collecting exit IPs example: false whois: type: boolean description: Ranges where we've observed VPN software/ports on AND have a WHOIS association with either VPNs in general or specific VPN providers example: false first_seen: type: string format: date description: Date when the activity on an anonymous IP address was first observed. Date in YYYY-MM-DD format, ISO-8601. Within the 3-month lookback period example: '2025-09-19' last_seen: type: string format: date description: Date when the activity on an anonymous IP address was last/recently observed. Date in YYYY-MM-DD format, ISO-8601 example: '2025-11-06' Error404: type: object required: - status - error properties: status: type: integer example: 404 error: type: object required: - title - message properties: title: type: string example: Wrong ip message: type: string example: Please provide a valid IP address Error500: type: string example: Internal server error Error403: type: object required: - title - message properties: title: type: string example: Unknown token message: type: string example: Please ensure you've entered your token correctly. Refer to https://ipinfo.io/developers for details, or contact us at support@ipinfo.io for help responses: TooManyRequests: description: Allocated API rate limit has been reached for the token. The user will be prompted with options to increase their API limit. content: application/json: schema: $ref: '#/components/schemas/Error429' PrivacyExtended: description: Privacy Detection Extended response with detailed methodologies. content: application/json: schema: $ref: '#/components/schemas/PrivacyExtendedResponse' NotFound: description: Wrong ip. Please provide a valid IP address. content: application/json: schema: $ref: '#/components/schemas/Error404' InternalServerError: description: Internal server error or server unavailable. content: text/plain: schema: $ref: '#/components/schemas/Error500' Forbidden: description: Unknown token or invalid permission. We return the same error for blocking malicious IP addresses as well. content: application/json: schema: $ref: '#/components/schemas/Error403' parameters: Ip: name: ip in: path description: A single IPv4 or IPv6 IP address. required: true schema: type: string securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: query name: token externalDocs: description: IPinfo Developers Portal / Documentation url: https://ipinfo.io/developers x-provenance: method: harvested publisher: IPinfo source: https://ipinfo.io/developers/openapi.yaml note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)