手把手教你用Python+Django打造免费的城市定位API（附完整代码）
从零构建高可用城市定位API：Python+Django地理数据处理实战
为什么我们需要自建城市定位服务？
去年夏天，我接手了一个需要实时获取用户所在城市的项目。最初直接调用了某商业地图API，结果上线三个月后收到账单时差点崩溃——日均10万次调用，月费用直接突破五位数。更糟的是，服务突然调整配额导致周末高峰期出现大面积超时。这次经历让我下定决心研究自建方案。
传统商业地图API确实方便，但存在三个致命问题：成本不可控、响应延迟高和数据不透明。特别是对于需要简单城市定位的中小项目，动辄数万元的年费实在难以承受。而自建方案不仅能将成本降低90%以上，还能根据业务特点灵活定制查询逻辑。
1. 地理数据获取与处理
1.1 权威数据源选择
优质的地理数据是服务准确性的基石。推荐以下几个经过验证的数据源：
- 国家基础地理信息中心：提供1:100万比例尺的行政区划数据
- OpenStreetMap：社区维护的全球开源地图数据
- Natural Earth：适合全球范围应用的公共领域数据集
# 自动化下载GeoJSON数据的Python脚本示例 import requests from pathlib import Path DATA_DIR = Path(__file__).parent / 'geodata' def fetch_geojson(url, save_path): response = requests.get(url, timeout=10) response.raise_for_status() save_path.parent.mkdir(exist_ok=True) with open(save_path, 'w', encoding='utf-8') as f: f.write(response.text) print(f"成功下载: {save_path}") # 下载省级边界数据 PROVINCE_URL = "https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json" fetch_geojson(PROVINCE_URL, DATA_DIR / "china_provinces.json")1.2 数据清洗与优化
原始地理数据往往包含冗余信息，需要进行以下处理：
- 坐标系转换：统一为WGS84坐标系
- 几何简化：使用Douglas-Peucker算法减少多边形点数
- 拓扑校验：修复自相交等几何错误
# 使用ogr2ogr工具进行数据转换 ogr2ogr -f "GeoJSON" -t_srs EPSG:4326 output.json input.shp2. 数据库设计与优化
2.1 PostgreSQL+PostGIS配置
PostgreSQL配合PostGIS扩展是处理空间数据的黄金组合。安装后需执行以下配置：
-- 创建空间数据库 CREATE DATABASE geo_db WITH ENCODING='UTF8'; \c geo_db CREATE EXTENSION postgis; CREATE EXTENSION postgis_topology;2.2 Django模型设计
GeoDjango提供了丰富的空间字段类型，以下是最佳实践模型：
from django.contrib.gis.db import models class AdministrativeArea(models.Model): LEVEL_CHOICES = [ ('country', '国家'), ('province', '省份'), ('city', '城市'), ('district', '区县') ] code = models.CharField(max_length=12, unique=True) name = models.CharField(max_length=50) level = models.CharField(max_length=10, choices=LEVEL_CHOICES) parent = models.ForeignKey('self', null=True, on_delete=models.CASCADE) centroid = models.PointField(srid=4326) boundary = models.MultiPolygonField(srid=4326) class Meta: indexes = [ models.Index(fields=['level']), models.Index(fields=['code']), models.GistIndex(fields=['boundary']) ]提示：为boundary字段创建GiST索引可提升空间查询性能100倍以上
3. API接口开发实战
3.1 核心查询逻辑实现
城市定位的核心算法是点面包含判断，需要注意以下边界情况：
- 飞地处理（如河北省的三河市）
- 沿海城市的海域边界
- 直辖市等特殊行政区划
from django.contrib.gis.geos import Point from rest_framework.response import Response def locate_city(latitude, longitude): target_point = Point(longitude, latitude, srid=4326) # 先查询国家边界 country = AdministrativeArea.objects.filter(level='country').first() if not country.boundary.contains(target_point): return None # 省级查询 provinces = AdministrativeArea.objects.filter( level='province', boundary__contains=target_point ) # 市级查询 for province in provinces: cities = AdministrativeArea.objects.filter( level='city', parent=province, boundary__contains=target_point ) if cities.exists(): return cities.first() return provinces.first() # 未匹配到城市则返回省份3.2 性能优化技巧
通过实测，以下优化可使API响应时间从200ms降至20ms：
| 优化措施 | 效果 | 实现方式 |
|---|---|---|
| 空间索引 | 提升100x | CREATE INDEX ON table USING GIST(geom) |
| 查询缓存 | 提升10x | django-redis缓存热点查询 |
| 数据分区 | 提升5x | 按省份水平分表 |
| 简化几何 | 提升2x | ST_SimplifyPreserveTopology |
4. 生产环境部署方案
4.1 高可用架构设计
+-----------------+ | 负载均衡 (Nginx) | +--------+--------+ | +----------------+-----------------+ | | | +----------+-------+ +------+--------+ +------+--------+ | API服务器1 | | API服务器2 | | API服务器3 | | (Gunicorn+Django)| | (Gunicorn+Django)| | (Gunicorn+Django)| +------------------+ +-----------------+ +-----------------+ | | | +--------+-------+-----------------+ | +--------+--------+ | PostgreSQL集群 | | (主从复制+读写分离)| +-----------------+4.2 监控与告警配置
使用Prometheus+Grafana监控以下关键指标：
- 查询延迟：P99应<100ms
- 缓存命中率：目标>90%
- 数据库负载：CPU利用率<70%
- 错误率：5xx错误<0.1%
# Prometheus告警规则示例 groups: - name: geoapi.rules rules: - alert: HighErrorRate expr: rate(geoapi_http_errors_total[5m]) > 0.01 for: 10m labels: severity: critical annotations: summary: "高错误率 ({{ $value }}%)"在实际部署中，我们使用Docker Swarm编排服务，每个容器都配置了资源限制。数据库采用Patroni管理的PostgreSQL集群，确保自动故障转移。这套架构支撑了日均500万次查询，月成本不到商业API的十分之一。