AMALYZE Falcon API

research.keyword.histogram (POST)

Endpoint

Endpoint research.keyword.histogram returns date histogram including metrics (e.g. searchVolume) for keywords / marketplaces

Method

POST research.keyword.histogram

Example call

curl https://falcon.amalyze.com/<VERSION>/research.keyword.histogram \
-X POST \
-H "X-Falcon-Token: <YOUR-TOKEN-HERE>" \
-d '
{
	"filters": {
		"keywords": [
			{
				"keyword": "vitamin d",
				"marketplace": "A1PA6795UKMFR9"
			},
			{
				"keyword": "vitamin e",
				"marketplace": "A1PA6795UKMFR9"
			}			
		],
		"start": "2018-01-01",
		"end": "2018-12-31",
		"interval": "day"
	},
	"metrics": [
		"searchVolume"
	]
}'

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

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

-X POST \

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

-d '

{

"filters": {

"keywords": [

{

"keyword": "vitamin d",

"marketplace": "A1PA6795UKMFR9"

},

{

"keyword": "vitamin e",

"marketplace": "A1PA6795UKMFR9"

}

],

"start": "2018-01-01",

"end": "2018-12-31",

"interval": "day"

},

"metrics": [

"searchVolume"

]

}'

JSON Payload

{
	"filters": {
		"keywords": [
			{
				"keyword": "vitamin d",
				"marketplace": "A1PA6795UKMFR9"
			},
			{
				"keyword": "vitamin e",
				"marketplace": "A1PA6795UKMFR9"
			}			
		],
		"start": "2018-01-01",
		"end": "2018-12-31",
		"interval": "day"
	},
	"metrics": [
		"searchVolume"
	]
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

{

"filters": {

"keywords": [

{

"keyword": "vitamin d",

"marketplace": "A1PA6795UKMFR9"

},

{

"keyword": "vitamin e",

"marketplace": "A1PA6795UKMFR9"

}

],

"start": "2018-01-01",

"end": "2018-12-31",

"interval": "day"

},

"metrics": [

"searchVolume"

]

}

Property	Type	Description	Further information
`filters`	object	Object containing the filter information
`filters.start`	date	Sart date in format YYYY-MM-DD	mandatory
`filters.end`	date	End date in format YYYY-MM-DD	mandatory
`filters.interval`	string	The interval, in which the data shall be returned	mandatory. valid intervals
`filters.keywords`	array	Array containing the keywords	mandatory
`filters.keywords.keyword`	string	String containing the keyword	mandatory
`filters.keywords.marketplace`	string	String containing the marketplace	mandatory. valid marketplaces
`metrics`	array	Array containing the returned metrics	mandator `searchVolume`

JSON Response

{
    "items": [
        {
            "dimensions": {
                "date": "2018-08-21"
            },
            "series": [
                {
                    "dimension": {
                        "keyword": "vitamin d",
                        "marketplace": "A1PA6795UKMFR9"
                    },
                    "metrics": {
                        "searchVolume": 2947
                    }
                },
                {
                    "dimension": {
                        "keyword": "vitamin e",
                        "marketplace": "A1PA6795UKMFR9"
                    },
                    "metrics": {
                        "searchVolume": 1085
                    }
                }
            ]
        },
        {
            "dimensions": {
                "date": "2018-08-25"
            },
            "series": [
                {
                    "dimension": {
                        "keyword": "vitamin d",
                        "marketplace": "A1PA6795UKMFR9"
                    },
                    "metrics": {
                        "searchVolume": 2863
                    }
                },
                {
                    "dimension": {
                        "keyword": "vitamin e",
                        "marketplace": "A1PA6795UKMFR9"
                    },
                    "metrics": {
                        "searchVolume": 1082
                    }
                }
            ]
        },
        {
            "dimensions": {
                "date": "2018-09-03"
            },
            "series": [
                {
                    "dimension": {
                        "keyword": "vitamin d",
                        "marketplace": "A1PA6795UKMFR9"
                    },
                    "metrics": {
                        "searchVolume": 3399
                    }
                },
                {
                    "dimension": {
                        "keyword": "vitamin e",
                        "marketplace": "A1PA6795UKMFR9"
                    },
                    "metrics": {
                        "searchVolume": 1155
                    }
                }
            ]
        }
    ],
    "request": {
        "id": "ec830959-3d10-4d59-9538-c65fd2e05608",
        "took": 0.3805,
        "costs": 60,
        "remaining": 99940,
        "method": "research.keyword.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

{

"items": [

{

"dimensions": {

"date": "2018-08-21"

},

"series": [

{

"dimension": {

"keyword": "vitamin d",

"marketplace": "A1PA6795UKMFR9"

},

"metrics": {

"searchVolume": 2947

}

},

{

"dimension": {

"keyword": "vitamin e",

"marketplace": "A1PA6795UKMFR9"

},

"metrics": {

"searchVolume": 1085

}

]

},

{

"dimensions": {

"date": "2018-08-25"

},

"series": [

{

"dimension": {

"keyword": "vitamin d",

"marketplace": "A1PA6795UKMFR9"

},

"metrics": {

"searchVolume": 2863

}

},

{

"dimension": {

"keyword": "vitamin e",

"marketplace": "A1PA6795UKMFR9"

},

"metrics": {

"searchVolume": 1082

}

]

},

{

"dimensions": {

"date": "2018-09-03"

},

"series": [

{

"dimension": {

"keyword": "vitamin d",

"marketplace": "A1PA6795UKMFR9"

},

"metrics": {

"searchVolume": 3399

}

},

{

"dimension": {

"keyword": "vitamin e",

"marketplace": "A1PA6795UKMFR9"

},

"metrics": {

"searchVolume": 1155

}

]

}

],

"request": {

"id": "ec830959-3d10-4d59-9538-c65fd2e05608",

"took": 0.3805,

"costs": 60,

"remaining": 99940,

"method": "research.keyword.histogram",

"success": true,

"error": {

"code": null,

"message": null,

"hint": null

}

Property	Type	Description
`items`	array	Array containing the keyword histogram items
`items.dimension`	object	Object 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.keyword`	string	String containing the series’ keyword
`items.series.dimension.marketplace`	string	String containing the series’ marketplace Id
`items.series.metrics`	object	Object containing the series’ metrics according to the requested metrics
`request`	object	The request information object (see request information object definition for more information)