API [beta]

The Committee to Protect Journalists is an independent, nonprofit organization that promotes press freedom worldwide. We defend the right of journalists to report the news safely and without fear of reprisal.

Since 1992, CPJ has collected detailed records of journalists worldwide who are killed or go missing in the line of duty. CPJ also conducts an annual global census of journalists imprisoned in relation to their work. Read about our methodology.

Each journalist has their own data entry. We also track the country in which the journalist was killed, imprisoned, or went missing, and the date they were killed, arrested, or last seen. We track each journalist’s gender, origin (foreign or local) employment status (freelance or staff), job, beat or coverage area, and in which type of media they worked.

CPJ encourages the use of our data to research, report on, and advocate for freedom of the press. (The text of our research and reporting is also available for publication, under terms of our Creative Commons BY NC ND 4.0 license. Images and other media are not covered by the Creative Commons license. For more information about permissions, see our FAQs.)

Available Endpoints:

GET /v1/persons/${personId}

Retrieves a list of people and associated entries. If the optional ${personId} path parameter is not supplied, a listing will be returned.

Examples:

curl --request GET https://api.cpj.org/v1/persons/
curl --request GET https://api.cpj.org/v1/persons/1234
curl --request GET https://api.cpj.org/v1/persons/?order=fullName
curl --request GET https://api.cpj.org/v1/persons/?fullName=John Doe
curl --request GET https://api.cpj.org/v1/persons/?fullName=John*

Advanced Querying & Filtering

Filter Operators

  • column=value – translates as expected into a sql column equality check “column = value”
  • column=’values can have spaces with encapsulated in quotes’
  • column=”double or single quotes work”
  • column=”the first quote type wins so a single quote like ‘ inside of double quotes is considered a literal”
  • column=”you can also \” escape quotes with a backslash
  • column=something*blah – translates into “column LIKE ‘something%blah'”
  • eq(column,value) – alternate form of column=value
  • gt(column,value) – greater than query filter eg: “column < value”
  • ge(column,value) – greater than or equal to
  • lt(column,value) – less than filter
  • le(column,value) – less than or equal to
  • ne(column,value) – not equal
  • in(column,val1,[val2…valN]) – translates into “where column in (val1,….valN)”
  • out(column,val1,[val2…valN]) – translates into “where column NOT in (val1,….valN)”
  • and(clause1,clause2,[…clauseN) – “where (clause1 AND clause2 AND clauseN)”
  • or(clause1,clause2,[…clauseN) – “where (clause1 OR clause2 OR clauseN)”
  • if(column OR expression, val_when_true, val_when_false)

Sorting / Ordering

  • sort=col1,+col2,-col3,colN OR sort(col1,[…colN]). Use of the + operator is the implied default.
  • order – same as ‘sort’

Pagination

  • page=N – translates into an offset clause using pagesize (or the default page size) as the multiplier
  • pagesize=N – the number of results to return

Select Functions and Aggregations

  • group(col1, […colN]) – adds cols to a GROUP BY clause
  • sum,count,min,max(col, [renamedAs]) – perform basic aggregate functions
  • countascol(col, value, […valueN]) – Roughly translates to “select sum(if(eq(col, value), 1, 0)) as value”.
  • distinct, distinct(column) – filters out duplicates
  • as(col, renamed) – you can rename a property in the returned JSON using the ‘as’ operator. Works just like the SQL as operator.

Property Inclusion / Exclusion

  • includes=col1,col2,colN OR includes(col1…colN) – restricts the properties returned in the document to the ones specified. All others will be excluded.
  • excludes=col1,col2,colN OR excludes(col1…colN) – specifically excludes the supplied props. All others will be included.

Nested Document Expansion

  • expands=collection.property[…property][,table2.property2…] – if “property” is a foreign key referenced entity will be included in the returned document instead of a reference to it being returned.