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 single 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: single description: Single info API. paths: /ip: get: tags: - single summary: IPinfo Returns the Current IP description: 'Returns the current public/external IP address. ' operationId: getCurrentIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/Ip' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/ip: get: tags: - single summary: IPinfo Returns a IP for the Selected IP description: 'Returns a ip for the selected IP. ' operationId: getIpByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/Ip' '404': $ref: '#/components/responses/NotFound' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /hostname: get: tags: - single summary: IPinfo Returns the Current Hostname description: 'Returns the current hostname. ' operationId: getCurrentHostname security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/Hostname' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/hostname: get: tags: - single summary: IPinfo Returns a Hostname for the Selected IP description: 'Returns a hostname for the selected IP. ' operationId: getHostnameByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/Hostname' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /city: get: tags: - single summary: IPinfo Returns the Current City description: 'Returns the current city. ' operationId: getCurrentCity security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/City' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/city: get: tags: - single summary: IPinfo Returns a City for the Selected IP description: 'Returns a city for the selected IP. ' operationId: getCityByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/City' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /region: get: tags: - single summary: IPinfo Returns the Current Region description: 'Returns the current region. If the region is not available, it will return an empty string. ' operationId: getCurrentRegion security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/Region' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/region: get: tags: - single summary: IPinfo Returns a Region for the Selected IP description: 'Returns a region for the selected IP. If the region is not available, it will return an empty string. ' operationId: getRegionByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/Region' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /country: get: tags: - single summary: IPinfo Returns the Current Country description: 'Returns a concise response consisting of a two-letter country code. If the country is not available, it will return an empty string. ' operationId: getCurrentCountry security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/Country' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/country: get: tags: - single summary: IPinfo Returns a Country for the Selected IP description: 'Returns a country for the selected IP in two letter ISO-3166 format. If the country is not available, it will return an empty string. ' operationId: getCountryByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/Country' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /loc: get: tags: - single summary: IPinfo Returns the Current Location description: 'The ''/loc'' API endpoint provides the geographical location of a user''s IP address in a response with latitude and longitude in comma-separated text format. ' operationId: getCurrentLocation security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/Location' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/loc: get: tags: - single summary: IPinfo GET a Location for the Selected IP description: 'The ''/loc'' API endpoint provides the geographic location of an IP address as latitude and longitude separated by a comma in text form. ' operationId: getLocationByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/Location' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /postal: get: tags: - single summary: IPinfo Returns the Current Postal Code or Zip Code description: 'The `/postal` API endpoint provides a straightforward method for retrieving the current postal code or zip code. When this endpoint is queried, the API responds with a simple string indicating the postal code for the current IP address. ' operationId: getCurrentPostal security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/Postal' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/postal: get: tags: - single summary: IPinfo Returns a Postal for the Selected IP description: 'The `/postal` API lets users input an IP address to get back the corresponding postal or zip code in a simple string format. ' operationId: getPostalByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/Postal' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /timezone: get: tags: - single summary: IPinfo Returns the Current Timezone description: 'The ''/timezone'' API endpoint returns the user''s timezone based on their IP address in IANA format. ' operationId: getCurrentTimezone security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/Timezone' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/timezone: get: tags: - single summary: IPinfo Returns a Timezone for the Selected IP description: 'The `/timezone` API endpoint returns the IANA timezone based on the user''s input IP address. ' operationId: getTimezoneByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/Timezone' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /org: get: tags: - single summary: IPinfo Returns the Current ASN and as Organization description: 'The ''/org'' API endpoint identifies the Autonomous System Number (ASN) and ASN organization associated with the user''s IP address. When called, the API returns a string with the ASN (prefixed by ''AS'') and organization name. ' operationId: getCurrentOrganization security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] responses: '200': $ref: '#/components/responses/Organization' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /{ip}/org: get: tags: - single summary: IPinfo Returns a Organization for the Selected IP description: 'The ''/org'' API endpoint provides the ASN and organization related to the user''s input IP address. It returns a string including the ASN (prefixed by ''AS'') and AS organization name. ' operationId: getOrganizationByIp security: - BasicAuth: [] - BearerAuth: [] - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/Ip' responses: '200': $ref: '#/components/responses/Organization' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: responses: Timezone: description: Timezone of the located IP address in the format of IANA Time Zones. content: text/plain: schema: type: string example: America/New_York Country: description: Name of the country in the 2 letter ISO 3166-1 alpha-2 for the IP address. content: text/plain: schema: type: string example: US BadRequest: description: If users try to access a field type that does not exist or do not have permissions to access it, they will encounter a wrong module or field type error. content: application/json: schema: $ref: '#/components/schemas/Error400' InternalServerError: description: Internal server error or server unavailable. content: text/plain: schema: $ref: '#/components/schemas/Error500' Location: description: Geographic coordinate of the IP address in the format of `, `. content: text/plain: schema: type: string example: 42.0999,-72.5783 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' NotFound: description: Wrong ip. Please provide a valid IP address. content: application/json: schema: $ref: '#/components/schemas/Error404' Ip: description: Public IP address. content: text/plain: schema: type: string example: 66.87.125.72 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' City: description: The city name of the IP address. content: text/plain: schema: type: string example: Springfield Region: description: The name of the region or state of the IP address. content: text/plain: schema: type: string example: Massachusetts Hostname: description: Hostname of the IP address. content: text/plain: schema: type: string example: ip-66-87-125-72.spfdma.spcsdns.net Postal: description: Postal code or zip code for the IP address. content: text/plain: schema: type: string example: '01105' Organization: description: ASN and AS organization name for the IP address. content: text/plain: schema: type: string example: AS51501 Khabarovsk home networks Ltd 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 Error400: type: object required: - title - message properties: title: type: string example: Wrong module or field type message: type: string example: No module or field of type exists for the provided field. Please check our documentation https://ipinfo.io/developers. 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 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 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