GET/traffic_report
This method returns a report that details the user traffic received by a seller's listings.
A traffic report gives sellers the ability to review how often their listings appeared on eBay, how many times their listings are viewed, and how many purchases were made. The report also returns the report's start and end dates, and the date the information was last updated.
For more information, see Traffic report details
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com
root URI with api.sandbox.ebay.com
URI parameters
Parameter | Type | Description |
---|---|---|
dimension | array of string | This query parameter specifies the dimension, or "attribute," that is applied to the report metric. Valid values: DAY or LISTING Examples
Occurrence: Required |
metric | array of string | This query parameter specifies the metrics you want covered in the report. Note: Unlike names for parameters and enumerated values, metric values are not case sensitive. Valid values:
Occurrence: Required |
filter | array of FilterField | This query parameter refines the information returned in the traffic report. Note: URL encode all the values you supply in the filter parameter. See URL encoding query parameter values as described in URL parameters. Configure the following properties of the filter parameter to tune the traffic report to your needs:
Example filter parameter The following example shows how to configure the filter parameter with the marketplace_ids and date_range filters:
See samples for additional examples. Occurrence: Required |
sort | array of SortField | This query parameter sorts the report on the specified metric. You can only specify a single metric in the sort parameter and the specified metric must be included in the configuration of the report's metric parameter. Sorting is helpful when you want to review how a specific metric is performing, such as the CLICK_THROUGH_RATE. Most reports can be sorted in ascending or descending order. Precede the value of a descending-order request with a minus sign (" - "), for example: sort=-CLICK_THROUGH_RATE .Note: There are a couple of constraints on sorting the report by different metrics:
Occurrence: Optional |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization
HTTP header for authentication authorization.
All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/sell.analytics.readonly
See OAuth access tokens for more information.
Request payload
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
Output container/field | Type | Description |
---|---|---|
dimensionMetadata | array of Metadata | A complex type containing the header of the report and the type of data containted in the rows of the report. Occurrence: Always |
dimensionMetadata.metadataHeader | MetadataHeader | The container that returns the dimensionKeys and metrics headers for the report. Occurrence: Always |
dimensionMetadata.metadataHeader.key | string | The key value used for the report. Occurrence: Always |
dimensionMetadata.metadataHeader.metadataKeys | array of Definition | The list of dimension key values used for the report header. Each list element contains the key name, its data type, and its localized name.
Occurrence: Always |
dimensionMetadata.metadataHeader.metadataKeys.dataType | DataTypeEnum | Indicates the data type of the returned dimension. For example, if the dimension is Occurrence: Always |
dimensionMetadata.metadataHeader.metadataKeys.key | string | The value the dimension or metric parameter as submitted in the request. Occurrence: Always |
dimensionMetadata.metadataHeader.metadataKeys.localizedName | string | The localized name of the metric or dimension (translated into the language specified in the Accept-Language HTTP request header). For example, if Accept-Language is set to Occurrence: Always |
dimensionMetadata.metadataRecords | array of MetadataRecord | A list of the individual report records. Occurrence: Always |
dimensionMetadata.metadataRecords.metadataValues | array of Value | A list of data in a row returned in the traffic report. The data in each of the cells match the labels in headers of the report. Occurrence: Always |
dimensionMetadata.metadataRecords.metadataValues.applicable | boolean | If set to Occurrence: Always |
dimensionMetadata.metadataRecords.metadataValues.value | any | The value of the report data. Occurrence: Always |
dimensionMetadata.metadataRecords.value | Value | The value of the key on which the report is based. Occurrence: Always |
dimensionMetadata.metadataRecords.value.applicable | boolean | If set to Occurrence: Always |
dimensionMetadata.metadataRecords.value.value | any | The value of the report data. Occurrence: Always |
endDate | string | Occurrence: Always |
header | Header | A complex type containing the header for the report. Occurrence: Always |
header.dimensionKeys | array of Definition | A list of the dimension or metric keys returned in the report. The values for each are is returned in the associated key fields. Occurrence: Always |
header.dimensionKeys.dataType | DataTypeEnum | Indicates the data type of the returned dimension. For example, if the dimension is Occurrence: Always |
header.dimensionKeys.key | string | The value the dimension or metric parameter as submitted in the request. Occurrence: Always |
header.dimensionKeys.localizedName | string | The localized name of the metric or dimension (translated into the language specified in the Accept-Language HTTP request header). For example, if Accept-Language is set to Occurrence: Always |
header.metrics | array of Definition | The list of metrics returned in the report. The values for each are is returned in the associated key fields. Occurrence: Always |
header.metrics.dataType | DataTypeEnum | Indicates the data type of the returned dimension. For example, if the dimension is Occurrence: Always |
header.metrics.key | string | The value the dimension or metric parameter as submitted in the request. Occurrence: Always |
header.metrics.localizedName | string | The localized name of the metric or dimension (translated into the language specified in the Accept-Language HTTP request header). For example, if Accept-Language is set to Occurrence: Always |
lastUpdatedDate | string | The date and time, in ISO 8601 format, that indicates the last time the data returned in the report was updated. Occurrence: Always |
records | array of Record | A complex type containing the individual data records for the traffic report. Occurrence: Always |
records.dimensionValues | array of Value | A list where each element contains either the string Occurrence: Always |
records.dimensionValues.applicable | boolean | If set to Occurrence: Always |
records.dimensionValues.value | any | The value of the report data. Occurrence: Always |
records.metricValues | array of Value | A list where each element contains a value field that indicates the record's value for the metric. Each element also contains an applicable field that indicates the veracity of the computed value. Occurrence: Always |
records.metricValues.applicable | boolean | If set to Occurrence: Always |
records.metricValues.value | any | The value of the report data. Occurrence: Always |
startDate | string | The start date of the date range used to calculate the report, in ISO 8601 format. Occurrence: Always |
warnings | array of ErrorDetailV3 | An array of any process errors or warnings that were generated during the processing of the call processing. Occurrence: Conditional |
warnings.category | string | Identifies whether the error was in the REQUEST or happened when running the APPLICATION. Occurrence: Conditional |
warnings.domain | string | The primary system where the error occurred. This is relevant for application errors. For Analytics errors, it always has the value Occurrence: Conditional |
warnings.errorId | integer | A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. Traffic report error IDs range from 50001 to 50500. Occurrence: Conditional |
warnings.inputRefIds | array of string | Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation. Occurrence: Conditional |
warnings.longMessage | string | A more detailed explanation of the error than given in the Occurrence: Conditional |
warnings.message | string | Information on how to correct the problem, in the end user's terms and language where applicable. Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale. Occurrence: Conditional |
warnings.outputRefIds | array of string | Identifies specific response elements associated with the error, if any. Path format is the same as Occurrence: Conditional |
warnings.parameters | array of ErrorParameterV3 | This optional list of name/value pairs that contain context-specific Occurrence: Conditional |
warnings.parameters.name | string | Name of the entity that threw the error. Occurrence: Conditional |
warnings.parameters.value | string | A description of the error. Occurrence: Conditional |
warnings.subdomain | string | If present, indicates which subsystem in which the error occurred. Occurrence: Conditional |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
Status | Meaning |
---|---|
200 | Success |
400 | Bad Request |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
50001 | API_ANALYTICS | REQUEST | Invalid dimension specified. For help, see the documentation. |
50002 | API_ANALYTICS | REQUEST | Invalid metric {metricName} specified. For help, see the documentation. |
50003 | API_ANALYTICS | REQUEST | Invalid date range. End date must be before or equal to start date. |
50004 | API_ANALYTICS | REQUEST | Invalid date range. Start date must be before or equal to end date. |
50005 | API_ANALYTICS | REQUEST | No filter is specified, which is required. For help, see the documentation. |
50006 | API_ANALYTICS | REQUEST | The sort field value {sortField} is not supported. |
50008 | API_ANALYTICS | REQUEST | The call requires at least one metric. For help, see the documentation. |
50009 | API_ANALYTICS | REQUEST | The call requires at least one URI query parameter. For help, see the documentation. |
50013 | API_ANALYTICS | REQUEST | Invalid date range format - Start Date. The format is yyyyMMdd. |
50014 | API_ANALYTICS | REQUEST | Invalid date range format - End Date. The format is yyyyMMdd. |
50018 | API_ANALYTICS | REQUEST | Neither the start date nor the end date can be in the future. |
50021 | API_ANALYTICS | REQUEST | Invalid filter field {filterField} specified. |
50022 | API_ANALYTICS | REQUEST | Specify at least one marketplace ID. |
50023 | API_ANALYTICS | REQUEST | The marketplace ID {marketplaceId} is not supported by this call. For help, see the documentation. |
50024 | API_ANALYTICS | REQUEST | The marketplace ID {marketplaceId} is not valid. |
50025 | API_ANALYTICS | REQUEST | The start date is too far in the past. The start date must be less than or equal to {maxStartDateInThePast}. |
50026 | API_ANALYTICS | REQUEST | The date range is too long. The date range must be less than or equal to {maxDateWindow}. |
50027 | API_ANALYTICS | REQUEST | The 'listing_id' value is empty. |
50028 | API_ANALYTICS | REQUEST | The maximum number of listing IDs has been exceeded. The maximum number of listing IDs is {maxListingIdsNumber}. |
50029 | API_ANALYTICS | REQUEST | Invalid listing ID {listingId}. |
50030 | API_ANALYTICS | REQUEST | Data for the listing ID {listingId} could not be found. |
50031 | API_ANALYTICS | REQUEST | Date range is required. |
50032 | API_ANALYTICS | APPLICATION | We are unable to process data for accounts, like this one, which have listed in more than a few thousand leaf categories in the past couple years. |
50033 | API_ANALYTICS | REQUEST | Invalid date range filter format {invalidDateRangeFilter}. |
50034 | API_ANALYTICS | REQUEST | Invalid listing ids filter format {invalidListingIdsFilter}. |
50035 | API_ANALYTICS | REQUEST | Requested sort field is not part of the list of metrics requested. |
50036 | API_ANALYTICS | REQUEST | {sortOrder} sort order is not supported for {sortField} metric. |
50037 | API_ANALYTICS | REQUEST | The Metric {metricName} does not have data available for the requested date range. |
50050 | API_ANALYTICS | APPLICATION | We are doing some maintenance and cannot show all your information right now. We are still tracking everything, and you will see your updated stats soon. |
50500 | API_ANALYTICS | APPLICATION | Internal server error. Wait a few minutes and try the call again. If error persists contact the eBay Developer Program. |
50600 | API_ANALYTICS | REQUEST | Data for the listing Ids {delayedListingIds} is not yet updated to {endDate} |
Warnings
This call has no warnings.
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Generate Traffic Report by Days
This sample generates the metrics for how often the seller's listings appeared in the search results page and the seller's store, and the sales conversion rate for each date in the date range. It also limits the report to the seller's listings on the eBay US site.
Input
The input fields are marketplace_ids, date_range, dimension, and metric fields.
GEThttps://api.ebay.com/sell/analytics/v1/traffic_report?filter=marketplace_ids:%7BEBAY_US%7D,date_range:%5B20160601..20160828%5D&dimension=DAY&metric=LISTING_IMPRESSION_SEARCH_RESULTS_PAGE,LISTING_IMPRESSION_STORE,SALES_CONVERSION_RATE
Output
The output contains the metrics (metrics.key) and the records container. Each record contains the aggregate records.dimensionValues.value, which is the date, and the metric value (metricValues.value) of the metric.
Sample 2: Generate Traffic Report by Listing
This sample generates the metrics for how often the seller's listings appeared in the search results page and the seller's store, and the sales conversion rate for each listing within the date range. It also limits the report to the seller's listing on the eBay US site and sorts the LISTING_IMPRESSION_STORE metric in ascending order.
Input
The input fields are marketplace_ids, date_range, dimension, and metric fields.
GEThttps://api.ebay.com/sell/analytics/v1/traffic_report?filter=marketplace_ids:%7BEBAY_US%7D,date_range:%5B20161007..20161009%5D&dimension=LISTING&metric=LISTING_IMPRESSION_SEARCH_RESULTS_PAGE,LISTING_IMPRESSION_STORE,SALES_CONVERSION_RATE&sort=LISTING_IMPRESSION_STORE
Output
The output contains the metrics (metrics.key), and the records container (records). Each record contains the aggregate records.dimensionValues.value, which is the listing Id, and the metric value (metricValues.value) of the metric.
It also includes the metadata (metadataKeys.key) and metadata records container (metadataRecords). Each of these records contain the metadataRecords.value, which is the listing Id and the (metadataRecords.metadataValues.value), which in this case, the listing title.