LocationNotes API 文档

基础 URL

本页上的所有示例均假定当前生产主机：

https://locationnotes.com

格式

请求和响应使用JSON。 GUIDs 是跨笔记、类别、团队和设备的主要标识符。

授权

专用、同步和团队端点需要 Authorization: Bearer <access token> 除非该路由在下面被标记为公开。

语言

公共和管理阅读可以通过 contentLanguage=en-US 或其他支持的内容语言来过滤返回的 note/category 内容。

所需的查询字符串： latitude, longitude 或完整地图边界 minLatitude, minLongitude, maxLatitude, maxLongitude.

可选查询字符串： radiusKm (默认 5), contentLanguage, includeAllLanguages

网站通常将当前路线语言发送为 contentLanguage，因此 /en-US 和 /tlh 公共页面默认情况下不会在同一地图或地带中混合创作笔记语言。

仅当客户端有意构建多语言浏览界面而不是镜像网站页面时，才设置 includeAllLanguages=true。

{
  "deviceId": "5dd06ca7-34a5-4f2e-812d-3f1ef3e48290",
  "notes": [
    {
      "noteId": "ef90c4ca-88a9-4a9b-b3a8-36e2649c5dcb",
      "ownerUserId": "a7cfd28f-c17f-4cf7-8913-47fa10fd0d1f",
      "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
      "title": "Offline inspection",
      "body": "Saved while disconnected.",
      "contentLanguage": "en-US",
      "latitude": null,
      "longitude": null,
      "visibility": "Private",
      "externalLinkUrl": "https://example.com/offline-inspection",
      "externalLinkDescription": "",
      "applyExternalLinkChanges": true,
      "isDeleted": false,
      "updatedUtc": "2026-03-13T20:12:00Z",
      "clientMutationId": "android-offline-42",
      "teamId": null
    }
  ],
  "categories": []
}

{
  "appliedNoteIds": [
    "ef90c4ca-88a9-4a9b-b3a8-36e2649c5dcb"
  ],
  "appliedCategoryIds": [],
  "conflicts": []
}

{
  "lastSyncUtc": "2026-03-13T19:45:00Z",
  "publicArea": {
    "minLatitude": 41.78,
    "minLongitude": -87.75,
    "maxLatitude": 41.96,
    "maxLongitude": -87.54
  }
}

{
  "serverSyncUtc": "2026-03-13T20:13:02Z",
  "userNotes": [],
  "userCategories": [],
  "teamCategories": [],
  "publicNotes": [],
  "teamNotes": []
}

阅读个人笔记

可选查询字符串： contentLanguage 和完整的地图边界 minLatitude, minLongitude, maxLatitude, maxLongitude.

注意读取有效负载现在包括 lastActivityUtc 因此客户端可以与持久性/update时间戳分开显示最近的活动。

创建笔记

{
  "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
  "title": "Category-only feedback",
  "body": "This note stays off the map on purpose.",
  "contentLanguage": "en-US",
  "externalLinkUrl": "https://example.com/field-guide",
  "externalLinkDescription": "",
  "latitude": null,
  "longitude": null,
  "visibility": "VisibleOnceAssociatedTrackableAccessed",
  "commentPolicy": "LoggedInUsers"
}

可见性接受 Private、Public 和 VisibleOnceAssociatedTrackableAccessed。关联可追踪模式的行为类似于公共，直到笔记具有一个或多个关联可追踪。此后，公开发现和笔记页访问要求查看者已经解锁这些关联的可跟踪项之一。

• 尚无关联的可跟踪项：该笔记的行为类似于公共笔记。
• 第一次关联后：该笔记退出匿名公开发现和正常的公共笔记页面访问。
• 已解锁的查看者：已解锁相关可追踪项的人可以打开笔记页面并使用连接的公共笔记页面 API 路线。
• 所有者或授权团队成员：保留正常的笔记访问和管理权限。

注意页面读取和操作

{
  "body": "I found it too."
}

{
  "trackableSecretCodes": "LN4C8R2Z",
  "selectedActiveTrackableIds": [
    "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31"
  ],
  "activeTrackableAttachMode": "Self"
}

这些笔记页面路由遵循笔记访问规则，包括私人笔记和由关联可跟踪访问控制的笔记。如果调用者可以打开笔记页面，API 可以返回该笔记的笔记和可见可跟踪项。附加可跟踪项需要笔记所有者或团队管理员。

• 在第一个关联的可跟踪对象存在之前，这些路由的行为类似于普通的公共笔记页面路由。
• 至少存在一个关联后，无法访问一个关联可跟踪项的调用者应该会收到来自公共笔记页面路由的 404，即使该笔记仍然存在。
• 对于所有者、授权团队成员或已解锁关联可追踪项的查看者，同一条笔记仍可返回 200。

阅读类别

工作区树助手

使用这些更轻的辅助路径来实现延迟加载的类别选择器和侧边栏树。树/sections按contentLanguage对根类别进行分组。 tree/children 返回一个父节点的直接子节点，并包含 childCategoryCount，以便客户端可以决定是否在加载孙子节点之前显示扩展可供性。

[
  {
    "contentLanguage": "en-US",
    "rootCategories": [
      {
        "categoryId": "68cb4c9b-d9bd-4bde-8c6a-a03a4c70b283",
        "name": "Field Reports",
        "contentLanguage": "en-US",
        "parentCategoryId": null,
        "childCategoryCount": 2
      }
    ]
  }
]

