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