본문으로 건너뛰기

[부록] 대시보드 API 사용법 안내

이 문서는 대시보드 API 소개의 실전 구현 가이드입니다. 실제 Python 코드 예제와 API 호출 방법을 다룹니다.

사전 준비​

  • 대시보드 API 소개 문서를 먼저 읽어보세요
  • Python 3.7+ 및 requests 라이브러리 설치 필요
  • mAsh 계정 및 대시보드 접근 권한 필요

대시보드 아이디 확인하기​

API를 호출하려면 먼저 대시보드의 고유 식별자(Dashboard UID)를 확인해야 합니다.

확인 방법:

  1. 매쉬보드에 로그인합니다.
  2. 대시보드 목록에서 데이터를 불러올 대시보드를 클릭합니다.
  3. 브라우저 상단 URL을 확인하면 /dashboards/ 다음에 대시보드 아이디가 표시됩니다.

예시:

https://app.mash-board.io/dashboards/9e59e9a9-273c-4f62-82b8-61e3b24742b7
                                      ↑ 이 부분이 dashboard_uid입니다

대시보드 데이터 조회 요청​

기본 사용법​

import requests

# 1. 인증 토큰 발급
email = "user@example.com"
password = "password123"

response = requests.post(
    "https://api.mash-board.io/api/token/",
    headers={"Content-Type": "application/json"},
    json={"email": email, "password": password}
)

access_token = response.json()["access"]

# 2. 대시보드 데이터 조회
dashboard_uid = "9e59e9a9-273c-4f62-82b8-61e3b24742b7"
start_date = "2024-01-01"
end_date = "2024-01-31"

response = requests.get(
    f"https://api.mash-board.io/dashboards/{dashboard_uid}/data",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    },
    params={
        "start_date": start_date,
        "end_date": end_date,
        "output_type": "JSON"  # 또는 "RAW_JSON"
    }
)

dashboard_data = response.json()

필수 파라미터​

파라미터타입설명
dashboard_uidstring (path)대시보드의 고유 식별자
start_datestring (query)조회 시작 날짜 (형식: YYYY-MM-DD)
end_datestring (query)조회 종료 날짜 (형식: YYYY-MM-DD)
output_typestring (query)결과 데이터 형식 (JSON 또는 RAW_JSON)

output_type 차이​

  • JSON: 매장과 구역 이름이 포매팅된 읽기 편한 데이터
  • RAW_JSON: 매장과 구역 ID가 포함된 원본 데이터 (프로그래밍 처리에 적합)

응답 데이터 구조​

{
  "dashboard_uid": "9e59e9a9-273c-4f62-82b8-61e3b24742b7",
  "dashboard_name": "매장 운영 대시보드",
  "is_all_data_available": true,
  "missing_data": {},
  "owner": {
    "uid": "user-uuid",
    "name": "홍길동",
    "email": "user@example.com"
  },
  "board_uid": "board-uuid",
  "board_name": "본사 보드",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-31T23:59:59Z",
  "widgets": {
    "widget-1": {
      "widget_uid": "widget-uuid-1",
      "name": "방문객 수",
      "data": {
        "records": [
          {
            "date": "2024-01-01",
            "visitors": 1234,
            "place_name": "강남점"
          },
          {
            "date": "2024-01-02",
            "visitors": 1456,
            "place_name": "강남점"
          }
        ],
        "metadata": {
          "date": {
            "key": "date",
            "label": "날짜",
            "description": "데이터 수집 날짜"
          },
          "visitors": {
            "key": "visitors",
            "label": "방문객 수",
            "description": "일일 방문객 수"
          },
          "place_name": {
            "key": "place_name",
            "label": "매장명",
            "description": "매장 이름"
          }
        }
      }
    }
  }
}

주요 필드 설명​

대시보드 정보​

  • dashboard_uid: 대시보드 고유 식별자
  • dashboard_name: 대시보드 이름
  • is_all_data_available: 모든 매장 데이터가 정상적으로 로드되었는지 여부
  • missing_data: 업데이트가 완료되지 않은 매장과 일자 목록

위젯 데이터 (widgets)​

각 위젯은 다음 구조를 가집니다:

  • records: 실제 데이터 레코드 배열

    • 각 레코드는 키-값 쌍의 객체
    • 키 이름은 metadata에서 확인 가능

  • metadata: 레코드 키에 대한 메타데이터

    • key: 레코드의 실제 키 이름
    • label: 사용자 친화적 표시 이름
    • description: 키에 대한 설명

주의사항​

인증 토큰 관리​

  • 발급된 access_token은 5분 동안 유효합니다.
  • 토큰 만료 시 refresh_token을 사용하여 새 토큰을 발급받으세요.
  • 자세한 내용은 1. 인증 토큰 발급하기를 참고하세요.

날짜 범위​

  • start_date와 end_date는 반드시 YYYY-MM-DD 형식이어야 합니다.
  • 너무 긴 기간을 요청하면 응답 시간이 길어질 수 있습니다.
  • 권장: 한 번에 최대 3개월 이내의 데이터 요청

데이터 가용성​

  • is_all_data_available 필드를 확인하여 데이터 완전성을 체크하세요.
  • missing_data에 누락된 매장과 날짜가 표시됩니다.

응답 크기​

  • 대시보드에 많은 위젯이 있거나 긴 기간의 데이터를 요청하면 응답 크기가 클 수 있습니다.
  • 필요한 경우 날짜 범위를 나누어 여러 번 요청하는 것을 권장합니다.

API 명세 상세 정보​

더 자세한 API 스펙은 아래 링크를 참고하세요:

API 명세 바로가기

관련 문서​