[
  {
    "categoryId": "c4b2e65f-5cf2-4ab6-8577-a89dfb51407f",
    "name": "Dock checks",
    "contentLanguage": "en-US",
    "parentCategoryId": "68cb4c9b-d9bd-4bde-8c6a-a03a4c70b283",
    "childCategoryCount": 0
  }
]

创建或移动类别

{
  "name": "Field Reports",
  "contentLanguage": "en-US",
  "parentCategoryId": null
}

个人 GPX 航路点切换

GET /api/notes/mine/gpx 仅导出映射的个人笔记，并将坐标保存为 GPX 1.1 航路点。

POST /api/notes/mine/gpx 接受具有文件、可见性和可选 contentLanguage 的多部分表单数据。导入仅读取航路点条目，创建法线映射笔记，并且绝不会覆盖现有笔记。

重复检查保留在选定的个人范围内。具有相同笔记文本的匹配标题加坐标将被报告为重复项。匹配的标题加坐标与不同的笔记文本将被跳过以避免覆盖。

curl "https://locationnotes.com/api/notes/mine/gpx" \
  -H "Authorization: Bearer <access token>"

curl -X POST "https://locationnotes.com/api/notes/mine/gpx" \
  -H "Authorization: Bearer <access token>" \
  -F "file=@waypoints.gpx;type=application/gpx+xml" \
  -F "visibility=Private" \
  -F "contentLanguage=en-US"

什么是导入和导出？ 介绍 GPX 航点交换与完整的 JSON 和便携式 ZIP 帐户导出有何不同。

常见读物

• GET /api/teams
• GET /api/teams/{teamId}/notes
• GET /api/teams/{teamId}/categories
• GET /api/teams/{teamId}/categories/tree
• GET /api/teams/{teamId}/invite-links

团队和团队笔记读取模型包括 lastActivityUtc. 公共修剪优先选择最近活动的记录。

团队类别树助手

这些路线使用与个人工作区树助手相同的部分和子节点形状，但数据保留在选定的团队范围内，并且仍然需要有效的团队成员资格。

使用 DELETE /api/teams/{teamId}/notes/{noteId} 当笔记应该离开团队工作空间但继续存在于所有者时，并使用 DELETE /api/teams/{teamId}/notes/{noteId}/delete 当团队笔记本身应该被永久删除时。

创建团队

{
  "name": "Beta Testers",
  "title": "Beta Testers",
  "description": "Public beta release gate for Android validation.",
  "externalLinkUrl": "https://example.com/beta-program",
  "externalLinkDescription": "",
  "joinPolicy": "RequestsAllowed",
  "pageVisibility": "Public",
  "defaultNoteVisibility": "Public",
  "contentLanguage": "en-US"
}

创建团队笔记

{
  "categoryId": "68cb4c9b-d9bd-4bde-8c6a-a03a4c70b283",
  "title": "Shared dock inspection",
  "body": "Visible to the team until we publish it.",
  "contentLanguage": "en-US",
  "externalLinkUrl": "https://example.com/shared-briefing",
  "externalLinkDescription": "",
  "latitude": 41.8818,
  "longitude": -87.6231,
  "visibility": "Private",
  "commentPolicy": "TeamMembers"
}

团队 GPX 航路点切换

GET /api/teams/{teamId}/notes/gpx 和 POST /api/teams/{teamId}/notes/gpx 在所选团队范围内应用相同的 GPX 规则。重复和覆盖检查仅与该团队的笔记进行比较。

curl "https://locationnotes.com/api/teams/{teamId}/notes/gpx" \
  -H "Authorization: Bearer <access token>"

curl -X POST "https://locationnotes.com/api/teams/{teamId}/notes/gpx" \
  -H "Authorization: Bearer <access token>" \
  -F "file=@team-waypoints.gpx;type=application/gpx+xml" \
  -F "visibility=Public" \
  -F "contentLanguage=en-US"

会员及邀请操作

• POST /api/teams/{teamId}/memberships/request
• POST /api/teams/{teamId}/memberships/invite
• POST /api/teams/{teamId}/memberships/{membershipId}/accept
• POST /api/teams/{teamId}/memberships/{membershipId}/refuse
• POST /api/teams/{teamId}/memberships/{membershipId}/approve
• POST /api/teams/{teamId}/memberships/{membershipId}/deny
• POST /api/teams/{teamId}/memberships/{membershipId}/promote-admin
• DELETE /api/teams/{teamId}/memberships/{membershipId}
• POST /api/teams/invite-links/{teamSlug}/{inviteCode}/join

{
  "isSingleUse": false
}

{
  "inviteLinkId": "9a4726dc-4fb1-4c16-b7b3-5d48ea68fdce",
  "teamId": "0f4ddf5d-f3dc-4417-b96d-8e212d24235e",
  "teamName": "Invite Team",
  "teamSlug": "invite-team",
  "code": "8K4V9T",
  "createdByDisplayName": "invite-admin",
  "createdByCurrentUser": true,
  "inviterIsCurrentlyAdmin": true,
  "isSingleUse": false,
  "createdUtc": "2026-03-18T21:15:00Z"
}

{
  "teamSlug": "invite-team",
  "membershipStatus": "RequestingMembership"
}

标识符格式和示例

