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 general 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: general
description: General API.
paths:
/:
get:
tags:
- general
summary: IPinfo Returns IP Information About the Current IP
description: 'Returns IP information about the current IP.
'
operationId: getCurrentInformation
security:
- BasicAuth: []
- BearerAuth: []
- ApiKeyAuth: []
responses:
'200':
$ref: '#/components/responses/FullResponse'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/{ip}:
get:
tags:
- general
summary: IPinfo Returns Information About the Provided IP
description: 'The ipinfo.io/{ip} endpoint provides comprehensive information about a specified IP address, including geographic location (city, region, country), coordinates, postal code, and timezone.
Based on the pricing tier, it also provides ASN (Autonomous System Number) details, associated company information, privacy settings (e.g., VPN, proxy usage), abuse contact information, and hosted domains associated with the IP.
This endpoint is useful for applications needing detailed IP intelligence, such as identifying geographic origin, privacy status, and potential abuse reporting information.
'
operationId: getInformationByIp
security:
- BasicAuth: []
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/Ip'
responses:
'200':
$ref: '#/components/responses/FullResponse'
'404':
$ref: '#/components/responses/NotFound'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/me:
get:
tags:
- general
summary: IPinfo Returns API Service Request Limit by Access Token
description: 'The `/me` API endpoint can be used to provide summary information on the access token limits, access to API products, and other related information.
The `/me` endpoint can be used in verifying access tokens as well.
'
operationId: getMe
security:
- BasicAuth: []
- BearerAuth: []
- ApiKeyAuth: []
responses:
'200':
$ref: '#/components/responses/Me'
'400':
$ref: '#/components/responses/BadRequestMe'
'500':
$ref: '#/components/responses/InternalServerError'
/batch:
post:
tags:
- general
summary: IPinfo Bulk IPinfo API Enrichment
description: Bulk or batch enrich IP addresses with IP information. See [documentation](https://ipinfo.io/developers/batch-enrichment-api).
operationId: batch
security:
- BasicAuth: []
- BearerAuth: []
- ApiKeyAuth: []
requestBody:
$ref: '#/components/requestBodies/Batch'
responses:
'200':
$ref: '#/components/responses/Batch'
/tools/summarize-ips:
post:
tags:
- general
summary: IPinfo Summarize IP Addresses
description: Get summary-level information of upto 500,000 IP addresses, including IP location on a map, IP types, privacy detection flags, top ASNs, top cities, and more. [Explore the IPinfo Summarize tool](https://ipinfo.io/tools/summarize-ips).
operationId: summarize
security:
- BasicAuth: []
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: cli
in: query
description: CLI flag parameter
required: false
schema:
type: integer
example: 1
requestBody:
$ref: '#/components/requestBodies/Summarize'
responses:
'200':
$ref: '#/components/responses/Summarize'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Rate limit exceeded. You can use the Summarize IPs tool up to 5 times per day. Please wait 24 hours or use our IPinfo Lite API service
/tools/map:
post:
tags:
- general
summary: IPinfo Highlight IP Addresses on a Map
description: Visualize upto 500,000 IP addresses on an interactive map. [Explore the IPinfo Map IPs tool](https://ipinfo.io/tools/map).
operationId: map
security:
- BasicAuth: []
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: cli
in: query
description: CLI flag parameter
required: false
schema:
type: integer
example: 1
requestBody:
$ref: '#/components/requestBodies/Map'
responses:
'200':
$ref: '#/components/responses/Map'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Rate limit exceeded. You can use the IP Map tool up to 5 times per day. Please wait 24 hours or use our IPinfo Lite API service
components:
schemas:
FullResponse:
type: object
required:
- ip
properties:
ip:
type: string
example: 66.87.125.72
bogon:
type: boolean
example: false
hostname:
type: string
example: ip-66-87-125-72.spfdma.spcsdns.net
city:
type: string
example: Springfield
region:
type: string
example: Massachusetts
country:
type: string
example: US
loc:
type: string
example: 42.0999,-72.5783
postal:
type: string
example: '01105'
timezone:
type: string
example: America/New_York
org:
type: string
example: AS51501 Khabarovsk home networks Ltd
asn:
$ref: '#/components/schemas/AsnResponse'
company:
$ref: '#/components/schemas/CompanyResponse'
carrier:
$ref: '#/components/schemas/CarrierResponse'
privacy:
$ref: '#/components/schemas/PrivacyResponse'
domains:
$ref: '#/components/schemas/DomainsResponse'
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: ''
Prefix:
type: object
required:
- netblock
- id
- name
- country
properties:
netblock:
type: string
example: 104.69.216.0/22
id:
type: string
example: AKAMAI
name:
type: string
example: Akamai Technologies, Inc.
country:
type: string
example: US
size:
type: string
example: '256'
status:
type: string
example: ALLOCATION
domain:
type: string
nullable: true
example: quadranet.com
AsnResponse:
type: object
required:
- asn
- name
- domain
- type
properties:
asn:
type: string
example: AS10507
name:
type: string
example: Sprint Personal Communications Systems
country:
type: string
example: US
allocated:
type: string
example: '1997-02-14'
registry:
type: string
example: arin
domain:
type: string
example: sprint.net
num_ips:
type: integer
example: 71224576
route:
type: string
example: 66.87.125.0/24
type:
type: string
example: isp
enum:
- isp
- business
- education
- hosting
- inactive
prefixes:
type: array
items:
$ref: '#/components/schemas/Prefix'
prefixes6:
type: array
items:
$ref: '#/components/schemas/Prefix6'
peers:
type: array
items:
type: string
example: '1299'
upstreams:
type: array
items:
type: string
example: '1299'
downstreams:
type: array
items:
type: string
example: '109'
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
CarrierResponse:
type: object
required:
- name
- mcc
- mnc
properties:
name:
type: string
example: Sprint Corporation
mcc:
type: string
example: '310'
mnc:
type: string
example: '120'
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.
DomainsResponse:
type: object
required:
- total
properties:
ip:
type: string
example: 1.1.1.1
page:
type: integer
example: 1
total:
type: integer
example: 17939
domains:
type: array
items:
type: string
example: udemy.com
MeResponse:
type: object
required:
- token
- requests
- features
properties:
token:
type: string
example: TOKEN
requests:
type: object
properties:
day:
type: integer
example: 0
month:
type: integer
example: 69
limit:
type: integer
example: 50000
remaining:
type: integer
example: 2147483578
features:
type: object
properties:
core:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
hostio:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
result_limit:
type: integer
example: 5
asn:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
abuse:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
whois:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
ranges:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
carrier:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
company:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
firmographics:
type: boolean
example: false
org_additional:
type: boolean
example: false
privacy:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
vpn_provider:
type: boolean
example: false
hosted_domains:
type: object
properties:
daily:
type: integer
example: 50000
monthly:
type: integer
example: 50000
result_limit:
type: integer
example: 5
Error500:
type: string
example: Internal server error
Error400Me:
type: object
required:
- error
properties:
error:
type: string
example: Invalid API token
token:
type: string
example: TOKEN
Prefix6:
type: object
required:
- netblock
- id
- name
- country
properties:
netblock:
type: string
example: 2601::/20
id:
type: string
example: COMCAST6NET
name:
type: string
example: Comcast Cable Communications, LLC
country:
type: string
example: US
size:
type: string
example: '20282409603651670423947251286016'
status:
type: string
example: ASSIGNMENT
domain:
type: string
example: comcast.com
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
Error422:
type: object
required:
- title
- message
properties:
title:
type: string
example: No IPs Found
message:
type: string
example: There were no valid IPs in the text.
CompanyResponse:
type: object
required:
- name
- domain
- type
properties:
name:
type: string
example: Sprint Springfield POP
domain:
type: string
example: sprint.com
type:
type: string
example: isp
enum:
- isp
- business
- education
- hosting
responses:
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'
Batch:
description: Batch response object.
content:
application/json:
schema:
type: object
additionalProperties:
type: object
example:
8.8.8.8/city: Mountain View
8.8.8.8:
ip: 8.8.8.8
hostname: dns.google
city: Mountain View
region: California
country: US
loc: 37.4056,-122.0775
org: AS15169 Google LLC
postal: 94043
timezone: America/Los_Angeles
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'
FullResponse:
description: Full response object.
content:
application/json:
schema:
$ref: '#/components/schemas/FullResponse'
NotFound:
description: Wrong ip. Please provide a valid IP address.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
Summarize:
description: Summarize response object.
content:
application/json:
schema:
type: object
example:
summary: Example of summarizing IP addresses
value:
status: Report Generated
reportUrl: https://ipinfo.io/tools/summarize-ips/3ea606f3-b3ad-4a37-a875-b897a0c2e718
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'
UnprocessableEntity:
description: The input payload does not meet the specification.
content:
application/json:
schema:
$ref: '#/components/schemas/Error422'
Me:
description: IPinfo access token rate and access information.
content:
application/json:
schema:
$ref: '#/components/schemas/MeResponse'
Map:
description: Map response object.
content:
application/json:
schema:
type: object
example:
summary: Example of mapping IP addresses
value:
status: Report Generated
reportUrl: https://ipinfo.io/tools/map/40c04638-a340-44b8-90de-f95afdff99d8
BadRequestMe:
description: If the passed IPinfo access token is not present or is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400Me'
requestBodies:
Summarize:
description: A file containing IP addresses with each IP on a separate line.
required: true
content:
text/plain:
schema:
type: string
example: '42.77.204.9
2a02:1811:1424:a200:a307:b776:645b:46b5
84.74.205.0
2601:19b:4980:2270:8869:1575:ffd0:5ba0
2a01:e0a:a2d:fd70::8056:6278
75.136.126.2
2400:4052:244:a900:8b5:16e9:badb:a2bd
104.103.81.185
2603:7000:8d40:47d7:64fc:6:56cf:1b54
216.211.59.51
'
Map:
description: A file containing IP addresses with each IP on a separate line.
required: true
content:
text/plain:
schema:
type: string
example: '46.95.248.61
215.113.215.175
27.7.158.28
209.99.186.255
192.40.165.85
2a02:c7f:f8c4:ca00:356d:ac4c:954c:e46
2001:16a2:9432:8126:2dbf:9aa0:8057:1246
2600:8807:a788:7c00:c828:264:8dcf:b37f
181.200.55.93
77.222.8.184
'
Batch:
description: A JSON array containing IP addresses.
required: true
content:
application/json:
schema:
type: array
example:
- 8.8.8.8/city
- 8.8.8.8
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