GSS Metric API

The GSS Metric API is used to get statistics about apps registered in Galaxy Store. The GSS Metric API provides programmatic access to some of the statistics in the Galaxy Store Statistics (GSS) system.

The GSS Metric API is part of the Galaxy Store Developer API. You must meet all of the requirements of the Galaxy Store Developer API including, but not limited to, creating the access token and including the access token in the authorization header of every GSS Metric API call.

Authorization header parameters

Every request must include authorization header parameters which specify the content type and your access token. See Create an Access Token for more information about how to create an access token and Use the Access Token for more information about how to use the access token.

Attribute Type Description
Authorization string Required. Use Bearer <your-access-token> where <your-access-token> is the access token you requested from the Galaxy Store authentication server
content-type string Required. Must be application/json
service-account-id header Required by sellerMetric. The service account ID used to create the JWT associated with the access token (can be found in the Assistance > API Service area of Seller Portal)

View seller metrics

Provides statistics about new downloads, downloads by devices, sales, and item sales for all of the seller's registered apps.

Request

POST /gss/query/sellerMetric
Name Type Description
metricIds string[] Required. The statistics you want to view about the seller's registered apps. If more than one ID is requested, separate each ID by a comma. The name in parentheses is where you would find similar data in the Galaxy Store Statistics system.

  • total_unique_installs_filter (New Downloads): The number of devices on which users download the app for the first time.
  • revenue_total (Sales): Total income the app has generated, including item sales.
  • dn_by_total_dvce (Downloads by Total Devices): The number of devices on which users download the app, including devices that uninstalled your app and are downloading it again.
  • revenue_item (Item Sales): Sales an item has generated.
periods[{current-period}, {prev-period}] JsonArray Required. Each period is a range of time, denoted by startDate and endDate, for which data is provided. Enter the startDate and endDate as yyyy-MM-dd. Typically used to view the most current data and compare it to the data from the previous time period.

Example:
[{"startDate":"2021-03-07","endDate":"2021-03-13"},{"startDate":"2021-02-28","endDate":"2021-03-06"}]
getDailyMetric boolean Whether or not to provide daily trend value for each metric.

  • true: Provide the percentage change of the metric between the specified time periods.
  • false: Do not provide trend data.
getBreakdownsByFilter boolean Whether or not to provide statistics broken down by country or device for each metric.

  • true: Provide statistics based on the filters specified in the filters[{country}, {device}] array attribute.
  • false: Provide summary data only.
noContentMetadata boolean Whether or not to provide content metadata.

  • true: Do not include content metadata.
  • false: Display content metadata.
trendAggregation string How the data is aggregated: day, week, or month (for example, the total number of downloads each day over the specified time periods).
filters[{country}, {device}] JsonArray If getBreakdownsByFilter is set to true, provide data by the specified countries and devices. If getBreakdownsByFilter is set to true but no filters are entered, all non-zero data is provided.
country:[countries], device:[devices]

Example: "filters": {"device":["Galaxy S21 5G","Galaxy S10e"],"country":["Korea", "USA"]}

 
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-access-token>" \  
  -H "service-account-id: <your-service-account-id>" \
  -d '{"periods":[ {"startDate":"2021-03-08","endDate":"2021-03-14"}, {"startDate":"2021-03-01","endDate":"2021-03-07"}], "getDailyMetric":false, "getBreakdownsByFilter":true,  "noContentMetadata":true, "metricIds":[ "total_unique_installs_filter", "revenue_total", "dn_by_total_dvce", "revenue_item"], "filters":{}, "trendAggregation":"day"}' \
  "https://devapi.samsungapps.com/gss/query/sellerMetric"