生成的公共代码令牌和生成的短秘密主体使用相同的防污字符系列。类型化查找将 O 视为 0，将 I 或 L 视为 1，将 S 视为 5，将 U 视为 V。对于系统短密代码，该规范化适用于文字前缀之后生成的正文。公共代码使用相同的配置前缀，并在生成的正文之前带有破折号，因此它们在视觉上与短秘密代码不同。

列表和详细阅读

公共列表的读取次数受到网站公共数据暴露限制的限制，目前默认为 500。

可跟踪和可跟踪组读取模型包括 lastActivityUtc，因此仪表板和 API 客户端可以明确显示最近的活动。

• GET /api/trackables/public
• GET /api/trackables/mine
• GET /api/trackables/{trackableId}
• POST /api/trackables/{trackableId}/watch
• DELETE /api/trackables/{trackableId}/watch
• GET /api/trackables/{trackableId}/journey
• POST /api/trackables/{trackableId}/journey-stops
• DELETE /api/trackables/{trackableId}/journey-stops/{journeyStopId}

GET /api/trackables/public 和网站的公共可追踪浏览页面保持多语言状态，因此公共旅程和物流数据不会被路线语言隐藏。

当您想要围绕相同的公共可跟踪数据进行本地化 Chrome 时，请切换网站语言。

创建一个可追踪的

{
  "name": "Promo coin",
  "description": "Launch event inventory item",
  "externalLinkUrl": "https://example.com/promo-coin",
  "externalLinkDescription": "",
  "teamId": null,
  "visibility": "AlwaysVisibleToEveryone",
  "activateImmediately": false,
  "secretCode": ""
}

{
  "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
  "heading": "Unactivated Trackable",
  "description": "Please activate this trackable item",
  "items": [
    {
      "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
      "name": "Unactivated Trackable",
      "publicCode": "LN-7K4V9T",
      "secretCode": "LN4C8R2Z",
      "scanUrl": "https://locationnotes.com/trackable/ABCD...<100 characters total>...",
      "qrPayload": "ABCD...<100 characters total>..."
    }
  ]
}

带上你自己的密码

{
  "name": "Marketing token",
  "description": "Bring-your-own identifier",
  "teamId": null,
  "visibility": "VisibleOnceAccessed",
  "activateImmediately": true,
  "secretCode": "TAG42"
}

服务器接受调用者提供的密码，这些密码不以 LN、GT 或 GC 开头，并且与任何现有的密码或公共代码不匹配。返回的公共代码仍然是系统生成的。

创建一个群组

{
  "name": "Gnomes in this hunt",
  "description": "Seasonal hunt inventory",
  "defaultTrackableTitle": "",
  "defaultTrackableDescription": "",
  "defaultExternalLinkUrl": "https://example.com/hunt-rules",
  "defaultExternalLinkDescription": "",
  "trackableCount": 12,
  "teamId": null,
  "visibility": "AlwaysVisibleToEveryone",
  "activateImmediately": false,
  "watchGroupActivityWhenCreated": true
}

群组限制为 100 个可追踪对象。未激活的项目将回退到组默认值，直到激活。一旦激活，他们必须使用自己的标题和描述。

当未激活的批次应在创建者的监视列表上启动时，可跟踪组创建也可以接受 watchGroupActivityWhenCreated。

查找和活动会话

• POST /api/trackables/lookup 在规范化上面列出的常见污迹字符替换后，匹配公共代码令牌或短密码。
• GET /trackable/{code} 是向用户和 API 客户端显示的简短网站入口路径。它接受公共代码、短密码或长 QR 令牌，然后路由到正确的流。
• GET /api/trackables/active 列出客户端当前活动的密码会话（如果存在）。
• GET /api/trackables/active/{trackableId} 返回活动着陆有效负载，包括激活要求和分组项目（如果可用）。
• POST /api/trackables/active/{trackableId}/message 更新记住的状态文本。
• DELETE /api/trackables/active/{trackableId} 结束该客户端上记住的密码会话。

秘密代码查找和仅扫描 QR 访问创建活动客户端会话，而不是返回秘密值。该活动会话允许稍后的笔记流附加可跟踪项，而无需重新输入代码。

当调用者经过身份验证时，相同的“访问一次可见”查找还将可跟踪链接到该帐户，以便以后登录的设备可以重新打开可跟踪、其组页面和正常的后续路由，而无需重新输入密码。

该网站特意对所有三种形式使用相同的直接输入基本路线：/trackable/{publicCode}、/trackable/{secretCode} 和 /trackable/{qrToken}。

本地化的/{lang}/trackable/{code}路线是自动选择语言后渲染的单项落地，但仍然不应该显示为可共享或打印的URL。

公共代码查找解析后，呈现的公共页面位于 /{lang}/trackable/{publicCode}。

即使配置的短代码长度稍后发生变化，共享入口路由仍然有效，因为服务器解析代码值而不是依赖于硬编码的网站路径变化。

所有者范围的网站可跟踪路线故意不属于公共 URL 系统的一部分。

这种区别也适用于笔记页面：公共代码用于打开公共可跟踪页面，而笔记附件则需要现有的短秘密代码或已经处于活动状态的浏览器会话。

GET /api/trackables/lookup?code=LN4C8R2Z

{
  "found": true,
  "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
  "isPublicCodeMatch": false,
  "usesSecretAccess": true,
  "redirectUrl": "/en-US/trackables/active/f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31"
}

GET /trackable/LN-7K4V9T

GET /en-US/trackables/LN-7K4V9T

GET /trackable/ABCD...<100 characters total>...

为自己或团队激活

