엔드포인트
모두 GET이며 JSON을 반환하고, 키가 필요 없습니다.
| 엔드포인트 | 반환 내용 |
|---|---|
| /api/v1/market | 지정한 스코프의 랭킹 한 페이지와 스냅샷 메타데이터 |
| /api/v1/cards/<id> | id로 카드 한 장. 등재되지 않았으면 404와 오류 본문 |
쿼리 파라미터
잘못된 값은 기본값으로 조용히 되돌리지 않고 HTTP 400을 반환합니다.
| 파라미터 | 허용 값 | 비고 |
|---|---|---|
| scope | all, pokemon, one-piece, watchlist | 그 외의 값은 400 |
| page | 양의 정수 | 숫자가 아니거나 0이면 400 |
| pageSize | 양의 정수 | 서버 상한으로 제한됨 |
응답 필드
마켓 응답은 카드 목록을 스냅샷 정체성과 함께 감싸므로, 저장해 둔 응답도 언제나 그것을 만든 빌드까지 되짚을 수 있습니다.
| 필드 | 의미 |
|---|---|
| generation | 응답이 나온 스냅샷 빌드의 식별자 |
| generatedAt | 스냅샷이 생성된 시각 |
| effectiveAt | 수치가 나타내는 날짜 |
| coverage | 표방한 범위 대비 스냅샷의 충족도 |
| count | 이 응답에 담긴 카드 수 |
| cards | 순위가 매겨진 카드. 각각 가격·개체수·시가총액 포함 |
요청 예시
포켓몬 스코프의 첫 페이지를 가져오기:
curl -s "https://cardzmarketcap.com/api/v1/market?scope=pokemon&page=1"응답은 엣지에서 짧게 캐시됩니다. 어느 날짜의 수치인지는 응답 시각이 아니라 effectiveAt 필드로 판단하세요.
갱신 주기
새 스냅샷은 매일 공개되며 API는 현재 스냅샷을 제공합니다. 과거 generation은 이 엔드포인트로 제공되지 않습니다.
응답을 저장한다면 generation과 effectiveAt도 함께 저장하세요. generation이 다른 두 수치는 날짜 없이는 비교할 수 없습니다.
공정 이용
API는 공개이고 인증이 없으므로 요청 빈도를 상식적인 수준으로 유지해 주세요. 한 페이지를 읽고 캐시하며, 데이터가 바뀌는 속도보다 빠르게 폴링하지 마세요. 스냅샷은 하루에 한 번만 움직입니다.
과도한 자동 트래픽은 속도 제한 대상이 될 수 있습니다. 대량 접근이 필요하면 스크래핑 대신 문의해 주세요.
출처 표시와 라이선스
수치는 CC BY 4.0(https://creativecommons.org/licenses/by/4.0/)에 따라 인용하고 다시 게재할 수 있습니다. CardZ Marketcap을 출처로 밝히고 인용한 페이지 또는 엔드포인트로 링크해 주세요.
시가총액은 매일 갱신될 때마다 다시 계산되므로, 출처 표기에는 해당 수치의 기준일을 반드시 함께 적어야 합니다.
출처 표기
CardZ Marketcap, https://cardzmarketcap.com, 데이터 기준일 2026-08-28
기계 판독 가능 파일
크롤러, 에이전트, 언어 모델용:
- /llms.txt — 사이트와 주요 페이지의 짧은 설명
- /llms-full.txt — 산출 방법 요약을 포함한 확장판
- /sitemap.xml — 색인 대상 전체 페이지
CardZ Marketcap은 트레이딩 카드 가격 지수입니다. 암호화폐도, 토큰도, 상장 기업도 아닙니다. 티커가 존재하지 않으며 CARDS라는 이름의 암호자산과도 무관합니다.
