AMALYZE Falcon API

research.products.keywords.rankings (POST)

Endpoint

Endpoint research.products.keywords.rankings returns the historical keyword positions for a ASIN / keyword / marketplace combination.

By default each keyword is queried at least once per week. Depending on its volatility (how often the results of keyword vary), the query interval will be algorithmical adopted.

Method

POST research.products.keywords.rankings

Example call

curl https://falcon.amalyze.com/<VERSION>/research.products.keywords.rankings \
-X POST \
-H "X-Falcon-Token: <YOUR-TOKEN-HERE>" \
-d '
{
	"filters": {
		"start": "2018-01-01", 
		"end": "2018-12-31", 
		"interval": "year"
	}, 
	"rankings": [
		{
			"keyword": "fatburner", 
			"marketplace": "A1PA6795UKMFR9", 
			"asin": "B071WKJX72"
		}
	]
}
'

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

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

-X POST \

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

-d '

{

"filters": {

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

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

"interval": "year"

},

"rankings": [

{

"keyword": "fatburner",

"marketplace": "A1PA6795UKMFR9",

"asin": "B071WKJX72"

}

]

}

'

JSON Payload

{
	"filters": {
		"start": "2018-01-01", 
		"end": "2018-12-31", 
		"interval": "year"
	}, 
	"rankings": [
		{
			"keyword": "fatburner", 
			"marketplace": "A1PA6795UKMFR9", 
			"asin": "B071WKJX72"
		}
	]
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

{

"filters": {

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

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

"interval": "year"

},

"rankings": [

{

"keyword": "fatburner",

"marketplace": "A1PA6795UKMFR9",

"asin": "B071WKJX72"

}

]

}

Property	Type	Description	Further information
`rankings.keyword`	string	The keyword, which ranking data is requested for
`rankings.asin`	string	The ASIN, for which ranking data is requested for
`rankings.marketplace`	string	The marketplace-ID, for which ranking data is requested for.	valid marketplace-IDs
`filters.start`	date	The start-date for which rankings shall be requested for.
`filters.end`	date	The end-date for which rankings shall be requeste for.
`filters.interval`	string	The interval, in which the ranking data shall be returned.	valid intervals

JSON Response

{
    "items": [
        {
            "marketplace": {
                "id": "A1PA6795UKMFR9",
                "name": "amazon.de"
            },
            "asin": "B071WKJX72",
            "keyword": "fatburner",
            "history": {
                "2018-01-01": {
                    "max": 3,
                    "min": 3,
                    "avg": 3
                }
            }
        }
    ],
    "request": {
        "id": "812b7820-c58e-4b22-813d-9b578e03c9eb",
        "took": 0.0679,
        "costs": 10,
        "remaining": 99990,
        "method": "research.products.keywords.rankings.history.get",
        "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

{

"items": [

{

"marketplace": {

"id": "A1PA6795UKMFR9",

"name": "amazon.de"

},

"asin": "B071WKJX72",

"keyword": "fatburner",

"history": {

"2018-01-01": {

"max": 3,

"min": 3,

"avg": 3

}

],

"request": {

"id": "812b7820-c58e-4b22-813d-9b578e03c9eb",

"took": 0.0679,

"costs": 10,

"remaining": 99990,

"method": "research.products.keywords.rankings.history.get",

"success": true,

"error": {

"code": null,

"message": null,

"hint": null

}

Property	Type	Description
`items.marketplace.id`	string	The marketplace ID, which the returned rankings refer to
`items.marketplace.name`	string	The marketplace name, which the returned rankings refer to
`items.asin`	string	The ASIN, which the returned rankings refer to
`items.keyword`	string	The keyword, which the returned rankings refer to
`items.history.date`	date	Depending of the requested interval, the day / week / month / year the returned rankings refer to.
`items.history.date.max`	float	The hightes (worst) ranking within the requested interval for the keyword-ASIN-marketplace-combination.
`items.history.date.min`	float	The lowest (best) ranking within the requested interval for the keyword-ASIN-marketplace-combination.
`items.history.date.avg`	float	The average ranking within the requested interval for the keyword-ASIN-marketplace-combination.