Response

  • Success

    Status: 200 Success

    {
  "metricIds":["total_unique_installs_filter"],
  "data":{
    "periods":[
      {
        "startDate":"2021-03-07",
        "endDate":"2021-03-13",
        "metricSubValues":{
          "total_unique_installs_filter":{
            "country":{
              "USA":142867.0,
              "Ireland":3378.0,
              ...
              "Korea":162398.0 
            },
            "carrier":{"unknown":1437474.0},
            "rgn":{
              "Middle East & Africa":149305.0,
              "Asia Pacific":537159.0,
              "Europe":316615.0,
              "America":348903.0,
              "CIS":85473.0,
              "unknown":19.0
            },
            "device":{
              "Galaxy A20 ":255.0,
              ...
              "Galaxy S21 Plus 5G":16728.0,
              "Galaxy J2 Core":689.0,
              "Galaxy Tab A Plus (10.1)":347.0,
              "Galaxy A51 ":39.0 
            }
          }
        },
        "contentMetrics":{},
        "metricSummaries":{"total_unique_installs_filter":1437474.0}
      }
    ]
  },
  "noContentMetadata":true,
  "trendAggregation":"day",
  "periods":[{"endDate":"2021-03-14","startDate":"2021-03-08"}],
  "filters":{},
  "getBreakdownsByFilter":true,
  "getDailyMetric":false
}

  • Failure: Undefined API

      Status: 404 Not Found

View content metrics

Provides statistics about new downloads, sales, item purchases, average rating, and ratings volume for the specified app.

Request

POST /gss/query/contentMetric
Name Type Description
contentId string Required. The unique 12-digit identifier of the app.
metricIds string[] Required. The statistics you want to view about the specified app. If more than one metricIds is requested, separate each metricIds by a comma. The name in parentheses is where you would find similar data in the Galaxy Store Statistics system.

  • total_unique_installs_filter (New Downloads): The number of devices on which users download the app for the first time.
  • revenue_total (Sales): Total income the app has generated, including item sales.
  • revenue_iap_order_count (Item Purchases): Number of items purchased and number of cancelled payments.
  • daily_rat_score (Average Rating): Daily average rating this app has received across all ratings submitted where the rating is in .5 star increments (that is, a rating of 10 is equal to a five-star rating and a rating of 2 is equal to a one-star rating).

    Note: The cumulativeValue is the sum of all ratings within a period to that date. For example, if the specified period is from Jul 1 to Jul 7 and the date is Jul 3, the cumulativeValue is the sum of all ratings from Jul 1, Jul 2, and Jul 3.

    To calculate the average rating over the entire specified period, divide the daily_rat_score cumulativeValue of the last day in the period by the daily_rat_volumne cumulativeValue of the last day in the period.
  • daily_rat_volumne (Ratings Volume): The number of ratings submitted.

    Note: The cumulativeValue is the sum of the number of ratings within a period to that date. For example, if the specified period is from Jul 1 to Jul 7 and the date is Jul 3, the cumulativeValue is the sum of the number of ratings from Jul 1, Jul 2, and Jul 3.
periods[{current-period}, {prev-period}] JsonArray Required. Each period is a range of time, denoted by startDate and endDate, for which data is provided. Enter the startDate and endDate as yyyy-MM-dd. Typically used to view the most current data and compare it to the data from the previous time period.

Example:
[{"startDate":"2021-03-07","endDate":"2021-03-13"},{"startDate":"2021-02-28","endDate":"2021-03-06"}]
noBreakdown boolean Whether or not to provide statistics broken down by country or device for each metric.

  • true: Provide summary data only.
  • false: Provide statistics based on the filters specified in the filters[{country}, {device}] array attribute.
trendAggregation string How the data is aggregated: day, week, or month (for example, the total number of downloads each day over the specified time periods).
filters[{country}, {device}] JsonArray If noBreakdown is set to false, provide data by the specified countries and devices. If noBreakdown is set to false but no filters are entered, all non-zero data is provided.
country:[countries], device:[devices]

Example: "filters": {"device":["Galaxy S21 5G","Galaxy S10e"],"country":["Korea", "USA"]}

 
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-access-token>" \ 
  -d '{ \
  "contentId":"000007654321","periods":[{"startDate":"2021-03-08","endDate":"2021-03-14"}, {"startDate":"2021-03-01","endDate":"2021-03-07"}], "noBreakdown":true, "metricIds":["total_unique_installs_filter", "revenue_total", "revenue_iap_order_count", "daily_rat_score", "daily_rat_volumne"], "filters":{}, "trendAggregation":"day"}' \  
  "https://devapi.samsungapps.com/gss/query/contentMetric"