{
  "name": "",
  "description": "",
  "useGroupDefaultTitle": true,
  "useGroupDefaultDescription": true,
  "externalLinkUrl": "",
  "externalLinkDescription": "",
  "useGroupDefaultExternalLink": true,
  "teamId": "optional-team-guid"
}

如果提供 teamId，则可跟踪对象将成为团队所有，团队管理员可以管理它，并且激活成员在留在该团队时保持控制。如果没有 teamId，可追踪设备将变为个人所有。

当激活分组项目时，所有者可以保存明确的项目标题和描述，也可以有意将组的当前默认标题和描述复制到项目中。

分离和重新附加组

• DELETE /api/trackables/{trackableId}/group 删除当前组关联。
• POST /api/trackables/{trackableId}/group 与 { "trackableGroupId": "..." } 将分离的可跟踪对象与新组关联起来。
• POST /api/trackables/groups/{trackableGroupId}/watch 开始监视该组的可见成员。来自同一组的现有成员项目监视仍然可以折叠到组监视中，并且每个用户都会对所有者或监视重叠进行重复数据删除。
• DELETE /api/trackables/groups/{trackableGroupId}/watch 停止监视该组。

可追踪对象一次只能属于一个组。服务器强制执行分离优先规则。只有原始激活者可以重新附加分离的可跟踪对象，并且目标组还必须由该用户或符合条件的团队管理员控制。

{
  "trackableGroupId": "4bdffcab-bb51-4fd8-8c15-59f7b2d72c3f"
}

可追踪的评论

• GET /api/trackables/{trackableId}/comments
• POST /api/trackables/{trackableId}/comments
• PUT /api/trackables/{trackableId}/comments/{commentId}
• DELETE /api/trackables/{trackableId}/comments/{commentId}

未激活的可追踪项无法接收评论或旅程停靠点。

经过身份验证的用户可以直接发表评论。匿名调用者也可以发帖，但每个匿名写入都必须来自该浏览器的活动可跟踪会话，或者重新发送该特定可跟踪的确切的短密码或私有 QR 令牌。

只有登录的评论作者才能编辑自己的评论。可追踪的所有者和当前团队管理员可以删除评论或旅程停靠点，但他们仍然无法重写其他人的话。

{
  "body": "Starting the route now.",
  "accessCode": "LN4C8R2Z"
}

直达旅程站点

行程提要现在是不可变的停靠历史记录。笔记支持的停靠点会在附加笔记时对位置进行快照，并且可以保存直接地图报告，而无需先创建笔记。

如果链接的笔记后来移动到不同的坐标，可追踪的旅程仍会保留原始的快照停止点，因此物流历史不会默默地重写自己。

匿名直接报告遵循与匿名评论相同的规则：调用者必须使用该浏览器的活动可跟踪会话或在写入请求上重新发送短密码或私有 QR 令牌。

{
  "latitude": 41.8819,
  "longitude": -87.6278,
  "accessCode": "LN4C8R2Z"
}

GET /api/trackables/{trackableId}/journey 返回标签第一位置的事实。每个点都带有 coordinateId、locationLabel 和 currentNotesAtCoordinate，因此客户端可以在该坐标处显示当前可见的笔记，而无需将停靠点视为拥有一个已保存的笔记。

旅程响应不再将外出合同拆分为城市、stateOrProvince 和国家/地区字段。改为读取 locationLabel 加上坐标。

[
  {
    "journeyStopId": "8a274ad6-5dd4-45c4-969a-c13cc1b8d92c",
    "coordinateId": "565c42dd-2e12-49b4-a16b-c89ff4502b8e",
    "latitude": 41.8819,
    "longitude": -87.6278,
    "associatedUtc": "2026-04-05T18:30:00Z",
    "isLocationOnly": false,
    "isAnonymous": false,
    "canDelete": false,
    "canConvertToNote": false,
    "locationLabel": "Chicago, Illinois, United States",
    "creatorDisplayText": "Jordan",
    "creatorProfileUserName": "jordan",
    "currentNotesAtCoordinate": [
      {
        "noteId": "4d6c5df3-3c53-4d0e-8e72-7d98a0f8a9f3",
        "title": "Lobby drop",
        "contentLanguage": "en-US",
        "thumbnailUrl": "/api/images/notes/4d6c5df3-3c53-4d0e-8e72-7d98a0f8a9f3/thumbnail"
      }
    ]
  }
]

可见性和行程披露

即使某些底层笔记是私人的，可追踪的旅程页面也可能会显示地图位置。在这些情况下，未经授权的查看者可以接收位置点，但无法接收受保护的笔记内容。

授权查看者直接从预加载的旅程有效负载和地图图钉弹出窗口接收笔记标题、描述和笔记链接。

删除和保留

删除一个帐户不会自动删除该帐户曾经接触过的每个可追踪项。可以保留共享的或团队拥有的可跟踪项，同时仅删除已删除用户的可移除个人活动。

查看“删除数据”页面和帐户删除 API 部分以了解当前保留边界。

已验证的流量

从找到的项目查找到浏览器秘密访问、登录、激活、笔记链接、直接旅程记录、审核和导出/deletion注意事项。

打开经过身份验证的可追踪API流程指南

匿名流量

对于不会登录但拥有确切密码或私人 QR 令牌并需要安全发布直接位置报告或评论的呼叫者。

打开匿名可追踪API流程指南

错误查找

