Search

[mAsh API] API로 데이터 조회하기

API를 통해 매쉬 데이터를 자유롭게 조회할 수 있습니다.
API 키 준비하기
API를 호출하려면 API 키가 필요합니다. [환경설정 - 개인 설정 - API 키]에서 「REST API」 권한을 포함해 키를 만들어 주세요. 만드는 방법은 「1. 계정 생성 및 계정 관리」의 API 키 절을 참고해 주세요.
발급한 키는 요청 헤더 X-MASH-API-KEY 에 넣어 보냅니다.
AI 에이전트로 조회하기
코드를 쓰지 않고 AI 에이전트(Claude, Cursor 등)에 mAsh를 연결해 데이터를 조회할 수도 있습니다. 「6. 대화형 AI 분석 기능」의 AI 에이전트 연결 절을 참고해 주세요. 연결 방법을 더 자세히 정리한 안내는 MCP 가이드에 있습니다.
매쉬 API 명세서는 다음 링크를 통해 확인하실 수 있습니다.
매쉬 API는 크게 네 가지 분류로 구성되어 있으며, 해당 구조를 간단히 표로 정리하면 다음과 같습니다.
API 조회 결과 샘플을 통해 “방문객 행동 이벤트” 데이터의 구조를 더 자세히 설명드리도록 하겠습니다.
다음은 동선 추적이 완료된 개별 방문객의 데이터인 "매장 방문객 행동" API의 조회 결과 샘플입니다.
•
"results" 하위의 각 항목이 개별 방문객의 정보를 담고 있습니다.
•
다음은 세부 attribute에 대한 설명입니다.
◦
id: 해당 방문객의 고유 ID입니다.
◦
age: 해당 방문객의 연령대입니다.
◦
gender: 해당 방문객의 성별입니다.
◦
place_start_time: 매장 입장 시각입니다.
◦
place_residence_time: 매장 입장 시각부터 마지막 이벤트 발생 시각까지의 차이로 계산한 초 단위의 매장 총 체류 시간입니다.
◦
place_id: 매장의 고유 ID입니다.
◦
line_ids: 해당 방문객이 매장 내에서 통과한 라인들의 목록입니다. "입/퇴장(라인) 목록" API를 통해 라인의 명칭 등 정보를 조회할 수 있습니다. (하단 첨부 이미지 참고)
◦
zone_ids: 해당 방문객이 매장 내에서 방문/체류한 구역(상품 매대)들의 목록입니다. "구역 목록" API를 통해 구역의 명칭 등 정보를 조회할 수 있습니다.
◦
zone_residence_times: 해당 방문객이 매장 내에서 방문/체류한 구역(상품 매대)에 대한 체류 시간들의 목록입니다. zone_ids의 항목들과 대응됩니다.
다음은 “입/퇴장(라인) 목록” API의 조회 결과 샘플입니다.
•
"results" 하위의 각 항목이 매장 내에 설정된 각 라인의 정보를 담고 있습니다.
•
"매장 방문객 행동" API 조회 결과의 line_ids와 대응됩니다.
E.O.D.