Managing 'Reporting Period Total' in JSON format

The Code of Practice allows for different facets of granularity in reporting usage metrics. One of those facets is whether usage is reported month-by-month, or as the sum of all months in the period covered by the report.

In tabular COUNTER reports there is a column labelled as ‘Reporting_Period_Total’. That column must be included for all four COUNTER Reports and their Standard Views. It is followed by the month-by-month breakdown (column heading format mmm-yyyy), unless the filter Exclude_Monthly_Details is set to True when you request the report.

In our JSON schema we default to showing only the month-by-month breakdown, without the Reporting_Period_Total. You can choose to mirror the Exclude_Monthly_Details tabular reporting using an Attribute called ‘granularity’. Granularity defines whether json reports should show either month-by-month usage data, or the total usage for all months in the reporting period. It’s only possible to have one value for granularity in COUNTER JSON files: either the report will show each month of usage separately, or it will show the total usage for the whole reporting period.

Month-by-month is the default. For a report covering January to March 2024, where the user has chosen to use the default granularity=Month, you will see metrics for each month, with the month formatted as yyyy-mm:

"Report_Attributes": 
  {
  …
    "Report_Items": [
    {
      "Attribute_Performance": [
      {
        "Performance": 
        {
          "Total_Item_Investigations":
          {
            "2024-01": 1700,
            "2024-02": 2120,
            "2024-03": 1965
          },
        …

If the user chooses to over-ride the default and see only the total usage for the whole period, the JSON needs to include granularity=Total, and instead of the month-by-month breakdown, you will see metrics reported only against the start of the reporting period. In the example above, granularity=Total for the period January to March 2024 would result in seeing metrics for 2024-01. Something like this:

"Report_Attributes":
  {
  "Granularity": "Totals",
  …
    "Report_Items": [
    {
      "Attribute_Performance": [
      {
        "Performance": 
        {
          "Total_Item_Investigations":
          {
            "2024-01": 5785
          },
        …

If you are stuck on a question about the COUNTER API (formerly sushi) or the JSON schema, get in touch with tasha@countermetrics.org. She might not have the answer, but she knows the person who does!