AirTag 데이터 내보내기 및 API
AirTag(에어태그) 위치 데이터 내보내기와 API 연동
TagLogger는 AirTag 기록을 CSV나 JSON으로 내보내고 API를 제공합니다. 데이터가 실제로 운영을 돌리는 ERP, CMMS, TMS, FSM에 바로 들어갑니다.
TagLogger가 내보내는 것
- 연결된 모든 AirTag의 현재 및 과거 위치(위도/경도 + 타임스탬프)
- 타임스탬프가 찍힌 지오펜스 진입 및 이탈 이벤트
- 미이동 자산 보고서: 설정한 기간 동안 움직이지 않은 자산
- 자산 메타데이터: 이름, 색상, 카테고리, 배정된 팀
- 활동 피드: 선택한 기간에 대한 AirTag별 전체 이벤트 로그
- 배터리 부족 상태와 AirTag 보고 주기
내보내기 형식
CSV는 가장 흔한 내보내기 형식으로, Excel, Google Sheets를 비롯해 거의 모든 업무 시스템과 호환됩니다. TagLogger의 CSV 내보내기에는 AirTag별로 타임스탬프, 위도, 경도, 자산 이름, 그리고 해당 행에 연결된 지오펜스 이벤트 열이 포함됩니다.
JSON 내보내기는 지오펜스 메타데이터, 자산 카테고리, 이벤트 유형을 포함한 데이터의 전체 중첩 구조를 보존합니다. JSON은 스크립트, 데이터 웨어하우스, 맞춤 연동에 프로그램으로 직접 적재할 때 유용합니다.
흔한 연동 패턴
- 일일 CSV 스냅샷: 예약 내보내기를 공유 드라이브나 ERP 폴더에 넣어 일괄 대조
- 주간 감사 보고서: 미이동 자산 CSV와 활동 요약을 운영 검토용으로
- 지오펜스 웹훅: 지오펜스 이벤트가 발생하면 TagLogger가 HTTP 웹훅을 보내 FSM이나 TMS 엔드포인트에 게시
- 실시간 API 폴링: 맞춤 대시보드나 모니터링 도구가 일정 주기(보통 1~5분마다)로 위치 데이터를 가져옴
- 이벤트 기반 자동화: 웹훅이 후속 워크플로를 실행(Slack 알림, 티켓 생성, 재고 조정)
연동 대상: ERP, CMMS, TMS, FSM
AirTag 위치 데이터는 네 가지 큰 범주의 운영 소프트웨어에 연결됩니다. 연동 형태는 어디서나 비슷합니다. 자산 레코드의 위치 필드를 일정에 따라 또는 웹훅으로 업데이트하는 것입니다.
ERP: NetSuite, SAP, Oracle, Dynamics
AirTag 위치 기록을 위치 필드가 있는 맞춤 자산 레코드로 가져와, 일일 CSV 가져오기나 API로 업데이트합니다. 흔한 용도: 실제 자산 위치를 ERP에 기록된 위치와 대조.
CMMS: Maximo, eMaint, Fiix, UpKeep
AirTag 위치를 자산 위치 속성에 넣어 예방 정비(PM) 일정을 지원하고(현장을 돌지 않고 정비할 자산을 찾기), 작업 지시의 자산 연결에도 넣어 기술자가 현재 위치로 배차되게 합니다.
TMS / WMS: Oracle TM, SAP TM, Blue Yonder, Manhattan
지오펜스 이벤트를 화물의 상태 업데이트로 게시하고, 트레일러와 컨테이너 위치를 야적장 관리 보고서에 공급합니다.
FSM: ServiceTitan, Housecall Pro, Jobber, FieldEdge
서비스 차량과 공구 키트의 AirTag 위치를 작업 배차 결정에 반영하고, 지오펜스 도착 이벤트를 자동 고객 알림으로 게시합니다.
API 접근 기본 사항
TagLogger API는 웹 UI에 표시되는 것과 같은 데이터에 프로그램으로 접근할 수 있게 합니다. 인증은 API 키 기반이며 워크스페이스 단위로 범위가 정해집니다. 주요 엔드포인트: AirTag 목록 조회, AirTag의 최신 위치 조회, 기간별 AirTag 위치 기록 조회, 지오펜스와 지오펜스 이벤트 목록 조회, 워크스페이스에서 정의한 태그 라벨 읽기.
고빈도 폴링의 경우 대부분의 연동은 나의 찾기(Find My) 네트워크의 실제 업데이트 주기에 맞춰 1~5분 주기로 자리 잡습니다. 그보다 자주 폴링해도 데이터가 늘지 않습니다. 기반이 되는 중계 주기가 병목이기 때문입니다.
이벤트 기반 연동에는 폴링보다 웹훅 구독이 효율적입니다. 지오펜스 진입/이탈 이벤트를 구독하면 관련 이벤트가 발생하는 순간 TagLogger가 귀사의 엔드포인트에 게시합니다.
AirTag API 빠른 시작: SDK를 설치하고 첫 요청 보내기
TagLogger는 AirTag 데이터 API용 SDK를 두 가지 제공합니다. 하나는 TypeScript와 JavaScript용, 하나는 Python용입니다. 하나를 설치하고, 설정 → API 키에서 워크스페이스 키를 만든 뒤, 몇 줄로 태그 목록을 조회하세요. API 빠른 시작이 각 단계를 안내하고, API 레퍼런스에 모든 엔드포인트가 정리되어 있습니다.
- TypeScript 또는 JavaScript: npm install @taglogger/sdk (npm 패키지). Node 18 이상에서 동작하며 자체 타입을 포함합니다.
- Python: pip install taglogger-sdk (PyPI 패키지). Python 3.9 이상에서 다른 의존성 없이 동작하며 taglogger_sdk로 임포트합니다.
- API 키: TAGLOGGER_API_KEY를 read:tags 범위가 있는 워크스페이스 키로 설정하세요. 인증에서 범위와 헤더를 다룹니다.
import os
from taglogger_sdk import TagLoggerClient
client = TagLoggerClient(api_key=os.environ["TAGLOGGER_API_KEY"])
page = client.tags.list(limit=50)
for tag in page["data"]:
print(tag["id"], tag["name"] or "")TypeScript SDK도 같은 형태입니다. new TagLoggerClient({ apiKey }) 다음에 client.tags.list({ limit: 50 })입니다. 두 SDK 모두 위치 기록, 지오펜스, 웹훅, 웹훅 서명 검증도 다룹니다.
흔한 내보내기 및 연동 활용 사례
- 감사 보고서: 내부 또는 외부 감사를 위해 자산 보관 주체와 이동 내역을 보여 주는 월간 또는 분기별 내보내기
- 보험 서류: 손실 청구와 도난 사건을 위한 위치 기록 CSV 내보내기
- 청구 대조: 추적한 자산 위치를 계약된 렌탈 기간이나 서비스 방문과 대조
- 재고 실사 자동화: 정기적인 전체 자산 스냅샷을 재고 관리 시스템으로
- 규정 준수 로그: 규제 요구사항(SOX 자산 통제, HIPAA 기기 추적)을 위한 타임스탬프 위치 기록
- 맞춤 대시보드: AirTag 데이터와 다른 운영 데이터(ERP, CRM, 텔레메트리)를 합친 통합 보기
- 분석 파이프라인: 자산 활용도 분석을 위해 AirTag 기록을 BigQuery/Snowflake/Redshift에 적재
내보내기와 API 접근의 보안 고려사항
AirTag 위치 데이터는 가치가 큽니다. 자산(그리고 종종 사람)이 어디 있고 어디 있었는지 드러내기 때문입니다. 내보내기와 API 데이터에는 적절한 접근 통제를 적용하세요. API 키는 필요한 최소 권한 범위로 제한하세요. API 키는 평문 설정 파일이 아니라 시크릿 관리 도구에 보관하세요. 감사를 위해 API 접근을 기록하세요.
외부(보험 손해사정인, 경찰, 분쟁 중인 고객)와 CSV 내보내기를 공유할 때는 전체 데이터를 통째로 넘기지 말고 필요한 기간과 자산만 공유하세요. TagLogger는 바로 이를 위해 자산별, 기간 한정 내보내기를 지원합니다.
규제 산업(의료, 금융 서비스)의 고객은 TagLogger 내보내기/API 데이터를 최종 시스템에 직접 넣는 대신 규정 준수 플랫폼을 거치게 하는 경우가 많습니다. TagLogger의 내보내기 형식이 지원하는 합리적인 패턴입니다.
내보내기와 API 시작하기
CSV 내보내기부터 시작하세요. 개발 작업이 필요 없고, 어떤 스프레드시트 도구에서도 열리며, 대부분의 감사와 대조 용도를 충족합니다. TagLogger 고객 대부분은 처음 3~6개월은 CSV를 쓰다가 구체적인 자동화 요구가 생겼을 때 비로소 API 연동으로 넘어갑니다.
API 연동이라면 실용적인 첫 목표는 지오펜스 웹훅입니다. 폴링 인프라 없이 이벤트 기반 신호를 주기 때문입니다. 웹훅 엔드포인트와 몇 줄의 로직만으로도 본격적인 맞춤 연동 없이 워크플로의 상당 부분(Slack 알림, 티켓 생성, 상태 업데이트)을 자동화할 수 있습니다.
완전한 ERP/CMMS 연동은 더 큰 프로젝트이며 보통 나중 일입니다. 그때쯤이면 AirTag 추적을 둘러싼 운영 패턴이 잘 파악되어 있어, 연동도 “모든 것을 연결”하기보다 특정 데이터 흐름을 겨냥하게 됩니다.
