Data Kiosk Use Case Guide
How to use the Data Kiosk API.
API Version: 2023-11-15
What is the Data Kiosk API?
The Selling Partner API for Data Kiosk lets you submit GraphQL queries from a variety of schemas to help selling partners manage their businesses.
Key points
- 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.
- The data document contains the output in JSONL format when a successful request is processed with
- A
processingStatus
ofDONE
with noerrorDocumentId
ordataDocumentId
in the response of thegetQuery
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.
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:
Body parameter
Name | Type | Description | Required |
---|---|---|---|
query |
string | The GraphQL query that is compliant with the schema. A query can be at most 8,000 characters after unnecessary whitespace is removed. Refer to the schema to build your query. | Yes |
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}}}}"
}
Response
A successful response includes the following property:
Name | Type | Description |
---|---|---|
queryId |
string | The identifier for the query. This identifier is unique only in combination with a selling partner ID. |
Response example
{
"queryId": "012345678901"
}
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 Verify that the 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.
Path parameter
Name | Type | Description | Required |
---|---|---|---|
documentId |
string | The identifier for the query result document. The identifier is unique only in combination with a selling partner ID. | Yes |
Request example
GET https://sellingpartnerapi-na.amazon.com/dataKiosk/2023-11-15/documents/DOC-b8b0-4226-b4b9-0ee058ea5760
Response
A successful response includes the following:
Name | Type | Description |
---|---|---|
documentId |
string | The identifier for the query document. The identifier is unique only in combination with a selling partner ID. |
documentUrl |
string | A presigned URL that can be used to retrieve the Data Kiosk document. This URL expires after five minutes. If the Data Kiosk document is compressed, the Content-Encoding header will indicate the compression algorithm. |
Response example
{
"documentId": "DOC-b8b0-4226-b4b9-0ee058ea5760",
"documentUrl": "https://d34o8swod1owfl.cloudfront.net/SampleResult%2BKey%3DSample%2BINITVEC%3D58+fa+bf+a7+08+11+95+0f+c1+a8+c6+e0+d5+6f+ae+c8"
}
Save the documentUrl
for use 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.
Note: 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);
}
}
}
}
Updated about 2 months ago