Sending a Request
Once you have signed up for Amazon Associates program and Product Advertising API, you can start sending requests to the API. You can send request to Product Advertising API either using its SDKs (recommended) or using any simple HTTP client. In this section we talk about what makes up a request and we give sample code to send a request. Before we begin please make use of Scratchpad (UI tool), to send requests to API. This will validate your credentials as well as help you get sample request. It'll also help you form a request for API and help understand endpoints, headers, request payload which you can use while sending a request. Scratchpad also provides code snippets, which you can use or refer to form and send requests.
Contents
Request contents
Request to Product Advertising API has following main components: request payload, headers, signing (sent as part of Authorization header). Product Advertising API has several parameters/headers which depend on the target Amazon Locale. These common parameters are listed here: Common Request Parameters.
Request payload
Request payload is of JSON format. You can use or refer request payload section from scratchpad, to send sample request or use it to troubleshoot and match it with your machine generated payload.
Sample request payload
{
"Keywords": "Harry",
"Marketplace": "www.amazon.com",
"PartnerTag": "xyz-20",
"PartnerType": "Associates",
"Resources": ["Images.Primary.Small","ItemInfo.Title","Offers.Listings.Price"],
"SearchIndex": "All"
}
Headers
You need to send following set of mandatory headers, which are required by the API. Following are set of required headers and their use. Note: Header keys and values are case sensitive.
| Key | Details |
|---|---|
| host | The host value of the target locale to which you are sending requests. It varies with target Amazon locale. For example if you are sending request to US Locale then host value is webservices.amazon.com. For more details and valid values, refer Common Request Parameters |
| content-type | The type of the request content in the body, use application/json; charset=utf-8. |
| content-encoding | Provide amz-1.0 as value |
| x-amz-date | The date used to create the signature. We re-calculate the signature using this header value and match signature with one generated by you to authenticate you, for this we need date used in signing. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). Example: 20120325T120000Z. |
| x-amz-target | It signifies target operation of the request and is operation specific. A concatenation of the following strings:
x-amz-target: com.amazon.paapi5.v1.ProductAdvertisingAPIv1.SearchItems For more details and valid values refer Common Request Parameters->Target |
| Authorization | It includes following information: Algorithm you used for signing (AWS4-HMAC-SHA256), Credential scope (with your Access Key), list of signed headers and Calculated signature. The signature allows us to authenticate you. For more information, see Signature Version 4 Signing Process |
Example Request Header
Following snippet is an example request header for a SearchItems request.
POST / HTTP/1.1
host: webservices.amazon.com
content-type: application/json; charset=utf-8
content-encoding: amz-1.0
x-amz-date: 20160925T120000Z
x-amz-target: com.amazon.paapi5.v1.ProductAdvertisingAPIv1.SearchItems
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=&5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924a6f2b5d7;
Signing
You need to sign every request that you send, we use this signing to authenticate you. Signing is based on multiple values like access key, secret key, host, region, path, headers, HTTP method and payload to generate signature. Please refer to the following detailed documentation for further details https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html. It'll guide you with details of signing process, also helps you trouble-shoot.
If you're using SDKs, the request is automatically signed for you. However, make sure you specify host, region and your credentials while making a call to Product Advertising API. For more information, see Integrating with SDK.