아티스트
1 크레딧/v1/spotify/artist아티스트 하나를 반환합니다. id, 이름, 팔로워 수, 월간 청취자 수, 장르, 관련 아티스트가 포함됩니다. Spotify 아티스트 URL 또는 id로 지정합니다.
id or url
Spotify API공개 Spotify 데이터 API
SocialCrawl API 키로 공개 Spotify 아티스트, 트랙, 앨범, 플레이리스트, 팟캐스트를 구조화 JSON으로 가져옵니다. Author, Post 스키마는 다른 플랫폼과 같습니다. 호출은 크레딧으로 과금됩니다.
/v1/spotify
활성 엔드포인트는 6개입니다.
- GET /v1/spotify/artist
- GET /v1/spotify/track
- GET /v1/spotify/album
- GET /v1/spotify/search
- GET /v1/spotify/podcast
- GET /v1/spotify/podcast/episodes
Spotify 엔드포인트
공개 Spotify 읽기 엔드포인트는 6개입니다. 아티스트, 트랙, 앨범, 플레이리스트 검색, 팟캐스트 쇼, 팟캐스트 회차를 제공합니다. 데이터 API만 지원하며 재생 제어, 비공개 라이브러리, 클라이언트 Spotify 사용자 OAuth는 포함되지 않습니다.
트랙
1 크레딧/v1/spotify/track트랙 하나를 반환합니다. 곡명, 참여 아티스트, 앨범과 커버 아트, 재생 시간, 재생 횟수, 공유 링크가 포함됩니다.
id or url
앨범
1 크레딧/v1/spotify/album앨범 하나를 반환합니다. 제목, 아티스트, 발매일, 커버 아트, 저작권 정보, 수록곡이 포함됩니다.
id or url
플레이리스트 검색
1 크레딧/v1/spotify/search키워드와 맞는 플레이리스트를 반환합니다. 현재는 플레이리스트만 나오며 트랙, 아티스트, 앨범, 팟캐스트는 검색 결과에 포함되지 않습니다.
query
팟캐스트 쇼
1 크레딧/v1/spotify/podcast팟캐스트 쇼 하나를 반환합니다. id, 이름, 설명, 커버 아트가 포함됩니다. Spotify /show/ URL 또는 id로 지정합니다.
id or url
팟캐스트 회차
1 크레딧/v1/spotify/podcast/episodes팟캐스트 하나의 회차를 반환합니다. 제목, 공개일, 재생 시간, 커버 아트, 짧은 미리듣기 오디오 URL이 포함됩니다. 직전 응답의 커서로 페이지를 넘깁니다.
id or url, cursor
Spotify API6개 엔드포인트 지원
문서 보기Spotify 아티스트 정보를 돌려줍니다. id와 이름, 팔로워 수, 월간 청취자 수, 장르, 관련 아티스트가 담깁니다.
아티스트 id나 URL이 있고 곡이나 앨범이 아니라 아티스트 자체를 볼 때 사용하세요.
1크레딧
GET/v1/spotify/artist?url=https%3A%2F%2Fopen.spotify.com%2Fartist%2F0cGUm45nv7Z6M6qdXYQGTX
$ curl https://www.socialcrawl.dev/v1/spotify/artist?url=https%3A%2F%2Fopen.spotify.com%2Fartist%2F0cGUm45nv7Z6M6qdXYQGTX \
-H "x-api-key: sc_YOUR_API_KEY"대기 중
// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다Spotify API 동작
Spotify도 다른 SocialCrawl 소셜 엔드포인트와 같습니다. API 키로 GET /v1/spotify/… 를 호출하고 캐시 미스에 크레딧을 쓰며 동일한 JSON 봉투를 받습니다. 클라이언트 Spotify 개발자 앱과 별도 SDK는 없습니다.
호출 인증
x-api-key 헤더에 키를 보냅니다. 앱에 Spotify OAuth 흐름은 필요 없습니다. 카탈로그 전 구간에 같은 키를 사용합니다.
GET과 쿼리 파라미터
Spotify 라우트는 모두 GET입니다. url, id, query, cursor를 쿼리로 전달합니다. 과금 전에 형식을 검증합니다.
크레딧 과금
Spotify 읽기는 라이브 미스당 1 크레딧입니다. 캐시 히트는 0 크레딧입니다. 빈 응답과 하드 실패는 환불됩니다.
JSON 봉투
응답 형태는 success, data, credits_used, credits_remaining, request_id, cached로 동일합니다. 회차 목록은 더 있을 때 페이지네이션을 가집니다.
연동 순서
대부분 제품은 아티스트나 쇼를 확인한 뒤 카탈로그 항목을 가져오고 필요한 트랙이나 회차만 깊게 읽습니다.
01아티스트 또는 쇼
GET /v1/spotify/search?query=…Author 형태 아티스트 또는 팟캐스트입니다. 팔로워, 장르, 커버가 포함됩니다.
카탈로그 목록 전에 URL 또는 id를 한 번 확정합니다.
02트랙 또는 앨범
GET /v1/spotify/podcast?url=…재생 수와 아트가 있는 Post 형태 트랙 또는 앨범입니다.
목록 행만으로 부족할 때 곡 하나 또는 음반 전체를 엽니다.
03플레이리스트 검색
GET /v1/spotify/podcast/episodes?url=…키워드에 맞는 플레이리스트 히트입니다.
트랙 id 없이 에디토리얼·커뮤니티 플레이리스트를 찾습니다.
04팟캐스트 회차
GET /v1/spotify/track?url=…미리듣기 URL과 재생 시간이 있는 회차 목록입니다.
쇼 신원을 안 뒤 회차를 페이지로 넘깁니다.
요청
GET /v1/spotify/artist
?url=https://open.spotify.com/artist/…
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
# podcast chain
GET /v1/spotify/podcast?url=https://open.spotify.com/show/…
GET /v1/spotify/podcast/episodes?url=…응답 봉투
{
"success": true,
"data": {
"id": "0TnOYISbd1XYRBk9myaseg",
"username": "artist_slug",
"display_name": "Example Artist",
"followers": 1200000,
"url": "https://open.spotify.com/artist/…",
"ext": {
"genres": ["pop"],
"popularity": 82
}
},
"credits_used": 1,
"credits_remaining": 9999,
"request_id": "req_…",
"cached": false
}data 형태
필드 이름은 SocialCrawl 나머지 플랫폼과 같습니다. 아티스트와 쇼는 Author, 트랙·앨범·회차는 Post 리프로 매핑됩니다.
Authorartist, podcast
id, username/display_name, avatar_url, bio, followers, url, ext(월간 청취자, 장르, 관련 아티스트)
PostList / Posttrack, album
트랙·앨범·회차 Post: id, url, content, engagement(재생), author/artists, published_at, media ext
Playlist searchsearch, podcast/episodes
query 플레이리스트 히트: id, name, description, cover, 공개 시 owner 필드
Episode listenvelope fields
items[]: 제목, 공개일, 재생 시간, 커버, 미리듣기 오디오 URL. 더 있으면 cursor
게이트웨이
다른 /v1 플랫폼 엔드포인트와 같은 요청 수명주기입니다. Spotify 전용 사이드카가 아닙니다.
- 01
엣지 수신
Next.js catch-all이 Hono 소셜 API로 들어갑니다. request_id를 발급하고 키를 인증한 뒤 분당 600회 한도와 키당 동시 50건을 적용합니다.
- 02
검증 후 차감
레지스트리에서 spotify/artist 등을 찾습니다. 필수 파라미터와 URL 형식 검증이 먼저입니다. 잘못된 입력은 400이며 과금하지 않습니다. 유효 호출은 업스트림 전에 1 크레딧을 원자적으로 차감합니다.
- 03
캐시 또는 조회
platform, resource, params로 캐시 키를 만듭니다. 히트면 즉시 반환하고 credits_used는 0입니다. 미스면 Spotify 라우트용 소셜 읽기 업스트림을 호출합니다. 5xx와 네트워크 오류는 재시도하며 불건전 시 서킷 브레이커가 동작합니다.
- 04
정규화 후 반환
업스트림 JSON을 Author, Post, PostList 또는 라우트 아키타입으로 매핑합니다. Zod로 검증한 뒤 성공 봉투로 감싸 빌링 감사에 남깁니다.
과금 규칙
- 표준 라이브 미스는 1 크레딧입니다.
- artist, track, album, search, podcast, episodes는 모두 1 크레딧입니다.
- 이 플랫폼에는 advanced 티어가 없습니다.
- 이 플랫폼에는 premium 티어가 없습니다.
- 캐시 히트는 0 크레딧입니다.
- 빈 응답과 하드 실패는 자동 환불됩니다.
- 잘못된 파라미터는 400이며 과금하지 않습니다.
- 잔액이 없으면 402이며 과금하지 않습니다.
- 비활성 라우트는 503이며 과금하지 않습니다.
데이터 수집
Spotify는 공개 읽기 음악·팟캐스트 카탈로그 데이터입니다. SocialCrawl 스키마로 정규화하므로 두 번째 OAuth를 코드에 넣을 필요가 없습니다.
API에서의 Spotify
공개 아티스트, 트랙, 앨범, 플레이리스트 검색 히트, 팟캐스트 쇼, 회차를 읽기 전용으로 제공합니다. 리서치, 모니터링, 제품 작업에 사용합니다. 비공개 라이브러리와 재생 제어는 없습니다.
업스트림
하나의 게이트웨이 뒤에서 소셜 읽기 업스트림을 호출합니다. open.spotify.com URL 또는 id를 보내면 클라이언트 Spotify 앱 없이 가져와 정규화합니다.
응답 형태
success, data, credits_used, request_id, cached를 담은 통합 JSON 봉투를 반환합니다. 아티스트와 쇼는 Author로, 트랙·앨범·회차는 아키타입이 맞는 범위에서 Post 리프로 정규화됩니다.
미제공 항목
쓰기 엔드포인트는 없습니다. 사용자 라이브러리와 플레이리스트 변경은 없습니다. 검색은 현재 플레이리스트만 반환합니다. 활성 목록은 레지스트리 문서를 따릅니다.
필드 매핑
artist / show card→ author.*아티스트 이름, 팔로워, 월간 청취자, 장르
track / album / episode→ post.* + ext.*트랙·앨범 제목, 아티스트, 커버, 재생 수
search playlist hits→ PostList items[]팟캐스트 회차 제목, 재생 시간, 미리듣기 오디오 URL
이 API의 활용 분야
이 API가 가장 많이 사용되는 작업입니다.
6active Spotify endpoints in the registry
1 credit라이브 미스당 고정 1 크레딧
카탈로그 보강과 팟캐스트 회차 모니터링
호출은 아티스트·트랙 상세, 앨범 조회, 플레이리스트 키워드 검색, 팟캐스트에서 회차로 이어지는 체인에 집중됩니다. 공유 스키마의 공개 Spotify 카탈로그 읽기와 크레딧 과금입니다. 이 공개 표면에는 클라이언트 Spotify 개발자 앱이 필요 없습니다.
아티스트, 트랙, 앨범, 쇼 호출은 라이브 미스 시 보통 수 초입니다. 회차 목록과 검색은 콜드 캐시에서 조금 더 걸릴 수 있습니다.
Spotify API 활용 사례
Spotify 데이터가 가장 많이 쓰이는 작업입니다. 각 항목에서 엔드포인트 순서와 과금 방식을 확인합니다.
활용 사례
이 데이터를 활용하는 대표적인 방식과 각 방식에서 주로 사용하는 스택입니다.
카탈로그 보강
Python, 워커, CMS 적재아티스트·트랙 URL을 구조화 카드로 해석합니다. 팔로워, 재생 수, 아트로 내부 카탈로그를 채웁니다.
팟캐스트 모니터
Node, cron, Slack 봇고정 쇼 집합에 podcast와 podcast/episodes를 폴링합니다. 새 회차가 공개되면 알립니다.
백엔드 제품 잡
Go, 워커, Explorer아티스트, 트랙, 앨범 체인 또는 키워드 플레이리스트 검색을 파이프라인에 연결합니다. 카탈로그와 같은 API 키를 사용합니다.
호출 예시
Spotify 라우트는 라이브 호출당 1 크레딧입니다. 캐시 히트는 무료입니다.
curl "https://www.socialcrawl.dev/v1/spotify/artist?url=https://open.spotify.com/artist/0TnOYISbd1XYRBk9myaseg" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/spotify/search?query=true+crime" \
-H "x-api-key: sc_your_api_key_here"엔드포인트
Spotify API는 어떤 데이터를 돌려주나요
모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.
비교
SocialCrawl과 공식 Spotify Web API, 뭐가 다른가요?
같은 Spotify 데이터를 받는 두 가지 방법을 나란히 비교했어요. 인증부터 비용까지 한눈에 확인해 보세요.
| 항목 | SocialCrawl | 공식 Spotify Web API |
|---|---|---|
| 인증 방식 | x-api-key 헤더 하나면 돼요 | OAuth 2.0 클라이언트 크리덴셜과 토큰 갱신이 필요해요 |
| 시작 절차 | 앱 등록 없이 가입 후 바로 호출할 수 있어요 | 첫 호출 전에 개발자 대시보드에서 앱을 등록해야 해요 |
| 레이트 리밋 | 크레딧 잔액만 신경 쓰면 돼요 | 앱 단위 레이트 리밋과 429 재시도를 직접 처리해야 해요 |
| 응답 스키마 | 68개 플랫폼이 같은 통합 JSON 스키마를 써요 | 문서화는 잘 돼 있지만 Spotify 전용 객체예요 |
| 요금 | 호출당 1 크레딧, 가입 시 100 크레딧 무료예요 | 카탈로그 메타데이터는 레이트 리밋 안에서 무료예요 |
| 데이터 범위 | 아티스트, 트랙, 앨범, 팟캐스트, 에피소드, 검색까지 커버해요 | 공식 카탈로그 전체와 사용자 동의 데이터까지 다뤄요 |
| 유지보수 | 통합 하나로 Spotify와 다른 67개 플랫폼을 함께 써요 | Spotify만을 위한 SDK와 토큰 로직을 따로 관리해야 해요 |
인증 방식
SocialCrawl
x-api-key 헤더 하나면 돼요
공식 Spotify Web API
OAuth 2.0 클라이언트 크리덴셜과 토큰 갱신이 필요해요
시작 절차
SocialCrawl
앱 등록 없이 가입 후 바로 호출할 수 있어요
공식 Spotify Web API
첫 호출 전에 개발자 대시보드에서 앱을 등록해야 해요
레이트 리밋
SocialCrawl
크레딧 잔액만 신경 쓰면 돼요
공식 Spotify Web API
앱 단위 레이트 리밋과 429 재시도를 직접 처리해야 해요
응답 스키마
SocialCrawl
68개 플랫폼이 같은 통합 JSON 스키마를 써요
공식 Spotify Web API
문서화는 잘 돼 있지만 Spotify 전용 객체예요
요금
SocialCrawl
호출당 1 크레딧, 가입 시 100 크레딧 무료예요
공식 Spotify Web API
카탈로그 메타데이터는 레이트 리밋 안에서 무료예요
데이터 범위
SocialCrawl
아티스트, 트랙, 앨범, 팟캐스트, 에피소드, 검색까지 커버해요
공식 Spotify Web API
공식 카탈로그 전체와 사용자 동의 데이터까지 다뤄요
유지보수
SocialCrawl
통합 하나로 Spotify와 다른 67개 플랫폼을 함께 써요
공식 Spotify Web API
Spotify만을 위한 SDK와 토큰 로직을 따로 관리해야 해요
자주 묻는 질문
자주 묻는 질문
API, 요금제, 기능에 대한 질문과 답변입니다.
문의하기Spotify 데이터는 어떻게 가져오나요?
x-api-key 헤더와 함께 GET 요청 한 번이면 돼요. 아티스트, 트랙, 앨범, 검색, 팟캐스트, 에피소드 목록까지 6개 엔드포인트가 모두 같은 방식으로 동작하고, 응답은 통합 스키마 JSON으로 정리돼서 와요.
Spotify 공식 API처럼 OAuth 인증이 필요한가요?
아니요, 앱 등록이나 토큰 갱신 없이 API 키 하나면 충분해요. 공식 Web API의 OAuth 플로우와 레이트 리밋 관리는 SocialCrawl이 대신 처리해 드려요.
어떤 Spotify 데이터를 받아볼 수 있나요?
아티스트의 팔로워 수·장르·연관 아티스트, 트랙과 앨범 메타데이터, 팟캐스트 정보와 에피소드 목록을 받아볼 수 있어요. 트랙·아티스트·앨범·팟캐스트·오디오북을 아우르는 키워드 검색도 함께 지원해요.
Spotify API 요금은 어떻게 되나요?
모든 Spotify 엔드포인트는 요청당 1 크레딧이에요(스탠다드 티어). 새 계정에는 100 크레딧이 무료로 제공돼서 신용카드 없이 약 100번 호출해 볼 수 있어요.
Spotify 레이트 리밋은 어떻게 처리되나요?
레이트 리밋과 재시도 처리는 SocialCrawl이 알아서 챙겨 드려요. 같은 리소스를 다시 요청하면 캐시에서 더 빠르게 받아볼 수 있고, 신경 쓸 것은 크레딧 잔액 하나뿐이에요.
프로덕션 환경에서 써도 되나요?
네, 안정적인 응답 속도와 통합 스키마를 제공해요. Spotify 응답 형식이 바뀌어도 스키마가 깨지지 않도록 SocialCrawl이 챙겨 드려서 안심하고 붙이실 수 있어요.
가장 좋은 Spotify 스크래퍼 API는 무엇인가요?
OAuth 없이 카탈로그 메타데이터만 필요하다면 SocialCrawl이 가장 간단해요. 아티스트, 트랙, 앨범, 검색, 팟캐스트, 에피소드를 비롯해 6개 엔드포인트를 호출당 1 크레딧으로 쓸 수 있고, 신용카드 없이 100 크레딧이 무료예요. 공식 Spotify Web API는 무료에 범위도 넓지만 앱 등록과 OAuth 토큰 갱신이 필요해요.
Spotify 데이터 스크래핑, 법적으로 괜찮을까요?
SocialCrawl은 누구나 볼 수 있는 공개 Spotify 데이터만 돌려드리고, 로그인이 필요한 비공개 콘텐츠에는 접근하지 않아요. 다만 실제 적법성은 활용 목적과 국가별 법률에 따라 달라져요. Spotify 이용약관과 GDPR·CCPA 같은 개인정보 보호 법규를 지키는 책임은 이용자에게 있어요. 이 답변은 일반 안내일 뿐, 법률 자문은 아니에요.
AI에게 SocialCrawl을 물어보세요