{"openapi":"3.0.3","info":{"title":"IP 归属地查询","description":"根据 IP 地址查询其归属地信息（所在国家、省份、城市等）。\n### 平台统一约定\n- **响应信封**：`output=json`（默认）返回 `{code, msg, data}`，code 与 HTTP 状态码一致；`output=raw` 直接返回简单文本或图片二进制\n- **鉴权**：公开接口无需凭据；需鉴权接口携带 `X-App-Id` + `X-App-Secret`（明文）或 `X-App-Id` + `X-Timestamp` + `X-Nonce` + `X-Signature`（HMAC-SHA256 签名），文档页右上角「鉴权助手」可在线生成请求头\n- **默认限流**：60 次/秒（粒度 {appid|ip}:{plugin}，appid 级配额可覆盖；超限返回 429）\n- **文档数据**：接口参数/返回/示例来自 handler 方法 PHPDoc 注解，方法注册/鉴权/限流来自 manifest","version":"1.0.0"},"servers":[{"url":"/api/ip","description":"当前站点"}],"tags":[{"name":"公开接口","description":"无需凭据即可调用"},{"name":"需鉴权接口","description":"需携带 appid/appsecret（明文双头或 HMAC 签名），详见「鉴权助手」"}],"paths":{"/query":{"get":{"tags":["公开接口"],"summary":"IP 归属地查询","description":"**返回**：data 为 {ip, country, province, city, area, isp}；country 取数据首段国家名，province/city 取后续层级，isp 从 area 匹配运营商\n\n**默认限流**：60 次/秒（appid 级配额可覆盖）","operationId":"ip_query","x-auth-required":false,"x-rate-limit":{"s":60},"parameters":[{"name":"ip","in":"query","required":true,"description":"待查询的 IPv4 地址（公网/内网均支持）","schema":{"type":"string"}},{"name":"output","in":"query","required":false,"description":"json（默认，统一信封）|raw（输出「country province city area isp」空格拼接，跳过与入参同名的 ip 回显字段）","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"msg":"","data":{"ip":"114.114.114.114","country":"中国","province":"江苏","city":"南京","area":"Alexa CN","isp":"南京信风信息技术 port 114 DNS"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"Envelope":{"type":"object","description":"平台统一响应信封，code 与 HTTP 状态码一致；output=raw 时无信封（直接输出文本/图片二进制）","properties":{"code":{"type":"integer","description":"200 成功；400 参数错误；401 凭据无效；403 拒绝访问；429 触发限流；500 服务异常"},"msg":{"type":"string","description":"提示信息"},"data":{"type":"object","description":"业务数据（结构见各接口说明）"}}}},"securitySchemes":{"plainAppId":{"type":"apiKey","in":"header","name":"X-App-Id","description":"明文方式：appid"},"plainSecret":{"type":"apiKey","in":"header","name":"X-App-Secret","description":"明文方式：appsecret（HTTPS 下使用）"},"hmacAppId":{"type":"apiKey","in":"header","name":"X-App-Id","description":"HMAC 方式：appid"},"hmacTimestamp":{"type":"apiKey","in":"header","name":"X-Timestamp","description":"HMAC 方式：秒级时间戳（±300s 时间窗）"},"hmacNonce":{"type":"apiKey","in":"header","name":"X-Nonce","description":"HMAC 方式：一次性随机串（5 分钟内不可重复）"},"hmacSignature":{"type":"apiKey","in":"header","name":"X-Signature","description":"HMAC 方式：base64(HMAC-SHA256(secret, 签名串))，签名串见「鉴权助手」"}},"responses":{"BadRequest":{"description":"参数错误（缺少必填/格式非法）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"Unauthorized":{"description":"凭据缺失或无效（appid 不存在/停用/未授权该插件/签名错误）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"Forbidden":{"description":"拒绝访问（IP/UA 名单命中）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"RateLimited":{"description":"触发限流（X-RateLimit-Remaining: 0，Retry-After 头提示等待秒数）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"ServerError":{"description":"服务端异常","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}},"x-plugin":{"slug":"ip","name":"IP 归属地查询","description":"根据 IP 地址查询其归属地信息（所在国家、省份、城市等）。","version":"1.0.0","methodCount":1,"authMethods":[],"rateLimit":{"s":60},"warnings":[]}}