IPinfo API Response Patterns

Abdullah · October 2, 2025, 8:33pm

API responses, like naming things, are tricky. With over 100 billion requests served, we want to make sure IPinfo’s API is predictable, consistent, and easy to use.

This guide explains how our API works, including endpoints, path segments, field selectors, tokens, nested objects, missing values, and data types.

API Services

For our primary API system we use API base URL:

api.ipinfo.io

We currently have two main API services:

Lite API: api.ipinfo.io/lite/
Paid APIs (IPinfo Core, IPinfo Plus, upcoming): api.ipinfo.io/lookup/

Path Segments

Each API call must specify the target IP address, either implicitly (/me) or explicitly (/<ip>):

/me – Returns information about the requester’s IP address (your server, client, or visitor).
- Lite: api.ipinfo.io/lite/me
- Paid: api.ipinfo.io/lookup/me
/<ip> – Returns information for a specific IPv4 or IPv6 address.
- Lite: api.ipinfo.io/lite/8.8.8.8
- Paid: api.ipinfo.io/lookup/8.8.8.8

Mandatory Token

All requests require an access token:

?token=<YOUR_ACCESS_TOKEN>

For example:

Lite API (your IP info): api.ipinfo.io/lite/me?token=123abc
Lite API (specific field): api.ipinfo.io/lite/me/country?token=123abc
Paid API (specific IP lookup): api.ipinfo.io/lookup/8.8.8.8?token=123abc etc.

Without a valid token, the API returns an authentication error.

Field Selectors

Optional field selectors let you request specific parts of the response:

Get the Country name from the IPinfo Lite API: api.ipinfo.io/lite/me/country

$ curl api.ipinfo.io/lite/me/country?token=$TOKEN
United States

Get the satellite status from the IPinfo Core/Plus API: api.ipinfo.io/lookup/99.168.160.145/is_satellite

 $ curl api.ipinfo.io/lookup/99.168.160.145/is_satellite?token=$TOKEN
false

Nested Fields

If you want to know the name of the city associated with your or a particular IP address using the IPinfo Core data, then you have to use api.ipinfo.io/lookup/me/geo/city and not api.ipinfo.io/lookup/me/city.

$ curl api.ipinfo.io/lookup/8.8.8.8/geo/city?token=$TOKEN
Mountain View

$ curl api.ipinfo.io/lookup/8.8.8.8/city?token=$TOKEN
{
  "error": "city is not a valid field."
}

The reason is that the field city is contained within the object geo. Currently, the API response for our paid tiers is nested, meaning that along with direct top level fields like ip and network flags (like is_anonymous), we provide some objects that contain similar grouped data like geo, as, mobile, etc. To access the data inside them, you have to prepend them with their parent field’s name for API parameters.

city inside geo: api.ipinfo.io/lookup/1.1.1.1/geo/city
ASN name inside as: api.ipinfo.io/lookup/1.1.1.1/as/name

$ curl api.ipinfo.io/lookup/1.1.1.1/geo/city?token=$TOKEN
Brisbane

$ curl api.ipinfo.io/lookup/1.1.1.1/as/name?token=$TOKEN
Cloudflare, Inc.

Now you can get the object itself. Rather than only getting a string of a specific value, you can get the entire geo field as an object response (api.ipinfo.io/lookup/me/geo)

$ curl api.ipinfo.io/lookup/1.1.1.1/geo?token=$TOKEN

{
  "city": "Brisbane",
  "region": "Queensland",
  "region_code": "QLD",
  "country": "Australia",
  "country_code": "AU",
  "continent": "Oceania",
  "continent_code": "OC",
  "latitude": -27.48159,
  "longitude": 153.0175,
  "timezone": "Australia/Brisbane",
  "postal_code": "4101",
  "geoname_id": "2174003",
  "radius": 5000,
  "last_changed": "2024-10-20"
}

Handling Missing Values

ASN Fields

It is quite common for ASN related information to not be present in our response. The reason is that these IP addresses are not being announced in BGP tables and are non-routable.

For our IP info Lite data, we do not show the ASN related fields as_name, asn, and as_domain. If you specifically query for these fields, for example: api.ipinfo.io/lite/me/asn, we will respond with null for the API response.

$ curl api.ipinfo.io/lite/1.1.1.1/?token=$TOKEN
{
  "ip": "1.1.1.1",
  "asn": "AS13335",
  "as_name": "Cloudflare, Inc.",
  "as_domain": "cloudflare.com",
  "country_code": "AU",
  "country": "Australia",
  "continent_code": "OC",
  "continent": "Oceania"
}

$ curl api.ipinfo.io/lite/1.1.1.1/as_domain?token=$TOKEN
cloudflare.com

$ curl api.ipinfo.io/lite/1.1.1.1/as_name?token=$TOKEN
Cloudflare, Inc.

$ curl api.ipinfo.io/lite/1.1.1.1/asn?token=$TOKEN
AS13335

$ curl api.ipinfo.io/lite/23.106.43.241?token=$TOKEN
{
  "ip": "23.106.43.241",
  "country_code": "US",
  "country": "United States",
  "continent_code": "NA",
  "continent": "North America"
}

$ curl api.ipinfo.io/lite/23.106.43.241/asn?token=$TOKEN

