Data Kiosk API v2023-11-15 Use Case Guide

The Selling Partner API for Data Kiosk lets you submit GraphQL queries from a variety of schemas to help selling partners manage their businesses.

Data Kiosk currently hosts Seller Sales and Traffic Data. Find details of the dataset in the schema explorer.

Data Kiosk is available globally in all SP-API Regions, including NA, EU, and FE.

Key features

• Data Kiosk can return a data document or an error document in the response of the getQuery operation. It can also return no document in the case that the query was successful but no data was returned.
  • The data document contains the output in JSONL format when a successful request is processed with DONE processing status.
  • The error document is in JSON format and contains the error message for an unsuccessful request with FATAL processing status.
• A processingStatus of DONE with no errorDocumentId or dataDocumentId in the response of the getQuery operation means that the request completed with no data or that there is no data for the given date range. Retry the request with different parameters.
• The Data Kiosk API does not support query scheduling.
• The Data Kiosk API does not support query backlogging. Data Kiosk limits the number of concurrent non-terminal queries per selling partner and per GraphQL query.

⭐

Tip

To request new data availability, you can submit your feedback on GitHub by opening an issue with the Data Request label.

You can find details of all the datasets available in Data Kiosk in the Data Kiosk Schema Explorer. New dataset launch announcements are posted to the Selling Partner API announcements page.

Data Kiosk API versus Reports API

Some features of Data Kiosk that differentiate it from Reports include:

• Detailed, interactive documentation: All data set schemas and data field definitions within Data Kiosk are publicly available. Data Kiosk also provides an interactive Schema Explorer complete with documentation and a query builder, which allows you to build custom queries to request custom reports.
• Domain-based datasets: Data Kiosk uses GraphQL, which allows dynamic report generation and advanced filtering and querying capabilities. You no longer have to call multiple reports, slice, and reconstruct them to create the schema that suits your needs.
• Schema updates: Data Kiosk uses GraphQL for a schema-first approach, which allows for continuous evolution of interfaces and safe data field updates. In this way, report schemas can be updated without breaking your integration.
• Reporting format: Data Kiosk provides all results in JSONL (JSON Lines) format, reducing the complexity of parsing.
• Pagination: Data Kiosk provides a nextToken that can be used in subsequent requests to retrieve the next page of data when size limits are exceeded.
• Security: Data Kiosk request visibility is limited to requests submitted by a given application, ensuring the security of selling partner data.

In addition to this, Data Kiosk only allows one request per query / selling partner / application combination. If there is already a pending request for a given query / selling partner / application combination, the createQuery request will fail.

📘

Note

Data Kiosk has all the functionality that the Reports API currently has and more. Reports within the Reports API will be deprecated after they are onboarded to Data Kiosk. You can find up-to-date deprecation dates in the SP-API deprecations table. Eventually, Data Kiosk will be the standard reporting platform for selling partner data.

Data Kiosk and SP-API roles

Each field available with Data Kiosk requires a certain role. Data Kiosk determines whether the requester has the required roles for each field in the query upon query creation. This authorization paradigm is much more granular than the Reports API. Additionally, queries are only visible to the requester.

Data Kiosk follows the standard role assignment and approval guidelines for all Selling Partner APIs. To find details of Selling Partner API roles and the approval process, refer to Roles in the Selling Partner API.

Tutorial: Request and filter data with a GraphQL query

This tutorial describes how to request and filter data with a GraphQL query.

Prerequisites

To complete this tutorial you will need:

• The appropriate role for the data you're requesting. This tutorial uses Sales and Traffic data in its examples, which requires the Brand Analytics role.

Step 1: Create a query request

Create an async query request by specifying the query. The query must be a valid GraphQL query which adheres to the schema. The query input parameters can be modified as desired and response fields can be included or excluded in any order.

Call the createQuery operation, providing the query in the body.

Request examples

Example 1: Create a query request for salesAndTrafficByDate to get a subset of fields in the response.

POST https://sellingpartnerapi-na.amazon.com/dataKiosk/2023-11-15/queries
{
  "query": "{analytics_salesAndTraffic_2023_11_15{salesAndTrafficByDate(startDate:\"2023-01-01\" endDate:\"2023-10-31\" aggregateBy:DAY marketplaceIds:[\"ATVPDKIKX0DER\"]){endDate marketplaceId startDate traffic{averageOfferCount browserPageViews averageParentItems browserPageViewsB2B browserSessions}sales{averageSalesPerOrderItem{amount currencyCode}averageSalesPerOrderItemB2B{amount currencyCode}averageSellingPrice{amount currencyCode}claimsGranted refundRate unitsOrderedB2B unitsRefunded unitsShipped}}}}"
}

