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 residential proxy detection… 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: residential proxy detection description: Residential Proxy Detection API. externalDocs: description: Find more info here url: https://ipinfo.io/developers/residential-proxy-api paths: /resproxy/{ip}: get: tags: - residential proxy detection summary: Returns residential proxy detection information for the selected IP description: 'The Residential Proxy Detection API provides detailed insights into IP addresses associated with residential, mobile, or datacenter proxy networks. This includes activity patterns (last seen date, percentage of days active), and proxy service identification. Services are suffixed with `_mobile` for carrier/mobile proxies or `_datacenter` for datacenter proxies.' operationId: getResidentialProxyByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/ResidentialProxy' '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 ResidentialProxyResponse: type: object required: - ip - last_seen - percent_days_seen - service properties: ip: type: string description: The IPv4 or IPv6 address associated with a residential proxy example: 175.107.211.204 last_seen: type: string format: date description: The last recorded date when the residential proxy IP was active (YYYY-MM-DD, UTC) example: '2025-06-24' percent_days_seen: type: integer minimum: 0 maximum: 100 description: The percentage of days the IP was active in the last 7-day period example: 14 service: type: string description: The name of the residential proxy service. Suffixed with _mobile for carrier/mobile or _datacenter for datacenter proxies example: ipfoxy 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' ResidentialProxy: description: Residential Proxy detection response. content: application/json: schema: $ref: '#/components/schemas/ResidentialProxyResponse' 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)