Facebook Event Details
Facebook Event Details는 이미 알고 있는 이벤트 URL을 바로 조회하는 엔드포인트입니다. /events/가 포함된 공개 Facebook URL을 하나 이상 제출하면, 제공되는 범위에서 이벤트 ID, 정식 URL, 이름, 설명, 시작·종료 시각, 장소, 공개 미디어, 공개된 지표, 수집 정보를 수집합니다.
Facebook Event Details API 주요 기능
- 이벤트 URL 직접 조회키워드, 카테고리, 도시, 날짜 검색 없이 알고 있는 공개 Facebook 이벤트 URL을 바로 조회합니다.
- 정규화된 이벤트 메타데이터식별 정보, 정식 URL, 이름, 설명, 수집 타임스탬프 필드로 구성된 안정적인 이벤트 구조를 반환합니다.
- 일정·장소 정보출처에서 공개되는 경우 정규화된 시작·종료 시각과 공개 장소 값을 가져옵니다.
- 미디어와 공개 지표이벤트에서 확인되는 범위에서 정규화된 공개 미디어와 일반적인 참여·반응 지표를 포함합니다.
Facebook Event Details API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | 공개 Facebook 이벤트 URL의 배열로, 필수 값입니다. 허용되는 호스트는 facebook.com, www.facebook.com, m.facebook.com이며, 각 경로에는 /events/가 포함되어야 합니다. |
Facebook Event Details API 사용 방법
이벤트 URL을 비동기 작업으로 제출하고, 작업 ID를 폴링한 뒤, 정규화된 이벤트 레코드를 읽습니다.
- 경로에 /events/가 포함된 공개 facebook.com, www.facebook.com, m.facebook.com URL을 하나 이상 준비합니다.
- urls 배열을 /v1/facebook/event-details로 POST합니다.
- status가 succeeded가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- /v1/tasks/{task_id}?limit=50에서 data.results.items를 읽고, results.has_more가 true인 동안에는 results.next_cursor를 따라갑니다.
curl -X POST "https://api.socq.ai/v1/facebook/event-details" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/events/123456789012345/"]}'
# Poll GET /v1/tasks/{task_id}, then read /v1/tasks/{task_id}?limit=50 and use data.results.items.Facebook Event Details API 추천 활용 사례
- 이벤트 메타데이터 보강: 저장해 둔 이벤트 URL에 정규화된 식별 정보, 이름, 설명, 장소, 일정, 미디어, 공개 지표를 보강합니다.
- 캘린더 연동: 확인되는 이벤트 이름, 시작·종료 시각, 설명, 장소, 원본 URL을 캘린더 파이프라인에 매핑합니다.
- 주최자·장소 조사: 기존 이벤트 URL 목록의 공개 설명, 장소, 일정, 미디어, 반응 신호를 살펴봅니다.
- 알고 있는 이벤트 갱신: 저장해 둔 이벤트 URL을 다시 실행해 출처에서 현재 확인되는 공개 필드를 최신 상태로 갱신합니다.
Facebook Event Details API 활용 팁
- 페이지의 이벤트 목록이나 events 경로 조각이 포함되었을 뿐인 다른 Facebook URL이 아니라, 정식 이벤트 상세 URL을 사용하세요.
- 이벤트마다 출처에서 보이는 범위가 다르므로 name, description, location, 일정, 미디어, 지표는 선택 값으로 취급하세요.
- 여러 URL을 제출한 요청의 결과를 대조할 때는 extra.input_url을 보존하세요. 제출한 URL 하나에서는 이벤트 레코드가 최대 1건 생성됩니다.
- 비공개, 삭제, 제한, 로그인 전용 이벤트는 이벤트 레코드가 반환되지 않은 채 작업이 완료될 수 있습니다.
관련 API
Facebook Event Details API 외에 Facebook의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Facebook Pages API — 공개 페이지 프로필, 연락처, 이미지, 공개된 오디언스 평점을 가져옵니다.
- Facebook Posts API — 지원되는 Facebook URL에서 공개 게시물, 미디어, 반응, 댓글, 공유 수를 수집합니다.
- Facebook Comments API — 게시물 URL에서 공개 댓글, 작성자, 참여도, 미디어, 출처 링크를 수집합니다.
- Facebook Video Transcript API — 공개 동영상 게시물 또는 릴스 URL에서 제공되는 스크립트 텍스트와 형식을 추출합니다.
- Facebook Events Search API — 키워드로 공개 이벤트를 검색하며, 일정, 장소, 참석자, 커버 미디어, 이벤트 상태 필드를 포함합니다.
- Facebook Profile Events API — 프로필 또는 페이지 URL과 연결된 공개 이벤트를 이름, 일정, 위치, 미디어, 공개된 지표, 출처 맥락과 함께 수집합니다.