Coverage API

Use the Coverage API to analyze media coverage data and gain insights.

Authentication

All API requests require an API key in the PULITZER-API-KEY header.

Header Setup

PULITZER-API-KEY: YOUR_API_KEY

Getting API Key

You can obtain an API key from the PulitzerAI dashboard.

Navigate to Settings after logging into the dashboard
Create a new key in the API Key Management section
Store the generated key securely

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

Coverage Overview

Retrieve coverage overview for all user workspaces.

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

Response

{
  "status": "SUCCESS",
  "message": "Request processed successfully.",
  "total_workspaces": 3,
  "total_coverage": 1245,
  "top_workspace": "Samsung Electronics PR Team",
  "workspaces": [
    {
      "workspace_id": 1,
      "workspace_name": "Samsung Electronics PR Team",
      "company_name": "Samsung Electronics",
      "coverage_count": 680
    }
  ]
}

Response Field Description

Field	Type	Description
`status`	string	Request processing status (e.g. SUCCESS, ERROR)
`message`	string	Request processing result message
`total_workspaces`	integer	Total number of workspaces
`total_coverage`	integer	Total coverage count
`top_workspace`	string	Name of workspace with highest coverage
`workspaces`	array	Coverage info by workspace
`workspaces[].workspace_id`	integer	Workspace ID
`workspaces[].workspace_name`	string	Workspace name
`workspaces[].company_name`	string	Company name
`workspaces[].coverage_count`	integer	Coverage count for this workspace

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

Workspace Coverage

Retrieve detailed coverage analysis for a specific workspace.

Request

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

Path Parameters

Parameter	Type	Required	Description
`workspace_id`	integer	✅	Workspace ID

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	❌	Start date (YYYY-MM-DD)
`end_date`	string	❌	End date (YYYY-MM-DD)

Response

{
  "status": "SUCCESS",
  "workspace_id": 1,
  "workspace_name": "Samsung Electronics PR Team",
  "company_name": "Samsung Electronics",
  "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": "Chosun Ilbo",
      "coverage_count": 125,
      "percentage": 18.38
    }
  ],
  "monthly_trend": [
    {
      "month": "2024-01",
      "coverage_count": 42
    }
  ]
}

Response Field Description

Field	Type	Description
`status`	string	Request processing status (e.g. SUCCESS, ERROR)
`workspace_id`	integer	Workspace ID
`workspace_name`	string	Workspace name
`company_name`	string	Company name
`coverage_stats`	object	Coverage statistics
`coverage_stats.total_coverage`	integer	Total coverage count
`coverage_stats.this_month_coverage`	integer	This month's coverage count
`coverage_stats.last_month_coverage`	integer	Last month's coverage count
`coverage_stats.coverage_growth`	float	Coverage growth rate (%)
`coverage_stats.avg_daily_coverage`	float	Average daily coverage count
`media_breakdown`	array	Coverage info by media
`media_breakdown[].media_name`	string	Media name
`media_breakdown[].coverage_count`	integer	Coverage count for this media
`media_breakdown[].percentage`	float	Percentage of total coverage for this media (%)
`monthly_trend`	array	Monthly coverage trend
`monthly_trend[].month`	string	Month (YYYY-MM format)
`monthly_trend[].coverage_count`	integer	Coverage count for this month

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"

Coverage Efficiency

Analyze coverage efficiency compared to press releases for a workspace.

Request

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

Path Parameters

Parameter	Type	Required	Description
`workspace_id`	integer	✅	Workspace ID

Response

{
  "status": "SUCCESS",
  "message": "Coverage efficiency retrieved successfully",
  "workspace_id": 1,
  "workspace_name": "Samsung Electronics PR Team",
  "efficiency_data": {
    "press_release_count": 45,
    "coverage_count": 680,
    "efficiency_ratio": 15.11,
    "average_coverage_per_release": 15.1
  }
}

Response Field Description

Field	Type	Description
`status`	string	Request processing status (e.g. SUCCESS, ERROR)
`message`	string	Request processing result message
`workspace_id`	integer	Workspace ID
`workspace_name`	string	Workspace name
`efficiency_data`	object	Efficiency data
`efficiency_data.press_release_count`	integer	Press release count
`efficiency_data.coverage_count`	integer	Coverage count
`efficiency_data.efficiency_ratio`	float	Efficiency ratio (%)
`efficiency_data.average_coverage_per_release`	float	Average coverage per press release

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

Coverage Trend

Retrieve monthly coverage trend for a workspace.

Request

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

Path Parameters

Parameter	Type	Required	Description
`workspace_id`	integer	✅	Workspace ID

Query Parameters

Parameter	Type	Required	Description
`months`	integer	❌	Number of months to query (1-24, default: 12)

Response

{
  "status": "SUCCESS",
  "message": "Coverage trend retrieved successfully",
  "workspace_id": 1,
  "workspace_name": "Samsung Electronics PR Team",
  "trend_data": [
    {
      "month": "2024-01",
      "coverage_count": 42,
      "press_release_count": 3,
      "efficiency_ratio": 14
    }
  ]
}

Response Field Description

Field	Type	Description
`status`	string	Request processing status (e.g. SUCCESS, ERROR)
`message`	string	Request processing result message
`workspace_id`	integer	Workspace ID
`workspace_name`	string	Workspace name
`trend_data`	array	Monthly coverage trend data
`trend_data[].month`	string	Month (YYYY-MM format)
`trend_data[].coverage_count`	integer	Coverage count for this month
`trend_data[].press_release_count`	integer	Press release count for this month
`trend_data[].efficiency_ratio`	float	Efficiency ratio (%)

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

Error Response

When an API request fails, you will receive the following error response.

Common Error Codes

Status Code	Error Code	Description
401	`UNAUTHORIZED`	Invalid API key
404	`WORKSPACE_NOT_FOUND`	Workspace not found
400	`INVALID_PARAMETER`	Invalid parameter

Error Response Format

{
  "status": "ERROR",
  "message": "API key is invalid.",
  "success": "FALSE"
}

# Request with invalid API key
curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/overview" \
  -H "PULITZER-API-KEY: INVALID_KEY"

# Query non-existent workspace
curl -X GET "https://api.pulitzer.ai/live/openapi/coverage/workspace/999" \
  -H "PULITZER-API-KEY: YOUR_API_KEY"

💡 Tip: Use appropriate date ranges and filters for effective media analysis.

⚠️ Note: Check API usage limits and maintain efficient calling patterns.