Google Maps Geocoding API 与美国地址结合使用

Geocoding（地理编码）是将人类可读的地址转换为机器可读的经纬度坐标的过程。对于需要地图展示、距离计算、位置分析的应用来说，Geocoding 是必不可少的环节。本文将详细介绍如何将 Google Maps Geocoding API 与美国地址系统结合使用。

Geocoding 基础概念

正向地理编码（Forward Geocoding）

将地址文本转换为经纬度坐标：

输入：```1600 Pennsylvania Ave NW, Washington, DC 20500```

输出：```lat: 38.8977, lng: -77.0365```

反向地理编码（Reverse Geocoding）

将经纬度坐标转换为地址文本：

输入：```lat: 38.8977, lng: -77.0365```

输出：```1600 Pennsylvania Ave NW, Washington, DC 20500, USA```

Google Maps Geocoding API 接入

1. 获取 API Key

2. 基础调用

```javascript

const API_KEY = 'YOUR_GOOGLE_MAPS_API_KEY';

const GEOCODE_URL = 'https://maps.googleapis.com/maps/api/geocode/json';

async function geocodeAddress(address) {

const params = new URLSearchParams({

address: address,

key: API_KEY,

region: 'us' // 优先返回美国结果

});

const response = await fetch(`${GEOCODE_URL}?${params}`);

const data = await response.json();

if (data.status === 'OK' && data.results.length > 0) {

const result = data.results[0];

return {

formatted_address: result.formatted_address,

location: result.geometry.location,

place_id: result.place_id,

address_components: result.address_components,

partial_match: result.partial_match || false

};

}

throw new Error(`Geocoding failed: ${data.status}`);

}

// 使用示例

const result = await geocodeAddress('1600 Pennsylvania Ave NW, Washington, DC');

console.log(result.location); // { lat: 38.8977, lng: -77.0365 }

```

3. Python 实现

```python

import requests

from typing import Optional, Dict, Any

class GoogleGeocoder:

def __init__(self, api_key: str):

self.api_key = api_key

self.base_url = "https://maps.googleapis.com/maps/api/geocode/json"

def geocode(self, address: str, region: str = 'us') -> Optional[Dict[str, Any]]:

"""正向地理编码"""

params = {

'address': address,

'key': self.api_key,

'region': region

}

response = requests.get(self.base_url, params=params, timeout=10)

data = response.json()

if data['status'] == 'OK' and data['results']:

result = data['results'][0]

return {

'formatted_address': result['formatted_address'],

'lat': result['geometry']['location']['lat'],

'lng': result['geometry']['location']['lng'],

'place_id': result['place_id'],

'types': result['types'],

'partial_match': result.get('partial_match', False)

}

return None

def reverse_geocode(self, lat: float, lng: float) -> Optional[Dict[str, Any]]:

"""反向地理编码"""

params = {

'latlng': f"{lat},{lng}",

'key': self.api_key

}

response = requests.get(self.base_url, params=params, timeout=10)

data = response.json()

if data['status'] == 'OK' and data['results']:

result = data['results'][0]

return {

'formatted_address': result['formatted_address'],

'address_components': result['address_components'],

'place_id': result['place_id']

}

return None

```

解析 address_components

Google Geocoding 返回的 ```address_components``` 包含地址的结构化信息，可以用来验证和补全美国地址。

```python

def parse_us_address_components(components):

"""从 Google Geocoding 结果解析美国地址字段"""

result = {}

for component in components:

types = component['types']

if 'street_number' in types:

result['street_number'] = component['long_name']

elif 'route' in types:

result['street_name'] = component['long_name']

elif 'locality' in types:

result['city'] = component['long_name']

elif 'administrative_area_level_1' in types:

result['state'] = component['short_name'] # CA, NY, etc.

elif 'postal_code' in types:

result['zip5'] = component['long_name']

elif 'postal_code_suffix' in types:

result['zip4'] = component['long_name']

elif 'country' in types:

result['country'] = component['short_name']

elif 'subpremise' in types:

result['apartment'] = component['long_name']

return result

使用示例

components = geocode_result['address_components']

parsed = parse_us_address_components(components)

print(parsed)

{

'street_number': '1600',

'street_name': 'Pennsylvania Avenue Northwest',

'city': 'Washington',

'state': 'DC',

'zip5': '20500',

'country': 'US'

}

```

与美国地址验证结合

完整验证流程

