addKeywordTask: Keyword Search Data API

Submit keywords to collect search results (3 pages by default; use page to collect up to 20), returning each ASIN’s position and placement type (SP ad / Amazon’s Choice / Best Seller / organic).

POST https://openapi.ksicdata.com/api/addKeywordTask

Request parameters

ParameterTypeRequiredDescription
keywordstringYesSearch keyword, e.g. ssd; must be shorter than 200 characters
pageintegerNoMaximum number of result pages to collect, 1-20; defaults to 3
regionstringYesMarketplace code, e.g. us — see supported marketplaces
zipCodestringYesDelivery postal code (required) — simulates a local delivery address

Request example

JSON
[
  {
    "keyword": "ssd",
    "page": 10,
    "region": "us",
    "zipCode": "10001"
  }
]
cURL example (click to expand)
cURL
curl -X POST "https://openapi.ksicdata.com/api/addKeywordTask" \
  -H "Content-Type: application/json" \
  -H "ks-token: YOUR_TOKEN" \
  -d '[
    {
      "keyword": "ssd",
      "page": 10,
      "region": "us",
      "zipCode": "10001"
    }
  ]'

Response example

JSON
{
  "code": 0,
  "msg": "请求成功",
  "t": 1735891200000
}
Collected data sample (click to expand)
JSON
{
    "keyword": "ssd",
    "page": 1,
    "pageSize": 16,
    "total": 35114,
    "date": 1788933441091,
    "data": [
        { "asin": "B09TVXVMVL", "type": 3 },
        { "asin": "B0BHJJ9Y77", "bought": "6K+", "type": 4 },
        { "asin": "B08HN37XC1", "bought": "7K+", "type": 5 },
        { "asin": "B0874XN4D8", "bought": "3K+", "type": 6 }
    ],
    "spProduct": [
        { "asin": "B09TVXVMVL", "info": { "widgetName": "sp_atf", "adId": "301470447530102", "adIndex": "0" } }
    ],
    "sbInfo": [
        { "asins": ["B0CM8W1S8K", "B0CM63ZP2Y"], "info": [{ "adId": "301302846015102", "title": "fanxiang" }] }
    ],
    "sbvProduct": [
        { "adId": "301199430453502", "asins": ["B0DX2G349M", "B0DX2DPJZ5"], "widgetType": "video-product-collection" }
    ],
    "relatedSearches": ["ssd 2tb", "pc case", "ram", "ssd m.2"],
    "brands": ["Samsung", "Sandisk", "Kingston", "Crucial"],
    "sellers": [{ "id": "ATVPDKIKX0DER", "name": "Amazon.com" }]
}

Returned fields

The complete field reference (with screenshots) lives in the API reference appendix — 15 keyword fields.

View the full field reference (with screenshots)

Every endpoint uses the https://openapi.ksicdata.com/api prefix, accepts a JSON array over POST, authenticates with ks-token and allows up to 2000 items per request.

FAQ

How many result pages can be collected per keyword?

The first 3 pages by default. Pass page to choose how many pages to collect — 1 to 20; when omitted the task collects 3 pages.

How does the page parameter work?

page is an Integer meaning the maximum number of result pages to collect (1-20). page=10 collects the first 10 pages of that keyword, returned page by page.

Is there a keyword length limit?

Keywords must be shorter than 200 characters; longer values return error 10003.

Why does the SP ad count vary?

Ad delivery depends on account environment, postal code and timing, so the number of SP ads collected varies between runs.

Which marketplaces are unsupported?

Keyword tasks are not supported for South Africa (za) and return error 10005.

Ready to get your Amazon data?

Scan the QR code for a custom quote and a free data sample.

WeChat customer service QR code

Scan the QR code to contact us

Get your custom quote and technical consultation

Or email us at
deepsleep@kszcdata.cn