{"_id":"5771aaadc755ca0e00617d6e","editedParams":true,"editedParams2":true,"parentDoc":null,"__v":2,"category":{"_id":"57717aee3dd24019004c9122","project":"568af724176a6c0d00a29ec4","version":"568af725176a6c0d00a29ec7","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-06-27T19:13:50.805Z","from_sync":false,"order":5,"slug":"reporting","title":"Reporting"},"project":"568af724176a6c0d00a29ec4","user":"568af6d197d8960d0012ab7d","version":{"_id":"568af725176a6c0d00a29ec7","project":"568af724176a6c0d00a29ec4","__v":11,"createdAt":"2016-01-04T22:50:13.289Z","releaseDate":"2016-01-04T22:50:13.289Z","categories":["568af725176a6c0d00a29ec8","56d9d397337fd11300d6a3e3","56d9d4287222d50b0070160b","56f424307ea0091700f63ac5","56f45babcb0dce29005a8e85","5739e5836c5ba134007a197d","57717aee3dd24019004c9122","5771b5d8c755ca0e00617d7d","579639964913990e001a5911","57e57e7df3d7fc0e009c5119","587569b6f4483a0f00d2e6b8"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-27T22:37:33.341Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"get","results":{"codes":[{"name":"","code":"{\n    \"queryProfile\":{\n        \"startDate\":\"2016-01-01\",\n        \"endDate\":\"2016-01-31\",\n        \"groupBy\":\"merchants\",\n        \"sortBy\":\"revenue\",\n        \"rowsPerPage\":1000,\n        \"page\":1,\n        \"campaignId\":null,\n        \"product\":null,\n        \"device\":null\n    },\n    \"columnHeaders\":[\n        {\n            \"name\":\"merchantGroupId\",\n            \"dataType\":\"INTEGER\"\n        },\n        {\n            \"name\":\"merchantId\",\n            \"dataType\":\"INTEGER\"\n        },\n        {\n            \"name\":\"merchantName\",\n            \"dataType\":\"STRING\"\n        },\n        {\n            \"name\":\"actions\",\n            \"dataType\":\"INTEGER\"\n        },\n        {\n            \"name\":\"clicks\",\n            \"dataType\":\"INTEGER\"\n        },\n        {\n            \"name\":\"status\",\n            \"dataType\":\"STRING\"\n        },\n        {\n            \"name\":\"revenue\",\n            \"dataType\":\"CURRENCY\"\n        },\n        {\n            \"name\":\"sales\",\n            \"dataType\":\"CURRENCY\"\n        },\n        {\n            \"name\":\"epc\",\n            \"dataType\":\"CURRENCY\"\n        }\n    ],\n    \"rows\":[\n        [\n            185,\n            1,\n            \"Amazon US\",\n            3405,\n            51646,\n            \"Active\",\n            4211.08,\n            88660.24,\n            0.08154\n        ],\n        [\n            1152,\n            20517,\n            \"Manual Compensation\",\n            0,\n            0,\n            \"Inactive\",\n            3500.58,\n            0,\n            0\n        ],\n        [\n            79889,\n            116270,\n            \"fabletics.com\",\n            212,\n            1088,\n            \"Active\",\n            900,\n            1322.36,\n            0.82721\n        ],\n        [\"...\"]\n    ]\n}","language":"json","status":200},{"name":null,"code":"{\n    \"error\": {\n        \"errors\": [\n            {\n                \"reason\": \"invalidParameter\",\n                \"message\": \"Invalid product requested. Please use all, convert, insert, spotlight\",\n                \"locationType\": \"parameter\",\n                \"location\": \"product\"\n            }\n        ]\n    },\n    \"code\": 400,\n    \"message\": \"Invalid product requested. Please use all, convert, insert, spotlight\"\n}","language":"json","status":400},{"status":401,"language":"json","code":"{\n    \"error\": {\n        \"errors\": [\n            {\n                \"reason\": \"invalidCredentials\",\n                \"message\": \"Authorization secret is missing or invalid. This can be found at https://publishers.viglink.com/account and can be sent as a parameter or Authorization header\",\n                \"locationType\": \"parameter\",\n                \"location\": \"secret\"\n            }\n        ]\n    },\n    \"code\": 401,\n    \"message\": \"Authorization secret is missing or invalid. This can be found at https://publishers.viglink.com/account and can be sent as a parameter or Authorization header\"\n}"},{"code":"{\n    \"error\": {\n        \"errors\": [\n            {\n                \"reason\": \"internalServerError\",\n                \"message\": \"An unexpected error occurred, but we are looking into it\"\n            }\n        ]\n    },\n    \"code\": 500,\n    \"message\": \"An unexpected error occurred, but we are looking into it\"\n}","language":"text","status":500}]},"settings":"57717d5327a5c20e00030dbd","examples":{"codes":[{"code":"<?php\n$ch = curl_init(\"https://rest.viglink.com/api/performance/ranked/merchants?sortBy=revenue&startDate=2016-01-01&endDate=2016-01-31\");\n\ncurl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: secret YOUR SECRET KEY'));\n\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);\n\n$response = curl_exec($ch);\n\ncurl_close($ch);","language":"php"},{"language":"ruby","code":"require 'httparty'\n\nurl = \"https://rest.viglink.com/api/performance/ranked/merchants?sortBy=revenue&startDate=2016-01-01&endDate=2016-01-31\"\n\nheaders = {Authorization: \"secret {SECRET KEY}\"}\n\nresponse = HTTParty.get(url, headers: headers)"},{"language":"curl","code":"curl -i -X GET -H \"Authorization: secret {SECRET KEY}\" 'https://rest.viglink.com/api/performance/ranked/merchants?sortBy=revenue&startDate=2016-01-01&endDate=2016-01-31'"}]},"auth":"required","params":[{"_id":"577199de45c7080e0072925c","ref":"","in":"path","required":true,"desc":"Generated a ranked report for 1 of 4 categories: merchants, merchandise, links, pages","default":"merchants","type":"string","name":"groupBy"},{"_id":"5771aaf045c7080e00729292","ref":"","in":"query","required":false,"desc":"Measure 1 of 6 possible metrics: clicks, ctr, epc, pageviews, revenue, sales","default":"revenue","type":"string","name":"sortBy"},{"_id":"577180b22d37b20e00c845a9","ref":"","in":"query","required":false,"desc":"Numeric ID of your campaign(s)","default":"NULL","type":"array_int","name":"campaignId"},{"_id":"577180b22d37b20e00c845a8","ref":"","in":"query","required":false,"desc":"Lowercase instance of a product (all, convert, insert or spotlight)","default":"NULL","type":"array_string","name":"product"},{"_id":"577181be2f16442900771117","ref":"","in":"query","required":false,"desc":"Lowercase device type (all, unknown, desktop, tablet, mobile)","default":"NULL","type":"array_string","name":"device"},{"_id":"577181be2f16442900771116","ref":"","in":"query","required":false,"desc":"Start of requested time series","default":"-31 Days","type":"yyyy-mm-dd","name":"startDate"},{"_id":"577181be2f16442900771115","ref":"","in":"query","required":false,"desc":"End of requested time series","default":"-1 Day","type":"yyyy-mm-dd","name":"endDate"},{"_id":"5771ad026b1f9a0e00e2d5aa","ref":"","in":"query","required":false,"desc":"Page to request","default":"1","type":"int","name":"page"},{"_id":"5771ad026b1f9a0e00e2d5a9","ref":"","in":"query","required":false,"desc":"Rows to be made available per page. Max allowed is 5,000","default":"1000","type":"int","name":"rowsPerPage"},{"_id":"577181be2f16442900771113","ref":"","in":"query","required":false,"desc":"Lowercase format of response: json, xml or csv","default":"json","type":"string","name":"format"},{"_id":"577181be2f16442900771112","ref":"","in":"query","required":false,"desc":"JSON-P callback method name","default":"NULL","type":"string","name":"callback"}],"url":"/performance/ranked/:groupBy"},"isReference":false,"order":2,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Authorization Header\",\n  \"body\": \"You must add authorization headers to this request.\\n```Authorization: secret {SECRET KEY}```\\n\\n<b>Replace {SECRET KEY} above with any secret key from any campaign in your account.</b> You can find a secret key in your [VigLink account](https://publishers.viglink.com/account). When logged into your dashboard, go to Manage > Account. Under the My Campaign sub-heading, copy a Secret Key. If you don’t have one, click “Get a Secret Key\\\" on any of your campaigns.\"\n}\n[/block]\nThe ranked report returns grouped performance records for one of four groups: `merchants`, `merchandise`, `links`, `pages`. You may sort by one of six metrics available: `clicks`, `ctr`, `epc`, `pageviews`, `revenue`, and `sales`.\n\n##Sort By Limitations\n\n`sortBy` values can't be used with all four reports. As such the available `sortBy` metrics are defined below:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Group Report\",\n    \"h-1\": \"Available sortBy metrics\",\n    \"0-0\": \"merchants\",\n    \"0-1\": \"`revenue`, `epc`, `clicks`, `sales`\",\n    \"1-0\": \"links\",\n    \"1-1\": \"`revenue`, `epc`, `clicks`, `sales`\",\n    \"2-0\": \"merchandise\",\n    \"2-1\": \"`revenue`, `sales`\",\n    \"3-0\": \"pages\",\n    \"3-1\": \"`revenue`, `epc`, `clicks`, `sales`, `pageviews`, `ctr`\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Query Profile Index\n\nA `queryProfile` index is returned to provide insight into changed query parameters (if invalid), default parameters used for the report and additional account data returned from the request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"queryProfile\\\":{\\n    \\\"startDate\\\":\\\"2016-01-01\\\",\\n    \\\"endDate\\\":\\\"2016-01-31\\\",\\n    \\\"groupBy\\\":\\\"merchants\\\",\\n    \\\"sortBy\\\":\\\"revenue\\\",\\n    \\\"rowsPerPage\\\":1000,\\n    \\\"page\\\":1,\\n    \\\"campaignId\\\":null,\\n    \\\"product\\\":null,\\n    \\\"device\\\":null\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n##Column Headers Index\n\nAn additional `columnHeaders` index is made available that defines each enumerated column in the `rows` index. This is designed to cut down on the size of the response, and to provide a definition of the type of data the value represents.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"columnHeaders\\\":[\\n    {\\n        \\\"name\\\":\\\"merchantGroupId\\\",\\n        \\\"dataType\\\":\\\"INTEGER\\\"\\n    },\\n    {\\n        \\\"name\\\":\\\"merchantId\\\",\\n        \\\"dataType\\\":\\\"INTEGER\\\"\\n    },\\n    {\\n        \\\"name\\\":\\\"merchantName\\\",\\n        \\\"dataType\\\":\\\"STRING\\\"\\n    },\\n    {\\n        \\\"name\\\":\\\"actions\\\",\\n        \\\"dataType\\\":\\\"INTEGER\\\"\\n    },\\n    {\\n        \\\"name\\\":\\\"clicks\\\",\\n        \\\"dataType\\\":\\\"INTEGER\\\"\\n    },\\n    {\\n        \\\"name\\\":\\\"status\\\",\\n        \\\"dataType\\\":\\\"STRING\\\"\\n    },\\n    {\\n        \\\"name\\\":\\\"revenue\\\",\\n        \\\"dataType\\\":\\\"CURRENCY\\\"\\n    },\\n    {\\n        \\\"name\\\":\\\"sales\\\",\\n        \\\"dataType\\\":\\\"CURRENCY\\\"\\n    },\\n    {\\n        \\\"name\\\":\\\"epc\\\",\\n        \\\"dataType\\\":\\\"CURRENCY\\\"\\n    }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe possible values for dataType are: `STRING`, `INTEGER`, `PERCENT`, `TIME`, `DATE`, `CURRENCY`, `FLOAT`.\n\nMap the enumerative indexes for each row to the `columnHeaders` index.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"rows\\\":[\\n    [\\n        185,\\n        1,\\n        \\\"Amazon US\\\",\\n        3405,\\n        51646,\\n        \\\"Active\\\",\\n        4211.08,\\n        88660.24,\\n        0.08154\\n    ]\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n##Warnings\n\nDepending on your request, a response can include a `warnings` index that includes a message about the response and possible actions taken. For example, if a `sortBy` parameter is passed on a report that doesn’t permit such a column to be sorted, `revenue` is used and a warning array and message is sent.\n\nSee [Sort By Limitations](#section-sort-by-limitations) above for valid requests.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"warnings: [\\n    {\\n        message: \\\"For this requested ranked report, only revenue, epc, clicks, sales are available as a sortBy column. This report has defaulted back to revenue\\\"\\n    }\\n]\\n\\n//for correct requests, warnings is false\\nwarnings: false\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"Get a detailed report of your campaign performance grouped by merchants, merchandise, links or pages.","slug":"ranked-reports","type":"endpoint","title":"Ranked Reports"}

getRanked Reports

Get a detailed report of your campaign performance grouped by merchants, merchandise, links or pages.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

groupBy:
required
stringmerchants
Generated a ranked report for 1 of 4 categories: merchants, merchandise, links, pages

Query Params

sortBy:
stringrevenue
Measure 1 of 6 possible metrics: clicks, ctr, epc, pageviews, revenue, sales
campaignId:
array of integersNULL
Numeric ID of your campaign(s)
product:
array of stringsNULL
Lowercase instance of a product (all, convert, insert or spotlight)
device:
array of stringsNULL
Lowercase device type (all, unknown, desktop, tablet, mobile)
startDate:
yyyy-mm-dd-31 Days
Start of requested time series
endDate:
yyyy-mm-dd-1 Day
End of requested time series
page:
integer1
Page to request
rowsPerPage:
integer1000
Rows to be made available per page. Max allowed is 5,000
format:
stringjson
Lowercase format of response: json, xml or csv
callback:
stringNULL
JSON-P callback method name

Examples


Result Format


Documentation

[block:callout] { "type": "warning", "title": "Authorization Header", "body": "You must add authorization headers to this request.\n```Authorization: secret {SECRET KEY}```\n\n<b>Replace {SECRET KEY} above with any secret key from any campaign in your account.</b> You can find a secret key in your [VigLink account](https://publishers.viglink.com/account). When logged into your dashboard, go to Manage > Account. Under the My Campaign sub-heading, copy a Secret Key. If you don’t have one, click “Get a Secret Key\" on any of your campaigns." } [/block] The ranked report returns grouped performance records for one of four groups: `merchants`, `merchandise`, `links`, `pages`. You may sort by one of six metrics available: `clicks`, `ctr`, `epc`, `pageviews`, `revenue`, and `sales`. ##Sort By Limitations `sortBy` values can't be used with all four reports. As such the available `sortBy` metrics are defined below: [block:parameters] { "data": { "h-0": "Group Report", "h-1": "Available sortBy metrics", "0-0": "merchants", "0-1": "`revenue`, `epc`, `clicks`, `sales`", "1-0": "links", "1-1": "`revenue`, `epc`, `clicks`, `sales`", "2-0": "merchandise", "2-1": "`revenue`, `sales`", "3-0": "pages", "3-1": "`revenue`, `epc`, `clicks`, `sales`, `pageviews`, `ctr`" }, "cols": 2, "rows": 4 } [/block] ##Query Profile Index A `queryProfile` index is returned to provide insight into changed query parameters (if invalid), default parameters used for the report and additional account data returned from the request. [block:code] { "codes": [ { "code": "\"queryProfile\":{\n \"startDate\":\"2016-01-01\",\n \"endDate\":\"2016-01-31\",\n \"groupBy\":\"merchants\",\n \"sortBy\":\"revenue\",\n \"rowsPerPage\":1000,\n \"page\":1,\n \"campaignId\":null,\n \"product\":null,\n \"device\":null\n}", "language": "json" } ] } [/block] ##Column Headers Index An additional `columnHeaders` index is made available that defines each enumerated column in the `rows` index. This is designed to cut down on the size of the response, and to provide a definition of the type of data the value represents. [block:code] { "codes": [ { "code": "\"columnHeaders\":[\n {\n \"name\":\"merchantGroupId\",\n \"dataType\":\"INTEGER\"\n },\n {\n \"name\":\"merchantId\",\n \"dataType\":\"INTEGER\"\n },\n {\n \"name\":\"merchantName\",\n \"dataType\":\"STRING\"\n },\n {\n \"name\":\"actions\",\n \"dataType\":\"INTEGER\"\n },\n {\n \"name\":\"clicks\",\n \"dataType\":\"INTEGER\"\n },\n {\n \"name\":\"status\",\n \"dataType\":\"STRING\"\n },\n {\n \"name\":\"revenue\",\n \"dataType\":\"CURRENCY\"\n },\n {\n \"name\":\"sales\",\n \"dataType\":\"CURRENCY\"\n },\n {\n \"name\":\"epc\",\n \"dataType\":\"CURRENCY\"\n }\n]", "language": "json" } ] } [/block] The possible values for dataType are: `STRING`, `INTEGER`, `PERCENT`, `TIME`, `DATE`, `CURRENCY`, `FLOAT`. Map the enumerative indexes for each row to the `columnHeaders` index. [block:code] { "codes": [ { "code": "\"rows\":[\n [\n 185,\n 1,\n \"Amazon US\",\n 3405,\n 51646,\n \"Active\",\n 4211.08,\n 88660.24,\n 0.08154\n ]\n]", "language": "json" } ] } [/block] ##Warnings Depending on your request, a response can include a `warnings` index that includes a message about the response and possible actions taken. For example, if a `sortBy` parameter is passed on a report that doesn’t permit such a column to be sorted, `revenue` is used and a warning array and message is sent. See [Sort By Limitations](#section-sort-by-limitations) above for valid requests. [block:code] { "codes": [ { "code": "warnings: [\n {\n message: \"For this requested ranked report, only revenue, epc, clicks, sales are available as a sortBy column. This report has defaulted back to revenue\"\n }\n]\n\n//for correct requests, warnings is false\nwarnings: false", "language": "json" } ] } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}