📋 接口概述
项目 说明
接口版本 v1.0
基础路径 https://ups.weiyida56.net/api/ups/remote-zip/2026
数据格式 请求/响应均为 JSON
编码格式 UTF-8
🔗 核心接口列表
接口名称 请求方式 接口路径 功能说明
获取支持国家列表 GET /countries 获取系统支持的所有国家(名称+IATA代码)
单邮编精准查询 GET /query 输入国家+邮编,查询是否偏远及附加费类型
批量邮编查询 POST /batch-query 一次性查询多个邮编,返回批量结果
按国家查询所有偏远邮编 GET /country-zips 获取指定国家的所有偏远邮编范围
1️⃣ 获取支持国家列表

作用:前端下拉选择国家时调用,加载所有支持的国家数据

GET https://ups.weiyida56.net/api/ups/remote-zip/2026/countries
请求参数

无请求参数

响应成功示例
{
    "code": 200,
    "msg": "获取成功",
    "data": {
        "total": 86,
        "list": [
            {
                "country_name": "Angola",
                "iata_code": "AO"
            },
            {
                "country_name": "Argentina",
                "iata_code": "AR"
            },
            {
                "country_name": "Australia",
                "iata_code": "AU"
            }
        ]
    }
}
代码示例
async function getCountries() {
    try {
        const response = await fetch(
            'https://ups.weiyida56.net/api/ups/remote-zip/2026/countries'
        );
        const data = await response.json();
        
        if (data.code === 200) {
            console.log('国家列表:', data.data.list);
            return data.data.list;
        }
    } catch (error) {
        console.error('请求失败:', error);
    }
}

// 调用示例
getCountries();
import requests

def get_countries():
    url = 'https://ups.weiyida56.net/api/ups/remote-zip/2026/countries'
    response = requests.get(url)
    
    if response.status_code == 200:
        data = response.json()
        print('国家列表:', data['data']['list'])
        return data['data']['list']

# 调用示例
get_countries()
2️⃣ 单邮编精准查询

作用:用户输入国家+邮编,一键查询是否偏远、附加费类型

GET https://ups.weiyida56.net/api/ups/remote-zip/2026/query
请求参数
参数名 类型 是否必填 说明
iata_code string 国家IATA代码(如AU、CN、BR)
postal_code string 待查询邮编(支持数字/字母组合)
响应成功示例(偏远地区)
{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "country_name": "Australia",
        "iata_code": "AU",
        "postal_code": "0822",
        "is_remote": true,
        "is_extended": false,
        "origin_surcharge": "Remote Area Surcharge",
        "destination_surcharge": "Remote Area Surcharge",
        "postal_range": {
            "low": "0822",
            "high": "0822"
        }
    }
}
响应成功示例(非偏远)
{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "country_name": "Australia",
        "iata_code": "AU",
        "postal_code": "2000",
        "is_remote": false,
        "is_extended": false,
        "origin_surcharge": "No",
        "destination_surcharge": "No",
        "postal_range": null
    }
}
代码示例
async function queryPostalCode(iataCode, postalCode) {
    try {
        const url = 
            `https://ups.weiyida56.net/api/ups/remote-zip/2026/query?iata_code=${iataCode}&postal_code=${encodeURIComponent(postalCode)}`;
        const response = await fetch(url);
        const data = await response.json();
        
        if (data.code === 200) {
            const result = data.data;
            console.log('查询结果:', result);
            
            if (result.is_remote) {
                console.log('该邮编属于偏远地区');
            } else if (result.is_extended) {
                console.log('该邮编属于扩展地区');
            } else {
                console.log('该邮编属于正常地区');
            }
            
            return result;
        } else {
            console.error('查询失败:', data.msg);
        }
    } catch (error) {
        console.error('请求失败:', error);
    }
}

// 使用示例
queryPostalCode('AU', '0822');
import requests

def query_postal_code(iata_code, postal_code):
    url = 'https://ups.weiyida56.net/api/ups/remote-zip/2026/query'
    params = {
        'iata_code': iata_code,
        'postal_code': postal_code
    }
    response = requests.get(url, params=params)
    
    if response.status_code == 200:
        data = response.json()
        result = data['data']
        print('查询结果:', result)
        
        if result['is_remote']:
            print('该邮编属于偏远地区')
        elif result['is_extended']:
            print('该邮编属于扩展地区')
        else:
            print('该邮编属于正常地区')
        
        return result

# 使用示例
query_postal_code('AU', '0822')
3️⃣ 批量邮编查询

作用:支持批量导入/输入邮编,一次性返回所有结果

