IPinfo privacy detection API

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](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 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
  description: Privacy Detection Standard API.
  externalDocs:
    description: Find more info here
    url: https://ipinfo.io/developers/privacy-standard-api
paths:
  /{ip}/privacy:
    get:
      tags:
      - privacy detection
      summary: IPinfo Returns Privacy Information About the Selected IP
      description: 'The IP to Privacy Detection or Anonymous IP API provides privacy-related information about a specified IP address.

        This includes whether the IP is associated with a VPN, proxy, Tor network, relay service, or a hosting service/data center (indicative of bots).

        The response details the privacy status of the IP, indicating any anonymizing services in use and specifies the type of service (e.g., NordVPN, TunnelBear, Mullvad, ProtonVPN, CyberGhost, ExpressVPN, Surfshark etc.).

        '
      operationId: getPrivacyInformationByIp
      security:
      - BasicAuth: []
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Ip'
      responses:
        '200':
          $ref: '#/components/responses/Privacy'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PrivacyResponse:
      type: object
      required:
      - vpn
      - proxy
      - tor
      - hosting
      - relay
      - service
      properties:
        vpn:
          type: boolean
          example: true
        proxy:
          type: boolean
          example: false
        tor:
          type: boolean
          example: false
        hosting:
          type: boolean
          example: false
        relay:
          type: boolean
          example: false
        service:
          type: string
          example: ''
    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
    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
    Error500:
      type: string
      example: Internal server error
    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
  parameters:
    Ip:
      name: ip
      in: path
      description: A single IPv4 or IPv6 IP address.
      required: true
      schema:
        type: string
  responses:
    InternalServerError:
      description: Internal server error or server unavailable.
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/Error500'
    NotFound:
      description: Wrong ip. Please provide a valid IP address.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404'
    Privacy:
      description: Privacy response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivacyResponse'
    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'
    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'
  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