AMALYZE Falcon API

research.product.keywords (POST)

Endpoint

Endpoint research.product.keywords returns the organic keywords the ASIN is ranking for.

Method

POST research.product.keywords

Example call

curl https://falcon.amalyze.com/<VERSION>/research.product.keywords \
-X POST \
-H "X-Falcon-Token: <YOUR-TOKEN-HERE>" \
-d '
{
	"pagination": {
		"page": 1, 
		"size": 1
	}, 
	"filters": {
		"asin": "B0041MP2YC", 
		"marketplace": "A1PA6795UKMFR9"
	}, 
	"sorting": [
		{
			"column": "keyword",
			"direction": "asc"
		}
	]
}
'

curl https://falcon.amalyze.com/<VERSION>/research.product.keywords \

-X POST \

-H "X-Falcon-Token: <YOUR-TOKEN-HERE>" \

-d '

{

"pagination": {

"page": 1,

"size": 1

"filters": {

"asin": "B0041MP2YC",

"marketplace": "A1PA6795UKMFR9"

"sorting": [

{

"column": "keyword",

"direction": "asc"

}

]

}

JSON Payload

{
	"pagination": {
		"page": 1, 
		"size": 1
	}, 
	"filters": {
		"asin": "B0041MP2YC", 
		"marketplace": "A1PA6795UKMFR9"
	}, 
	"sorting": [
		{
			"column": "keyword",
			"direction": "asc"
		}
	]
}

{

"pagination": {

"page": 1,

"size": 1

"filters": {

"asin": "B0041MP2YC",

"marketplace": "A1PA6795UKMFR9"

"sorting": [

{

"column": "keyword",

"direction": "asc"

}

]

}

Property	Type	Description	Further information	Version
`pagination`	object	Object containing the pagination information	pagination object definition	0.1.12
`filters`	object	Object containing the filter information		0.1.12
`filters.query`	string	Fulltext search over all available fields	optional	0.1.12
`filters.asin`	string	The ASIN for which ranking data is requested for		0.1.12
`filters.marketplace`	date	The marketplace-ID, for which ranking data is requested for.	valid marketplace-IDs	0.1.12
`filters.keywordExact`	string	Only return items, matching (exact) the required keyword	optional	0.1.12
`filters.keywordPhrase`	string	Only return items, matching (phrase) the required keyword	optional	0.1.12
`filters.positionOld`	object	Object containing the conditions regarding the old ranking values	optional	0.1.12
`filters.positionOld.min`	integer	Return only items, where the old ranking position was greater or equal x	optional	0.1.12
`filters.positionOld.max`	integer	Return only items, where the old ranking position was less or equal x	optional	0.1.12
`filters.positionNew`	object	Object containing the conditions regarding the current ranking values	optional	0.1.12
`filters.positionNew.min`	integer	Return only items, where the current ranking position was greater or equal x	optional	0.1.12
`filters.positionNew.max`	integer	Return only items, where the current ranking position was less or equal x	optional	0.1.12
`filters.statsImpressions`	object	Object containing the searchVolume for this keyword	optional	0.1.15
`filters.statsImpressions.min`	integer	Return only items, where the monthly searchVolume is greater or equal x	optional	0.1.15
`filters.statsImpressions.max`	integer	Return only items, where the monthly searchVolume is less or equal x	optional	0.1.15
`filters.types`	array	Return only keywords, matching the criteria	`up`: returns only keywords the ranking did improve `down`: returns only keywords the ranking did decline `new`: returns only new keywords `lost`: returns only lost keywords `equal`: returns only keywords the ranking did not change	0.1.12
`filters.choice`	boolean	Return only keywords, for which the specific ASIN has the "Choice Badge"	optional `true` `false`	0.3.0
`sorting`	array	Array containing the sorting information		0.1.12
`sorting.column`	string	The column to sort	`score`: sort by the internal score `keyword`: sort by the keyword alphabetically `position.old`: sort by the old position `position.new`: sort by the new position `change`: sort by the type of change `stats.salesRate`: sort by salesRate `stats.conversionsRate`: sort by conversionsRate `choice` `: sort by keywords, the ASIN owns the choice badge`	0.1.12
`sorting.direction`	string	The direction to sort	valid direction values	0.1.12

JSON Response

{
	"items": [
		{<keywordranking>}
	],
	"pagination": {
		"filtered": 245
	},
	"request": {
		"id": "ec0c1c94-d355-413f-813d-74827489c797",
		"took": 0.4768,
		"costs": 1,
		"remaining": 99999,
		"method": "research.product.keywords.get",
		"success": true,
		"error": {
			"code": null,
			"message": null,
			"hint": null
		}
	}
}

{

"items": [

{<keywordranking>}

"pagination": {

"filtered": 245

"request": {

"id": "ec0c1c94-d355-413f-813d-74827489c797",

"took": 0.4768,

"costs": 1,

"remaining": 99999,

"method": "research.product.keywords.get",

"success": true,

"error": {

"code": null,

"message": null,

"hint": null

}

Property	Type	Description
`items`	array	The keywords for the requested ASIN (see keywordranking object definition for more information)
`pagination`	object	The pagination object (see request information object definition for more information
`request`	object	The request information object (see request information object definition for more information

Updates / Changes

Version	Description
0.3.0	added `filters.choice` to request
	added `choice as valid sorting.column option`
	added `choice` to response
0.1.15	`stats` added to response
	`stats.impressions` added to response
	`stats.salesRate` added to response
	`stats.impressions` added to response
	`statsImpressions` added to filters
	`stats.salesRate` added to sorting
	`stats.conversionsRate` added to sorting
	`stats.impressions` added to sorting