Guide

Analytics REST API

Custom REST routes for post analytics queries and Civis CSV exports.

Base path: /wp-json/prc-api/v3/

Admin settings also expose GET/POST /wp-json/prc-analytics/v1/settings and POST .../settings/generate-civis-key for manage_options users. Those power the Settings UI and are not documented as a public contract here.

Auth summary

AccessRoutes
edit_postsPOST /analytics/query-by-url/, GET /analytics/query/
X-Civis-API-Key headerGET /analytics/civis/*

POST /analytics/query-by-url/

Returns post metadata plus Parse.ly metrics for a single URL.

Permission: current_user_can( 'edit_posts' )

Reference

Request body

Typed options, defaults, and constraints in one scannable reference.
1 field
url url required
Canonical post URL to resolve.
Request POST /wp-json/prc-api/v3/analytics/query-by-url/
HeadersKey: value
Content-Type application/jsonAccept application/json
Request bodyJSON
{
  "url": "https://alpha.pewresearch.org/pewresearch-org/example-article/"
}
Response 200 OK
BodyJSON
{
  "id": 123,
  "title": "Example",
  "parsely_metrics": {},
  "word_count": 1200
}

Response fields include id, parent_id, date_published, date_modified, content, title, bylines, label (format taxonomy), topics, primary_topic, research_teams, parsely_metrics, word_count.

Errors: WP_Error code 404 for malformed requests, missing URL, or URL helper failures.

GET /analytics/query/

Paginated list of posts with metadata and Parse.ly metrics (25 per page).

Permission: current_user_can( 'edit_posts' )

Reference

Query parameters

Typed options, defaults, and constraints in one scannable reference.
6 fields
post_type string
Comma-separated post types.
Defaultpost,fact-sheet,quiz,chart,dataset,feature,short-read
page number
Page number.
Default1
start_date string
strtotime()-compatible inclusive start.
end_date string
Inclusive end; defaults to today when start_date is set.
research_team string
Research team taxonomy slug.
return_only_corrections boolean
Limit to posts containing correction in the body.
Defaultfalse

Civis export routes

All Civis routes require header X-Civis-API-Key: <key> validated by API_Key_Auth. Responses are text/csv with X-Total-Count and X-Has-More. Common params: limit (default 1000, max 10000), offset.

MethodPathDescription
GET/analytics/civis/datasetsDataset download stats (day or month rows)
GET/analytics/civis/usersUser rows from Firebase
GET/analytics/civis/quiz-groupsQuiz group aggregates; optional quiz_id
GET/analytics/civis/quiz-submissionsIndividual submissions; optional quiz_id

Auth errors

CodeStatusMeaning
civis_api_key_not_configured500No key saved in settings
civis_api_key_missing401Header absent
civis_api_key_invalid401Header does not match

Users and quiz exports may also return firebase_not_available, firebase_not_configured, or firebase_error (500).

Request GET /wp-json/prc-api/v3/analytics/civis/datasets?limit=100&offset=0
HeadersKey: value
X-Civis-API-Key your-key-hereAccept text/csv
Response 200 OK
BodyRAW
day,daily_count,new_data_uploaded
2024-01-01,12,true

Was this helpful?