$ curl api.ipinfo.io/lite/23.106.43.241/as_name?token=$TOKEN

$ curl api.ipinfo.io/lite/23.106.43.241/as_domain?token=$TOKEN

However, for our paid tier (/lookup) API response, we do something slightly different. Our ASN related information is contained within the as object. Inside the as object, we have fields like name (ASN name), domain (ASN domain), type (ASN type), etc. So, when the ASN related information is not present, we show an empty object for the as field value.

$ curl api.ipinfo.io/lookup/23.106.43.241/as?token=$TOKEN
{}

$ curl api.ipinfo.io/lookup/23.106.43.241/as/asn?token=$TOKEN

$ curl api.ipinfo.io/lookup/23.106.43.241/as/name?token=$TOKEN

$ curl api.ipinfo.io/lookup/23.106.43.241/as/domain?token=$TOKEN

Geo Fields

Fields inside the geo object may or may not exist, such as region or region_code for Singaporean IP addresses, and postal_code for UAE-based IP addresses, etc.

$ curl api.ipinfo.io/lookup/103.78.29.171/geo?token=$TOKEN
{
  "city": "Singapore",
  "country": "Singapore",
  "country_code": "SG",
  "continent": "Asia",
  "continent_code": "AS",
  "latitude": 1.28967,
  "longitude": 103.85007,
  "timezone": "Asia/Singapore",
  "postal_code": "018989",
  "geoname_id": "1880252",
  "radius": 50,
  "last_changed": "2024-01-28"
}

$ curl api.ipinfo.io/lookup/74.125.98.127/geo?token=$TOKEN
{
  "city": "Al Fujairah City",
  "region": "Fujairah",
  "region_code": "FU",
  "country": "United Arab Emirates",
  "country_code": "AE",
  "continent": "Asia",
  "continent_code": "AS",
  "latitude": 25.11641,
  "longitude": 56.34141,
  "timezone": "Asia/Dubai",
  "geoname_id": "292878",
  "radius": 20,
  "last_changed": "2025-06-29"
}

Privacy / Anonymous Fields (Plus API)

The privacy name information describes the name of the anonymous IP service being used. This could be the name of the VPN provider or relay service provider, etc. This privacy name information is available on the IPinfo Plus “anonymous” object.

The anonymous object contains 5 fields, with 4 fields returning boolean responses - like proxy, Tor, VPN, and relay. If we cannot identify the privacy service name, we will not return the field name even if we have “true” as a value for one of the anonymous IP services.

For example, it could be a VPN service, but the privacy name field will not be present. If we identify the IP address as hosting a corporate VPN IP service - not a commercial VPN service, we cannot pinpoint this to a particular service, so we do not show the privacy field itself.
anonymous object contains:

is_proxy (boolean)
is_vpn (boolean)
is_tor (boolean)
is_relay (boolean)
name (string, optional)

If the service name can’t be identified, name is omitted and direct queries for anonymous/name return null.

$ curl api.ipinfo.io/lookup/103.77.189.54/anonymous?token=$TOKEN
{
  "name": "NetScop",
  "is_proxy": false,
  "is_relay": false,
  "is_tor": false,
  "is_vpn": true
}

$ curl api.ipinfo.io/lookup/74.142.128.130/anonymous?token=$TOKEN
{
  "is_proxy": false,
  "is_relay": false,
  "is_tor": false,
  "is_vpn": true
}

Boolean Fields and F

Booleans are always true or false (never null):

Top-level: /is_anonymous, /is_anycast, /is_hosting
Nested: /anonymous/is_proxy, /anonymous/is_relay

Summary of the API response Data Types

Field Type	Example Fields	Format / Notes
String	`ip`, `hostname`, `country`, `city`	Plain text
Boolean	`is_hosting`, `is_anycast`, `is_proxy`	true / false only
Float	`geo/latitude`, `geo/longitude`	Signed float values
Integer	`geo/radius`, `geo/geoname_id`	Integer values
Date	`as/last_changed`, `geo/last_changed`	YYYY-MM-DD
Null	Queried fields with no data	Explicit null
Empty Obj	`as` when no ASN data is present	{}

URL Breakdown

An IPinfo API URL consists of four main parts:

https://api.ipinfo.io/<service>/<path_segment>/<field_selector>?token=<YOUR_TOKEN>

Part	Example	Description
API service	`lite` or `lookup`	Which API service you’re calling
Path segment	`me` or `8.8.8.8`	Target IP, either your IP (`me`) or any IPv4/IPv6
Field selector	`country`, `geo/city`, `as/name`	Specific field(s) in the response (optional)
Query parameter	`?token=123abc`	Mandatory access token for authentication

If you want to explore our data more closesly, I highly recommend you checkout the
Code Snippets - IPinfo.io documentation

Topic		Replies	Views
IPinfo Lite: The ultimate IP to country API service General	6	157	September 6, 2025
The updated API systems requires two mandatory parameters: `context` and `parameter` for the IP General	2	74	November 14, 2025
Overview of IPinfo API endpoints General	2	300	July 16, 2025
How our API works on IPv4 and IPv6 connection General api	0	297	July 11, 2025
Ipinfo.io/me tells you about the API access you have and your limits General	0	61	December 16, 2025