🎯 字段查询 Field

只需要某个字段？用单字段端点，省流量、更快。

单字段端点

ipapi.co 提供 GET /{ip}/{field}/ 端点，只返回该字段的值（纯文本）。本库封装为 GetField：

country, _ := client.GetField(ctx, "8.8.8.8", "country_code")
fmt.Println(country) // US

查询客户端 IP 的单字段用 GetClientField：

city, _ := client.GetClientField(ctx, "city")

定义在 api.go 的 validFields，共 28 个：

类别	字段
🌐 网络	`ip` `network` `version`
🏙 地理	`city` `region` `region_code` `postal`
🌍 国家	`country` `country_name` `country_code` `country_code_iso3` `country_capital` `country_tld` `continent_code` `in_eu`
🧭 坐标	`latitude` `longitude` `latlong`
⏰ 时间	`timezone` `utc_offset`
🗣 语言	`languages` `country_calling_code`
💱 货币	`currency` `currency_name`
📊 统计	`country_area` `country_population`
📡 ASN	`asn` `org` `hostname`

字段含义详见字段总览。

传非法字段会返回 ErrInvalidField：

_, err := client.GetField(ctx, "8.8.8.8", "nonexistent")
// err 满足 errors.Is(err, ipapi.ErrInvalidField)

校验在客户端完成，不发网络请求。

🎨 一图抵千言

决策树看的是“选哪个端点”的分支，下面这张时序图则把一次 GetField 调用从入参到返回的完整时间线摊开：本地校验先行、不发网络，校验通过后才依次走鉴权、请求、解析、计费。

🎨 一图抵千言

下面的决策树帮你快速判断该用 GetIPInfo 还是 GetField，关键在配额权衡：两者每次调用各消耗 1 次配额，所以需要的字段越多，单字段查询越不划算。

💡 配额注意

无论完整还是单字段，每次调用都消耗 1 次配额。若需要 5 个以上字段，直接用 GetIPInfo 更划算。

需要 3 个字段时，建议一次 GetIPInfo 取全部：

info, _ := client.GetIPInfo(ctx, "8.8.8.8", "json")
// 一次拿到 city、country、asn
fmt.Println(info.City, info.CountryCode, info.ASN)