실시간 추적
실시간 추적은 게시된 지도에 차량이 지금 어디에 있고 오늘 어디에 정차하는지 보여 줍니다. 푸드트럭 노선, 셔틀 순환, 이동 진료소 등입니다. 방문자는 근무 중인 각 차량이 지도 위에서 움직이는 모습, 지금 여기, 영업 중, 오늘 휴무가 표시된 오늘의 정류장, 다음 정류장까지 남은 시간의 추정치를 봅니다. 방문자에게 보이는 내용은 실시간 레이아웃을 참고하세요.
세 부분으로 이루어지며 모두 Kaleidr Studio에 있습니다.
| 구성 | 내용 |
|---|---|
| 정류장 컬렉션 | 일정: 각 정류장, 주소, 주간 운행 시간대. 다른 컬렉션과 같은 장소 라이브러리 컬렉션입니다. |
| 플릿 | 차량, 근무, 방문자에게 보이는 정밀도. 데이터, 플릿에서 관리합니다. |
| 위치 | 각 차량의 위치로, 운전자의 체크인 링크, 운전자 모드 휴대폰, 자체 트래커, 텔레매틱스 제공업체와의 커넥터 중 하나에서 옵니다. |
위치는 차량이 근무 중일 때만 표시됩니다. 차량의 어떤 근무에도 속하지 않는 시각에 기록된 위치는 도착하는 즉시 버려집니다. 저장되거나 표시되지 않고 개수만 집계됩니다. 근무를 참고하세요.
플릿
데이터에서 플릿 탭을 선택한 다음 새 플릿을 선택합니다. 이름과 시간대를 정하고, 정류장 컬렉션이 있으면 정류장 컬렉션에서 고릅니다. Studio는 같은 이름의 차량 컬렉션을 만듭니다. 이 컬렉션이 지도 위의 플릿이며, 다른 컬렉션처럼 지도에 추가합니다. 가져온 장소는 들어 있지 않으며, 차량은 플릿의 차량입니다.
플릿 페이지의 차량 추가로 한 대를 추가합니다.
| 필드 | 방문자에게 표시 | 용도 |
|---|---|---|
| 이름 | 예 | 지도와 패널에 표시되는 차량 레이블(예: "트럭 1"). 플릿 안에서 고유합니다. |
| 종류 | 예 | 트럭, 밴, 승용차, 버스, 셔틀, 보트, 카트, 자전거. |
| 색상 | 예 | 지도 위 차량의 색. |
| 설명 | 예 | 카드에 표시되는 짧은 한 줄, 최대 200자. |
| 외부 ID | 아니요 | 내 ID로, 커넥터와 정류장의 차량 열에서 대조에 사용합니다. |
| 근무 시간 | 아니요 | 시간 지정 플릿의 근무가 따르는 주간 시간. 근무를 참고하세요. |
비활성화한 차량은 표시되지 않으며 위치도 버려집니다. 플릿 페이지에는 플릿의 실시간 지도가 최대 정밀도로, 나에게만 표시됩니다.
플릿과 차량은 소유자, 관리자, 구성원이 관리하고 뷰어는 볼 수 있습니다. 플릿 삭제, 차량 기록 삭제, 커넥터 관리는 소유자와 관리자만 할 수 있습니다. 플릿 삭제는 플릿과 그 차량, 기기, 링크, 근무, 기록, 커넥터를 삭제한 다음 차량 컬렉션을 삭제합니다.
정류장 일정
일정은 정류장 컬렉션입니다. 각 정류장은 이름과 주소 또는 좌표가 있는 장소이며, 다음 필드가 언제 운행하는지를 정합니다.
| 필드 | 의미 |
|---|---|
| 영업시간 | 정류장의 주간 운행 시간대로, 영업시간처럼 작성하며 하루 최대 네 개까지 지정합니다. 시간대는 자정을 넘을 수 있으며, 시작한 날에 속합니다. |
| 시간대 | 운행 시간대를 작성한 시간대. 비어 있으면 컬렉션의 시간대입니다. |
| 상태 | paused이면 정류장이 모든 날에서 빠집니다. 다른 값이거나 비어 있으면 유지됩니다. |
| 차량 | 정류장을 담당하는 차량의 이름이나 외부 ID. 비어 있으면 플릿의 어떤 차량이든 됩니다. |
| 운행 날짜 | YYYY-MM-DD 형식의 날짜를 쉼표 나 공백으로 구분한 것. 있으면 정류장은 그 날짜에만 운행합니다. |
특정 날짜의 정류장 운행 시간대는 다음과 같습니다.
- 상태가
paused이거나 시간대가 유효하지 않으면 없음. - 운행 날짜가 있는데 그 날짜가 포함되지 않으면 없음.
- 영업시간이 없으면, 운행 날짜에 그 날짜가 있을 때 하루 종일, 아니면 없음.
- 그 밖에는 해당 요일의 영업시간.
오늘의 시간대가 현지 시각을 포함하거나, 자정을 넘는 어제의 시간대가 포함하면 정류장은 지금 영업 중입니다. "오늘"은 플릿 시간대의 날짜입니다.
| 정류장 | 확인 시각 | 시간대 | 영업 중 |
|---|---|---|---|
| 영업시간 월요일 11:00–14:00 | 월요일 12:00 | 11:00–14:00 | 예 |
| 같음 | 월요일 15:00 | 11:00–14:00 | 아니요 |
같음, 운행 날짜 2026-11-02 포함 | 월요일 2026-11-09, 12:00 | 없음 | 아니요 |
운행 날짜 2026-11-02, 영업시간 없음 | 2026-11-02, 09:00 | 하루 종일 | 예 |
영업시간 월요일 11:00–14:00, 상태 Paused | 월요일 12:00 | 없음 | 아니요 |
| 영업시간 금요일 22:00–02:00 | 토요일 01:00 | 금요일의 22:00–02:00 | 예 |
| 영업시간 월요일 11:00–14:00, 유효하지 않은 시간대 | 월요일 12:00 | 없음 | 알 수 없음 |
운행 날짜 2026-11-02, 2026-11-03 2026-11-04, 영업시간 월요일 11:00–14:00 | 화요일 2026-11-03 | 화요일 영업시간: 없음 | 아니요 |
템플릿 빌더의 Location 템플릿과 샘플 시트 다운로드로 미리 채워진 정류장 컬렉션에서 시작할 수 있습니다.
체크인 링크
체크인 링크를 사용하면 운전자가 앱이나 계정 없이 어떤 휴대폰 브라우저에서든 차량이 정류장에 있음을 표시할 수 있습니다.
플릿 페이지에서 만드세요. 차량을 선택하고 체크인 링크, 링크 만들기를 선택합니다. Studio는 링크를 한 번만 보여 주며, 링크 복사와 스캔용 QR 코드를 함께 표시합니다. 링크는 https://map-embed.kaleidr.com/checkin.html#… 형태입니다.
- 링크는 차량당 하나이며, 180일 동안 유효합니다. 링크 교체는 새 링크를 발급하고 이전 링크를 즉시 무효화합니다. 휴대폰을 잃어버리거나 운전자가 그만둘 때 사용하세요. 링크 취소는 링크를 무효화합니다. 그 후 Studio에는 링크의 마지막 네 글자, 만료 시점, 마지막 사용 시각만 표시됩니다.
- 링크는 열쇠입니다. 링크를 가진 사람은 누구나 정류장 근처에서 차량을 체크인할 수 있습니다. 운전자에게만 공유하세요.
- 브라우저에서 여세요. 이 페이지는 다른 페이지의 프레임 안에서는 동작하지 않습니다.
운전자 페이지에는 차량, 오늘의 정류장과 상태가 표시됩니다.
- 지금 도착했어요는 휴대폰 위치를 한 번 읽고 범위 안의 정류장에 체크인합니다. 범위는 250미터에 측정 정확도를 더한 거리이며, 정확도는 100미터 이내여야 합니다. 범위 안에 정류장이 여러 개이거나 없으면 오늘의 정류장 목록이 표시되고, 운전자가 2,000미터 이내의 정류장 하나를 고릅니다. 정류장 밖 체크인 허용이 켜진 플릿에서는 예정에 없는 정류장도 선택할 수 있습니다.
- 오늘 영업 종료는 그 차량의 오늘 남은 정류장을 오늘 휴무로 표시하고 근무를 끝냅니다. 같은 날이라면 오늘 다시 영업으로 이 표시를 지울 수 있습니다. 근무는 시작되지 않습니다.
체크인하면 정류장 시간대가 끝난 뒤 30분까지 근무가 열리며, 차량은 휴대폰 위치가 아니라 정류장 자체의 위치에 표시됩니다. 휴대폰 위치는 정류장을 찾는 데 쓰인 뒤 버려집니다. 정류장 밖에서 체크인하면 차량은 약 10미터 단위로 반올림한 휴대폰 위치에 네 시간 동안 표시됩니다. 플릿의 공개 정밀도가 그보다 낮으면 그 정밀도로 반올림됩니다.
운전자 모드 휴대폰
Kaleidr 앱이 설치된 운전자 휴대폰은 운전자가 근무 중인 동안 차량 위치를 공유합니다. 플릿 페이지에서 차량의 휴대폰 연결을 선택한 다음 연결 코드 보기 버튼을 선택하면 QR 코드와 8 자리 코드가 표시되며, 10분 동안 한 번만 사용할 수 있습니다. 운전자는 휴대폰 카메라로 QR을 스캔하거나 앱에 코드를 입력합니다. 운전자 쪽 절차는 운전자 모드를 참고하세요.
기기에는 각 차량의 휴대폰과 트래커가 나열됩니다. 연결 해제는 기기를 즉시 제거합니다. 그 기기의 다음 호출은 거부되고, 그 기기가 시작한 근무는 끝납니다.
트래커와 위치 API
트래커는 위치를 보내는 내 기기나 시스템을 말합니다. HTTP 클라이언트가 있는 GPS 장치나 자체 배차 소프트웨어 등입니다. 플릿 페이지에서 차량의 트래커 추가를 선택하고 이름을 정하면, Studio가 키를 한 번만 보여 줍니다. 키는 그 차량에 속합니다.
curl https://api.kaleidr.com/live-api/v1/positions \
-H "Authorization: Bearer YOUR_DEVICE_KEY" \
-H "Content-Type: application/json" \
-d '{
"positions": [
{ "lat": 40.74110, "lng": -73.98970, "heading": 90, "speed": 8.3, "accuracy": 12,
"recorded_at": "2026-10-22T15:04:05Z" }
],
"sent_at": "2026-10-22T15:04:06Z"
}'
| 필드 | 규칙 |
|---|---|
positions | 1~100개 지점이며 순서는 상관없습니다. 본문은 최대 64 KiB입니다. |
lat, lng | 필수. 범위 안이어야 하며 둘 다 0이면 안 됩니다. |
heading | 북쪽 기준 각도. |
speed | 초당 미터. |
accuracy | 미터. 정확도가 100미터보다 나쁜 지점은 버려집니다. |
recorded_at | 필수. 위치를 측정한 시각으로, RFC 3339 또는 1970년 이후 밀리초. |
sent_at | 기기 시계 기준으로 배치를 보낸 시각. Kaleidr 시계와 5초보다 크고 하루보다 작게 차이 나면 각 recorded_at을 그 차이만큼 보정하며, 하루 이상 차이 나면 배치가 거부됩니다. |
응답:
{
"accepted": 1,
"dropped": { "off_shift": 0, "stale": 0, "future": 0, "inaccurate": 0, "rate": 0, "duplicate": 0 },
"shift": { "id": "…", "state": "on", "ends_at": "2026-10-23T03:04:05Z" },
"min_interval_s": 10
}
| 버려진 이유 | 설명 |
|---|---|
off_shift | 차량의 어떤 근무에도 속하지 않는 시각에 기록되었거나 차량이 비활성 상태입니다. 저장되지 않습니다. |
stale | 12시간 이상 전에 기록되었습니다. |
future | Kaleidr 시계보다 30초 이상 앞선 시각으로 기록되었습니다. |
inaccurate | 정확도가 100미터보다 나쁘거나, 속도나 정확도가 음수입니다. |
rate | 차량의 이전 지점과의 시간 간격이 요금제의 업데이트 간격보다 짧습니다. |
duplicate | 같은 recorded_at의 지점이 이미 저장되어 있습니다. |
GET /live-api/v1/device는 기기, 해당 차량, 플릿, 열려 있는 근무를 반환합니다. POST /live-api/v1/device/shift에 { "action": "start" } 또는 { "action": "end" }를 보내면 기기에서 차량 근무를 시작하거나 끝냅니다.
| 상태 | error | 의미 |
|---|---|---|
| 400 | invalid_request | 본문 형식이 잘못되었습니다. field가 해당 부분을 알려 줍니다. |
| 400 | clock_invalid | sent_at이 Kaleidr 시계와 하루 이상 차이 납니다. |
| 401 | unauthorized | 키가 없거나 알 수 없는 키입니다. |
| 401 | device_revoked | Studio에서 기기가 제거되었습니다. 전송을 멈추세요. |
| 409 | off_shift | 배치에 지점이 있었지만 어느 것도 근무에 속하지 않았고, 열린 근무도 없습니다. 근무가 시작될 때까지 전송을 멈추세요. |
| 413 | batch_too_large | 100개 지점 또는 64 KiB를 넘었습니다. |
| 429 | rate_limited | 이 기기에서 분당 요청이 12건을 넘었습니다. Retry-After의 초만큼 기다리세요. |
오류는 { "error": <code>, "message": <sentence> } 형태입니다. 이동 중에는 10~30초마다 보내세요. 지점마다 요청을 보내는 것보다 여러 지점을 묶어 보내는 편이 낫습니다.
커넥터
커넥터는 차량이 이미 보고하고 있는 텔레매틱스 시스템에서 위치를 가져옵니다. 소유자와 관리자가 플릿 페이지 의 커넥터, 커넥터 추가에서 추가합니다. 커넥터는 Pro와 Enterprise에서 사용할 수 있습니다.
| 커넥터 | 제공할 것 | 위치가 들어오는 방식 |
|---|---|---|
| Samsara | 차량 위치 읽기 권한이 있는 API 토큰 | Kaleidr가 가져오기 간격마다 Samsara에 새 위치를 요청합니다. |
| Geotab | 서버(geotab.com 호스트), 데이터베이스, 사용자 이름, 비밀번호 | Kaleidr가 가져오기 간격마다 Geotab에 새 로그 레코드를 요청합니다. |
| Traccar | 없음: Studio가 수집 URL과 시크릿을 보여 줍니다 | Traccar 서버가 각 위치를 전달합니다. |
| Webhook | 없음: Studio가 수집 URL과 시크릿을 보여 줍니다 | 내 시스템이 서명된 배치를 보냅니다. |
- 자격 증명은 쓰기 전용입니다. Studio는 Samsara나 Geotab 자격 증명을 저장하기 전에 한 번 호출해 확인하며, 다시는 보여 주지 않습니다. 자격 증명 교체로 바꿉니다.
- 수집 시크릿은 한 번만 표시됩니다. 비밀 교체로 새 시크릿을 발급하며, 이전 시크릿도 24시간 동안 계속 작동합니다.
- 연결 기준은 제공업체의 차량이 내 차량을 찾는 방법을 정합니다. 외부 ID(기본값) 또는 이름입니다. 일치하는 차량이 없는 제공업체 차량은 대조되지 않은 차량에 차량으로 추가와 함께 표시되며, 그 위치는 버려집니다.
- 가져오기 간격은 최소 30초이며, 요금제의 업데이트 간격보다 짧을 수 없습니다.
- 상태: 활성, 일시 중지(직접 멈췄거나 요금제가 허용하는 커넥터 수가 줄어서), 오류(조회가 5번 연속 실패, 계속 재시도), 유효하지 않음(제공업체가 자격 증명을 거부, 교체할 때까지). 일시 중지되었거나 유효하지 않은 Traccar나 웹훅 커넥터는 보낸 데이터를 거부합니다.
커넥터에서 온 위치에도 근무 규칙이 적용됩니다.
Traccar
Studio에 표시된 URL과 시크릿으로 Traccar 서버 구성 파일 traccar.xml에 다음 줄을 추가하고 Traccar를 다시 시작합니다.
<entry key='forward.enable'>true</entry>
<entry key='forward.url'>https://api.kaleidr.com/live-api/v1/ingest/YOUR_CONNECTOR_ID/traccar</entry>
<entry key='forward.json'>true</entry>
<entry key='forward.header'>X-Kaleidr-Connector-Secret: YOUR_CONNECTOR_SECRET</entry>
Traccar 기기는 고유 ID(외부 ID)나 이름으로 차량과 대조됩니다. Traccar가 유효하지 않다고 표시한 위치는 버려집니다.
웹훅
요청당 최대 100개 지점을 커넥터 시크릿으로 서명해 수집 URL로 보냅니다.
import { createHmac } from 'node:crypto';
const body = JSON.stringify({
positions: [
{ vehicle: 'TRUCK-1', lat: 40.7411, lng: -73.9897, heading: 90, speed: 8.3, accuracy: 12,
recorded_at: '2026-10-22T15:04:05Z' },
],
});
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.KALEIDR_CONNECTOR_SECRET).update(`${t}.${body}`).digest('hex');
await fetch('https://api.kaleidr.com/live-api/v1/ingest/YOUR_CONNECTOR_ID/webhook', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Kaleidr-Signature': `t=${t},v1=${v1}` },
body,
});
Kaleidr-Signature는t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>이며, 예약 웹훅과 같은 방식을 반대 방향으로 사용합니다.t는 Kaleidr 시계와 5분 이내여야 하며, 서명은 보내는 바이트 그대로에 대해 계산해야 합니다.vehicle은 연결 기준에 따른 차량의 외부 ID 또는 이름입니다.speed는 초당 미터,accuracy는 미터,recorded_at은 RFC 3339 또는 1970년 이후 밀리초입니다.- 서명이 잘못되면 401
signature_invalid로 거부됩니다.
근무
근무는 차량을 표시해도 되는 시간입니다. 차량마다 열린 근무는 최대 하나이며, 최대 16시간 동안 지속됩니다. 근무는 다음 네 가지 방식 중 하나로 열리고 닫힙니다.
| 시작 방식 | 종료 |
|---|---|
| 운전자 모드의 근무 시작 | 근무 종료 또는 16시간 후 |
| 체크인 | 정류장 시간대가 끝난 뒤 30분, 오늘 영업 종료, 또는 16시간 후 |
| Studio에서 차량의 근무 시작 | Studio의 근무 종료 또는 16시간 후 |
| 근무 방식가 예정 시간인 플릿에서 차량의 근무 시간 | 그 시간의 끝 |
- 근무 외에는 아무것도 게시하거나 보관하지 않습니다. 어떤 근무에도 속하지 않는 시각에 기록된 위치는 도착하는 즉시 버려집니다. 사용량 섹션을 위해 버린 위치의 개수만 보관합니다.
- 근무를 끝내면 다음 새로 고침 때 차량이 지도에서 사라집니다.
- 커넥터와 트래커는 항상 보고하므로 근무가 기준이 됩니다. 수동 플릿에서는 운전자, 체크인, Studio 중 하나가 연 근무가 열려 있는 동안에만 위치가 통과합니다. 예정 시간 플릿에서는 차량의 근무 시간이 근무를 열고 닫습니다.
- 기기를 제거하면 그 기기가 시작한 근무가 끝납니다.
공개 정밀도
플릿 페이지의 개인정보 및 표시에서 방문자에게 차량을 얼마나 정밀하게 보여 줄지 정합니다.
| 공개 정밀도 | 방문자에게 보이는 것 | 방향과 속도 |
|---|---|---|
| 정확 | 약 1미터 단위의 위치 | 표시 |
| 거리, 약 100m(기본값) | 약 100미터 단위로 반올림한 위치 | 표시 |
| 지역, 약 1km | 약 1킬로미터 단위로 반올림한 위치 | 숨김 |
- 정류장에 체크인한 차량은 정류장 자체의 위치에 표시됩니다.
- 오래됨 표시 기준(30~900초, 기본값 120): 이보다 오래 보고가 없는 차량에는 5분 전에 확인됨이 표시됩니다.
- 숨김 기준(60~3,600초, 기본값 900): 이보다 오래 보고가 없는 차량은 표시되지 않습니다.
- 방문자는 각 차량의 이름, 종류, 색상, 설명, 상태, 반올림한 위치, 마지막 보고 이후 경과 시간과, 지역, 약 1km 정밀도가 아닐 때의 방향과 속도만 봅니다. 기기, 외부 ID, 기록은 절대 게시되지 않습니다.
기록과 보관
기록에서 각 차량의 하루 이동 경로를 최대 정밀도로 볼 수 있습니다. 기록은 30초마다(요금제의 업데이트 간격이 더 길면 그 간격마다) 최대 한 지점을 보관하며, 마지막으로 보관한 지점에서 200미터 이상 떨어진 지점도 보관합니다. 지점은 요금제의 기록 일수가 지나면 삭제되며, 90일을 넘겨 보관되지 않습니다.
- 기록 지우기(소유자와 관리자)는 차량의 모든 위치와 끝난 근무를 한 번에 삭제합니다.
- 차량이나 플릿을 삭제하면 그 기록도 함께 삭제됩니다. 기기 연결을 해제해도 차량 기록은 남습니다.
- 기록 일수가 더 짧은 요금제에서는 다음 일일 정리 때 초과한 기록이 삭제됩니다.
운전자는 Kaleidr 계정이 아닙니다. 여기에 서는 직접 입력한 기기 이름 외에 사람을 식별하는 정보가 없습니다.
도착 시간 추정
실시간 레이아웃은 차량이 다음 정류장까지, 또는 **나한테 오려면 얼마나?**라고 묻는 방문자에게까지 얼마나 걸릴지 보여 줍니다. 이런 시간은 모두 예상입니다.
- 도로 거리와 일반적인 속도로 계산합니다. 교통 상황은 포함되지 않으며, 차량의 실제 경로는 다를 수 있습니다.
- 방문자에게 보이는 위치, 즉 플릿의 공개 정밀도에 따른 위치에서 출발합니다.
- 약 12분처럼 소요 시간으로 표시하며, 도착 시각으로는 표시하지 않습니다. 도로 경로가 없으면 예상 없음입니다.
- 방문자의 위치는 이 추정에만 쓰이며, 저장하거나 기록하지 않습니다.
- 도로 경로는 OpenStreetMap 데이터로 만들며, © OpenStreetMap contributors, ODbL에 따릅니다.
추정은 방문자 한 명당 분당 20회, 지도 하나당 하루 2,000회로 제한됩니다. Kaleidr AI 사용량에는 포함되지 않습니다.
Kaleidr 지도 전용
실시간 차량은 Kaleidr 자체 베이스맵을 사용하는 지도에 그려집니다. 모든 임베드 viewer와 Studio입니다. Kaleidr Map은 다른 제 공업체의 지도를 표시하는 동안에는 플릿의 차량을 그리지 않습니다. 차량 위치는 외부 지도 제공업체로 전송되지 않습니다.
한도
| 한도 | Free | Pro | Enterprise |
|---|---|---|---|
| 조직 전체의 활성 차량 | 2 | 25 | 계약에서 정함 |
| 위치 기록 일수 | 1 | 30 | 90 |
| 차량 지점 사이의 최단 간격 | 30초 | 10초 | 5초 |
| 커넥터 | 없음 | 3 | 계약에서 정함 |
플릿 하나에는 최대 500대의 차량이 들어갑니다. 한도는 새 작업만 막습니다. 한도를 넘은 조직은 가진 것을 유지하지만, 요금제 일수를 넘는 기록과 요금제를 넘는 커넥터(일시 중지됨)는 예외입니다.
플릿 페이지의 사용량에는 오늘의 집계가 표시됩니다. 받아들인 위치, 버린 위치와 그 이유, 방문자 조회 수, 추정 횟수입니다.