Java 調用百度地圖 IP 定位 API 獲取地理位置完整示例

前言

百度地圖開放平台提供 IP 定位服務，通過 HTTP GET 請求即可獲取 IP 對應的城市、經緯度等信息。本文演示 Java 原生 HttpURLConnection + org.json 解析的完整調用流程，含 AK 申請、參數構建、異常處理、結果映射。

準備工作

1. 註冊百度開發者賬號，創建應用獲取 AK (Access Key)。
2. 啟用「IP 定位 API」服務 (控制台 -> 應用 -> 服務管理)。
3. 引入 JSON 解析依賴 (或使用 JDK 內置 javax.json / JsonParser JDK 11+)。

<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20231013</version>
</dependency>

API 文檔關鍵點

• 請求地址：https://api.map.baidu.com/location/ip
• 必填參數：ak (您的 AK)、ip (目標 IP，可選，默認自動獲取調用方 IP)。
• 返回格式：JSON，核心字段 status (0 成功)、content.address (詳細地址)、content.point (經緯度)、content.city (城市名)。

完整調用代碼

import org.json.JSONObject;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class BaiduIpLocationClient {

    private static final String API_URL = "https://api.map.baidu.com/location/ip";
    private static final String AK = "您的AK"; // 替換為真實 AK

    public static void main(String[] args) {
        try {
            String ip = "202.198.16.3"; // 測試 IP，可為 null 使用自動檢測
            JSONObject result = getLocation(ip);
            if (result != null) {
                System.out.println("完整響應: " + result.toString(2));
                System.out.println("地址: " + result.getJSONObject("content").getString("address"));
                System.out.println("城市: " + result.getJSONObject("content").getString("city"));
                System.out.println("經緯度: " + result.getJSONObject("content").getJSONObject("point").toString());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static JSONObject getLocation(String ip) throws IOException {
        StringBuilder urlBuilder = new StringBuilder(API_URL).append("?ak=").append(AK);
        if (ip != null && !ip.isEmpty()) {
            urlBuilder.append("&ip=").append(ip);
        }

        HttpURLConnection conn = null;
        try {
            URL url = new URL(urlBuilder.toString());
            conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setConnectTimeout(5000);
            conn.setReadTimeout(5000);
            conn.setRequestProperty("Accept", "application/json");

            int code = conn.getResponseCode();
            if (code != 200) {
                throw new IOException("HTTP 錯誤碼: " + code);
            }

            try (BufferedReader reader = new BufferedReader(
                    new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
                StringBuilder response = new StringBuilder();
                String line;
                while ((line = reader.readLine()) != null) {
                    response.append(line);
                }
                JSONObject json = new JSONObject(response.toString());
                if (json.getInt("status") != 0) {
                    throw new IOException("API 業務錯誤: " + json.getString("message"));
                }
                return json;
            }
        } finally {
            if (conn != null) conn.disconnect();
        }
    }
}

結果對象映射 (POJO)

public class BaiduLocationResult {
    private int status;
    private String message;
    private Content content;

    public static class Content {
        private String address;
        private String city;
        private String cityCode;
        private Point point;
        // Getter/Setter
    }
    public static class Point {
        private double x; // 經度
        private double y; // 緯度
        // Getter/Setter
    }
    // Getter/Setter
}

// 使用 Jackson/Gson 直接反序列化
// BaiduLocationResult result = objectMapper.readValue(jsonStr, BaiduLocationResult.class);

進階：高併發場景優化

1. 連接池：使用 Apache HttpClient / OkHttp 替代 HttpURLConnection，配置連接池複用 TCP 連接。
2. 異步非阻塞：CompletableFuture.supplyAsync() 或 WebClient (Spring WebFlux) 實現非阻塞調用。
3. 本地緩存：IP 地址變化較慢，引入 Caffeine/Guava Cache 緩存 24h，Key 為 IP，極大降低外部調用延遲與配額消耗。
4. 熔斷限流：Resilience4j / Sentinel 保護下游服務，防止百度 API 故障拖垮主業務。

常見錯誤碼對照

總結

百度 IP 定位 API 調用極其簡單，核心在於「AK 管理、超時設置、錯誤碼處理、高併發優化」。生產環境務必引入 HTTP 客端連接池、本地緩存與熔斷機制，確保服務穩定性。若需更高精度 (街道級)，可結合瀏覽器 Geolocation API (前端獲取經緯度) 反向地理編碼，實現多源定位融合。