可跟踪的问题详细信息响应现在包括稳定的机器可读代码字段。使用错误参考页面将故障映射到可能的原因和修复方法。

打开可跟踪的 API 错误参考

验证链接

在自定义客户端中显示描述字段之前调用此方法。成功的响应会返回规范化的 URL、页面标题中建议的描述以及针对审核问题的支持 URL。当目标站点本身返回 HTTP 错误时，失败的响应将返回 HTTP 400，并包含详细消息、支持 URL 和 upstreamStatusCode。

{
  "url": "https://example.com/hunt-rules"
}

{
  "normalizedUrl": "https://example.com/hunt-rules",
  "suggestedDescription": "Example Domain",
  "supportUrl": "/zh-SG/support"
}

{
  "title": "Request rejected.",
  "status": 400,
  "detail": "The external page returned HTTP 405 Method Not Allowed during verification.",
  "supportUrl": "/zh-SG/support",
  "upstreamStatusCode": 405
}

笔记、团队和同步字段

使用 externalLinkUrl 加上 externalLinkDescription 创建和更新笔记、团队和同步有效负载。当同步笔记有效负载上的 ApplyExternalLinkChanges 为 true 时，服务器会在保存之前重新验证链接。

• CreateNoteRequest.ExternalLinkUrl
• CreateNoteRequest.ExternalLinkDescription
• CreateTeamRequest.ExternalLinkUrl
• CreateTeamRequest.ExternalLinkDescription
• UpdateTeamSettingsRequest.ExternalLinkUrl
• UpdateTeamSettingsRequest.ExternalLinkDescription
• NoteDto.ExternalLinkUrl
• NoteDto.ExternalLinkDescription
• NoteDto.ApplyExternalLinkChanges

可跟踪和分组字段

可跟踪创建和更新有效负载使用 externalLinkUrl、externalLinkDescription 和 externalLinkAppendPublicTrackableCode。可跟踪组的创建和更新使用 defaultExternalLinkUrl、defaultExternalLinkDescription 和 defaultExternalLinkAppendPublicTrackableCode。当所有者有意希望从组的默认值开始时，激活仍然接受 useGroupDefaultStatusMessage 以及 useGroupDefaultTitle、useGroupDefaultDescription 和 useGroupDefaultExternalLink。

TrackableGroupCreateInputModel.Name 接受请求中的字母、数字、空格和大写字母。服务器以带下划线的小写形式单独存储页面 slug，并在创建后保持该 slug 固定。

当选择加入存储的可跟踪或可跟踪组默认链接时，仅当从特定可跟踪页面开始单击时，LocationNotes 才会附加 LN={publicCode}。组页面仍然单独使用存储的 URL，因为那里的上下文中没有单独的可跟踪代码。

当应在同一请求中创建第一个跟踪位置时，激活还可以接受可选的 initialJourneyStopLatitude 和 initialJourneyStopLongitude 值。

• TrackableCreateInputModel.ExternalLinkUrl
• TrackableCreateInputModel.ExternalLinkDescription
• TrackableCreateInputModel.ExternalLinkAppendPublicTrackableCode
• TrackableActivationInputModel.StatusMessage
• TrackableGroupCreateInputModel.DefaultExternalLinkUrl
• TrackableGroupCreateInputModel.DefaultExternalLinkDescription
• TrackableGroupCreateInputModel.DefaultExternalLinkAppendPublicTrackableCode
• TrackableGroupCreateInputModel.DefaultStatusMessage
• TrackableGroupCreateInputModel.WatchGroupActivityWhenCreated
• TrackableActivationInputModel.UseGroupDefaultTitle
• TrackableActivationInputModel.UseGroupDefaultDescription
• TrackableActivationInputModel.UseGroupDefaultStatusMessage
• TrackableActivationInputModel.ExternalLinkUrl
• TrackableActivationInputModel.ExternalLinkDescription
• TrackableActivationInputModel.UseGroupDefaultExternalLink
• TrackableActivationInputModel.InitialJourneyStopLatitude
• TrackableActivationInputModel.InitialJourneyStopLongitude

服务器行为

• 在验证成功之前，客户端应将 externalLinkDescription 视为不可用。
• 如果客户端将描述留空，服务器将使用经过验证的页面标题或“在外部页面上找不到标题”。
• 被拒绝的目标可能会失败，因为 URL 格式无效、主机是本地或专用主机、无法访问页面、页面未成功返回或发现成人内容信号。
• 公共页面通过 LocationNotes 退出页面呈现保存的外部链接，而不是将访问者直接发送到第三方目的地。

按父级列出图像

使用这些读物来填充画廊。每个项目包括图像 GUID、原始尺寸以及缩略图、小、中和大存储副本的相对 URLs。

originalWidth和originalHeight描述上传的源图像以供参考。实际的可下载文件仍然是由thumbnailUrl、smallUrl、mediumUrl和largeUrl链接的调整大小的存储变体。

curl "https://locationnotes.com/api/images/notes/4d6c5df3-3c53-4d0e-8e72-7d98a0f8a9f3"

[
  {
    "contentImageId": "f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1",
    "targetType": 1,
    "noteId": "4d6c5df3-3c53-4d0e-8e72-7d98a0f8a9f3",
    "originalWidth": 1600,
    "originalHeight": 1200,
    "createdUtc": "2026-03-18T21:15:00Z",
    "thumbnailUrl": "/Images/Thumbnail/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1-64.jpg",
    "smallUrl": "/Images/Small/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1-306.jpg",
    "mediumUrl": "/Images/Medium/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1-612.jpg",
    "largeUrl": "/Images/Large/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1-1024.jpg"
  }
]

