Документація API LocationNotes

Базовий URL

Усі приклади на цій сторінці припускають поточний робочий хост:

https://locationnotes.com

Формат

Запити та відповіді використовують JSON. Ідентифікатори GUID є основними ідентифікаторами для нотаток, категорій, команд і пристроїв.

Авторизація

Приватні, синхронізовані та командні кінцеві точки вимагають Authorization: Bearer <access token> заголовок, якщо маршрут не позначено як публічний нижче.

Мова

Читання громадськості та керівництва можуть бути прийняті contentLanguage=en-US або іншою підтримуваною мовою вмісту, щоб відфільтрувати повернутий вміст примітки/категорії.

Необхідний рядок запиту: 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 щоб клієнти могли відображати останню активність окремо від часових позначок збереження/оновлення.

Створіть нотатку

{
  "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"
}

Поле visibility приймає значення Private, Public і VisibleOnceAssociatedTrackableAccessed. Режим пов’язаного трекера поводиться як Public, доки нотатка не має одного або кількох пов’язаних трекерів. Після цього публічне виявлення та доступ до сторінки нотатки вимагають, щоб відвідувач уже розблокував один із цих пов’язаних трекерів.

• Пов'язаних трекерів ще немає: нотатка поводиться як публічна нотатка.
• Після першого зв'язку: нотатка зникає з анонімного публічного виявлення та звичайного доступу до публічної сторінки нотатки.
• Розблокований відвідувач: той, хто вже розблокував один пов'язаний трекер, може відкрити сторінку нотатки та використовувати пов'язані публічні API-маршрути сторінки нотатки.
• Власник або уповноважений учасник команди: зберігає звичайний доступ до нотатки та права керування.

Читання та дії сторінки нотатки

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

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

Ці маршрути сторінок нотаток поважають правила доступу до нотаток, включно з приватними нотатками та нотатками, захищеними доступом через пов'язаний трекер. Якщо запитувач може відкрити сторінку нотатки, API може повернути коментарі та видимі трекери для цієї нотатки. Прикріплення трекерів вимагає власника нотатки або адміністратора команди.

• До появи першого пов'язаного трекера ці маршрути поводяться як звичайні маршрути публічної сторінки нотатки.
• Після появи принаймні одного зв'язку викликачі без доступу до одного з пов'язаних трекерів повинні очікувати 404 від публічних маршрутів сторінки нотатки, навіть якщо сама нотатка все ще існує.
• Та сама нотатка все ще може повертати 200 для власника, уповноважених учасників команди або відвідувачів, які вже розблокували один пов'язаний трекер.

Читайте категорії

Допоміжні маршрути дерева робочого простору

Використовуйте ці легші допоміжні маршрути для відкладено завантажуваних вибирачів категорій і дерев бічної панелі. tree/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 приймає multipart-дані з файлом, visibility і необов’язковим 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 і публічні сторінки перегляду трекерів на сайті залишаються багатомовними, щоб відкриті дані про маршрут і логістику не ховалися через мову маршруту.

Змініть мову сайту, якщо хочете бачити локалізований інтерфейс навколо тих самих публічних даних трекера.

Створити трекер

