AMALYZE Falcon API

research.product.histogram (POST)

Endpoint

Endpoint research.product.histogram returns the histogram data for a ASIN marketplace:

bestseller ranks
keyword counts
average ranking position
AMASCORE
number of reviews
rating
changes of bestseller badge

Endpoint

POST research.product.histogram

Example call

curl https://falcon.amalyze.com/<VERSION>/research.product.keywords \
-X POST \
-H "X-Falcon-Token: <YOUR-TOKEN-HERE>" \
-d '
{
	"metrics":[
		"ranks",
		"keywords.organic.count",
		"keywords.organic.average",
		"amascore",
		"reviews",
		"rating",
		"badges.bestseller"
	],
	"filters": {
		"asins": [
			{
				"asin": "B07BR1FNCV",
				"marketplace":"A1PA6795UKMFR9"
			}
		],
		"interval":"day",
		"start":"2018-11-03",
		"end":"2018-11-13"
	}
}
'

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

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

-X POST \

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

-d '

{

"metrics":[

"ranks",

"keywords.organic.count",

"keywords.organic.average",

"amascore",

"reviews",

"rating",

"badges.bestseller"

],

"filters": {

"asins": [

{

"asin": "B07BR1FNCV",

"marketplace":"A1PA6795UKMFR9"

}

],

"interval":"day",

"start":"2018-11-03",

"end":"2018-11-13"

}

'

JSON Payload

{
	"metrics":[
		"ranks",
		"keywords.organic.count",
		"keywords.organic.average",
		"amascore",
		"reviews",
		"rating"
	],
	"filters": {
		"asins": [
			{
				"asin": "B07BR1FNCV",
				"marketplace":"A1PA6795UKMFR9"
			}
		],
		"interval":"day",
		"start":"2018-11-03",
		"end":"2018-11-13"
	}
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

{

"metrics":[

"ranks",

"keywords.organic.count",

"keywords.organic.average",

"amascore",

"reviews",

"rating"

],

"filters": {

"asins": [

{

"asin": "B07BR1FNCV",

"marketplace":"A1PA6795UKMFR9"

}

],

"interval":"day",

"start":"2018-11-03",

"end":"2018-11-13"

}

Property	Type	Description	Further information	Version
`metrics`	array	Array containing the requested metric	`ranks`: the bestseller ranks for main and sub-categories `keywords.organic.count`: number of organic keywords the ASIN is ranking for `keywords.organic.average`: average position of organic keywords the ASIN is ranking for `amascore`the amascore `reviews`number of reviews `rating`products rating (stars) `badges.bestseller` indicates if the product has had a besteller badge (in search)	0.2.1
`filters`	object	Object containing the filter information	mandatory	0.2.1
`filters.asins`	array	Array containing the ASIN / marketplace combination	mandatory	0.2.1
`filters.asins.asin`	string	The ASIN for which ranking data is requested for	mandatory	0.2.1
`filters.asins.marketplace`	date	The marketplace-ID, for which ranking data is requested for.	madantory valid marketplace-IDs	0.2.1
`filters.interval`	string	The intervai, in wich the data shall be returned	mandatory valid intervals	0.2.1
`filters.start`	date	Start date in format YYYY-MM-DD	mandatory	0.2.1
`filters.end`	object	End+ date in format YYYY-MM-DD	mandatory	0.2.1

JSON Response

{
    "items": [
        {
            "dimensions": {
                "date": "2018-11-03"
            },
            "series": [
                {
                    "dimension": {
                        "asin": "B07BR1FNCV",
                        "marketplace": "A1PA6795UKMFR9"
                    },
                    "metrics": {
                        "ranks": [
                            {
                                "category": {
                                    "id": "340843031",
                                    "isMain": true
                                },
                                "rank": {
                                    "min": 123,
                                    "max": 123,
                                    "avg": 123
                                }
                            },
                            {
                                "category": {
                                    "id": "430221031",
                                    "isMain": false
                                },
                                "rank": {
                                    "min": 123,
                                    "max": 123,
                                    "avg": 123
                                }
                            }
                        ],
                        "amascore": null,
                        "keywords": {
                            "organic": {
                                "count": null,
                                "average": null
                            }
                        },
                        "reviews": {
                            "total": 106
                        },
                        "rating": {
                            "score": 4.5
                        },
                        "badges": {
                            "besteller": true
                        }
                    }
                }
            ]
        },
        {...},
        {...},
        {...},
        {
            "dimensions": {
                "date": "2018-11-13"
            },
            "series": [
                {
                    "dimension": {
                        "asin": "B07BR1FNCV",
                        "marketplace": "A1PA6795UKMFR9"
                    },
                    "metrics": {
                        "ranks": [],
                        "amascore": 45.819999694824,
                        "keywords": {
                            "organic": {
                                "count": 697,
                                "average": null
                            }
                        },
                        "reviews": {
                            "total": 107
                        },
                        "rating": {
                            "score": 4.6
                        },
                        "badges": {
                            "besteller": false
                        }

                    }
                }
            ]
        }
    ],
    "request": {
        "id": "b0c959cf-336e-46d0-ab64-c26fa32f8bd0",
        "took": 0.3593,
        "costs": 110,
        "remaining": 99890,
        "method": "research.product.histogram",
        "success": true,
        "error": {
            "code": null,
            "message": null,
            "hint": null
        }
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

{

"items": [

{

"dimensions": {

"date": "2018-11-03"

},

"series": [

{

"dimension": {

"asin": "B07BR1FNCV",

"marketplace": "A1PA6795UKMFR9"

},

"metrics": {

"ranks": [

{

"category": {

"id": "340843031",

"isMain": true

},

"rank": {

"min": 123,

"max": 123,

"avg": 123

}

},

{

"category": {

"id": "430221031",

"isMain": false

},

"rank": {

"min": 123,

"max": 123,

"avg": 123

}

],

"amascore": null,

"keywords": {

"organic": {

"count": null,

"average": null

}

},

"reviews": {

"total": 106

},

"rating": {

"score": 4.5

},

"badges": {

"besteller": true

}

]

},

{...},

{

"dimensions": {

"date": "2018-11-13"

},

"series": [

{

"dimension": {

"asin": "B07BR1FNCV",

"marketplace": "A1PA6795UKMFR9"

},

"metrics": {

"ranks": [],

"amascore": 45.819999694824,

"keywords": {

"organic": {

"count": 697,

"average": null

}

},

"reviews": {

"total": 107

},

"rating": {

"score": 4.6

},

"badges": {

"besteller": false

}

]

}

],

"request": {

"id": "b0c959cf-336e-46d0-ab64-c26fa32f8bd0",

"took": 0.3593,

"costs": 110,

"remaining": 99890,

"method": "research.product.histogram",

"success": true,

"error": {

"code": null,

"message": null,

"hint": null

}

Property	Type	Description
`items`	array	Array containing the returned histogram items
`items.dimensions`	object	bject containing the histogram item’s dimensions
`items.dimension.date`	date	String containing the date, according to the requested interval
`items.series`	array	Array containing the histogram item’s series
`items.series.dimension`	object	Object containing the serie’s dimensions
`items.series.dimension.asin`	string	String containing the ASIN
`items.series.dimension.marketplace`	string	String containing the marketplace id . valid marketplace ids
`items.series.metrics`	object	Object containing the series’ metrics according to the requested metrics
`items.series.metrics.ranks`	array	Array containing the bestseller ranks for each single category (only available if product is extended tracked)
`items.series.metrics.ranks.category`	object	Object containing information about the category
`items.series.metrics.ranks.category.id`	string	String containing categories id
`items.series.metrics.ranks.category.isMain`	boolean	Indicates, if category is main category (`true`) or sub category (`false`)
`items.series.metrics.ranks.rank`	object	Object containing the bestseller rank within the specific category
`items.series.metrics.ranks.rank.min`	float	The minimum beststeller rank within the specific category according to the selected interval
`items.series.metrics.ranks.rank.avg`	float	The average beststeller rank within the specific category according to the selected interval
`items.series.metrics.ranks.rank.max`	float	The maximium beststeller rank within the specific category according to the selected interval
`items.series.metrics.keywords`	object	Object containing information about the keyword rankings of an ASIN
`items.series.metrics.keywords.organic`	object	Object containing information about the organic keyword rankings of an ASIN
`items.series.metrics.keywords.organic.count`	integer	Number of keywords, the ASIN ranks (organic) for
`items.series.metrics.keywords.organic.average`	float	Average position of the (organic) keywords, the ASIN ranks for
`items.series.metrics.amascore`	float	ASINs AMSCORE
`items.series.metrics.reviews`	object	Object containing information about the number of reviews
`items.series.metrics.reviews.total`	integer	Number of reviews
`items.series.metrics.rating`	object	Object containing information about the rating (stars)
`items.series.metrics.rating.score`	float	Average rating (stars) for the ASIN
`items.series.metrics.badges`	object	Object containing information about the badges
`items.series.metrics.badges.bestseller`	boolean	Indicates, if the product has had a bestseller badge (within search)

Updates / Changes

Version	Description
0.2.3	`items.series.metrics.ranks.rank` is now an object containing `.min`, `.avg` and `.max` properties
	added `items.series.metrics.reviews`
	added `items.series.metrics.rating`
	added `items.series.metrics.badges`