下载存储的字节

有效的变体值为缩略图、小、中和大。响应返回图像/jpeg.

/Images/{Variant}/{guid}-{size}.jpg 下的网站文件 URLs 在提供图像字节之前强制执行相同的父级可见性规则，因此直接图像链接仍受连接的个人资料、笔记、团队、可跟踪或可跟踪组权限的保护。

curl -L "https://locationnotes.com/api/images/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1/large" --output note-large.jpg

上传图片

发送一个名为 file. 的多部分文件字段。调用者必须已经拥有目标的父管理权限，这意味着团队页面的团队管理员访问权限以及其他父类型的正常编辑/management权限。上传的内容在保存之前会经过筛选，然后仅存储为调整大小的 JPEG 副本。

curl -X POST "https://locationnotes.com/api/images/trackables/721f5205-ed2c-43e8-8ecd-1502d5bb7b56" \
  -H "Authorization: Bearer <access token>" \
  -F "file=@tracker.jpg"

{
  "image": {
    "contentImageId": "f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1",
    "targetType": 3,
    "trackableId": "721f5205-ed2c-43e8-8ecd-1502d5bb7b56",
    "originalWidth": 1600,
    "originalHeight": 1200,
    "createdUtc": "2026-03-18T21:15:00Z",
    "thumbnailUrl": "/Images/Thumbnail/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1-64.jpg",
    "smallUrl": "/Images/Small/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1-306.jpg",
    "mediumUrl": "/Images/Medium/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1-612.jpg",
    "largeUrl": "/Images/Large/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1-1024.jpg"
  }
}

删除图像

删除需要与上传相同的家长管理权限。删除成功后，内容图像行和所有存储的调整大小的变体将一起删除。

API 客户端必须在此处发送 HTTP DELETE 谓词。直接在浏览器地址栏中打开此 URL 会发送 GET，这会返回 405 Method Not allowed，因为此路由不是下载页面。

网站删除按钮使用 /{culture}/images/{contentImageId}/delete 处的本地化网站表单路由，因此浏览器图库删除可保持防伪保护。

curl -X DELETE "https://locationnotes.com/api/images/f1d52aa2-4d59-49bf-8d21-7d0b4e9e57f1" \
  -H "Authorization: Bearer <access token>"

什么是图像？ 解释了这些路由背后的可见性、审核、报告、调整大小、导出和删除规则。

提交报告

如果调用者通过网站 cookie 或不记名令牌进行身份验证，则创建的报告将附加到该帐户，因此它会显示在 GET /api/compliance/reports/mine. 下

{
  "pageType": 2,
  "contentType": 5,
  "pageTitle": "Reported note title",
  "pageUrl": "/en-US/Note/2f4a9f80-b7db-4f4b-9d34-0c2cb8777d9a#note-page-title",
  "pageReference": "2f4a9f80-b7db-4f4b-9d34-0c2cb8777d9a",
  "contentLabel": "Note Page title and content",
  "contentReference": "2f4a9f80-b7db-4f4b-9d34-0c2cb8777d9a:page-content",
  "contentPreview": "Title: Reported note title\n\nContent: Reported note body",
  "reportTitle": "Needs review",
  "reportExplanation": "This title is not appropriate for a public note."
}

跟踪 API 票证或报告应用程序错误

如果 API 路由已失败并出现意外的 500，并在问题详细信息 JSON 中返回 ticketNumber，请在此处发布该票证，而不是创建第二个错误日志行。当呼叫者想要超级管理员跟进时，包括userExplanation并设置trackInSupportTickets。

{
  "ticketNumber": "ERR-1M7Q4D9K2X5R8V6N",
  "userExplanation": "Android app hit this right after I tapped refresh twice.",
  "trackInSupportTickets": true,
  "clientContext": {
    "platform": "Android",
    "screen": "My Journeys",
    "appVersion": "1.0.0-beta.20260318.1"
  }
}

当故障仅发生在 Android 应用程序内部且尚无服务器票证时，请创建一个新的错误票证，其中包含描述应用程序所在位置的标记。

{
  "pageMarkerType": "Android screen",
  "pageMarker": "My Journeys",
  "requestCulture": "en-US",
  "requestUrl": "https://locationnotes.com/api/trackables/active/721f5205-ed2c-43e8-8ecd-1502d5bb7b56?includeHistory=true",
  "httpMethod": "GET",
  "responseStatusCode": 503,
  "exceptionType": "Java.Lang.IllegalStateException",
  "exceptionMessage": "Journey list render failed.",
  "stackTrace": "at com.locationnotes.trackables.MyJourneysFragment.render(MyJourneysFragment.kt:42)",
  "userExplanation": "This happened right after scanning a QR code.",
  "trackInSupportTickets": true,
  "clientContext": {
    "platform": "Android",
    "deviceModel": "Pixel 9",
    "osVersion": "Android 17",
    "appVersion": "1.0.0-beta.20260318.1"
  }
}

{
  "ticketNumber": "ERR-1M7Q4D9K2X5R8V6N",
  "usedExistingTicket": false,
  "explanationSaved": true,
  "trackedInSupportTickets": true,
  "trackedContentReportId": "d91f6e1c-b8e2-4e38-9e96-f2de0cc4f0e2"
}