```python

class AddressVerificationService:

def __init__(self, google_api_key: str, usps_user_id: str):

self.geocoder = GoogleGeocoder(google_api_key)

self.usps_validator = USPSValidator(usps_user_id)

async def verify_and_geocode(self, address: dict):

"""完整验证流程：USPS 验证 + Google Geocoding"""

# 第1步：USPS 格式验证

usps_result = await self.usps_validator.verify(address)

if not usps_result:

return {

'status': 'invalid',

'error': 'USPS 验证失败，地址格式不正确'

}

# 第2步：地理编码

full_address = f"{usps_result['address_line1']}, {usps_result['city']}, {usps_result['state']} {usps_result['zip5']}"

geo_result = self.geocoder.geocode(full_address)

if not geo_result:

return {

'status': 'partial',

'usps': usps_result,

'error': '无法获取地理坐标'

}

# 第3步：交叉验证

google_parsed = parse_us_address_components(geo_result['address_components'])

verification = self._cross_verify(usps_result, google_parsed)

return {

'status': 'verified',

'address': usps_result,

'coordinates': {

'lat': geo_result['lat'],

'lng': geo_result['lng']

},

'place_id': geo_result['place_id'],

'verification_confidence': verification['confidence'],

'discrepancies': verification['discrepancies']

}

def _cross_verify(self, usps_result, google_parsed):

"""交叉验证 USPS 和 Google 的结果"""

discrepancies = []

if usps_result['state'] != google_parsed.get('state'):

discrepancies.append(f"州不匹配: USPS={usps_result['state']}, Google={google_parsed.get('state')}")

if usps_result['zip5'] != google_parsed.get('zip5'):

discrepancies.append(f"邮编不匹配: USPS={usps_result['zip5']}, Google={google_parsed.get('zip5')}")

confidence = 'high' if not discrepancies else 'medium'

return {'confidence': confidence, 'discrepancies': discrepancies}

```

成本优化策略

Google Geocoding API 按请求次数收费，美国区域定价约为 $5 / 1000 次请求。

1. 缓存策略

```python

import hashlib

from functools import lru_cache

class CachedGeocoder:

def __init__(self, geocoder, cache_client):

self.geocoder = geocoder

self.cache = cache_client

def _get_cache_key(self, address: str) -> str:

normalized = address.lower().strip()

return f"geocode:{hashlib.md5(normalized.encode()).hexdigest()}"

async def geocode(self, address: str):

cache_key = self._get_cache_key(address)

# 查缓存

cached = await self.cache.get(cache_key)

if cached:

return json.loads(cached)

# 调用 API

result = await self.geocoder.geocode(address)

# 写入缓存（TTL 30 天，地址很少变化）

await self.cache.set(cache_key, json.dumps(result), ttl=2592000)

return result

```

2. 批量处理优化

3. 预处理过滤

在调用 Geocoding API 之前，先用正则表达式过滤明显错误的地址：

```python

def should_geocode(address: dict) -> bool:

"""判断地址是否值得调用 Geocoding API"""

# 邮编格式校验

if not re.match(r'^\d{5}$', address.get('zip', '')):

return False

# 州缩写校验

valid_states = {'AL','AK','AZ','AR','CA','CO','CT','DE','FL','GA','HI','ID','IL','IN','IA','KS','KY','LA','ME','MD','MA','MI','MN','MS','MO','MT','NE','NV','NH','NJ','NM','NY','NC','ND','OH','OK','OR','PA','RI','SC','SD','TN','TX','UT','VT','VA','WA','WV','WI','WY','DC'}

if address.get('state') not in valid_states:

return False

# 街道地址校验

if not re.match(r'^\d+\s+', address.get('address_line1', '')):

return False

return True

```

使用场景

1. 距离计算

```python

import math

def calculate_distance(lat1, lng1, lat2, lng2):

"""计算两点之间的距离（英里）"""

R = 3959 # 地球半径（英里）

lat1_rad = math.radians(lat1)

lat2_rad = math.radians(lat2)

delta_lat = math.radians(lat2 - lat1)

delta_lng = math.radians(lng2 - lng1)

a = math.sin(delta_lat/2)2 + math.cos(lat1_rad) * math.cos(lat2_rad) * math.sin(delta_lng/2)2

c = 2 * math.atan2(math.sqrt(a), math.sqrt(1-a))

return R * c

计算华盛顿到纽约的距离

distance = calculate_distance(38.8977, -77.0365, 40.7128, -74.0060)

print(f"Distance: {distance:.1f} miles") # Distance: 204.5 miles

```

2. 配送范围验证

```python

def is_within_delivery_range(customer_address, warehouse_location, max_distance_miles=50):

"""判断客户地址是否在配送范围内"""

customer_geo = geocoder.geocode(customer_address)

if not customer_geo:

return False

distance = calculate_distance(

warehouse_location['lat'],

warehouse_location['lng'],

customer_geo['lat'],

customer_geo['lng']

)

return distance <= max_distance_miles

```

总结

Google Maps Geocoding API 与美国地址系统结合使用，可以实现：

通过合理的缓存策略和预处理过滤，可以将 Geocoding API 的成本降低 50%-80%，同时保持系统的响应速度。