Freika/dawarich项目API接口详解：地理位置数据处理平台

项目概述

Freika/dawarich是一个专注于地理位置数据处理的平台，提供了一系列API接口用于管理地理区域、跟踪位置点、记录访问城市以及处理相关照片数据。该项目采用了标准的RESTful API设计，遵循OpenAPI 3.0规范，为开发者提供了清晰、一致的接口体验。

核心API功能解析

1. 区域管理API

区域管理API允许用户创建、查询和删除地理区域，这些区域通常用于地理围栏或兴趣点标记。

创建区域(POST /api/v1/areas)

{
  "name": "Home",
  "latitude": 40.7128,
  "longitude": -74.006,
  "radius": 100
}

• 参数说明：
  • name: 区域名称(必填)
  • latitude: 纬度坐标(必填)
  • longitude: 经度坐标(必填)
  • radius: 区域半径(米)(必填)

获取所有区域(GET /api/v1/areas)

返回所有已创建的区域列表，包含每个区域的ID、名称、坐标和半径信息。

删除区域(DELETE /api/v1/areas/{id})

通过指定区域ID删除特定区域。

2. 访问城市统计API

获取指定日期范围内的访问城市(GET /api/v1/countries/visited_cities)

该接口返回用户在指定时间段内访问过的城市和国家列表，包含详细的停留信息。

请求参数：

• start_at: 开始日期(YYYY-MM-DD格式)(必填)
• end_at: 结束日期(YYYY-MM-DD格式)(必填)

响应示例：

{
  "data": [
    {
      "country": "Germany",
      "cities": [
        {
          "city": "Berlin",
          "points": 4394,
          "timestamp": 1724868369,
          "stayed_for": 24490
        }
      ]
    }
  ]
}

• points: 该城市的跟踪点数
• timestamp: 最后一次访问的时间戳(Unix时间)
• stayed_for: 停留时间(分钟)

3. 健康检查API

获取应用状态(GET /api/v1/health)

简单的健康检查接口，返回应用状态和版本信息。

响应头包含：

• X-Dawarich-Response: 状态消息
• X-Dawarich-Version: 应用版本号

4. 位置数据处理API

项目提供了两种不同的位置数据接收方式：

Overland批量位置数据接口(POST /api/v1/overland/batches)

用于接收批量位置数据，适合移动设备定期上传的位置轨迹。

数据格式：

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [13.356718, 52.502397]
  },
  "properties": {
    "timestamp": "2021-06-01T12:00:00Z",
    "altitude": 0,
    "speed": 0,
    "horizontal_accuracy": 0,
    "vertical_accuracy": 0,
    "motion": ["walking"],
    "activity": "unknown",
    "battery_state": "unknown",
    "battery_level": 0
  }
}

OwnTracks单点位置接口(POST /api/v1/owntracks/points)

专为OwnTracks应用设计的接口，接收单个位置点数据。

数据格式：

{
  "batt": 85,
  "lon": -74.006,
  "lat": 40.7128,
  "acc": 8,
  "tst": 1706965203,
  "topic": "owntracks/jane/iPhone 12 Pro"
}

5. 照片管理API

获取照片列表(GET /api/v1/photos)

根据日期范围查询照片数据。

请求参数：

• start_date: 开始日期(ISO8601格式)(必填)
• end_date: 结束日期(ISO8601格式)(必填)

安全机制

所有API接口都需要通过api_key查询参数进行身份验证，确保只有授权用户可以访问数据。

技术特点

1. 标准化设计：严格遵循OpenAPI 3.0规范，接口定义清晰
2. 多种数据格式支持：支持JSON格式的请求和响应
3. 详细错误处理：提供明确的错误状态码和错误信息
4. 地理位置专业化：针对地理位置数据处理进行了专门优化
5. 多平台兼容：支持Overland和OwnTracks等多种位置数据来源

应用场景

1. 个人位置追踪：记录和分析个人日常活动轨迹
2. 旅行足迹统计：统计访问过的城市和国家
3. 地理围栏应用：基于定义区域触发特定操作
4. 位置数据分析：分析移动模式和停留时间
5. 照片地理位置关联：将照片与位置数据关联

最佳实践建议

1. 批量处理：对于频繁的位置更新，优先使用批量接口
2. 合理设置区域半径：根据实际需求设置区域半径，平衡精度和性能
3. 日期范围查询：对于大数据量查询，尽量缩小日期范围
4. 错误处理：实现完善的错误处理机制，特别是处理401未授权错误
5. 数据缓存：对于不常变化的数据(如区域列表)，考虑本地缓存

Freika/dawarich项目通过这套完善的API体系，为开发者提供了强大的地理位置数据处理能力，无论是构建个人位置追踪应用还是企业级地理分析系统，都能提供可靠的技术支持。