使用 pageMarkerType 值，例如 URL、Android 屏幕或 Android 后台任务。对于服务器生成的票证，请保留原始的 URL 标记并将返回的 ticketNumber 发送回此处，以便记录的 API URL 保持附加到同一张票证。

记者状态读取

这些路由仅返回调用者自己的报告，除非调用者是超级管理员。使用它们来显示“已报告”、“正在审阅”或“已解决”以及内容报告和跟踪的系统错误的任何最终解决说明。

{
  "contentReportId": "3ab419ab-4b71-4d43-b52c-303d6039f01f",
  "reporterUserId": "6d650c55-b235-4370-8572-e4b772cd1aea",
  "pageType": 2,
  "pageTypeLabel": "Note Page",
  "contentType": 5,
  "contentTypeLabel": "Title and content",
  "status": 2,
  "statusLabel": "Resolved",
  "pageTitle": "Reported note title",
  "pageUrl": "/en-US/Note/2f4a9f80-b7db-4f4b-9d34-0c2cb8777d9a#note-page-title",
  "pageReference": "2f4a9f80-b7db-4f4b-9d34-0c2cb8777d9a",
  "contentLabel": "Note Page title and content",
  "contentReference": "2f4a9f80-b7db-4f4b-9d34-0c2cb8777d9a:page-content",
  "contentPreview": "Title: Reported note title\n\nContent: Reported note body",
  "reportTitle": "Needs review",
  "reportExplanation": "This title is not appropriate for a public note.",
  "resolutionText": "Reviewed and recorded for moderation follow-up.",
  "reporterDisplayName": "site-compliance-reporter",
  "reviewerDisplayName": "site-compliance-admin",
  "createdUtc": "2026-03-18T18:00:00Z",
  "reviewedUtc": "2026-03-18T18:10:00Z"
}

超级管理员审核

管理列表包括报告链接、页面元数据、违规内容元数据、报告者身份（如果可用）以及任何先前的审核笔记。更新写入当前审阅状态和可见分辨率文本。

{
  "status": 1,
  "resolutionText": "Review opened and queued for follow-up."
}

将状态设置为 2，并在关闭已解决的报告时包含非空 resolutionText。

枚举值

• pageType: 0 个人资料页, 1 团队页面, 2 笔记页, 3 可追踪页面, 4 可追踪的群组页面, 5 系统错误, 6 支持页面
• contentType: 0 标题, 1 描述, 2 评论, 3 身体, 4 生物, 5 标题和内容, 6 错误详情, 7 图像, 8 支持请求
• status: 0 报道, 1 审查, 2 已解决

网站页面级报告现在使用 5 个，因此一个报告按钮可以同时覆盖可见标题和可见描述 /body。评论级报告仍然使用特定于评论的内容类型。

网站一般支持请求通过同一 COMPLIANCE.ContentReports 存储创建支持页面和支持请求票证，即使浏览器表单使用支持页面而不是此原始 API 路由。

跟踪的网站、API 和 Android 应用程序错误存储在 LOG.Errors 中。启用 trackInSupportTickets 后，链接的支持票证也会出现在 COMPLIANCE.ContentReports 中，因此超级管理员审核和报告者状态遵循相同的工作流程。

将此用于运行状况检查、Android 兼容性门控、当前 beta 页面 URL 以及当前请求的已解析映射 /privacy 状态。

返回暂存的 Android beta 元数据，包括显示版本、版本代码、最低兼容版本和发行说明。

返回当前请求的尽力而为的基于 IP 的位置，以进行地图居中和故障排除。 当客户端 IP 是私有、本地或其他不受信任的 IP 时，响应保持 HTTP 200 并解释失败 failureReason 而不是抛出传输错误。

将纬度 /longitude 对反向地理编码为城市、州 /province 和国家/地区标签，以用于停止规划器和地图选择流程。 无效坐标返回非抛出有效负载 resolved=false 和 failureReason=invalid-coordinates.

身份认证与账户安全

• POST /api/auth/register 匿名
• POST /api/auth/login 匿名
• POST /api/auth/refresh 匿名
• GET /api/auth/confirmEmail 匿名
• POST /api/auth/resendConfirmationEmail 匿名
• POST /api/auth/forgotPassword 匿名
• POST /api/auth/resetPassword 匿名
• GET /api/auth/manage/info 承载者
• POST /api/auth/manage/info 承载者
• POST /api/auth/manage/2fa 承载者

帐户、系统、同步和外部链接

• DELETE /api/account 承载者
• GET /api/system/status 匿名
• GET /api/system/beta-android 匿名
• GET /api/system/ip-location 匿名
• GET /api/system/coordinate-locality 匿名
• POST /api/sync/push 承载者
• POST /api/sync/pull 承载者
• POST /api/external-links/verify 承载者

笔记和公共笔记页面

• GET /api/notes/public/bounds 匿名
• GET /api/notes/public/nearby 匿名
• GET /api/notes/mine 承载者
• POST /api/notes/mine 承载者
• GET /api/notes/mine/gpx 承载者
• POST /api/notes/mine/gpx 承载者
• POST /api/notes/mine/{noteId}/move 承载者
• DELETE /api/notes/mine/{noteId} 承载者
• GET /api/public/profiles/{userName}/notes/nearby 匿名或不记名
• GET /api/public/teams/{teamName}/notes/nearby 匿名或不记名
• GET /api/public/notes/{noteId} 匿名或不记名
• GET /api/public/notes/{noteId}/comments 匿名或不记名
• POST /api/public/notes/{noteId}/comments 承载者
• GET /api/public/notes/{noteId}/trackables 匿名或不记名
• POST /api/public/notes/{noteId}/trackables 承载者

