NAV
R Shell Headers

CRAN checks API

CRAN checks API is an API providing access to CRAN checks data in a machine-readable format.

For a recent overview of the API, check out the Overview of the CRAN checks API blog post on the R-Hub blog.

The API was created and is maintained by Scott Chamberlain.

Base URL

https://cranchecks.info/

R package cchecks 📦

Most endpoints are supported in the cchecks R client.

HTTP methods

This is mostly a read only API. That is, we only allow GET (and HEAD) requests on this API.

Requests of all other types will be rejected with appropriate 405 code.

Media types

JSON mostly, image/svg+xml for badges.

Pagination

The query parameters limit (default = 10) and offset (default = 0) can be sent.

limit (integer, optional)
number of records to return. Default: 10. Max: see endpoint docs.
offset (integer, optional)
Record number to start at. Default: 0. Max: see endpoint docs.

Above parameters can be used only on /pkgs, /maintainers, and /pkgs/{package_name}/history.

The response body from the server will include data on records found in found and number returned in count.

Response codes

For this section of the docs, examples of (bad) requests are given in the Shell tab on the right, and the headers are in the Headers tab.

200 (OK)

Request good!

302 (Found)

The root /, redirects to /heartbeat, and /docs redirects to what you’re reading right now.

400 (Bad request)

When you have a malformed request, fix it and try again

404 (Not found)

When you request a route that does not exist, fix it and try again. E.g. in the example here we misspell “maintainers” to “maintainer”. 🙈

405 (Method not allowed)

When you use a prohibited HTTP method for a given route. Don’t do that. 😉

500 (Internal server error)

Server got itself in trouble 😱 😭; get in touch with us.

Root

This path redirects to /heartbeat

Heartbeat

Get heartbeat for the API 💓 (i.e. the list of endpoints).

GET [/heartbeat]

Function of the cchecks R package: cch_heartbeat().

Docs

This path redirects to the docs (hopefully here! 😸). See Headers tab.

GET [/docs]

Maintainers

Get checks data by package maintainer.

Function of the cchecks R package: cch_maintainers().

Maintainers

Get checks summaries for all maintainers.

GET [/maintainers]

Default limit of 10, max of 1000.

Example with custom offset and limit.

Maintainers by email

Get checks data by email of the package maintainer.

GET [/maintainers/{email}]

⚠️ jane.doe@example.com has to be transformed to jane.doe_at_example.com.

Packages

Get packages based checks.

Function of the cchecks R package: cch_pkgs().

Packages

Get checks data for all packages.

GET [/pkgs] Default limit of 10, max of 1000.

Example with custom offset and limit.

Packages by name

Get checks summary by package name.

Function of the cchecks package: cch_pkgs_history()

GET [/pkgs/{package}]

Packages by name (history)

Get checks history by package name.

GET [/pkgs] Default limit of 10, max of 50.

GET [/pkgs/{package}/history]

For historical data across packages see the history endpoint.

Badges

Get packages based checks to display in your package README for instance.

In a Markdown-based README to add a badge you just need something like ![alt text](https://cranchecks.info/badges/summary/{package}).

You might want the badge to point at either the CRAN results page or the CRAN checks API page i.e. either

[![Worst CRAN checks result for the rhub package](https://cranchecks.info/badges/worst/rhub)](https://cran.r-project.org/web/checks/check_results_rhub.html) to obtain Badges example, worst for the rhub package.

or

[![Worst CRAN checks result for the rhub package](https://cranchecks.info/badges/worst/rhub)](https://cranchecks.info/pkgs/rhub) to obtain Badges example, worst for the rhub package.

Summary badges

Get badge for CRAN checks summary by package name.

GET [/badges/summary/{package_name}]

[![Summary of CRAN checks results for the rhub package](https://cranchecks.info/badges/summary/rhub)](https://cranchecks.info/pkgs/rhub) gives Summary of CRAN checks results for the rhub package.

Worst badges

Get badge for CRAN checks worst result by package name. 😰

GET [/badges/worst/{package_name}]

[![Worst CRAN checks results for the rhub package](https://cranchecks.info/badges/summary/rhub)](https://cranchecks.info/pkgs/rhub) gives Worst CRAN checks results for the rhub package.

Flavor badges

Get badge for summary of CRAN checks by flavor and package name.

GET [/badges/flavor/{flavor}/{package}]

💡 List of platforms/flavors

[![CRAN checks result on r-devel-linux-x86_64-debian-clang for the rhub package](https://cranchecks.info/badges/flavor/r-devel-linux-x86_64-debian-clang/rhub)](https://cranchecks.info/pkgs/rhub) gives CRAN checks result on r-devel-linux-x86_64-debian-clang for the rhub package.

History

The /history/:date route allows GET requests only. The route is intended for fetching compressed new-line delimited JSON for an individual date, where all CRAN checks data across all packages is combined.

Parameter:

:date
should be of the form YYYY-MM-DD, the minimal value is 2018-12-18.

A request to /history/:date leads to a redirect (http status 302) and a returned JSON body with a message telling the user to follow the link in the Location response header in case they aren’t familiar with redirects. The link to follow is a temporary Amazon S3 link to the JSON file for the given date.

One can automatically get the link to the JSON file by following the redirect. You can do this in curl with the -L flag, or in R by using the followlocation curl option like followlocation=1.

An important note is the data in the JSON file is NOT valid JSON as an entire entity. Each line of the file IS valid JSON; called newline delimited JSON (NDJSON). You don’t have to worry about these details if you use cchecks::cch_history(), which takes care of downloading the file and reading in the compressed NDJSON. On the command line, you can do e.g, download the file, save to a .json.gz gzip-compressed file extension, then in the next line decompress the file with gzip, then pipe to jq, and use head to get the first 10 lines

⚠️ 💡 For historical data by package refer to the package history endpoint.

Search

Search package history data. This is a full text search ONLY of the output in check_details field.

Function of the cchecks package: cch_pkgs_search()

GET [/search]

Parameters:

q (string)
full text query, e.g, q=memory
package (string)
a package name. limit results to a single package, e.g, package=taxize
one_each (boolean)
if true, return a single result for each package; useful if you want to find out what packages have match a particular query, and don’t care which day that match happened. default: false; e.g., one_each=true
fields (string)
comma separated string with field to return, e.g., fields=package,check_details
limit/offset
see pagination docs. Max of 50.