Example 2: Create a query request for salesAndTrafficByAsin to get a subset of fields in the response.

POST https://sellingpartnerapi-na.amazon.com/dataKiosk/2023-11-15/queries
{
  "query": "{analytics_salesAndTraffic_2023_11_15{salesAndTrafficByAsin(startDate:\"2023-01-01\" endDate:\"2023-10-31\" aggregateBy:PARENT marketplaceIds:[\"ATVPDKIKX0DER\"]){childAsin endDate marketplaceId parentAsin sales{orderedProductSales{amount currencyCode}totalOrderItems totalOrderItemsB2B}sku startDate traffic{browserPageViews browserPageViewsB2B browserPageViewsPercentage browserPageViewsPercentageB2B browserSessionPercentage unitSessionPercentageB2B unitSessionPercentage}}}}"
}

Step 2: Confirm that query processing has completed

After you call the createQuery operation, Amazon receives the request and begins processing the query. Confirm that processing has completed before you continue. To confirm that the query processing is complete, refer to Tutorial: Verify that query processing is complete.

Step 3: Get information required to retrieve the query result

Call the getDocument operation to get the information required for retrieving the query result document's contents. This includes a pre-signed URL for the document. If the document is compressed, the Content-Encoding header will show the compression algorithm. Note that this differs from the way the Reports API provides information on compression.

You will use the documentUrl from the response in the following step.

Step 4: Download the document

You must download the query document using the information returned in Step 3.

The following sample code demonstrates how to download a Data Kiosk document. Use the documentUrl value from the previous step as the argument for the url parameter of the download method of the DownloadExample class.

❗️

Warning

You must always maintain encryption at rest. Unencrypted query result document content must never be stored on disk, even temporarily, because the query result document can contain sensitive information. The following sample code demonstrates this principle.

// DownloadExample.java
// This example is for use with the Selling Partner API for Data Kiosk, Version: 2023-11-15

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;

import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;
import com.squareup.okhttp.ResponseBody;

/**
 * Example that downloads a Data Kiosk document.
 */
public class DownloadExample {

    public static void main(String[] args) {
        String url = "<URL from the getDocument response>";

        DownloadExample obj = new DownloadExample();
        try {
            obj.download(url);
        } catch (IOException e) {
            // Handle exceptions here.
            e.printStackTrace();
        }
    }

    /**
     * Download the document from the given Amazon Simple Storage Service (Amazon S3) URL.
     *
     * @param url the signed Amazon S3 URL to retrieve the document from.
     * @throws IOException when there is an error reading the response.
     */
    public void download(String url) throws IOException {
        OkHttpClient httpclient = new OkHttpClient();
        Request request = new Request.Builder()
                .url(url)
                .get()
                .build();

        Response response = httpclient.newCall(request).execute();
        if (!response.isSuccessful()) {
            System.out.printf("Call to download content was unsuccessful with response code: %d and message: %s%n",
                    response.code(), response.message());
            return;
        }

        try (ResponseBody responseBody = response.body();
              InputStream inputStream = responseBody.byteStream();
              // Note: If the Data Kiosk document is compressed, the 'Content-Encoding' header will indicate the
              // compression algorithm. Most HTTP clients are capable of automatically decompressing downloaded files
              // based on the 'Content-Encoding' header.
              // More Information: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding
              //
              // The OkHttp client will automatically set the "Accept-Encoding" header and respect the
              // "Content-Encoding" header, so it is not required to unzip the stream.
              // For clients which do not automatically decompress, wrapping the stream in a GZIP stream may be
              // required, for example:
              // InputStream unzippedInputStream = new GZIPInputStream(inputStream);
              InputStreamReader inputStreamReader = new InputStreamReader(inputStream, StandardCharsets.UTF_8);
              BufferedReader reader = new BufferedReader(inputStreamReader)) {
            String line;
            while ((line = reader.readLine()) != null) {
                // Process line by line.
                System.out.println(line);
            }
        }
    }
}

Tutorial: Verify that query processing is complete

After you call the createQuery operation, Amazon receives the request and begins processing the query. This tutorial describes how to verify that processing has completed.

Step 1. Monitor the processing status

Periodically call the getQuery operation, passing the queryId value you received from createQuery, until the response contains a processingStatus value of one of the following:

• CANCELLED
• DONE
• FATAL

The response also includes one of the following:

• A dataDocumentId value if data is available as a result of the query.
• An errorDocumentId value if there is an error while processing the query.
• Neither of these when there is no data returned as a result of processing the query.

If processingStatus is IN_PROGRESS or IN_QUEUE, then processing has not ended, and you should continue to poll the getQuery operation until processingStatus is CANCELLED, DONE or FATAL.