Coverage API

Coverage API를 사용하여 언론 커버리지 데이터를 분석하고 인사이트를 얻을 수 있습니다.

인증

모든 API 요청에는 PULITZER-API-KEY 헤더에 API 키가 필요합니다.

헤더 설정

PULITZER-API-KEY: YOUR_API_KEY

API 키 획득

API 키는 PulitzerAI 대시보드에서 발급받을 수 있습니다.

대시보드 로그인 후 설정 메뉴로 이동
API 키 관리 섹션에서 새 키 생성
생성된 키를 안전하게 보관

curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/overview" \
  -H "PULITZER-API-KEY: YOUR_API_KEY"

전체 커버리지 개요

사용자의 모든 워크스페이스 커버리지 개요를 조회합니다.

GET https://api.pulitzer.ai/live/openapi/coverage/overview

응답

{
  "status": "SUCCESS",
  "message": "요청이 성공적으로 처리되었습니다.",
  "total_workspaces": 3,
  "total_coverage": 1245,
  "top_workspace": "삼성전자 홍보팀",
  "workspaces": [
    {
      "workspace_id": 1,
      "workspace_name": "삼성전자 홍보팀",
      "company_name": "삼성전자",
      "coverage_count": 680
    }
  ]
}

응답 필드 설명

필드	타입	설명
`status`	string	요청 처리 상태 (예: SUCCESS, ERROR)
`message`	string	요청 처리 결과 메시지
`total_workspaces`	integer	전체 워크스페이스 수
`total_coverage`	integer	전체 커버리지 수
`top_workspace`	string	가장 높은 커버리지를 가진 워크스페이스 이름
`workspaces`	array	워크스페이스별 커버리지 정보
`workspaces[].workspace_id`	integer	워크스페이스 ID
`workspaces[].workspace_name`	string	워크스페이스 이름
`workspaces[].company_name`	string	회사 이름
`workspaces[].coverage_count`	integer	해당 워크스페이스의 커버리지 수

curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/overview" \
  -H "PULITZER-API-KEY: YOUR_API_KEY"

워크스페이스 커버리지

특정 워크스페이스의 상세 커버리지 분석을 조회합니다.

요청

GET https://api.pulitzer.ai/live/openapi/coverage/workspace/{workspace_id}

Path Parameters

파라미터	타입	필수	설명
`workspace_id`	integer	✅	워크스페이스 ID

Query Parameters

파라미터	타입	필수	설명
`start_date`	string	❌	시작 날짜 (YYYY-MM-DD)
`end_date`	string	❌	종료 날짜 (YYYY-MM-DD)

응답

{
  "status": "SUCCESS",
  "workspace_id": 1,
  "workspace_name": "삼성전자 홍보팀",
  "company_name": "삼성전자",
  "coverage_stats": {
    "total_coverage": 680,
    "this_month_coverage": 45,
    "last_month_coverage": 38,
    "coverage_growth": 18.42,
    "avg_daily_coverage": 1.45
  },
  "media_breakdown": [
    {
      "media_name": "조선일보",
      "coverage_count": 125,
      "percentage": 18.38
    }
  ],
  "monthly_trend": [
    {
      "month": "2024-01",
      "coverage_count": 42
    }
  ]
}

응답 필드 설명

필드	타입	설명
`status`	string	요청 처리 상태 (예: SUCCESS, ERROR)
`workspace_id`	integer	워크스페이스 ID
`workspace_name`	string	워크스페이스 이름
`company_name`	string	회사 이름
`coverage_stats`	object	커버리지 통계 정보
`coverage_stats.total_coverage`	integer	전체 커버리지 수
`coverage_stats.this_month_coverage`	integer	이번 달 커버리지 수
`coverage_stats.last_month_coverage`	integer	지난 달 커버리지 수
`coverage_stats.coverage_growth`	float	커버리지 성장률 (%)
`coverage_stats.avg_daily_coverage`	float	일 평균 커버리지 수
`media_breakdown`	array	미디어별 커버리지 정보
`media_breakdown[].media_name`	string	미디어 이름
`media_breakdown[].coverage_count`	integer	해당 미디어의 커버리지 수
`media_breakdown[].percentage`	float	전체 커버리지에서 해당 미디어의 비율 (%)
`monthly_trend`	array	월별 커버리지 트렌드
`monthly_trend[].month`	string	월 (YYYY-MM 형식)
`monthly_trend[].coverage_count`	integer	해당 월의 커버리지 수

curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/workspace/1?start_date=2024-01-01&end_date=2024-07-04" \
  -H "PULITZER-API-KEY: YOUR_API_KEY"

커버리지 효율성

워크스페이스의 보도자료 대비 커버리지 효율성을 분석합니다.

요청

GET https://api.pulitzer.ai/live/openapi/coverage/workspace/{workspace_id}/efficiency

Path Parameters

파라미터	타입	필수	설명
`workspace_id`	integer	✅	워크스페이스 ID

응답

{
  "status": "SUCCESS",
  "message": "커버리지 효율성 조회 성공",
  "workspace_id": 1,
  "workspace_name": "삼성전자 홍보팀",
  "efficiency_data": {
    "press_release_count": 45,
    "coverage_count": 680,
    "efficiency_ratio": 15.11,
    "average_coverage_per_release": 15.1
  }
}

응답 필드 설명

필드	타입	설명
`status`	string	요청 처리 상태 (예: SUCCESS, ERROR)
`message`	string	요청 처리 결과 메시지
`workspace_id`	integer	워크스페이스 ID
`workspace_name`	string	워크스페이스 이름
`efficiency_data`	object	효율성 데이터
`efficiency_data.press_release_count`	integer	보도자료 수
`efficiency_data.coverage_count`	integer	커버리지 수
`efficiency_data.efficiency_ratio`	float	효율성 비율 (%)
`efficiency_data.average_coverage_per_release`	float	보도자료당 평균 커버리지 수

curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/workspace/1/efficiency" \
  -H "PULITZER-API-KEY: YOUR_API_KEY"

커버리지 트렌드

워크스페이스의 월별 커버리지 트렌드를 조회합니다.

요청

GET https://api.pulitzer.ai/live/openapi/coverage/workspace/{workspace_id}/trend

Path Parameters

파라미터	타입	필수	설명
`workspace_id`	integer	✅	워크스페이스 ID

Query Parameters

파라미터	타입	필수	설명
`months`	integer	❌	조회할 개월 수 (1-24, 기본값: 12)

응답

{
  "status": "SUCCESS",
  "message": "커버리지 트렌드 조회 성공",
  "workspace_id": 1,
  "workspace_name": "삼성전자 홍보팀",
  "trend_data": [
    {
      "month": "2024-01",
      "coverage_count": 42,
      "press_release_count": 3,
      "efficiency_ratio": 14
    }
  ]
}

응답 필드 설명

필드	타입	설명
`status`	string	요청 처리 상태 (예: SUCCESS, ERROR)
`message`	string	요청 처리 결과 메시지
`workspace_id`	integer	워크스페이스 ID
`workspace_name`	string	워크스페이스 이름
`trend_data`	array	월별 커버리지 트렌드 데이터
`trend_data[].month`	string	월 (YYYY-MM 형식)
`trend_data[].coverage_count`	integer	해당 월의 커버리지 수
`trend_data[].press_release_count`	integer	해당 월의 보도자료 수
`trend_data[].efficiency_ratio`	float	효율성 비율 (%)

curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/workspace/1/trend?months=12" \
  -H "PULITZER-API-KEY: YOUR_API_KEY"

에러 응답

API 요청이 실패할 경우 다음과 같은 에러 응답을 받습니다.

공통 에러 코드

상태 코드	에러 코드	설명
401	`UNAUTHORIZED`	API 키가 유효하지 않음
404	`WORKSPACE_NOT_FOUND`	워크스페이스를 찾을 수 없음
400	`INVALID_PARAMETER`	잘못된 파라미터

에러 응답 형식

{
  "status": "ERROR",
  "message": "API 키가 유효하지 않습니다.",
  "success": "FALSE"
}

# 유효하지 않은 API 키로 요청
curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/overview" \
  -H "PULITZER-API-KEY: INVALID_KEY"

# 존재하지 않는 워크스페이스 조회
curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/workspace/999" \
  -H "PULITZER-API-KEY: YOUR_API_KEY"

💡 팁: 효과적인 언론 분석을 위해 적절한 날짜 범위와 필터를 활용하세요.

⚠️ 주의: API 사용량 제한을 확인하고, 효율적인 호출 패턴을 유지하세요.