openapi: 3.0.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](https://ipinfo.io/developers#authentication)
## IPinfo API Tiers
IPinfo offers three 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](https://ipinfo.io/developers/lite-api)
### 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](https://ipinfo.io/developers/core-api)
### 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: `/plus/me`, `/plus/{ip}`, `/plus/{ip}/{field}`
- Base URL: `https://api.ipinfo.io/`
- [Documentation](https://ipinfo.io/developers/plus-api)
## Specialized Detection APIs
### Residential Proxy Detection
Detect residential, mobile, and datacenter proxy IPs with activity insights, last seen dates, and proxy service identification.
- Endpoints: `/{ip}/resproxy`
- [Documentation](https://ipinfo.io/developers/residential-proxy-api)
### 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](https://ipinfo.io/developers/privacy-standard-api)
### Privacy Detection Extended
Advanced anonymous IP detection with detailed methodologies, confidence metrics, and metadata for VPNs, proxies, Tor, hosting providers, and relays.
- Endpoints: `/{ip}/privacy_extended`
- [Documentation](https://ipinfo.io/developers/privacy-extended-api)
## Legacy API Products
For backwards compatibility, legacy endpoints remain available:
- [IP to Geolocation API](https://ipinfo.io/products/ip-geolocation-api) - Use Core or Plus instead
- [IP to Privacy Detection API](https://ipinfo.io/products/proxy-vpn-detection-api) - Use Plus instead
- [ASN API](https://ipinfo.io/products/asn-api) - `/AS{asn}` endpoint
- [IP to Company API](https://ipinfo.io/products/ip-company-api) - `/{ip}/company` endpoint
- [Hosted Domains API](https://ipinfo.io/products/reverse-ip-api) - `/domains/{ip}` endpoint
- [IP to Phone Carrier Detection API](https://ipinfo.io/products/ip-carrier-api) - `/{ip}/carrier` endpoint
- [IP to Abuse Contact API](https://ipinfo.io/products/ip-abuse-contact-api) - `/{ip}/abuse` endpoint
- [IP WHOIS API](https://ipinfo.io/products/whois-api) - `/whois/*` endpoints
## Special Endpoints
- **Token Info**: `/me` - View request limits and API access for your token
- **Batch Requests**: `/batch` - Enrich multiple IPs in a single request
- **IP Summarization**: `/tools/summarize-ips` - Analyze up to 500,000 IPs
- **IP Mapping**: `/tools/map` - Visualize up to 500,000 IPs on an interactive map
- **Single Field**: `/{ip}/{field}` - Get specific field values as plaintext
## Rate Limits
- **IPinfo Lite**: Unlimited requests on paid plans
- **Paid Plans**: Monthly request limits with configurable alerts and automatic metered billing
- **Rate Limit Exceeded**: 429 HTTP status code when limit reached
[View pricing and limits](https://ipinfo.io/pricing)
## Resources
- **Developer Portal**: [https://ipinfo.io/developers](https://ipinfo.io/developers)
- **API Libraries**: Official libraries for Python, Node.js, Java, Ruby, PHP, Go, and more
- **Sign Up**: [Free account](https://ipinfo.io/signup) with up to 50,000 requests/month
- **Community Support**: [https://community.ipinfo.io/](https://community.ipinfo.io/)
- **Email Support**: support@ipinfo.io
---
'
version: 1.0.0
title: IPinfo.io OpenAPI Specification abuse privacy detection extended API
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: IPinfo 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:
responses:
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'
NotFound:
description: Wrong ip. Please provide a valid IP address.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
PrivacyExtended:
description: Privacy Detection Extended response with detailed methodologies.
content:
application/json:
schema:
$ref: '#/components/schemas/PrivacyExtendedResponse'
InternalServerError:
description: Internal server error or server unavailable.
content:
text/plain:
schema:
$ref: '#/components/schemas/Error500'
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'
parameters:
Ip:
name: ip
in: path
description: A single IPv4 or IPv6 IP address.
required: true
schema:
type: string
schemas:
Error500:
type: string
example: Internal server error
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
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
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'
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
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