Pinterest Board Pins
Pinterest 보드의 핀은 누군가 하나의 아이디어를 중심으로 모아 둔 이미지로, 핀마다 짧은 제목이나 설명, 그 핀을 저장한 계정, 원래 너비와 높이 그대로의 원본 이미지가 있습니다. 보드가 보여 주는 순서대로 한데 모으면 무드보드, 디자인 리서치, 이미지 데이터셋에 바로 쓸 수 있는 시각 자료가 되고, 큐레이션된 컬렉션이 어떻게 바뀌는지 지켜보는 데도 쓰입니다.
Pinterest Board Pins API 주요 기능
- 보드 순서를 지킨 핀행은 보드가 직접 보여 주는 순서를 따르므로, 큐레이터가 배치한 흐름 그대로 컬렉션을 읽을 수 있습니다.
- 원본 이미지와 썸네일media.url 값은 원본 크기 이미지를, media.thumbnail_url 값은 작은 미리보기를 가리키며 모든 파일에 픽셀 단위 너비와 높이가 붙습니다.
- 저장한 계정과 핀 문구author 값은 각 핀을 저장한 계정을 사용자 이름, 표시 이름, 프로필 링크, 아바타와 함께 알려 주고, text 값에는 핀의 제목이나 설명이 담깁니다.
- 핀마다 돌아가는 링크url 값은 핀 id로 만든 핀 페이지 주소이므로, 세트 안의 어떤 이미지든 Pinterest의 원래 위치까지 추적할 수 있습니다.
- 보드당 최대 1,000개 핀results_limit 값은 보드마다 따로 적용되며 기본값은 50, 최대 1,000이고, urls 배열에 여러 보드를 함께 넣을 수 있습니다.
Pinterest Board Pins API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | https://www.pinterest.com/lizmrodgers/moms-night/처럼 /{username}/{board}/ 형식으로 된 Pinterest 보드 링크입니다. |
results_limit | 선택 | 보드마다 반환할 최대 핀 수로 1~1000 사이 정수이며 기본값은 50입니다. |
Pinterest Board Pins API 사용 방법
보드 링크를 보내고 작업을 기다린 뒤 핀을 페이지별로 읽습니다.
- urls 배열에 보드 링크를 넣고, 보드당 50개보다 많은 핀이 필요하면 results_limit 값도 함께 /v1/pinterest/board로 POST합니다.
- 받은 task_id 값으로 GET /v1/tasks/{task_id}를 폴링해 작업이 성공할 때까지 기다립니다.
- results.items에서 핀을 가져오고, has_more 값이 true인 동안 results.next_cursor로 계속 요청합니다.
curl -X POST "https://api.socq.ai/v1/pinterest/board" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/lizmrodgers/moms-night/"],"results_limit":50}'
# 0.5 credits per pin; boards that do not exist return no pins.Pinterest Board Pins API 추천 활용 사례
- 보드 이미지 일괄 다운로드: 보드의 media.url 값을 모두 저장해 원본 파일로 된 로컬 레퍼런스 라이브러리를 만들고, width와 height 값으로 세로 사진과 가로 사진을 나눕니다.
- 설명이 붙은 이미지 데이터셋 구축: 이미지마다 핀의 text 값과 출처 보드를 짝지어 디자인 리서치나 모델 학습용 라벨링 예시를 만듭니다.
- 경쟁사 시즌 보드 모니터링: 같은 보드를 매주 수집하고 지난 실행과 핀 id를 비교해 새로 추가된 핀을 정확히 확인합니다.
- 무드보드 이미지 출처 표기: 이미지 옆에 author.username 값과 핀 url 값을 함께 보관해 발표 자료 속 모든 사진에 출처를 달고 다시 열어 볼 수 있게 합니다.
Pinterest Board Pins API 활용 팁
- 보드 자체의 두 단계 링크를 사용하세요. /{username}/_saved/나 /{username}/pins/ 같은 프로필 탭, 더 깊은 섹션 경로, pin.it 단축 링크는 거부되므로 보드를 열고 주소를 복사하는 것이 안전합니다.
- 먼저 Pinterest User Boards API로 보드의 metrics.pins_count 값을 확인하고 그에 맞춰 results_limit 값을 정하면, 큰 보드가 기본값 50개에서 잘리지 않습니다.
- 그리드와 미리보기에는 thumbnail_url 값을 쓰고 실제로 보관할 이미지만 media.url로 받으세요. 핀이 수백 개인 보드에서 대역폭을 아낄 수 있습니다.
관련 API
Pinterest Board Pins API 외에 Pinterest의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Pinterest Pins API — 공개 핀 URL을 정규화된 콘텐츠, 크리에이터, 미디어, 분류, 타임스탬프, 공개된 지표로 변환합니다.
- Pinterest User Pins API — 프로필 URL에서 공개 핀을 찾으며, 프로필별 결과 수 제한과 정규화된 콘텐츠, 크리에이터, 미디어, 타임스탬프, 공개된 지표를 포함합니다.
- Pinterest Profiles API — 프로필 URL에서 공개 프로필 정보, 소개, 이미지, 웹사이트, 공개된 계정 수치, 수집 맥락을 수집합니다.
- Pinterest Search API — 텍스트 검색어와 결과 수 제한으로 공개 핀을 검색하고, 정규화된 콘텐츠, 크리에이터, 미디어, 분류, 타임스탬프, 공개된 지표를 반환합니다.
- Pinterest User Boards API — 프로필 URL로 Pinterest 프로필의 보드를 나열하며 이름, 설명, 커버, 생성일과 핀·팔로워·섹션·협업자 수를 포함합니다.
- Pinterest Topic API — Pinterest 아이디어 페이지 URL로 주제별 월간 검색 수, 갱신 시점, 그 아래 추천된 세부 주제를 읽어 옵니다.