Geotrackable API 接口

地图边界内的公共位置

当客户端已有地图视口并需要该区域内可见的公共位置笔记时，请使用边界查询。

curl "https://Geotrackable.com/api/notes/public/bounds?minLatitude=41.78&minLongitude=-87.75&maxLatitude=41.96&maxLongitude=-87.54&contentLanguage=en-US"

[
  {
    "noteId": "4d6c5df3-3c53-4d0e-8e72-7d98a0f8a9f3",
    "title": "Trailhead parking",
    "body": "Small public lot near the north entrance.",
    "contentLanguage": "en-US",
    "latitude": 41.8818,
    "longitude": -87.6231,
    "visibility": 1,
    "updatedUtc": "2026-06-20T12:00:00Z"
  }
]

创建常规个人位置

此路由创建一个不附加到追踪物的位置。省略 categoryId 可使用账户的默认类别。响应为已保存的位置，并包含供后续请求使用的 noteId。

创建请求接受如下所示的可读枚举名称，例如 Private、Public 和 Disabled，并继续接受相应的数值。位置备注响应目前以数字编码 visibility 和 commentPolicy：visibility 0 为 Private，1 为 Public，2 为 VisibleOnceAssociatedTrackableAccessed；commentPolicy 0 为 Disabled，1 为 LoggedInUsers，2 为 TeamMembers。

curl -X POST "https://Geotrackable.com/api/notes/mine" \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cache hide approach",
    "body": "Use the east footpath after rain.",
    "contentLanguage": "en-US",
    "latitude": 41.8818,
    "longitude": -87.6231,
    "visibility": "Private",
    "commentPolicy": "Disabled"
  }'

curl -X POST "https://Geotrackable.com/api/categories/mine" \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend route checks",
    "contentLanguage": "en-US",
    "parentCategoryId": null
  }'

推送请求

curl -X POST "https://Geotrackable.com/api/sync/push" \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "5dd06ca7-34a5-4f2e-812d-3f1ef3e48290",
    "notes": [
      {
        "noteId": "ef90c4ca-88a9-4a9b-b3a8-36e2649c5dcb",
        "ownerUserId": "a7cfd28f-c17f-4cf7-8913-47fa10fd0d1f",
        "categoryId": "ca90c4ca-88a9-4a9b-b3a8-36e2649c5dcb",
        "title": "Offline field stop",
        "body": "Saved while disconnected.",
        "contentLanguage": "en-US",
        "latitude": 41.8818,
        "longitude": -87.6231,
        "visibility": 0,
        "isDeleted": false,
        "updatedUtc": "2026-06-20T12:05:00Z",
        "clientMutationId": "android-offline-42",
        "teamId": null
      }
    ],
    "categories": [
      {
        "categoryId": "ca90c4ca-88a9-4a9b-b3a8-36e2649c5dcb",
        "ownerUserId": "a7cfd28f-c17f-4cf7-8913-47fa10fd0d1f",
        "name": "Offline field notes",
        "contentLanguage": "en-US",
        "teamId": null,
        "parentCategoryId": null,
        "sortOrder": 0,
        "isDeleted": false,
        "updatedUtc": "2026-06-20T12:04:00Z"
      }
    ]
  }'

每条位置笔记都必须引用登录账户已可见的类别，或同一次推送中包含的类别。离线同时创建两者时，请确保两条记录中的 categoryId 完全相同。

拉取请求

curl -X POST "https://Geotrackable.com/api/sync/pull" \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lastSyncUtc": "2026-06-20T11:30:00Z",
    "publicArea": {
      "minLatitude": 41.78,
      "minLongitude": -87.75,
      "maxLatitude": 41.96,
      "maxLongitude": -87.54
    }
  }'

{
  "serverSyncUtc": "2026-06-20T12:06:00Z",
  "userNotes": [],
  "userCategories": [],
  "teamCategories": [],
  "publicNotes": [],
  "teamNotes": []
}

创建团队

curl -X POST "https://Geotrackable.com/api/teams" \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "trail-club",
    "title": "Trail Club",
    "description": "Weekend route and trackable group.",
    "joinPolicy": "RequestsAllowed",
    "pageVisibility": "Public",
    "defaultNoteVisibility": "Public",
    "contentLanguage": "en-US"
  }'

创建邀请链接

curl -X POST "https://Geotrackable.com/api/teams/73edb511-cd8c-4888-8c45-3a04b3d6da11/invite-links" \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "isSingleUse": false
  }'

curl -X POST "https://Geotrackable.com/api/teams/invite-links/trail-club/INVITE-CODE/join" \
  -H "Authorization: Bearer <access token>"

问题响应结构

Content-Type: application/problem+json
{
  "type": "/en-US/api-docs#errors-and-problem-details",
  "title": "Trackable access is required.",
  "status": 403,
  "detail": "This request needs access to this specific trackable.",
  "instance": "/api/trackables/13a2c0b1-582f-4a7b-92aa-16922f7bdb63/comments",
  "code": "trackable_access_code_required",
  "action": "Sign in, keep this trackable active in this client, or provide its secret code or private QR access value.",
  "requestId": "0HN7EXAMPLE:00000002",
  "documentation": "/en-US/api-docs#errors-and-problem-details"
}

各字段的用途

type

此问题详情约定的稳定 URI。客户端逻辑应使用 code（而非 type 或易读文本）来区分具体故障。

title

适合作为标题的简短易读摘要。请勿依据此文本分支客户端逻辑。

status

在正文中重复的 HTTP status，以便所捕获的诊断信息仍易于理解。

detail

针对本次请求说明失败原因，但不会回显凭据或私密令牌。

instance

与本次问题关联的请求路径。包含秘密代码的网站入口路径可能会被遮盖。

code

客户端应据此分支处理的稳定机器可读标识符。

action

具体的恢复步骤：更正字段、完成身份验证、等待、减小负载或选择其他值。

requestId

可安全包含在支持请求中的关联值。请将它与 status、code、请求方法和路由模板一并保留。

documentation

针对该故障类别或确切 code 的帮助页面位置。