类别和工作区树

• GET /api/categories/mine 承载者
• GET /api/categories/mine/tree 承载者
• GET /api/categories/mine/tree/sections 承载者
• GET /api/categories/mine/tree/children 承载者
• POST /api/categories/mine 承载者
• POST /api/categories/mine/{categoryId}/move 承载者
• DELETE /api/categories/mine/{categoryId} 承载者

团队、会员资格和邀请链接

• GET /api/teams 承载者
• POST /api/teams 承载者
• PUT /api/teams/{teamId}/settings 承载者
• GET /api/teams/{teamId}/notes 承载者
• GET /api/teams/{teamId}/notes/gpx 承载者
• DELETE /api/teams/{teamId}/notes/{noteId} 承载者
• POST /api/teams/{teamId}/notes 承载者
• POST /api/teams/{teamId}/notes/gpx 承载者
• POST /api/teams/{teamId}/notes/{noteId}/move 承载者
• DELETE /api/teams/{teamId}/notes/{noteId}/delete 承载者
• GET /api/teams/{teamId}/categories 承载者
• GET /api/teams/{teamId}/categories/tree 承载者
• GET /api/teams/{teamId}/categories/tree/sections 承载者
• GET /api/teams/{teamId}/categories/tree/children 承载者
• POST /api/teams/{teamId}/categories 承载者
• POST /api/teams/{teamId}/categories/{categoryId}/move 承载者
• DELETE /api/teams/{teamId}/categories/{categoryId} 承载者
• POST /api/teams/{teamId}/memberships/request 承载者
• POST /api/teams/{teamId}/memberships/invite 承载者
• POST /api/teams/{teamId}/memberships/{membershipId}/accept 承载者
• POST /api/teams/{teamId}/memberships/{membershipId}/refuse 承载者
• POST /api/teams/{teamId}/memberships/{membershipId}/approve 承载者
• POST /api/teams/{teamId}/memberships/{membershipId}/deny 承载者
• POST /api/teams/{teamId}/memberships/{membershipId}/promote-admin 承载者
• DELETE /api/teams/{teamId}/memberships/{membershipId} 承载者
• GET /api/teams/{teamId}/invite-links 承载者
• POST /api/teams/{teamId}/invite-links 承载者
• DELETE /api/teams/{teamId}/invite-links/{inviteLinkId} 承载者
• POST /api/teams/invite-links/{teamSlug}/{inviteCode}/join 承载者
• DELETE /api/teams/{teamId} 承载者

可追踪和活跃的秘密支持会话

• GET /api/trackables/public 匿名或不记名
• GET /api/trackables/mine 承载者
• GET /api/trackables/{trackableId} 匿名或不记名
• GET /api/trackables/{trackableId}/journey 匿名或不记名
• POST /api/trackables 承载者
• POST /api/trackables/groups 承载者
• POST /api/trackables/{trackableId}/activate 承载者
• POST /api/trackables/{trackableId}/watch 承载者
• DELETE /api/trackables/{trackableId}/watch 承载者
• DELETE /api/trackables/{trackableId}/group 承载者
• POST /api/trackables/{trackableId}/group 承载者
• POST /api/trackables/groups/{trackableGroupId}/watch 承载者
• DELETE /api/trackables/groups/{trackableGroupId}/watch 承载者
• GET /api/trackables/lookup 匿名
• POST /api/trackables/lookup 匿名
• GET /api/trackables/active 匿名
• GET /api/trackables/active/{trackableId} 匿名
• POST /api/trackables/active/{trackableId}/message 匿名
• DELETE /api/trackables/active/{trackableId} 匿名
• GET /api/trackables/{trackableId}/comments 匿名或不记名
• POST /api/trackables/{trackableId}/comments 匿名或不记名
• PUT /api/trackables/{trackableId}/comments/{commentId} 承载者
• DELETE /api/trackables/{trackableId}/comments/{commentId} 承载者
• POST /api/trackables/{trackableId}/journey-stops 匿名或不记名
• DELETE /api/trackables/{trackableId}/journey-stops/{journeyStopId} 承载者

图像和合规性

• GET /api/images/profiles/{userId} 匿名或不记名
• GET /api/images/notes/{noteId} 匿名或不记名
• GET /api/images/teams/{teamId} 匿名或不记名
• GET /api/images/trackables/{trackableId} 匿名或不记名
• GET /api/images/trackable-groups/{trackableGroupId} 匿名或不记名
• GET /api/images/{contentImageId}/{variant} 匿名或不记名
• POST /api/images/profiles 承载者
• POST /api/images/notes/{noteId} 承载者
• POST /api/images/teams/{teamId} 承载者
• POST /api/images/trackables/{trackableId} 承载者
• POST /api/images/trackable-groups/{trackableGroupId} 承载者
• DELETE /api/images/{contentImageId} 承载者
• POST /api/compliance/reports 匿名或不记名
• POST /api/compliance/errors 匿名或不记名
• GET /api/compliance/reports/mine 承载者
• GET /api/compliance/reports/{contentReportId} 承载者
• GET /api/compliance/reports 承载+超级管理员
• PUT /api/compliance/reports/{contentReportId} 承载+超级管理员