Get Graph Settings

Gets the Graph settings of the App.
For more information, refer to the following article:
Creating Charts on the "App Settings" Screen (External link)

MethodGET
URLhttps://{subdomain}.kintone.com/k/v1/app/reports.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/app/reports.json
Authentication Password Authentication , API Token Authentication , Session Authentication
Content-Typeapplication/json (not needed if specifying the query with a query string)

Contents

Pre-live Settings

Apps may hold pre-live settings that have not yet been deployed to the live App.
Access the pre-live settings with the below URL.

URL https://{subdomain}.kintone.com/k/v1/preview/app/reports.json
URL(guest space) https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/app/reports.json

Permissions

  • App Management Permissions are needed.

Request Parameters

Parameter Value Required Description
app Integer or String Yes The App ID.
lang String The localized language to retrieve the data in:
  • default: retrieves the default names
  • en: retrieves the localized English names
  • zh: retrieves the localized Chinese names
  • ja: retrieves the localized Japanese names
  • user: retrieves the localized names, in the same language as the language setting* set on the user used for the authentication.
If ignored, the default names will be retrieved.

*If the user language setting is set to Use Web browser settings, the settings set in the Accept-Language header will be used. If there is no Accept-Language header, the language set in the Localization settings in the System Administrator's menu will be used.

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var body = {
  'app': kintone.app.getId(),
  'lang': 'en'
};