Response

  • Success

    Status: 200 Success

    {
  "metricIds":[
    "total_unique_installs_filter",
    "revenue_total",
    "revenue_iap_order_count",
    "daily_rat_score",
    "daily_rat_volumne"
  ],
  "data":{
    "periods":[
      {
        "endDate":"2021-03-06",
        "startDate":"2021-02-28",
        "000007654321":{
          "total_unique_installs_filter":{
            "dailyTrend":{
              "2021-03-05":{
                "value":361.0,
                "cumulativeValue":2014.0,
                "subValuesMap":null
              },
              ...
            },
            "value":2300.0,
            "summary":{}
          },
          "daily_rat_score":{
            "dailyTrend":{
              "2021-03-05":{
                "value":0.0,
                "cumulativeValue":0.0,
                "subValuesMap":null
              },
              ...
            },
            "value":0.0,
            "summary":{}
          },
          "revenue_iap_order_count":{
            "dailyTrend":{
              "2021-03-05":{
                "value":0.0,
                "cumulativeValue":0.0,
                "subValuesMap":null
              },
              ...
            },
            "value":0.0,
            "summary":{}
          },
          "daily_rat_volumne":{
            "dailyTrend":{
              "2021-03-05":{
                "value":0.0,
                "cumulativeValue":0.0,
                "subValuesMap":null
              },
              ...
            },
            "value":0.0,
            "summary":{}
          },
          "revenue_total":{
            "dailyTrend":{
              "2021-03-05":{
                "value":0.0,
                "cumulativeValue":0.0,
                "subValuesMap":null
              },
              ...
            },
            "value":0.0,
            "summary":{}
          }
        }
      },
      {
        "endDate":"2021-03-13",
        "startDate":"2021-03-07",
        "000007654321":{
          "total_unique_installs_filter":{
            "dailyTrend":{
              "2021-03-13":{
                "value":153.0,
                "cumulativeValue":1085.0,
                "subValuesMap":null
              },
              ...
            },
            "value":1085.0,
            "summary":{}
          },
          "daily_rat_score":{
            "dailyTrend":{
              "2021-03-13":{
                "value":0.0,
                "cumulativeValue":0.0,
                "subValuesMap":null
              },
              ...
            },
            "value":0.0,
            "summary":{}
          },
          "revenue_iap_order_count":{
            "dailyTrend":{
              "2021-03-13":{
                "value":0.0,
                "cumulativeValue":0.0,
                "subValuesMap":null
              },
              ...
            },
            "value":0.0,
            "summary":{}
          },
          "daily_rat_volumne":{
            "dailyTrend":{
              "2021-03-13":{
                "value":0.0,
                "cumulativeValue":0.0,
                "subValuesMap":null
              },
              ...
            },
            "value":0.0,
            "summary":{}
          },
          "revenue_total":{
            "dailyTrend":{
              "2021-03-13":{
                "value":0.0,
                "cumulativeValue":0.0,
                "subValuesMap":null
              },
              ...
            },
            "value":0.0,
            "summary":{}
          }
        }
      }
    ],
    "distinctValues":{},
    "content":{
      "content_name":"The best app ever!",
      ...
      "store_type":"Apps",
      "updated_date":"2021-03-02",
      "content":"000007654321",
      "status":"For Sale"
    }
  },
  "noBreakdown":true,
  "trendAggregation":"day",
  "contentId":"000007654321",
  "periods":[
    {"endDate":"2021-03-13","startDate":"2021-03-07"},
    {"endDate":"2021-03-06","startDate":"2021-02-28"}
  ],
  "filters":{"country":["Korea"], "device":["Galaxy S21 5G"]}
}

  • Failure: Content ID is required

    Status: 400 Bad Request

  • Failure: Undefined API

    Status: 404 Not Found