{
  "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, щоб клієнти могли показувати поточні видимі нотатки для цієї координати, не трактуючи зупинку так, ніби вона назавжди володіє однією збереженою нотаткою.

Відповіді маршруту більше не розбивають зовнішній контракт місця на поля city, stateOrProvince і country. Натомість читайте 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 видалення облікового запису, щоб дізнатися про поточні межі зберігання.

Автентифікований потік

Від пошуку знайдених предметів через таємний доступ у веб-переглядачі, входу, активації, зв’язування нотаток, прямого журналювання подорожей, модерації та питань експорту/видалення.

Відкрийте автентифікований посібник із відстеження API

Анонімний потік

Для абонентів, які не збираються входити, але мають точний секретний код або приватний QR-токен і їм потрібно опублікувати звіт про прямий місцезнаходження або безпечно залишити коментар.

Відкрийте посібник з анонімного відстеження API

Пошук помилок

Відповіді problem-details для трекованих об’єктів тепер містять стабільне машинозчитуване поле code. Використовуйте довідкову сторінку помилок, щоб зіставити збої з імовірними причинами та виправленнями.

Відкрийте довідку про помилку API, що відстежується

Перевірте посилання

Викличте це перед показом поля опису в спеціальному клієнті. Успішна відповідь повертає нормалізовану URL-адресу, пропонований опис із заголовка сторінки та URL-адресу підтримки для проблем із переглядом. Невдалі відповіді повертають HTTP 400 із детальним повідомленням, URL-адресою підтримки та upstreamStatusCode, коли сам сайт призначення повертає помилку HTTP.

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

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

{
  "title": "Request rejected.",
  "status": 400,
  "detail": "The external page returned HTTP 405 Method Not Allowed during verification.",
  "supportUrl": "/uk-UA/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 у запитах приймає літери, цифри, пробіли та великі літери. Сервер зберігає слаг сторінки окремо в нижньому регістрі з підкресленнями й залишає цей слаг незмінним після створення.

Коли збережене посилання трекера або типове посилання групи трекерів вмикає цю опцію, 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 зображення, оригінальні розміри та відносні URL-адреси для мініатюр, малих, середніх і великих збережених копій.

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.

URL-адреси файлів веб-сайтів у розділі /Images/{Variant}/{guid}-{size}.jpg застосовують те саме правило видимості батьківського елемента до того, як подаються байти зображень, тому прямі посилання на зображення все ще захищені дозволами підключеного профілю, примітки, команди, дозволів для відстеження або групи для відстеження.

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

Завантажити зображення

Надіслати одне багатокомпонентне поле файлу з назвою файл. Абонент уже повинен мати дозвіл на батьківське керування для цілі, що означає доступ адміністратора команди до сторінок команди та звичайний дозвіл на редагування/керування для інших батьківських типів. Завантажені файли перевіряються перед збереженням, а потім зберігаються лише як копії 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 і повернув ticketNumber у JSON з інформацією про проблему, опублікуйте це звернення тут замість створення другого рядка журналу помилок. Включіть 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 назад сюди, щоб зареєстрована URL-адреса API залишалася приєднаною до того самого звернення.

Статус репортера читає

Ці маршрути повертають лише власні звіти абонента, якщо він не є суперадміністратором. Використовуйте їх, щоб відобразити Повідомлені, Перевірені або Вирішені, а також будь-яку остаточну примітку про вирішення як для звітів про вміст, так і для відстежених системних помилок.

{
  "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 і включіть непорожній резолюційний текст під час закриття звіту як вирішеного.

Значення переліку

• pageType: 0 сторінка профілю, 1 сторінка команди, 2 сторінка приміток, 3 сторінка трекера, 4 сторінка групи трекерів, 5 системна помилка, 6 сторінка підтримки
• contentType: 0 заголовок, 1 опис, 2 коментар, 3 текст, 4 біо, 5 заголовок і вміст, 6 деталі помилки, 7 зображення, 8 запит на підтримку
• status: 0 повідомляється, 1 перегляд розділу, 2 вирішено

У звітах на рівні сторінки веб-сайту тепер використовується 5, тому одна кнопка звіту може охоплювати як видимий заголовок, так і видимий опис/основну частину разом. У звітах на рівні коментарів все ще використовуються типи вмісту для коментарів.

Загальні запити до підтримки на вебсайті створюють звернення типів Сторінка підтримки та Запит до підтримки через те саме сховище COMPLIANCE.ContentReports, навіть хоча форма браузера використовує сторінку Підтримка, а не цей прямий маршрут API.

Трековані об’єкти помилки веб-сайту, API та програми Android зберігаються в LOG.Errors. Коли trackInSupportTickets увімкнено, зв’язаний запит на підтримку також з’являється в COMPLIANCE.ContentReports, тому перевірка суперадміністратором і статус звіту відбуваються в тому самому робочому процесі.

Використовуйте це для перевірок стану, контролю сумісності Android, поточної URL-адреси бета-сторінки та розв’язаного стану карти й приватності для поточного запиту.

Повертає поетапні метадані бета-версії Android, зокрема версію дисплея, код версії, мінімальну сумісну версію та примітки до випуску.

Повертає найкраще доступне місцезнаходження для поточного запиту, визначене за IP, для центрування мапи та діагностики. Коли IP-адреса клієнта є приватною, локальною або з іншої причини ненадійною, відповідь усе одно повертається з HTTP 200 і пояснює збій у failureReason замість того, щоб викидати транспортну помилку.

Виконує зворотне геокодування пари широта/довгота в мітки міста, області або штату та країни для планувальника зупинок і сценаріїв вибору на мапі. Некоректні координати повертають безпечний для клієнта результат із resolved=false і failureReason=invalid-coordinates.

Автентифікація identity та безпека облікового запису

• 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 Bearer + Суперадміністратор
• PUT /api/compliance/reports/{contentReportId} Bearer + Суперадміністратор