如何在Python中限制GoogleMaps API地理编码范围至指定城市？

阿华AIGC实验室

2026-5-19

如何在Python中限制Google Geocoding V3仅搜索指定城市范围？

这个问题我之前也碰到过！Google Geocoding API默认会全局匹配地址，同名街道很容易跑偏，要精准锁定Derwood区域，关键是用好API的组件过滤（components）参数——这比bounds或region参数的限制更严格，能直接强制返回目标区域内的结果。

核心思路：用Components参数强制限定区域

Google Geocoding API的components参数允许你明确指定地址必须归属的行政区域，完美适配你的需求。针对Derwood的场景，我们可以设置：

locality:Derwood：指定目标城市为Derwood
administrative_area:MD：限定所在州为马里兰州
country:US：锁定国家为美国

组合这些参数后，API只会返回符合所有组件条件的地址结果，彻底避免匹配到其他地区的Columbus Avenue。

Python实现示例

首先你需要先申请Google Geocoding API密钥（在Google Cloud控制台启用Geocoding API即可），然后用requests库调用API，完整代码如下：

import requests

def geocode_address(address, api_key, target_locality, target_state, target_country):
    base_url = "https://maps.googleapis.com/maps/api/geocode/json"
    
    # 构造组件过滤参数，用|分隔不同条件
    components = f"locality:{target_locality}|administrative_area:{target_state}|country:{target_country}"
    
    params = {
        "address": address,
        "components": components,
        "key": api_key
    }
    
    response = requests.get(base_url, params=params)
    result = response.json()
    
    if result["status"] == "OK":
        # 提取第一个匹配结果的位置对象和格式化地址
        geometry = result["results"][0]["geometry"]
        return {
            "location": geometry["location"],  # 包含lat和lng的位置对象
            "formatted_address": result["results"][0]["formatted_address"],
            "viewport": geometry["viewport"]  # 可选：地址的视口范围
        }
    elif result["status"] == "ZERO_RESULTS":
        return f"未找到{target_locality}附近的{address}"
    else:
        return f"地理编码失败：{result['status']}"

# 使用示例
API_KEY = "你的Google API密钥"
target_address = "Columbus Avenue"
location_data = geocode_address(
    target_address,
    API_KEY,
    target_locality="Derwood",
    target_state="MD",
    target_country="US"
)

print(location_data)