kintone.api(kintone.api.url('/k/v1/app/reports.json', true), 'GET', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

XMLHttpRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
var appId = kintone.app.getId();
var url = 'https://{subdomain}.kintone.com/k/v1/app/reports.json?app=' + appId + '&lang=en';

var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send();

Response Parameters

Parameter Type Description
reports Object An object of Graph settings data.
The key of the object is the graph's unique identifier, which is set as the graph's name in its default language settings (this is regardless of the lang request parameter's value).
The values of the key are the various graph settings associated with that graph.
reports.{graphname}.chartType String The chart type of the graph. For more information, refer to the following article:
Chart Types and Their Usage (External link)
  • BAR: Bar chart
  • COLUMN: Column chart
  • PIE: Pie chart
  • LINE: Line chart
  • PIVOT_TABLE: Pivot Table
  • TABLE: Table
  • AREA: Area chart
  • SPLINE: Spline chart
  • SPLINE_AREA: Spline area chart
reports.{graphname}.chartMode String The display mode of the graph. For more information, refer to the following article:
Chart Types and Their Usage (External link)
  • NORMAL: Clustered graph or Non-stacked graph
  • STACKED: Stacked graph
  • PERCENTAGE: 100% stacked graph
If the reports.{graphname}.chartType parameter is set to BAR or COLUMN, then NORMAL refers to Clustered graph display mode.

If the reports.{graphname}.chartType parameter is set to AREA or SPLINE\_AREA, then NORMAL refers to Non-stacked graph display mode.

This parameter is returned only if the reports.{graphname}.chartType parameter is set to BAR, COLUMN, AREA, or SPLINE\_AREA.
reports.{graphname}.id String The ID of the graph.
reports.{graphname}.name String The name of the graph.
The maximum limit is 64 characters.
When the lang request parameter is specified, the graph's name in that language will be returned.
reports.{graphname}.index String The order of the graphs, starting from 0.
reports.{graphname}.groups Array An array of objects containing the Group by options.
The order of the objects are in the order of Level 1, Level 2, and Level 3.
Levels that are not set will not be included in the array.

This parameter is returned only if the Group by option is configured.
reports.{graphname}.groups[].code String The field code of the field used to determine the Group by option.
reports.{graphname}.groups[].per String The time unit used for the Group by option.
  • YEAR: by the year
  • QUARTER: by the quarter
  • MONTH: by the month
  • WEEK: by the week
  • DAY: by the day
  • HOUR: by the hour
  • MINUTE: by the minute
This parameter is returned if one of the following fields are specified in reports.{graphname}.groups[].code:
  • Created datetime
  • Updated datetime
  • Date and time
  • Date (Only YEAR, QUARTER, MONTH, WEEK, or DAY)
  • Time (Only HOUR or MINUTE)
If no unit was specified (i.e. left as "--"), the minimum time unit will be returned:
  • For DateTime or Time fields: MINUTE
  • For Date fields: DAY
reports.{graphname}.aggregations Array An array of objects containing the Function options.
reports.{graphname}.aggregations[].type String The type of the Function option.
  • COUNT: Number of records
  • SUM: Total
  • AVERAGE: Average
  • MAX: Maximum
  • MIN: Minimum
reports.{graphname}.aggregations[].code String The field code of the field used in the Function option.

This parameter is not returned if the reports.{graphname}.aggregations[].type is set to COUNT.
reports.{graphname}.filterCond String The record's filter condition in query string format that reflects the Filter option.
For more data on query formats refer to the following document:
Query String

The request will fail if a deleted User, Group, or Organization is specified in the filter condition.
reports.{graphname}.sorts Array An array of objects containing the Sort by options.
reports.{graphname}.sorts[].by String How the graph is sorted.
  • TOTAL: Total
  • GROUP1: Level 1
  • GROUP2: Level 2
  • GROUP3: Level 3
reports.{graphname}.sorts[].order String The order of sorting.
  • ASC: Ascending order
  • DESC: Descending order
reports.{graphname}.periodicReport Object An objects containing the Periodic Reports options. For more information, refer to the following article:
What Are Periodic Reports? (External link)
If the Generate reports periodically option have never been configured, null will be returned.
reports.{graphname}.periodicReport.active Boolean The activation status of the Periodic Reports option.
  • true: Active
  • false: Inactive
reports.{graphname}.periodicReport.period Object An object containing the Period options.
reports.{graphname}.periodicReport.period.every String The time interval type used to determine when to generate the Periodic Reports.
  • YEAR: by the year
  • QUARTER: by the quarter
  • MONTH: by the month
  • WEEK: by the week
  • DAY: by the day
  • HOUR: by the hour
reports.{graphname}.periodicReport.period.month String The month when the Periodic Report will be generated.
The month is returned as an integer, ranging from 1 (January) to 12 (December).

This parameter is returned only if the reports.{graphname}.periodicReport.period.every parameter is set to YEAR.
reports.{graphname}.periodicReport.period.time String The time when the Periodic Report will be generated.
Format: HH:MM

This parameter is returned only if the reports.{graphname}.periodicReport.period.every parameter is set to YEAR, QUARTER, MONTH, WEEK, or DAY.
reports.{graphname}.periodicReport.period.pattern String The months when the quarterly Periodic Report will be generated.
  • JAN_APR_JUL_OCT: January, April, July, October
  • FEB_MAY_AUG_NOV: February, May, August, November
  • MAR_JUN_SEP_DEC: March, June, September, December
This parameter is returned only if the reports.{graphname}.periodicReport.period.every parameter is set to QUARTER.
reports.{graphname}.periodicReport.period.dayOfMonth String The day when the Periodic Report will be generated.
The day is returned as an integer, ranging from 1 to 31, or set as END_OF_MONTH*.
*Only for graphs where the reports.{graphname}.periodicReport.period.every parameter is set to QUARTER or MONTH.

This parameter is returned only if the reports.{graphname}.periodicReport.period.every parameter is set to YEAR, QUARTER, or MONTH.
reports.{graphname}.periodicReport.period.dayOfWeek String The day of the week when the Periodic Report will be generated.
  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
This parameter is returned only if the reports.{graphname}.periodicReport.period.every parameter is set to WEEK.
reports.{graphname}.periodicReport.period.minute String The minute when the hourly Periodic Report will be generated.
The minute will be returned as 0, 10, 20, 30, 40 or 50.

This parameter is returned only if the reports.{graphname}.periodicReport.period.every parameter is set to HOUR.
revision String The revision number of the App settings.

Sample Response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
{
  "reports": {
    "Graph1 (Default Settings)": {
      "id": "7319",
      "chartType": "BAR",
      "chartMode": "NORMAL",
      "name": "Graph1 (Default Settings)",
      "index": "0",
      "groups": [
        {
          "code": "Created_by"
        }
      ],
      "aggregations": [
        {
          "type": "COUNT"
        }
      ],
      "filterCond": "",
      "sorts": [
        {
          "by": "TOTAL",
          "order": "DESC"
        }
      ],
      "periodicReport": null
    },
    "Graph2 (Table)": {
      "id": "7321",
      "chartType": "TABLE",
      "name": "Graph2 (Table)",
      "index": "1",
      "groups": [
        {
          "code": "Radio_button"
        },
        {
          "code": "Created_datetime",
          "per": "YEAR"
        },
        {
          "code": "Time",
          "per": "MINUTE"
        }
      ],
      "aggregations": [
        {
          "type": "COUNT"
        },
        {
          "type": "SUM",
          "code": "Number"
        },
        {
          "type": "AVERAGE",
          "code": "Calculated"
        },
        {
          "type": "MAX",
          "code": "Created_datetime"
        },
        {
          "type": "MIN",
          "code": "Time"
        }
      ],
      "filterCond": "Record_number = \"1\" and Rich_text like \"aaa\"",
      "sorts": [
        {
          "by": "TOTAL",
          "order": "DESC"
        },
        {
          "by": "GROUP1",
          "order": "ASC"
        },
        {
          "by": "GROUP2",
          "order": "DESC"
        }
      ],
      "periodicReport": null
    },
    "Graph3 (Periodic report ON)": {
      "id": "7323",
      "chartType": "BAR",
      "chartMode": "NORMAL",
      "name": "Graph3 (Periodic report ON)",
      "index": "2",
      "groups": [
        {
          "code": "Radio_button"
        }
      ],
      "aggregations": [
        {
          "type": "COUNT"
        }
      ],
      "filterCond": "",
      "sorts": [
        {
          "by": "TOTAL",
          "order": "DESC"
        }
      ],
      "periodicReport": {
        "active": true,
        "period": {
          "every": "QUARTER",
          "pattern": "JAN_APR_JUL_OCT",
          "dayOfMonth": "END_OF_MONTH",
          "time": "23:30"
        }
      }
    }
  },
  "revision": "77"
}

Limitations

If multiple graphs have the same name within the same App, this API will return an error.