Pinterest User Pins
Pinterest 사용자 핀은 프로필과 연관된 공개 비주얼 게시물로, 제목, 설명, 크리에이터 정보, 미디어 참조, 카테고리, 해시태그, 타임스탬프, 공개된 참여 수치로 표현됩니다. 이러한 콘텐츠·관찰 필드는 프로필별 컬렉션 아카이빙, 비주얼 주제 조사, 출처 표기, 수집 시점 비교에 활용할 수 있습니다.
Pinterest User Pins API 주요 기능
- 프로필 기반 핀 탐색공개 Pinterest 프로필 URL을 하나 이상 받아, 프로필 메타데이터가 아니라 제출한 프로필마다 연관된 핀 레코드를 반환합니다.
- 프로필별 수집 깊이results_limit을 모든 프로필 URL에 따로 적용하며, 기본값은 100이고 허용 범위는 1부터 2,000까지입니다.
- 정규화된 핀·작성자·미디어 레코드핀 식별자, URL, 제목, 텍스트, 공개 작성자 필드, 이미지·동영상 참조를 일관된 결과 형태로 반환합니다.
- 참여 수치와 출처 정보공개된 좋아요·댓글 수와 크리에이터 팔로워 수를 게시 시각, collected_at, 분류 필드, 사용 가능한 경우 discovery_input과 함께 보관합니다.
Pinterest User Pins API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | 예약되지 않은 경로 세그먼트가 정확히 하나인 공개 HTTP 또는 HTTPS Pinterest 프로필 URL의 목록으로, 필수 값입니다. 핀, 검색, 아이디어, pin.it URL은 거부됩니다. |
results_limit | 선택 | 프로필 URL마다 요청하는 핀의 최대 개수입니다. 기본값은 100이며 1부터 2,000까지의 정수를 받습니다. |
Pinterest User Pins API 사용 방법
공개 Pinterest 프로필 URL을 프로필별 결과 제한과 함께 제출하고, 비동기 작업을 추적한 뒤, 정규화된 핀을 커서 페이지네이션으로 읽습니다.
- 프로필 경로 세그먼트가 하나뿐인 공개 Pinterest 프로필 URL을 하나 이상 준비합니다.
- urls와 선택 사항인 results_limit을 /v1/pinterest/user-pins로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패를 반환할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고, has_more가 true인 동안 반환된 next_cursor로 다음 페이지를 요청합니다.
curl -X POST "https://api.socq.ai/v1/pinterest/user-pins" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/example/"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is truePinterest User Pins API 추천 활용 사례
- 공개 프로필 핀 아카이빙: 정해 둔 프로필 URL에 대해 핀 ID, 원본 URL, 제목, 텍스트, 작성자 필드, 미디어 참조, 타임스탬프, discovery_input을 보존합니다.
- 비주얼·분류 체계 조사: 미디어 유형, post_type, 카테고리, 해시태그, 제목, 텍스트를 활용해 선택한 공개 프로필에서 반복되는 형식과 테마를 살펴봅니다.
- 프로필 간 신호 비교: 공개된 좋아요·댓글 수를 크리에이터 팔로워 정보와 함께 프로필 컬렉션 간에 비교하고, collected_at으로 각 관찰 시점을 고정합니다.
Pinterest User Pins API 활용 팁
- 프로필 경로 세그먼트가 정확히 하나인 공개 Pinterest 프로필 URL을 제출하세요. 핀 링크, pin.it 단축 링크, 검색 페이지, 더 깊은 경로는 프로필 검증에서 실패합니다.
- 제한이 프로필마다 따로 적용되므로, 요청 깊이와 요청 전 크레딧 예상치는 urls 개수에 results_limit을 곱한 값으로 계산하세요.
- 하위 데이터셋이 제출한 프로필과 관찰 시점을 유지하도록, 모든 핀에 discovery_input과 collected_at을 함께 저장하세요.
- media, created_at, categories, hashtags, source, 작성자 정보, 개별 지표는 선택 사항으로 취급하고, 분류가 반환되지 않았을 때 핀을 직접 만든 것인지 저장한 것인지 추정하지 마세요.
관련 API
Pinterest User Pins API 외에 Pinterest의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Pinterest Pins API — 공개 핀 URL을 정규화된 콘텐츠, 크리에이터, 미디어, 분류, 타임스탬프, 공개된 지표로 변환합니다.
- Pinterest Profiles API — 프로필 URL에서 공개 프로필 정보, 소개, 이미지, 웹사이트, 공개된 계정 수치, 수집 맥락을 수집합니다.
- Pinterest Search API — 텍스트 검색어와 결과 수 제한으로 공개 핀을 검색하고, 정규화된 콘텐츠, 크리에이터, 미디어, 분류, 타임스탬프, 공개된 지표를 반환합니다.
- Pinterest User Boards API — 프로필 URL로 Pinterest 프로필의 보드를 나열하며 이름, 설명, 커버, 생성일과 핀·팔로워·섹션·협업자 수를 포함합니다.
- Pinterest Board Pins API — 보드 URL로 Pinterest 보드의 핀을 보드 순서대로 수집하며 핀 텍스트, 저장한 계정, 원본 이미지, 핀 링크를 포함합니다.
- Pinterest Topic API — Pinterest 아이디어 페이지 URL로 주제별 월간 검색 수, 갱신 시점, 그 아래 추천된 세부 주제를 읽어 옵니다.