# IPinfo API Response Patterns **URL:** \ **Category:** Knowledgebase\ **Tags:** api\ **Created:** [October 2, 2025, 8:33pm UTC](https://community.ipinfo.io/t/ipinfo-api-response-patterns/7125 "2025-10-02T20:33:42Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![Abdullah](https://yyz1.discourse-cdn.com/flex035/user_avatar/community.ipinfo.io/abdullah/32/4973_2.png) [@Abdullah](https://community.ipinfo.io/u/Abdullah)\ **Post date:** [October 2, 2025, 8:33pm UTC](https://community.ipinfo.io/t/ipinfo-api-response-patterns/7125/1 "2025-10-02T20:33:42Z")
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: ```auto 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 (`/`): - **`/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` - **`/`** – 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: ```auto ?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` ```auto $ 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` ```auto $ 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`. ```auto $ 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` ```auto $ 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`) ```auto $ 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. ```auto $ 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 ``` ```auto $ 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. ```auto $ 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. ```auto $ 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`. ```auto $ 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: ```auto https://api.ipinfo.io///?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](https://ipinfo.io/developers/code-snippets) documentation