AMALYZE Falcon API

research.products (POST)

Endpoint

Endpoint research.products returns the general information (title, bulletpoints, price, etc.) for a ASIN / keyword combination.

Method

Example call

curl https://falcon.amalyze.com/<VERSION>/research.products \
-X POST \
-H "X-Falcon-Token: <YOUR-TOKEN-HERE>" \
-d '
{
	"pagination": {
		"size": 1, 
		"page": 1
	}, 
	"filters": {
		"asins": [
			"B076T5Q41Z"
		], 
		"marketplaces": [
			"A1PA6795UKMFR9"
		]
	}, 
	"sorting": [
		{
			"column": "amazon.title",
			"direction": "asc"
		}
	]
}
'

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

-X POST \

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

-d '

{

"pagination": {

"size": 1,

"page": 1

"filters": {

"asins": [

"B076T5Q41Z"

"marketplaces": [

"A1PA6795UKMFR9"

]

"sorting": [

{

"column": "amazon.title",

"direction": "asc"

}

]

}

JSON Payload

{
	"pagination": {
		"size": 1, 
		"page": 1
	}, 
	"filters": {
		"asins": [
			"B076T5Q41Z"
		], 
		"marketplaces": [
			"A1PA6795UKMFR9"
		]
	}, 
	"sorting": [
		{
			"column": "amazon.title",
			"direction": "asc"
		}
	]
}

{

"pagination": {

"size": 1,

"page": 1

"filters": {

"asins": [

"B076T5Q41Z"

"marketplaces": [

"A1PA6795UKMFR9"

]

"sorting": [

{

"column": "amazon.title",

"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.marketplaces`	array	Array containing all the marketplaces to search in	valid marketplaces ids	0.1.12
`filters.asins`	array	Array containing the ASINs to search for	optional	0.1.12
`filters.parents`	array	Array containing the parent ASINs to search for	optional / not yet available	0.2.4
`filters.title`	string	The title to search for	optional	0.1.12
`filters.brands`	array	Array containing the brands to search for (full text search)	optional	0.1.12
`filters.brandsExact`	array	Array containing the brands to search for (exact match)	optional	0.1.12
`filters.merchants`	array	Array containing the merchant names to search for (full textsearch)	optional	0.1.12
`.filters.merchantsExact`	array	Array containing the merchant names to search for (exact match)	optional	0.1.12
`filters.merchantsId`	array	Array containing the merchant ids to search for	optional	0.1.12
`filters.available`	boolean	Filters for products that must (not) be available	optional	0.2.0
`filters.categories`	array	Array containing the category IDs to search for	deprecated	0.1.12
`filters.mainCategory`	array	Array containing the main category IDs to search for	optional	0.2.0
`filters.mainCategoryRank`	object	Object holding information about main categorys best seller rank	optional	0.2.0
`filters.mainCategoryRank.min`	integer	Number of minimum best seller rank for main category	optional	0.2.0
`filters.mainCategoryRank.max`	integer	Number of maximum best seller rank for main category	optional	0.2.0
`filters.subCategory`	array	array containing the sub category IDs to search for	optional	0.2.0
`filters.subCategoryRank`	object	Object holding information about sub categorys best seller rank	optional	0.2.0
`filters.subCategoryRank.min`	integer	Number of minimum best seller rank for sub category	optional	0.2.0
`filters.subCategoryRank.max`	integer	Number of maximum best seller rank for sub category	optional	0.2.0
`filters.prime`	boolean	Filters for products that must (not) be offered as prime	optional	0.1.12
`filters.advertisingSpa`	boolean	Filters for products that must (not) be advertising as sponsored product ads	optional	0.1.12
`filters.buyboxExists`	boolean	Filters for products that must (not) have a buybox	optional	0.1.12
`filters.query`	string	Fulltext search over all available fields	optional	0.1.12
`filters.types`	array	Array containing the product type	optional (see product type definition for more information)	0.1.12
`filters.release`	object	Object containing information about the release date	optional	0.2.0
`filters.release.start`	dateTime	The start date	optional (Format YYYY-MM-DD)	0.2.0
`filters.release.end`	dateTime	The end date	optional (Format YYYY-MM-DD)	0.2.0
`filters.competitors`	object	Object containing information about the competitors	optional / not yet available	0.1.12
`filters.competitors.min`	integer	Number of minimum competitors the products may have	optional / not yet available	0.1.12
`filters.competitors.max`	integer	Number of maximum competitors the products may have	optional / not yet available	0.1.12
`filters.price`	object	Object containing information about the products price	optional	0.1.12
`filters.price.min`	float	Minimum price the products must have	optional	0.1.12
`filters.price.max`	float	Maximum price the products must have	optional	0.1.12
`filters.optimization`	object	Object containing information about the products optimization	optional / not yet available	0.1.12
`filters.optimization.min`	float	Minimum (percentage) optimization the products must have	optional / not yet available	0.1.12
`filters.optimization.max`	float	Maximum (percentage) optimization the products must have	optional / not yet available	0.1.12
`filters.rating`	object	Object containing information about the products rating	optional	0.1.12
`filters.rating.min`	float	Minimum rating (stars) the products must have	optional	0.1.12
`filters.rating.max`	float	Maximum rating (stars) the products must have	optional	0.1.12
`filters.reviews`	object	Object containing information about the products reviews	optional	0.1.12
`filters.reviews.min`	integer	Minimum reviews the products must have	optional	0.1.12
`filters.reviews.max`	integer	Maximum reviews the products must have	optional	0.1.12
`filters.reviewsTops`	object	Object containing information about the reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTops.min`	integer	Minimum number of reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTops.max`	integer	Maximum number of reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTopsRating`	object	Object containing information about the average rating of the reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTopsRating.min`	float	Minimum average rating of reviews, directly shown on the product detail age	optional	0.2.0
`filters.reviewsTopsRating.max`	float	Maximum average rating of reviews, directly shown on the product detail age	optional	0.2.0
`filters.reviewsTopsDiffPerc`	object	Object containing information about the (relative) difference between products overall rating and average rating of the reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTopsDiffPerc.min`	float	Minimum relative difference between products overall rating and average rating of the reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTopsDiffPerc.max`	float	Maximum relative difference between products overall rating and average rating of the reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTopsDiffAbs`	object	Object containing information about the (absolute) difference between products overall rating and average rating of the reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTopsDiffAbs.min`	float	Minimum absolute difference between products overall rating and average rating of the reviews, directly shown on the product detail page	optional	0.2.0
`filters.reviewsTopsDiffAbs.max`	float	Maximum absolute difference between products overall rating and average rating of the reviews, directly shown on the product detail page	optional	0.2.0
`filters.keywordsOrganicPos`	object	Object containing the information about the average position of organic keywords	optional	0.1.15
`filters.keywordsOrganicPos.min`	integer	Minimum average position of organic keywords	optional	0.1.15
`filters.keywordsOrganicPos.max`	integer	Maximum average position of organic keywords	optional	0.1.15
`filters.keywordsOrganicCount`	object	Object containing the information about the number of organic keywords	optional	0.1.15
`filters.keywordsOrganicCount.min`	integer	Minimum number of organic keywords	optional	0.1.15
`filters.keywordsOrganicCount.max`	integer	Maximum number of organic keywords	optional	0.1.15
`filters.keywordsOrganicChoices`	object	Object containing information about the number of organic keywords, the product has the Choice badge	optional	0.4.0
`filters.keywordsOrganicChoices.min`	integer	Minimum number of organic keywords	optional	0.4.0
`filters.keywordsOrganicChoices.max`	integer	Maximum number of organic keywords	optional	0.4.0
`filters.statsOrganicImpressions`	object	Object containing the information about the searchVolumne for all the keywords the product ranks for	optional	0.1.15
`filters.statsOrganicImpressions.min`	integer	Minimum searchVolume	optional	0.1.15
`filters.statsOrganicImpressions.max`	integer	Maximum searchVolume	optional	0.1.15
`filters.advertisementsSPA`	array	Array containing the ASINs being advertised as sponsored product on products detail page	optional	0.2.0
`filters.similaritiesFvtWidget`	array	Array containing the ASINs which have been frequently viewed together with product	optional	0.2.0
`filters.similaritiesFbtWidget`	array	Array containing the ASINs which have been purchased frequently together with product	optional	0.2.0
`filters.similaritiesFbtDirect`	array	Array containing the ASINs which have been purchased frequently together and can be put together on shopping cart	optional	0.2.0
`filters.tags`	array	Array containing the tags to search for	optional	0.5.0
`filters.unitPrice`	string	String containing the price per unit (full text)	optional	0.6.0
`sorting`	array	Array containing the sorting information		0.1.12
`sorting.column`	string	The column to sort	`score`: sort by internal matching score `amazon.asin` `amazon.parent` `amazon.title`: sort by products title `amazon.reviews.total`:sort by number of reviews `amazon.reviews.score`: sort by average rating `amazon.reviews.tops.total`: sort by number of reviews, displayed directly on products detail page code>amazon.reviews.tops.diff.abs: sort by (absolute) difference between products overall rating and average rating of reviews, directly displayed on product detail page `amazon.reviews.tops.diff.perc`: sort by (relative) difference between products overall rating and average rating of reviews, directly displayed on product detail page `amazon.brand.name`: sort by brand name `amazon.buybox.merchant.name`: sort by merchant name owning the buybox `amazon.buybox.prices.rrp`: sort be recommended retail price `amazon.buybox.prices.offer`: sort by offer price `amazon.category.rank`:order by main categorys bestseller rank `amazon.release`: sort by release date (available on amazon since …) `amazon.categories.rank`:order by subcategory bestseller rank `amalyze.keywords.organic.pos`: sort by average position of organic keywords `amalyze.keywords.organic.count`: sort by number of organic keywords `amalyze.keywords.organic.choices`: sort by number of organic keywords the product has the Choice badge `amalyze.stats.organic.impressions`: sort by monthy impressions, all the keywords the product ranks for, generate code>amazon.buybox.unitPrice: sort by price per unit	0.1.12
`sorting.direction`	string	The direction to sort	valid direction values	0.1.12

JSON Response

{
    "items": [
        {<product>}
    ],
    "pagination": {
        {"filtered": 123}
    },
    "request": {
        "id": "708f6b29-0c41-4cd1-ba9a-4346a66fedf9",
        "took": 0.0571,
        "costs": 1,
        "remaining": 99999,
        "method": "research.products",
        "success": true,
        "error": {
            "code": null,
            "message": null,
            "hint": null
        }
    }
}

{

"items": [

{<product>}

"pagination": {

{"filtered": 123}

"request": {

"id": "708f6b29-0c41-4cd1-ba9a-4346a66fedf9",

"took": 0.0571,

"costs": 1,

"remaining": 99999,

"method": "research.products",

"success": true,

"error": {

"code": null,

"message": null,

"hint": null

}

Property	Type	Description
`items`	array	Array containing the product items (for more information see product object definition
`pagination`	object	The pagination object (see Pagination for more information)
`request`	object	The request information object (see Request information for more information)

Updates / Changes

Version	Description
0.6.0	`filters.unitPrice` added
	`amazon.buybox.unitPrice` added to `sorting.column`
0.5.0	`filters.tags` added
0.4.0	`filters.keywordsOrganicChoices` added
	`amalyze.keywords.organic.choices` added to `sorting.column`
0.2.4	`filters.parents` added
	`sorting.amazon.parent` added
0.2.0	`filters.available` added
	`filters.mainCategory` added
	`filters.mainCategoryRank` added
	`filters.mainCategoryRank.min` added
	`filters.mainCategoryRank.max` added
	`filters.subCategory` added
	`filters.subCategoryRank` added
	`filters.subCategoryRank.min` added
	`filters.subCategoryRank.max` added
	`filters.release` added
	`filters.release.start` added
	`filters.release.end` added
	`filters.bsr` removed
	`filters.bsr.min` removed
	`filters.bsr.max` removed
	`filters.reviewsTops` added
	`filters.rreviewsTops.min` added
	`filters.rreviewsTops.max` added
	`filters.reviewsTopsRating` added
	`filters.reviewsTopsRating.min` added
	`filters.reviewsTopsRating.max` added
	`filters.reviewsTopsDiffPerc` added
	`filters.reviewsTopsDiffPerc.min` added
	`filters.reviewsTopsDiffPerc.max` added
	`filters.reviewsTopsDiffAbs` added
	`filters.advertisementsSPA` added
	`filters.similaritiesFvtWidget` added
	`filters.similaritiesFbtWidget` added
	`filters.similaritiesFbtDirect` added
	`sorting.amazon.reviews.tops.total` added
	`sorting.amazon.reviews.tops.diff.abs` added
	`sorting.amazon.reviews.tops.diff.perc` added
	`sorting.amazon.category.rank` added
	`sorting.amazon.categories.rank` added
	`sorting.amazon.release` added
	`amazon.category.id` returns now real data
	`amazon.category.bsr` returns now real data
	`amazon.category.name` returns now real data
	`amazon.categories` returns now real data
	`amazon.categories.id` added
	`amazon.categories.bsr` added
	`amazon.categories.name` added
	`amazon.attributes` returns now real data
	`amazon.attributes.size` returns now real data
	`amazon.attributes.color` returns now real data
	`amazon.attributes.weight` returns now real data
	`amazon.attributes.weight.item` returns now real data
	`amazon.attributes.weight.package` returns now real data
	`amazon.attributes.model` added
	`amazon.attributes.batteries` added
	`amazon.attributes.custom` returns now real data
	`amazon.attributes.custom.key` added
	`amazon.attributes.custom.value` added
	`amazon.similarities` added
	`amazon.similarities.fvt` added
	`amazon.similarities.fvt.widget` added
	`amazon.similarities.fbt` added
	`amazon.similarities.fbt.widget` added
	`amazon.similarities.fbt.direct` added
	`amazon.available` returns now real data
0.1.15	renamed to `research.products`
	`amalyze.keywords.organic.count` returns now real data
	`amalyze.keywords.organic.pos` returns now real data
	`amalyze.stats.organic.impressions` returns the aggregated searchvolume for all the keywords, the product is ranking for
	`amazon.reviews.total` added to sorting parameters
	`amazon.reviews.score` added to sorting parameters
	`amazon.brand.name` added to sorting parameters
	`amazon.buybox.merchant.name` added to sorting parameters
	`amazon.buybox.prices.rrp` added to sorting parameters
	`amazon.buybox.prices.offer` added to sorting parameters
	`amalyze.buybox.organic.pos` added to sorting parameters
	`amalyze.buybox.organic.count` added to sorting parameters
	`amalyze.stats.organic.impressions` added to sorting parameters
	`filters.keywordsOrganicPos` added
	`filters.keywordsOrganicCount` added
	`filters.statsOrganicImpressions` added
0.1.13	added property `filters.merchantsExact`
	added property `filters.merchantsId`
	added property `filters.brandsExact`
0.1.12	renamed property `filters.amalyze.generic` to `filters.query`