We're excited to announce one of our most frequently requested features, the ability to use our API to extract data rendered in our site's charts, is now live!
The Reports API gives you the ability to get an exact equivalent to our timeline-based area charts, such as those you'd see on our Velocity reports page. If you have any sort of use case that requires pulling this data down and treating it in a specific way, you're likely already doing so via individual CSV downloads. This new API functionality allows you to accomplish the same thing, dramatically faster, and to fetch data programmatically.
To get a sample of how to use this functionality to get a simple, timeline-based view of recent Diff Delta in your repo, you can run this simple curl, with appropriate values substituted for your API token and resource path (which can just be your entity slug - the part that appears directly after entities/ and before the next slash in the URL) to one of your reports:
(This request uses your entity's default team, all-contributors, but you can use any team you happen to be a member of)
This will request the past 30 days of Diff Delta data within your entity. You should see a result that looks something like this (truncated for simplicity):
You'll see here that we list the interval of data points, the unit that the results are presented in, and a set of X/Y data points, with the X values being dates and the Y values being the Diff Delta on that particular date. Each data point also includes a URL that points back to commits on that particular date, as represented on our Commit Activity Browser.
In case resource_path isn't familiar to you, this the path to the specific resource you want to target. You may target a specific entity (e.g. some-entity), an organization within an entity (some-entity/some-org) or a repo in an organization (some-entity/some-org/some-repo). It will the immediate chunks of the URL after some-entity on one of your pages.
The key parameter that you'll want to use to generate different types of data is segment_by, which changes the graph segmentation, or, put simply: What type of data you are grabbing. There are a set of values you can give to segment_by that are more thoroughly documented on our API documentation , but for a simple exercise, we can select ticket_type, which breaks everything down by the particular ticket category in Jira (e.g. New feature, bug...). We'll also change our days_ago to 90, giving us a broader data set:
Translates to this result:
A few things may jump out to you about this: The data points on the X axis are now shown in weekly installments (on each Monday), given the longer timeframe. Time spans beyond a month are automatically segmented weekly, rather than daily, and ones that are beyond a year will segment by month, rather than by week.
You may also notice the fact that the series segments are now much more descriptive - in this case, each segment has its own name that matches the particular issue type at that time. Hence, you can see how each issue type's Diff Delta has trended at each data point.
One thing that you can optionally pass is calculate_summary_stats=true, which will render a set of high-level stats that compliment the particular segmentation given, similar to the summary stat boxes below the top chart on the Velocity reports page. Here, we'll do that, and segment by our entity's PR cycle time:
Which will generate this example output:
You'll notice that unit here is now days (as one would expect for looking at PR cycle time), and we now have a series of new keys added to our JSON response, which describe various high-level stats, including whether or not they have diminished (have a negative trend line) in the current time frame relative to the previous. In addition, as is the case for PR cycle time, data is now segmented repo-by-repo.
One final method of digging through data is to grab stats for a particular individual contributor, which we can do by specifying a committer_user_name (matching the username given in the URL when you visit a stats page for that contributor). Using this request:
We get a result like this, with Diff Delta for that individual contributor:
That's it! From here, you should be able to grab all sorts of interesting stats from your GitClear data. You can see full details on this endpoint from our API reference. If you have any questions, or need help using some particular aspect of this new reports API, leave a comment here or contact support@gitclear.com.