Parsing ASN, City, and Network Org JSON Responses Reliably
A software engineering guide to normalizing disparate IP intelligence payloads, parsing heterogeneous ASN strings, and validating schemas using Zod and Pydantic.
Quick Answer
Every IP intelligence provider structures its JSON response differently: IPinfo combines ASN and ISP into a single 'org' string, MaxMind uses nested integer/string objects, and coordinates alternate between comma-delimited strings and discrete numbers. Reliable parsing requires building a normalization adapter with runtime schema validators (Zod in TypeScript, Pydantic in Python) to output a unified data model.
- ASN Normalization: Standardize strings ("AS13335 Cloudflare") into discrete integer and organization fields.
- Coordinate Parsing: Split and validate float ranges (-90 to +90 lat, -180 to +180 lon) to prevent NaNs.
- Runtime Validation: Enforce Zod or Pydantic models to guarantee downstream type safety.
1. The Heterogeneous Schema Challenge
Compare how different major providers represent the exact same network entity:
2. Field-by-Field Schema Mapping Matrix
Compare how key attributes are declared across the three leading IP providers:
| Target Normalized Field | IPinfo.io Format | MaxMind GeoIP2 Format | DB-IP JSON Format | Target Data Type |
|---|---|---|---|---|
| IP Address | ip: "1.1.1.1" | traits.ip_address: "1.1.1.1" | ipAddress: "1.1.1.1" | String (IPv4 or IPv6) |
| Autonomous System (ASN) | org: "AS13335 Name" (Regex required) | traits.autonomous_system_number: 13335 | asn: 13335 | Integer (e.g. 13335) |
| Organization / ISP | org: "AS13335 Name" (Regex required) | traits.autonomous_system_organization | organization: "Name" | String |
| Coordinates | loc: "-33.8688,151.2093" (String) | location.latitude / location.longitude | latitude / longitude | Float pair [lat, lon] |
| Country Code | country: "AU" (ISO 3166-1) | country.iso_code: "AU" | countryCode: "AU" | String (2-letter uppercase) |
| City Name | city: "Sydney" | city.names.en: "Sydney" | city: "Sydney" | String or Null |
Schema Normalization Pipeline Decision Tree
[ Ingest Raw Vendor IP Intelligence JSON ]
|
+----------------+----------------+
| |
[ Detect Vendor Schema ] [ Check for Bogon / Error ]
IPinfo, MaxMind, or DB-IP? "bogon": true or 404?
| |
+----------------+----------------+
|
[ Schema Normalization Pipeline ]
1. Extract ASN as Integer: parse "AS13335" -> 13335
2. Normalize Coordinates: split "lat,lon" -> float[]
3. Validate ISO 3166-1 alpha-2 country code
4. Format IPv6 to lowercase compressed hex
|
[ Unified NormalizedIPRecord ]
Guaranteed type-safe schema across app
3. Production Implementation: TypeScript Normalizer with Zod
A TypeScript normalizer converting IPinfo strings into a standardized type-safe interface:
4. Production Implementation: Python Pydantic V2 Model
In Python, use Pydantic field validators to parse coordinate strings automatically:
Frequently Asked Questions
Why do different IP intelligence APIs format the ASN field differently?
There is no universal standard for IP JSON schemas. IPinfo formats ASN and ISP as a combined single string (e.g. "org": "AS13335 Cloudflare, Inc."), MaxMind splits them into an integer and string (e.g. "autonomous_system_number": 13335, "autonomous_system_organization": "Cloudflare"), and Team Cymru provides pipe-delimited text. Applications must use normalization adapters to clean these into unified objects.
How should coordinates formatted as "37.751,-122.42" be parsed safely?
Never assume the coordinate string is valid. Split by comma, parse both segments using parseFloat(), and validate that the latitude falls strictly within -90.0 to +90.0 and longitude falls within -180.0 to +180.0. If parsing fails or numbers are NaN, fall back to null to avoid application crashes.
How do you handle missing fields when querying Bogon or private IPs?
When a user looks up 127.0.0.1 or 192.168.1.1, external APIs return either HTTP 404, an error JSON with "bogon": true, or omit city and country objects entirely. Normalization schemas must define all geographic properties as optional/nullable with safe default fallbacks.
What is the advantage of using Zod or Pydantic for IP JSON parsing?
Schema libraries like Zod (TypeScript) and Pydantic (Python) enforce strict runtime type safety. They automatically strip malformed attributes, coerce strings to numbers, validate ISO country codes, and raise descriptive validation errors before invalid data reaches your database or user interface.
Data & Technical Sources
- IETF RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format
- ISO 3166-1 Country Codes — Standardized two-letter country codes (alpha-2)
- Zod TypeScript Schema Validation — TypeScript-first schema declaration and validation library