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 `<latitude>, <longitude>`.
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