POST https://ups.weiyida56.net/api/ups/remote-zip/2026/batch-query
请求体参数
{
    "iata_code": "AU",
    "postal_codes": ["0822", "2563", "2000", "3139"]
}
参数名 类型 是否必填 说明
iata_code string 国家IATA代码
postal_codes array 邮编数组,最多100个
响应成功示例
{
    "code": 200,
    "msg": "批量查询成功",
    "data": {
        "total": 4,
        "remote_count": 2,
        "list": [
            {
                "postal_code": "0822",
                "is_remote": true,
                "is_extended": false,
                "origin_surcharge": "Remote Area Surcharge",
                "destination_surcharge": "Remote Area Surcharge"
            },
            {
                "postal_code": "2563",
                "is_remote": false,
                "is_extended": true,
                "origin_surcharge": "Extended Area Surcharge",
                "destination_surcharge": "Extended Area Surcharge"
            },
            {
                "postal_code": "2000",
                "is_remote": false,
                "is_extended": false,
                "origin_surcharge": "No",
                "destination_surcharge": "No"
            },
            {
                "postal_code": "3139",
                "is_remote": true,
                "is_extended": false,
                "origin_surcharge": "Remote Area Surcharge",
                "destination_surcharge": "Remote Area Surcharge"
            }
        ]
    }
}
代码示例
async function batchQuery(iataCode, postalCodes) {
    try {
        const url = 
            'https://ups.weiyida56.net/api/ups/remote-zip/2026/batch-query';
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                iata_code: iataCode,
                postal_codes: postalCodes
            })
        });
        const data = await response.json();
        
        if (data.code === 200) {
            const result = data.data;
            console.log('总查询数:', result.total);
            console.log('偏远/扩展数:', result.remote_count);
            console.log('详细结果:', result.list);
            
            return result;
        } else {
            console.error('查询失败:', data.msg);
        }
    } catch (error) {
        console.error('请求失败:', error);
    }
}

// 使用示例
batchQuery('AU', ['0822', '2563', '2000', '3139']);
import requests

def batch_query(iata_code, postal_codes):
    url = 'https://ups.weiyida56.net/api/ups/remote-zip/2026/batch-query'
    payload = {
        'iata_code': iata_code,
        'postal_codes': postal_codes
    }
    response = requests.post(url, json=payload)
    
    if response.status_code == 200:
        data = response.json()
        result = data['data']
        print('总查询数:', result['total'])
        print('偏远/扩展数:', result['remote_count'])
        print('详细结果:', result['list'])
        
        return result

# 使用示例
batch_query('AU', ['0822', '2563', '2000', '3139'])
4️⃣ 按国家查询所有偏远邮编

作用:查看指定国家的所有偏远邮编范围,用于后台管理/数据核对

GET https://ups.weiyida56.net/api/ups/remote-zip/2026/country-zips
请求参数
参数名 类型 是否必填 说明
iata_code string 国家IATA代码
page number 页码(默认1)
size number 每页条数(默认50,最大100)
响应成功示例
{
    "code": 200,
    "msg": "获取成功",
    "data": {
        "country_name": "Australia",
        "total": 1665,
        "page": 1,
        "size": 50,
        "list": [
            {
                "postal_low": "0822",
                "postal_high": "0822",
                "origin_surcharge": "Remote Area Surcharge",
                "destination_surcharge": "Remote Area Surcharge"
            },
            {
                "postal_low": "0852",
                "postal_high": "0852",
                "origin_surcharge": "Remote Area Surcharge",
                "destination_surcharge": "Remote Area Surcharge"
            }
        ]
    }
}
代码示例
async function getCountryZips(iataCode, page = 1, size = 50) {
    try {
        const url = 
            `https://ups.weiyida56.net/api/ups/remote-zip/2026/country-zips?iata_code=${iataCode}&page=${page}&size=${size}`;
        const response = await fetch(url);
        const data = await response.json();
        
        if (data.code === 200) {
            const result = data.data;
            console.log('国家:', result.country_name);
            console.log('总记录数:', result.total);
            console.log('当前页:', result.page);
            console.log('邮编范围列表:', result.list);
            
            return result;
        } else {
            console.error('获取失败:', data.msg);
        }
    } catch (error) {
        console.error('请求失败:', error);
    }
}

// 使用示例 - 获取第一页
getCountryZips('AU', 1, 50);
import requests

def get_country_zips(iata_code, page=1, size=50):
    url = 'https://ups.weiyida56.net/api/ups/remote-zip/2026/country-zips'
    params = {
        'iata_code': iata_code,
        'page': page,
        'size': size
    }
    response = requests.get(url, params=params)
    
    if response.status_code == 200:
        data = response.json()
        result = data['data']
        print('国家:', result['country_name'])
        print('总记录数:', result['total'])
        print('当前页:', result['page'])
        print('邮编范围列表:', result['list'])
        
        return result

# 使用示例 - 获取第一页
get_country_zips('AU', 1, 50)
📌 通用字段说明
字段名 类型 说明
code number 响应码(200=成功,400=参数错误,500=服务异常)
msg string 响应提示信息
is_remote boolean 是否偏远地区(Remote Area)
is_extended boolean 是否扩展地区(Extended Area)
origin_surcharge string 出发地附加费类型
destination_surcharge string 目的地附加费类型
🔢 响应码规范
响应码 说明
200 请求成功
400 请求参数错误(如IATA代码/邮编为空、格式错误)
404 国家IATA代码不支持
500 服务器内部异常
⚠️ 注意事项
批量查询限制:批量查询最多支持 100个/次,超出部分会被截断
邮编格式:邮编查询支持数字和字母组合,不区分大小写
跨域支持:所有接口都支持跨域访问(CORS)
最佳实践:建议在实际使用中,先获取国家列表再进行查询
分页限制:分页获取邮编范围时,最大每页条数为 100